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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.