WebVM bindings

Introduction

WebVM provides the means of binding application elements provided as web content (markup + script) to modules provided as Java content (typically a jar file conforming to specific Java profile requirements). In order to provide maximum flexibility, there are various forms that this binding can take; this section explains the various supported bindings and the specific requirements associated with each of them.

Binding contents

A binding defines:

Java configuration and profile(s): the APIs made available by the Java environment to the Java content, and the specific form of the Java content;
Packaging: how the Java content is packaged together with its metadata and other resources;
Provisioning: the available mechanisms for provisioning the content to the device and associated protocols and packaging implications, together with the details of how the content is referenced from within the web content;
Lifecycle model: the Java interfaces by which the library is activated and deactivated;
Persistence model: the means by which the Java content is able to store data persistently, and the rules for namespacing and controlling access to that data;
Security model: the rules by which the trustworthiness and authorisation of the content are established and the rules for enforcement of permissions in relation to security-relevant actions. The security model in general, and binding-specific details, are presented in section 3.

Terminology

Bindings differ according to how the provisioning of the Java content is handled. Thin client provisioning of the Java content refers to the situation where certain Java content (a JAR file, say) is referenced from a web page and is downloaded (for subsequent execution) within the context of that page; after leaving the page, the Java content may be discarded. (As with other assets, such as images, the browser may elect to cache the Java content in the HTTP cache, but it is eligible to be discarded at any time without reference to the user.)

Persistent installation of the Java content refers to the situation where the Java content undergoes an installation step, typically requiring explicit interactive confirmation by the user, and is expected to remain installed on the device until explicitly uninstalled or upgraded. Persistent installation is compatible with Java content that must be purchased or must undergo other one-off activation or configuration procedures. Persistent installation also enables data associated with the content (such as a record store) to be persistently stored with the content.

Generic binding mechanism

The following paragraphs describe aspects of WebVM that are common to all bindings.

General

A WebVM element is an tag that references a WebVM control (which can be in a binding-specific way).

A WebVM instance is created when a DOM node corresponding to a WebVM element is instanced (typically when the tag is a statically referenced in the markup and the document is loaded, but also in the event that a node is dynamically instanced and added to the document under script control).

The WebVM instance is destroyed when the DOM node is destroyed (typically when leaving the page but also in the event that the node is dynamically removed from the document under script control).

There is at most one VM (or isolate5) instance associated with a single WebVM instance. If there are multiple WebVM instances belonging to the same page (strictly, belonging to documents attached to the same window object) then these WebVM instances share the same VM instance.

The VM instance associated with a WebVM instance is created on the first occasion that an operation is performed (eg a method called on that WebVM instance) that requires the VM instance to exist. This allows pages to include static references to WebVM elements but only incur the overhead of instancing a VM when required.

The usual semantics apply to class statics and other VM state for classes loaded within the VM instance corresponding to a WebVM instance. In particular, class statics are shared between all WebVM instances belonging to the same scope6. All VM state is destroyed when the window.location is changed.

WebVM instance definition

A WebVM instance is defined by an OBJECT node, its attributes and its contained PARAM elements.

The following attributes are required:

Attribute name	Attribute value	Comments
type	application/x-vnd-aplix-webvm	This is the standard means of resolving the OBJECT element to the WebVM plugin. There might be alternative browser-specific means to resolve to the WebVM plugin for those cases where browser plugin handling is nonstandard.
id	A document-wide unique id string	This is required to be a unique id among all WebVM instances within the current scope.

The following PARAM entries are understood by the WebVM system (although not all are applicable in all bindings).

Param name	Param value	Comments
archive	URI containing reference to the java content for this instance.	The allowed protocols and expected contents of the archive are binding- dependent. Typically this is a reference to a .jad or .jar file.
install	One of the values “true”, “false”	Indicates whether or not the page is requesting thin client provisioning or persistent installation of the library. Handing of this PARAM is binding-specific.
launch	One of the values “true”, “false”	Indicates whether or not the WebVM instance should be launched immediately on completion of document loading. (If absent, or false, the default behaviour is to defer launch of the VM instance to the first occasion that a script calls a method on the instance.)
log	The string id of a div in the current document	Specifies the destination of log messages, typically for debugging purposes, that record errors and other significant events relating to this WebVM instance.
debug	The string id of a div in the current document	Specifies the destination of log messages, typically for debugging purposes, that record errors relating to this WebVM instance.

