Introduction
The Scriptable interface and the Event interface are the conduit through which JavaScript calls are passed to Java and in the opposite direction, respectively. In order for this to be possible, WebVM places restrictions on the interfaces, and on the types passed as arguments in each direction. This section states the restrictions and defines how arguments are converted from one environment to the other.
Method and field name overloading
No overloading of method or field names is permitted in either the Scriptable or Event interface. That is, public fields and methods in any given class or interface (including inherited fields/methods) cannot share names. Further, there can be no two public methods in any given class or interface (including inherited methods) that share method name. This is to simplify the binding and ensure that any given method name resolves statically to a single method on any given class or interface, and does not depend on the runtime types of any supplied arguments.
Note that static methods or fields can never (directly) be part of a Scriptable or Event interface.
Scriptable interface calls
To make a call on the Scriptable interface, a script simply makes a call to a JavaScript method with the same name as the target Java method on the WebVM element. Since no method overloading is permitted, this resolves to a single method on the Scriptable object.
The JavaScript method call blocks and control is passed to a Java thread which invokes the Java method on the Scriptable object. JavaScript execution blocks while the invoked Java method executes.
All Java library methods are expected to be non-blocking. A Java method that blocks for an unacceptably long period (defined either by the host browser or WebVM implementation) may be arbitrary terminated and the resulting behaviour is undefined17.
WebVM assumes there is only a single thread of JavaScript execution and thus all WebVM method invocations and field accesses are serialised and may be executed by a single Java-side thread. There is no guarantee, however, that the same Java-side thread will be used for all operations.
If there is an uncaught exception in the invoked Java method, the invoking JavaScript method call generates an Error.
Event interface calls
Java code can generate asynchronous events and deliver them to JavaScript via the Event interface.
Java code generates the event simply by calling a method from the Event interface on the Event object.
A JavaScript function can be run in response to that event. Two methods are supported for hooking Javascript functions to these event calls.
Globally visible function
A Javascript function f() may be registered as the handler for an event with name ev on instance inst by doing:
- webvm.instance[inst].event[ev] = f;
This mechanism is available in any situation where WebVM is used, including situations where the OBJECT tag for the WebVM instance is included statically by the invoking page.
Inaccessible function
In a mashup situation, globally visible registered event handlers might be vulnerable to misuse by other Javascript code running on a page. On order to avoid this, the WebVM module loader (see section 5) provides a means for a caller to supply a collection of event callbacks at the time a WebVM instance is created, in a way that hides those callbacks from any other Javascript running in the same global scope.
The relevant API is:
- webvm.addInstance(id, params, handlers);
where:
id is the (document-wide unique) id attribute for the WebVM instance;
params is an object containing the contents of the PARAM elements in the instance definition;
handlers is an object containing the event handler functions. (For example, if the events ev1, ev2, a€¦ have corresponding handler function objects func1, func2, etc, handlers would be {ev1:func1, ev2:func2, a€¦}.
All calls from Java threads on the Events object are serialised by synchronising on the Event object. A call from Java on a method on the Event object MAY block until the corresponding event handler in JavaScript has run to completion.
All methods on the Event interface MUST have void result type and therefore no results are passed back from JavaScript to the Java caller.
JavaScript to Java type conversions
WebVM attempts to be flexible in supporting natural mappings from a given JavaScript argument type to a given Java destination type. The supported conversions are listed in the table below, organised according to the JavaScript argument type. The a€oeJava destination typea€ in the table refers to the declared type of a Java Field, or the declared type of an argument to a Java Method. Where there is no conversion available, an error is generated and the attempted JavaScript operation fails with an Error.
JavaScript type: undefined
Java destination type
Conversion technique
Java.lang.Object
Java.lang.String
Assign to the interned literal String a€oeundefineda€
Other
None available
JavaScript type: Boolean
Java destination type
Conversion technique
boolean
Map true/false directly to Java equivalent
Java.lang.Object
Java.lang.Boolean
Construct an instance of Java.lang.Boolean18
Java.lang.String
Assign to the interned literal String a€oetruea€ or a€oefalsea€
Other
None available
JavaScript type: Number
Java destination type
Conversion technique
double
Map directly to Java value with no loss of precision
Java.lang.Object
Java.lang.Double
Construct an instance of Java.lang.Double with no loss of precision19
float
Round to float precision. Unrepresentably large numbers map to +/- infinity.
long
int
short
byte
char
Truncate to integral value by eliminating fractional part;
NaNs or numbers too large to be represented in the destination type result in a runtime Error.
Java.lang.String
Convert number to String according to ECMA 9.8.1, ToString() applied to Number type.
Other
None available
JavaScript type: String
Java destination type
Conversion technique
Java.lang.Object
Java.lang.String
Convert from Unicode JavaScript String to Java.lang.String.
double
float
long
int
short
byte
Convert String to Number as per ECMA 9.3.1.
Convert this result to destination type using rules in a€oeJavaScript type: Numbera€ section above.
char
For single-character Strings, result is Unicode character.
Otherwise, convert as number using rule directly above.
Other
None available
JavaScript type: Null
Java destination type
Conversion technique
Any Java class or interface type
Null
Other (including primitive types)
Convert to zero
JavaScript type: Array
Java destination type
Conversion technique
Primitive type array
Create a new Java array of the appropriate type with a length equal to that of the JS Array object. Fill in each element of the Java array by converting each element of the JS array, including undefined elements, to an equivalent Java value using these method invocation conversion rules.
If conversion is not possible for any single element of an array, the method invocation results in an error.
Note: Since the contents of the JS array are copied, side-effects made by the invoked Java method to the Java array will not be reflected in the JS array argument.
Other
See generic object conversions, below.
JavaScript type: Object
Java destination type
Conversion technique
Java.lang.String
Call the JS object’s toString() method and return the result as a Java.lang.String
double
float
long
int
short
byte
Apply the ToPrimitive operator (ECMA 9.3) to the JavaScript object with hint Number.
Then convert to the destination type using the conversion rules for Number, specified above.
Other
None available
Java to JavaScript type conversion
Java to JavaScript type conversion occurs in the following situations:
when reading a Java Field as a JavaScript property;
when returning the result of a Java Method call;
when Java arguments are passed to an Events interface call.
The supported conversions are listed in the table below. The a€oeJava source typea€ in the table refers to the declared type of the Java Field, or the declared result type of a Java Method. Where there is no conversion available, an error is generated and the attempted JavaScript operation fails with an Error. No exception is thrown in the Java-side method body and (Java-side) side-effects of the method execution are not rolled back.
Java source type
Conversion technique
double
float
long
int
short
byte
Convert to JavaScript Number
Boolean
Convert to JS boolean
Array
Java arrays are converted to a JS pseudo-Array object, with each element being converted according to these rules.
Java.lang.String
Convert to JS String20.
Other
None available
Liveness and garbage collection
Each Scriptable object remains live for the life of the corresponding VM instance21. Thus, any objects referenced by it and (in the case of CDC configurations, its ClassLoader) remain live.
Java object instances constructed as a result of argument conversion from a JavaScript method call remain live for the duration of the call and (unless otherwise referenced) become eligible for garbage collection when the method returns.
Java object instances constructed during the execution of a method invoked from JavaScript remain live while in scope but (unless otherwise referenced) become eligible for garbage collection when no longer in scope. Objects returned by such a method are converted (using the defined procedure, if any) to JavaScript and those Java objects become out of scope as soon as execution returns to JavaScript.