Difference between revisions of "Function (extension point)"

Latest revision as of 15:13, 17 June 2013

Identifier

ru.biosoft.plugins.javascript.function

Plugin

ru.biosoft.plugins.javascript

[edit] Description

Using this extension plug-in can define JavaScript functions that will be available from JavaScipt shell. Plug-in functions will be shown under analyses/JavaScript/functions section in repository tree. Function help will be shown in information box when the function item will be selected in repository tree.

When the JavaScript function is called the specified by extension class method will be invoked. The METHOD must match one of two forms: with fixed or variable number of arguments.

[edit] Fixed arguments number

The first form is a member with zero or more parameters of the following types: Scriptable, Object, String, boolean, byte, short, int, float, or double. The long type is not supported because the double representation of a long (which is the EMCA-mandated storage type for Numbers) may lose precision. The return value must be void or one of the types allowed for parameters.

The runtime will perform appropriate conversions based upon the type of the parameter. A parameter type of Object specifies that no conversions are to be done. A parameter of type String will use Context.toString to convert arguments. Similarly, parameters of type double, boolean, and Scriptable will cause Context.toNumber, Context.toBoolean, and Context.toObject, respectively, to be called.

If the method is not static, the Java 'this' value will correspond to the JavaScript 'this' value. Any attempt to call the function with a 'this' value that is not of the right Java type will result in an error.

[edit] Variable arguments number

The second form is the variable arguments (or "varargs") form. The method must be a static Java method with parameters:

(Context cx, Scriptable thisObj, Object[] args, Function funObj) 

args

parameter contains the arguments

thisObj

is the JavaScript 'this' value

funObj

is the function object for the invoked function.

The Java method should return an Object result.

[edit] Configuration Markup

<!ELEMENT function (argument*, doc?)>
<!ATTLIST function>
   name              CDATA   #REQUIRED
   class             CDATA   #REQUIRED
   method            CDATA   #REQUIRED
   varargs           CDATA   "false"
   javadoc           CDATA
>

argument

function arguments.

doc

the function description (documentation).

name

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

class

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

member

the method or constructor that will be invoked to process the function call.

varargs

indicates the function form: fixed or variable argument number.

javadoc

URL to javadoc for the function description.

<!ELEMENT argument>
<!ATTLIST argument>
   class             CDATA   #REQUIRED
>

class

the fully-qualified name of a argument type.

<!ELEMENT doc (argument*, returns?, throws*, example*)>
<!ATTLIST doc>
     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.

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] Examples

This is example of function definition with variable number of arguments.

<extension id="defineClass" point="ru.biosoft.plugins.javascript.function"> 
   <function
     name="defineClass" 
     class="ru.biosoft.plugins.javascript.Global" 
     method="defineClass" 
     varargs="true"> 
       <doc description="%defineClass.descr">
          <argument name="clazz" type="String" obligatory="true" description="%defineClass.arg_1"/>
          <returns type="void"/>    
          <throws type="IllegalAccessException"
            description="if access is not available to a reflected class member"/>
          <throws type="InstantiationException" 
            description="if unable to instantiate the named class"/>
          <throws type="InvocationTargetException"
            description="if an exception is thrown during execution of methods of the named class"/>
          <throws type="ClassDefinitionException"
            description="if the format of the class causes this exception in ScriptableObject.defineClass"/>
          <throws type="PropertyException"
            description="if the format of the class causes this exception in ScriptableObject.defineClass"/>
       </doc>
   </function>
</extension>