net.rim.device.api.script
Interface ScriptEngine

public interface ScriptEngine

This interface allows code to interact with a script engine that has been instantiated. This interface is not meant to be implemented by third-party code; implementations of ScriptEngine will be exposed by other device APIs. Additional methods may be added to this class at any time, so third-party code that attempts to implement this interface may break in future releases.

Since:

BlackBerry API 5.0.0

Method Summary
void	addExtension(String name, Object value) Injects extensions into the script engine.
Object	compileScript(String script) Compiles a script for optimized use.
Object	executeCompiledScript(Object compiledScript, Object context) Executes a compiled script.
Object	executeScript(String script, Object context) A convenience method for executing scripts.

Method Detail

addExtension

void addExtension(String name,
                  Object value)
                  throws Exception

Injects extensions into the script engine. The name parameter corresponds to the injection point, and the value parameter corresponds to the object being injected.
To provide a concrete example, imagine an user that wished to inject an object at "window.myobject". This object would have two read-only fields, "foo1" and "foo2", with values "bar1" and "bar2" respectively. The following sample code would accomplish this:

     ScriptableImpl myobj = new ScriptableImpl();
     myobj.putField( "foo1", "bar1" );
     myobj.putField( "foo2", "bar2" );
     _scriptEngine.addExtension( "window.myobject", myobj );
 

The script environment would then have access to "bar1" and "bar2" as "window.myobject.foo1" and "window.myobject.foo2" respectively.

Note: attempting to inject something to a location that is already mapped to an existing object (e.g. if "window.myobject" already existed prior to the injection above) results in undefined behavior.

Parameters:

name - The location at which the object should be injected.

value - The object to be injected. This may be of any type accepted by the script engine (see Scriptable for details), including null.

Throws:

IllegalStateException - if the ScriptEngine cannot inject the object in its current state (e.g. it has been suspended or terminated).

IllegalArgumentException - if an error occurred during the injection.

Exception

Since:

BlackBerry API 5.0.0

executeScript

Object executeScript(String script,
                     Object context)
                     throws IllegalStateException,
                            IllegalArgumentException,
                            RuntimeException

A convenience method for executing scripts. Calling executeScript( string, context ) is equivalent to calling executeCompiledScript( compileScript( script ), context ).

Throws:

IllegalStateException

IllegalArgumentException

RuntimeException

See Also:

ScriptEngine.compileScript(String), ScriptEngine.executeCompiledScript(Object,Object)

Since:

BlackBerry API 5.0.0

executeCompiledScript

Object executeCompiledScript(Object compiledScript,
                             Object context)
                             throws IllegalStateException,
                                    IllegalArgumentException,
                                    RuntimeException

Executes a compiled script.

Parameters:

compiledScript - A compiled script obtained from a previous call to compileScript.

context - A engine-specific context object. This may be null. The details of the object to pass in will be provided by the provider of the ScriptEngine interface.

Returns:

The object returned from the script. This may be null. This will be Scriptable.UNDEFINED if the script does not return a value.

Throws:

IllegalStateException - if the ScriptEngine cannot run scripts in its current state (e.g. it has been suspended or terminated).

IllegalArgumentException - if the compiledScript could not be executed, or if the context object was determined to be illegal. This exception is also thrown upon encountering uncaught script errors during execution.

RuntimeException - certain types of error thrown during script execution (e.g. DOMExceptions from failed DOM operations) will get propagated out in their original form. These error should generally be dealt with in a similar fashion to the IllegalArgumentExceptions thrown by this method, although they may provide more detailed information to diagnose the error.

Since:

BlackBerry API 5.0.0

compileScript

Object compileScript(String script)
                     throws IllegalArgumentException

Compiles a script for optimized use. The compiled script may be executed multiple times.

Parameters:

script - The script to compile. This must not be null.

Returns:

The compiled script in an opaque format. Callers should not attempt to modify this object in any way.

Throws:

IllegalArgumentException - if the script could not be compiled. This is most likely caused by syntax errors in the script.

Since:

BlackBerry API 5.0.0