An OBJECT definition can optionally also include a number of PARAM tags to pass additional instance-specific data to the instance. The names and content of the various PARAMs is expected to be known by the content. PARAMs are specified using the name and value attributes as defined in the HTML5 spec. The type and valuetype attributes not supported.

These PARAM values are available to the Java runtime by calling getAppProperty on the WebVMContext. This applies to all PARAMs that are explicitly set, irrespective of whether or not they have a special significance as indicated above.

PARAM elements are required to be present at the time the WebVM instance is created (ie by the time document loading completes in the case of instances added statically in the markup, or at the time the OBJECT node is added in the case of instances added dynamically under script control. Changes (ie additions or deletions) to the PARAM set after that time are not guaranteed to be propagated through to the Java content.

WebVM Context

On the Java side, the WebVM Context (an instance of com.aplixcorp.webvm.WebVMContex t) encapsulates instance-wide data for the WebVM instance. The WebVM is constructed at the time the Java-side state for the WebVM instance is created.

The full WebVM context API is below:

public abstract interface WebVMContext {

/* get the WebVM context */

public static WebVMContext getContext();

/* get a property associated with this WebVM instance */

public String getAppProperty(String key);

/* set the scriptable object */

public void setScriptableObject(Object obj);

/* get the events object */

public Object getEventObject();

}

Scriptable object

The WebVM element is a proxy for a specific Java object instanced by the Java content: this is the scriptable object. Once instanced, the object must be registered with the WebVM Context by calling setScriptableObject. Methods called and properties set on the WebVM element are translated into the corresponding Java operation on the scriptable object. The specific mappings between the two environments are defined in section 4. The interface exposed by the scriptable object is defined by a specific interface, identified by the webvm-script-interface property in a binding-specific manner.

Events object

The WebVM instance can optionally cause a further object to be created, the event object. This enables events to be passed asynchronously from the Java content to the web application.

The event interface for a given WebVM instance is defined by the webvm-event- interface property in a binding-specific manner. If declared, the Java content can obtain the event instance by calling the getEventObject on the WebVM context. This object is of synthetic type and implements the designated event interface. The Java content generates events by calling any of the methods declared in the event interface and these are translated into events on the WebVM instance9.

VM instancing

A VM instance is created on the first occurrence of any of the following events for any of the WebVM instances in a given scope:

any attempt to call a method on the WebVM;
any attempt to get or set a property on the WebVM instance.

VM instancing proceeds by the following steps:

VM-wide phase (occurs once for each VM instance):
validation of the archive(s), verification of signature(s), determination of trust domain (binding-specific);
WebVM instance-wide phase (occurs once for each WebVM instance):
construction of the WebVM Context and associated properties and other state;
binding-specific initialisation, which results in construction of the scriptable object and registration of that object with the WebVM context;
verification that the scriptable object does indeed implement the scripting interface identified in the webvm-script-interface property.

The scriptable object is uniquely associated with a single WebVM instance. Once registered with the WebVM context, it remains live for the lifetime of the VM instance.

CLDC binding

General

The CLDC binding is the simplest available (and least capable) binding. It enables the thin client provisioning of a CLDC application and associated classes, which can then be directly instanced and executed within the context of the page. Prior installation of the CLDC application is not necessary.

This binding is invoked under the following conditions:

the archive attribute of the WebVM element definition references a valid JAR containing a CLDC application.

Java Configuration and Profiles

This binding supports CLDC (1.1 or later) plus any available optional Java profiles that are compatible with CLDC. No MIDP packages are available under this binding.

Packaging

The Java content is packaged as a CLDC application in a JAR file. The manifest MUST contain the Main-Class property declaring the name of the class whose void main(String[]) method is invoked to launch the application.

Other properties are declared by including them in the main section of the JAR manifest in accordance with the JAR specification.

The following properties are mandatory:

webvm-script-interface =
webvm-event-interface =

The WebVMContext.getAppProperty method returns all properties declared in the main section of the JAR manifest together with properties declared as PARAM elements in the WebVM instance definition. In the event of duplicate property definitions, the JAR manifest declarations take precedence.

Signed JARs are not supported in this binding. (Note, however, that the JAR may assume a trusted identity if referenced via a https URI and the server identity is validated.)

Provisioning model

The JAR is referenced directly by the archive PARAM of the element of the WebVM instance definition.

Any URI scheme can be used in the archive PARAM to specify the location of the WebVM library. Support for the http: scheme is mandatory, whereas support for all other schemes is optional.

If http: is used and the library is cached locally, the cacheing behaviour must respect any cacheing indications advertised in the HTTP response when the library is first delivered. This cacheing does not amount to “installation” of the JAR in any sense that alters the behaviour of the code.

Support for both absolute and relative URIs is mandatory, and relative URIs are treated as relative to the containing page.

The JAR and its contents are only available to pages that reference that same archive URI directly10.

Lifecycle model

In this binding, only a single WebVM instance can exist within a single window scope. An attempt to create multiple instances within a single scope will fail and cause an error to be thrown.

The Java application is started by invoking the void main(String[]) method of the main class indicated in the Main-Class property in the manifest. The implementation MAY pass the empty array or null to the main method.

Within the body of the main method, the application is expected to instance the scriptable object, get the WebVM context, and register the scriptable object by calling setScriptableObject on the WebVM context.

The CLDC VM remains live until the WebVM instance is destroyed, even if the main method returns before having created any user threads. When the WebVM instance is destroyed, the VM is forcibly terminated, irrespective of the existence of any user threads.

The WebVM context, scriptable object and event object remain live for the lifetime of the VM.

Persistence model

The CLDC binding does not support persistence, except if enabled by other JME profiles such as JSR75 or JSR179. The semantics of those profiles is unchanged in this binding. JSR75 does not support any application-local filesystem roots in this binding.

Security model

(See section 3 for a detailed explanation of the general security framework.)

The CLDC binding supports the pass-through trust model. The trusted subsystem model is not supported.

The security properties are listed in the table below.

Property	Context information	Comments
midp:		In profiles that declare MIDP permissions, those permissions become security
properties in this binding.
webvm-bind	The most reliable available identity for the archive, which is the first available of JAR signer DN, https server DN, archive URI	Governs binding of a web page to a CLDC Java application under the CLDC binding. Triggered at the time the WebVM instance is created.

Thin IMP binding

General

In this binding, Java content is presented as an IMlet under the Information Module Profile (JSR195) or the Information Module Profile “” Next Generation (JSR228). IMs are essentially “headless” MIDlets.

Two bindings are supported for IMlets “” this one is based on thin client provisioning so the IMlet can be directly instanced and executed within the context of the page. Prior installation of the IMlet is not necessary.

This binding is invoked under the following conditions:

the archive attribute of the WebVM element definition references a valid JAD or JAR containing an IMlet suite; AND
EITHER:
the install PARAM is absent;
the install PARAM is present and its value is “false”; OR
the install PARAM is present and its value is “true” but, when prompted, the user declined to install the IMlet permanently.

Java Configuration and Profiles

A WebVM implementation exposes an environment compliant with JSR228 (plus any further optional profiles that happen to be available on that device). As such, it is able to host IMlets compliant either with the IMP 1.0 (JSR195) or IMP-NG (JSR228) profiles.

The MIDP profile is NOT exposed.

Packaging

This binding supports IMlets and associated classes and metadata packaged as a JAR file in accordance with the JSR228 specification.

The archive PARAM can optionally specify a JAD or JAR file. A JAD file is not mandatory.

The JAR manifest (and JAD if present) MUST contain all mandatory MIDlet-* properties as defined in JSR228. The optional MIDlet-* properties MAY be included and, if present, are honoured in accordance with the JSR228 specification.

The following further properties are mandatory:

webvm-script-interface =
webvm-event-interface =

The WebVMContext.getAppProperty method returns all properties declared in the relevant MIDlet section of the JAR manifest together with properties declared as PARAM elements in the WebVM instance definition. In the event of duplicate (non-MIDlet-*) property definitions, the JAD/manifest declarations take precedence.

The JAR may optionally be signed using the usual MIDP JAR signing rules. (This does not grant any additional trust to the library, except to make the Distinguished Name of the library available as context information for the webvm-bind event.) It is not possible to sign the JAR without the JAD being present. (Note, however, that the JAR may assume a trusted identity if referenced via a https URI and the server identity is validated.)

Provisioning model

The JAR is referenced directly by the archive attribute of the element of the WebVM instance definition.

Any URI scheme can be used in the archive attribute to specify the location of the WebVM library. Support for the http: scheme is mandatory, whereas support for all other schemes is optional.

If http: is used and the library is cached locally, the cacheing behaviour must respect any cacheing indications advertised in the HTTP response when the library is first delivered.

Support for relative URIs is mandatory. If relative, the archive URI is treated as relative to the containing page. If a JAD is present, the JAR is located using the MIDlet-Jar-URL entry, which itself may be absolute or relative. If relative, the JAR URL is treated as being relative to the JAD (ie not the containing page).

The JAR and its contents are only available to pages that reference that same archive URI directly.

Creation of the WebVM instance corresponds to the installation trigger in the terminology of the JSR228 specification. The installation occurs prior to the instancing of the VM, and the deinstallation occurs following destruction of the VM (e.g. when leaving the page). Installation by this method is NOT considered to be “User-initiated OTA provisioning” and therefore the provisions of section 4.2 of the JSR228 specification do not apply to this installation11.

Lifecycle model

In this binding, multiple WebVM instances can exist within a single window scope.

Following creation of the VM, the implementation locates the IMlet class via the MIDlet properties in the JAR manifest and instances the MIDlet in the usual way. The startApp() method is called immediately on construction of the MIDlet instance.

Within the body of the startApp() method, the application is expected to instance the scriptable object, get the WebVM Context, and register the scriptable object by calling setScriptableObject on the WebVM Context.

The Java app can exit at any time by calling notifyDestroyed(). As is standard for the IM profile, an attempt to call System.exit() will throw an exception. When the VM is destroyed (eg on leaving the page) the destroyApp() method of the IMlet will be called with an unconditional parameter set to true.

The WebVM Context, scriptable object and event object remain live for the lifetime of the VM.

Persistence model

The IM profile supports the rms package.

In this binding, since it follows a thin provisioning model, any record stores associated with the WebVM library are destroyed when uninstalling the library, which corresponds to destruction of the VM instance. Therefore it is not possible to store data that survives a single invocation of the corresponding application.

The system-determined location of each record store depends on the record store name, the IMlet vendor and name, plus the domain name of the page invoking the IMlet. Thus multiple invocations of the same library from different web pages never share rms data unless they originate from the same domain.

Security model

The Thin IMP binding supports the pass-through trust model. The trusted subsystem model is not supported.

In this binding, the IMlet is judged to be running in the untrusted domain (whether signed or not). The IMlet MUST declare the permissions it requires in order to run in its JAR manifest in accordance with the JSR228 specification. The actual decision to permit a security-relevant action at runtime is made in accordance with WebVM permissions mechanism based on the WebVM/browser security configuration (possibly involving interactive confirmation by the user)12.

The security properties are listed in the table below.

Property

Context information

Comments

midp:

In profiles that declare MIDP permissions, those permissions become security properties in this binding.

webvm-bind

The most reliable available identity for the archive, which is the first available of JAR signer DN, https server DN, JAR URI

Governs binding of a web page to a IMP Java application under the Thin IMP binding. Triggered at the time the WebVM instance is created.

Persistent IMP binding

General

Two bindings are supported for IMlets “” this one is based on persistent installation, so an installed IMlet becomes available immediately to any web page that references it. Persistent installation allows the library to store data persistently (using the rms and possibly other profiles such as JSR75) and also allows the library to be trusted independently of the pages that load it, and hence it is able to support the “trusted subsystem” security model.

The consequence of local persistent installation is that the user must explicitly permit the application to be installed, and must be given the means to uninstall it (and any associated data). Thus, the user experience will resemble the situation on a desktop where the user must explicitly authorise the installation of a browser plugin when first encountering a content type that is unsupported by the currently available plugins. Once the library is installed, however, the user will not have to repeat the procedure when accessing any other pages that make use of the same library.

This binding is invoked under the following conditions:

the archive attribute of the WebVM element definition references a valid JAD or JAR containing an IMlet suite; AND
the install PARAM is present and its value is “true”; AND
when prompted, the user authorised the installation of the IMlet.

Once this binding is invoked, the WebVM definition and the referenced IMlet suite MUST satisfy all of the requirements of this binding in order for the binding to succeed. If the binding fails, creation of the WebVM instance fails. There is no fallback to the Thin IMP binding in the event that one or more of the conditions of this binding are not satisfied.

Java Configuration and Profiles

The MIDP profile is NOT exposed.

Packaging

This binding supports IMlets and associated classes and metadata packaged as a JAR file in accordance with the JSR228 specification. Both JAR-only and JAD+JAR provisioning are supported.

The JAR manifest and JAD MUST contain all mandatory MIDlet-* properties as defined in JSR228. The optional MIDlet-* properties MAY be included and, if present, are honoured in accordance with the JSR228 specification.

The following further properties are mandatory:

webvm-script-interface =
webvm-event-interface =

These are private properties defined by the IMlet and therefore, in accordance with the JSR228 specification, these properties can either appear in the JAD only (for an unsigned IMlet) or identically in both JAD and manifest (for a signed IMlet).

The WebVMContext.getAppProperty method returns all properties declared in the relevant MIDlet section(s) of the JAD+manifest together with properties declared as PARAM elements in the WebVM instance definition. In the event of duplicate (non-MIDlet-*) property definitions, the JAD/manifest declarations take precedence.

The JAR may optionally be signed using the usual IMP signing rules.

Provisioning model

The archive attribute of the element of the WebVM instance definition references the IMlet, either by referencing the JAD or the JAR file.

Any URI scheme can be used in the archive attribute to specify the location of either the JAD or the JAR containing the WebVM library. Support for the http: scheme is mandatory, whereas support for all other schemes is optional.

Once locally installed, any reference to the same IMlet (ie any reference to a library that has identical name, vendor and version attributes) is treated as a request to bind to the current installed library and not as a reinstall request. (There MAY, nonetheless, be an interactive means for a user to explicitly trigger reinstallation via a Discovery Application.) If the archive attribute references a JAD containing identical name, vendor and version attributes, the JAR is not re-provisioned and the properties in the referencing JAD file do not take precedence over any properties associated with the currently installed IMlet suite. If the JAD is a “stub” JAD file containing only vendor, name and version properties, and the corresponding IMlet is already installed, all properties associated with the currently installed IMlet suite remain valid. Note that this makes it possible to bind to an existing library, specifying vendor, name and version attributes only in a minimal stub JAD and encoding its contents in a data: URI.

Support for relative URIs is mandatory. If relative, the archive URI is treated as relative to the containing page. If a JAD is present, the JAR is located using the MIDlet-Jar-URL entry, which itself may be absolute or relative. If relative, the Jar URL is treated as being relative to the JAD (ie not the containing page).

On the first occasion that a given IMlet suite is referenced, loading of the page containing the reference acts as the installation trigger in the terminology of the JSR228 specification. The implementation MUST request confirmation from the user before installing the IMlet suite.

The installation occurs prior to the instancing of the VM. The IMlet remains installed unless explicitly deinstalled by the user or upgraded.

Installation by this method complies with the “User-initiated OTA provisioning” provisions of section 4.2 of the JSR228 specification.

Lifecycle model

In this binding, multiple WebVM instances can exist within a single window scope.

Within the body of the startApp() method, the application is expected to instance the scriptable object, get the WebVM context, and register the scriptable object by calling setScriptableObject on the WebVM context.

The Java app can exit at any time by calling notifyDestroyed(). As is standard for the IMP profile, an attempt to call System.exit() will throw an exception. When the VM is destroyed (eg on leaving the page) the destroyApp() method of the IMlet will be called with an unconditional parameter set to true.

The WebVM context, scriptable object and event object remain live for the lifetime of the VM.

Persistence model

The IM profile supports the rms package.

In this binding, since it follows a persistent installation model, any record stores associated with the WebVM library are retained when leaving the scope of the web page that loaded the WebVM instance. Removal of persistent data is usually possible through the MIDP AMS”™ UI and in any event is possible by explicit deinstallation of the IMlet suite.

The system-determined location of each record store defaults to creating record stores separately for each domain that references that IMlet suite. Thus, by default, the path to each record store is a unique function of the record store name, the IMlet vendor and name, plus the domain name of the page invoking the IMlet.

It is possible to override this default on a per-record-store basis (and thus allow data to be shared between multiple pages that load the same WebVM library) by including one or more of the following properties with the IMlet suite.

Property name

Value

Comments

webvm-rms-share-

Enables shared access to the named record store for all IMlets within this suite. The record store is created with a path that is not qualified by the domain name of the invoking page.

is a serial number and is handled using the same rules as for other property groups.

If the rms is created in sharing mode (using AUTHMODE_ANY), then it is shared automatically (without a domain-specific root), irrespective of any webvm-rms- share property. (That is, the standard rms sharing mode takes precedence over the webvm-specific properties.

The JSR75 FileConnection optional package is handled similarly. If a platform exposes a filesystem root that corresponds to an application-local directory, then by default this is managed on a per-domain basis but this behaviour can be overridden by inclusion of the following property.

Property name

Value

Comments

webvm-fileconnection-share-

Enables shared access to the named filesystem root store for all IMlets within this suite. The application-local directory is created with a path that is not qualified by the domain name of the invoking page.

is a serial number and is handled using the same rules as for other property groups.

Security model

The Persistent IMP binding supports the pass-through trust model and, under certain conditions, is capable of supporting the trusted subsystem model.

The IMlet suite becomes a trusted subsystem if it is signed (using the IMP-NG signing rules) and the signature is successfully verified using a valid root certificate and validation method according to the JSR228 specification.

The IMlet MUST declare the permissions it requires in order to run in its JAR manifest in accordance with the JSR228 specification.

The actual decision to permit a security-relevant action at runtime is made based on the the verified identity (ie the Distinguished Name of the signer of the library), together with the WebVM permissions mechanism based on the WebVM/browser security configuration (possibly involving interactive confirmation by the user)13.

Under the generic security model (see section 3), an IMlet suite as a trusted subsystem:

MAY declare additional security properties, which then become subject to checking under the generic WebVM permissions mechanism;
exposes an additional identity (ie the signer”™s DN) which is then used when applying rulesets under the WebVM permissions mechanism.

Permissions that are granted interactively by the user that are granted on the basis of the library”™s identity MAY, at the user”™s option, be stored persistently with the IMlet suite and avert further interactive checks for that same action by the same IMlet.

An IMlet declares new security properties by declaring one or more properties in its JAD+manifest as follows.

Property name

Value

Comments

webvm-permission-

< name of action>

Creates a new Security Property

webvm-lib:::

is a serial number and is handled using the same rules as for other property groups.

webvm-permission-bind—

[:]

Binds the Security Property defined by

webvm-permission - to calls to the indicated method on the scriptable object.

is a serial number for entries relating to webvm-permission - and is handled using the same rules as for other property groups.

The other applicable security properties are listed in the table below.

Property

Context information

Comments

midp:

In profiles that declare MIDP permissions, those permissions become security properties in this binding.

These properties may be granted to the library as a trusted subsystem on the basis of the verified identity of the library itself and WebVM permissions rulesets so that interactive permission check is not necessarily required.

webvm-bind: <vendor>:<MIDlet name>

The most reliable available identity for the archive, which is the first available of JAR signer DN, https server DN, JAR URI

Governs binding of a web page to a IMP Java application under the Thin IMP binding. Triggered at the time the WebVM instance is created.

Note that treating a library as a trusted subsystem should not cause a more restrictive policy to apply (ie granting fewer permissions) than would apply in the pass-through model. If there are no rulesets in the WebVM security configuration that match the Distinguished Name of the signer of the JAR library (or https server), then the remaining rulesets apply, as would be the case under the pass-though model.

Future bindings

For future consideration, WebVM bindings could be specified for:

CDC + Xlet14;
MIDP3 liblets15.