Difference between revisions of "Host object (extension point)"

Latest revision as of 15:12, 16 May 2013

Identifier

ru.biosoft.plugins.javascript.hostObject

Plugin

ru.biosoft.plugins.javascript

[edit] Description

Using this extension point plug-in can provide access to particular Java objects (host objects) provided by plug-in. Plug-in host oblects will be shown in 'Analyses/JavaScript/host objects' section in repository tree. Host object description (help) will be shown in View/Edit tab when the host object item will be selected in repository tree.

[edit] Configuration Markup

<!ELEMENT hostObject (doc?)>
<!ATTLIST hostObject>
  name              CDATA   #REQUIRED
  class             CDATA   #REQUIRED
  javadoc           CDATA
>

name

the function name (how it will be used JavaScript).

class

the fully-qualified name of a class that provides corresponding static method.

javadoc

URL to javadoc for the corresponding Java class.

<!ELEMENT doc (property*, function*)>
<!ATTLIST doc>
  type              CDATA   #IMPLIED 
  description       CDATA   #REQUIRED
>

doc

description of host object, its properties, functions and examples.

property

description of host object property.

function

description of host object function.

example

host object usage example.

<!ELEMENT property>
<!ATTLIST property>
  name              CDATA   #REQUIRED
  type              CDATA   #REQUIRED
  readOnly          CDATA   "false"
  description       CDATA   #REQUIRED
>

name

the property name.

type

the property type.

obligatory

indicates whether the property is read only.

description

the property description.

<!ELEMENT function (argument*, returns?, throws*, example*)>
<!ATTLIST function>
  name              CDATA   #REQUIRED
  description       CDATA   #REQUIRED
>

argument

function argument description.

returns

description of the function result.

throws

description of exceptions that can be thrown by the function.

example

usage examples.

name

function name.

description

function description.

<!ELEMENT argument>
<!ATTLIST argument>
  name             CDATA   #REQUIRED
  type             CDATA   #REQUIRED
  obligatory       CDATA   "true"
  description      CDATA   
>

name

the argument name.

type

the argument type.

obligatory

indicates whether the argument is obligatory.

description

the argument description.

<!ELEMENT returns>
<!ATTLIST returns>
  type             CDATA   #REQUIRED
  description      CDATA   
>

type

the returned value type.

description

the returned value description.

<!ELEMENT throws>
<!ATTLIST throws>
  type             CDATA   #REQUIRED
  description      CDATA   
>

type

the exception type.

description

describes when and why the exception can be thrown.

<!ELEMENT example>
<!ATTLIST example>
  code             CDATA   #REQUIRED
  description      CDATA   
>

code

the code example.

description

comment.

[edit] Example

<extension id="dataFilter" point="ru.biosoft.plugins.javascript.hostObject"> 
  <hostObject name="dataFilter" class="ru.biosoft.access.javascript.JavaScriptFilter" >
    <doc description="Facade for data-filtering">
      <function name="byValue" description="returns error from last stament or null if there is no such">
        <argument name="source" type="Object" obligatory="true" description="data-source, can be String (path to DC) or DataCollection"/>
        <argument name="property" type="String" obligatory="true" description="DataElement name value"/>
        <argument name="values" type="String" obligatory="true" description="column value"/>
        <returns type="ru.biosoft.access.FilteredDataCollection" description="null on failure"/>
      </function>
      <function name="byExpression" description="filters by given javascript expression">
        <argument name="source" type="Object" obligatory="true" description="data-source, can be String (path to DC) or DataCollection"/>
        <argument name="expression" type="String" obligatory="true" description="data-source, can be String (path to DC) or DataCollection"/>
        <returns type="ru.biosoft.access.FilteredDataCollection" description="null on failure"/>
      </function>
      <function name="bySet" description="filters by given data collection, used as permitable set of values">
        <argument name="source" type="Object" obligatory="true" description="data-source, can be String (path to DC) or DataCollection"/>
        <argument name="filterSource" type="Object" obligatory="true" description="filter data-source, can be String (path to DC) or DataCollection"/>
        <returns type="ru.biosoft.access.FilteredDataCollection" description="null on failure"/>
      </function>
    </doc>
  </hostObject>
</extension>

[edit] Host objects for analyses

There is a special lightweight family of host objects specially designed for analysis methods. These host objects must subclass JavaScriptAnalysisHost class and have @PropertyName and @PropertyDescription annotations:

import ru.biosoft.analysis.javascript.JavaScriptAnalysisHost;
import ru.biosoft.util.bean.PropertyDescription;
import ru.biosoft.util.bean.PropertyName;

@PropertyName("siteAnalysis")
@PropertyDescription("Analyses related to sites, sequences and tracks")
public class JavaScriptSiteAnalysis extends JavaScriptAnalysisHost
{
}

You don't have to create any methods in this class. Registration of such host object can be done without javadoc part:

<extension id="siteAnalysis" point="ru.biosoft.plugins.javascript.hostObject"> 
  <hostObject name="siteAnalysis" class="ru.biosoft.bsa.analysis.JavaScriptSiteAnalysis" >
  </hostObject>
</extension>

After that this host object is ready for methods. If you create any analysis method, you can add js="siteAnalysis.methodName" when registering the method and method methodName will be generated automatically in host object siteAnalysis along with documentation.

[edit] See also

• List of host objects