net.rim.device.api.script
Class Scriptable

java.lang.Object
  net.rim.device.api.script.Scriptable

Direct Known Subclasses:

ScriptableFunction, ScriptableImpl

public abstract class Scriptable
extends Object

The base class for java objects intended to be accessed from scripts. This class should be extended by objects that need to be accessed from scripts executing in a script engine. The relevant methods should be overridden to provide field, element, and/or superclass access, depending on the scripting engine being used. This class therefore represents a "pull" model scriptable object, and allows for dynamic changing of values with very little overhead. The Object values passed in and returned from the various methods on this interface should be either language-dependent primitive values, or other Scriptable objects. For ECMA-262 engines, for example, the primitive types consist of String, Integer, Double, Boolean, and Date. These will get converted to ECMA strings, numbers, boolean, and Date values. Java objects that are neither a primitive type or a Scriptable may not be correctly mapped to an object in the script environment.

Since:

BlackBerry API 5.0.0

Field Summary
static Object	UNDEFINED The object indicating an undefined value.

Method Summary
void	enumerateFields(Vector v) This method is called to enumerate the fields attached to this object.
Object	getElement(int index) Requests an indexed element from this object.
int	getElementCount() Requests the number of indexed elements in this object.
Object	getField(String name) Requests a field from this object.
Scriptable	getParent() This method is called to obtain the superclass of this object.
boolean	putElement(int index, Object value) Attempts to set an indexed element on this object.
boolean	putField(String name, Object value) Attempts to set a field on this object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNDEFINED

public static final Object UNDEFINED

The object indicating an undefined value. This may be passed in or returned from the methods in this class to indicate an undefined value if supported by the underlying script engine.

Since:

BlackBerry API 5.0.0

Method Detail

getParent

public Scriptable getParent()

This method is called to obtain the superclass of this object. For a prototype-based scripting language such as ECMA-262, this should return the prototype object. The default implementation returns null.

Returns:

The superclass of this object, or null if there is none.

Since:

BlackBerry API 5.0.0

enumerateFields

public void enumerateFields(Vector v)

This method is called to enumerate the fields attached to this object. Implementations of this method should add strings to the vector indicating the names of the enumerable fields in this object. The default implementation adds no strings.

Parameters:

v - The vector to which the names should be added. This must not be null.

Since:

BlackBerry API 5.0.0

getField

public Object getField(String name)
                throws Exception

Requests a field from this object. Implementations of this method should return the field corresponding to the name passed in, or UNDEFINED if no such field exists. The default implementation returns UNDEFINED.

Parameters:

name - The name of the field being requested. This must not be null.

Returns:

The named field in this scriptable object. This may be null.

Throws:

Exception - if an exception occurs while accessing the field. This may occur for many reasons; for instance, attemping to access a field which the caller does not have permission to access. Exceptions thrown by implementations will be converted to exceptions thrown in the script environment where possible.

Since:

BlackBerry API 5.0.0

putField

public boolean putField(String name,
                        Object value)
                 throws Exception

Attempts to set a field on this object. Implementations of this method should add/update the field requested, or return false to indicate that the field was not added/updated and that the script engine should handle it directly. This is useful in cases where the Scriptable subclass only cares about a handful of named fields, but the scripting language provides support for an arbitrary number of fields. In this case, the subclass would return true when the name parameter matches one of the special named fields, but would return false for the other names. Note that the subclass may return true even if no actual update takes place (e.g. it wishes to ignore attempts to set a known field with a read-only value). The default implementation returns false.

Parameters:

name - The name of the field being modified. This must not be null.

value - The value that the caller wishes to set as the field value. This may be null.

Returns:

true if the field mutation was handled, or false if the caller should handle it instead.

Throws:

Exception - if an exception occurs while mutating this field. This may occur for many reasons; for instance, attempting to modify a field that the caller does not have permission to modify. Exceptions thrown by implementations will be converted to exceptions in the script environment where possible.

Since:

BlackBerry API 5.0.0

getElementCount

public int getElementCount()

Requests the number of indexed elements in this object. Implementations of this method should return the number of indexed elements that are available via the getElement method. Typically, indices in the range [0, getElementCount()) provide "sane" values when passed in to the getElement method, although this is only true by convention and is not enforced anywhere. The default implementation returns 0.

Returns:

The number of indexed elements in this object.

Since:

BlackBerry API 5.0.0

getElement

public Object getElement(int index)
                  throws Exception

Requests an indexed element from this object. Implementations of this method should return the element corresponding to the index passed in, or UNDEFINED if no such element exists. The default implementation returns UNDEFINED.

Parameters:

index - The index of the element being requested. This may be any integer, including negative values.

Returns:

The indexed element in this scriptable object. This may be null.

Throws:

Exception - if an exception occurs while accessing the element. This may occur for many reasons; for instance, attemping to access an element which the caller does not have permission to access. Exceptions thrown by implementations will be converted to exceptions thrown in the script environment where possible.

Since:

BlackBerry API 5.0.0

putElement

public boolean putElement(int index,
                          Object value)
                   throws Exception

Attempts to set an indexed element on this object. Implementations of this method should add/update the element requested, or return false to indicate that the element was not added/updated and that the script engine should handle it directly. This is useful in cases where the Scriptable subclass does not care about arbitrarily-indexed elements, but the scripting language provides support for it. This behavior parallels that of putField, but for indexed element access. The default implementation returns false.

Parameters:

index - The index of the element being modified. This may be any integer, including negative values.

value - The value that the caller wishes to set as the element value. This may be null.

Returns:

true if the element mutation was handled, or false if the caller should handle it instead.

Throws:

Exception - if an exception occurs while mutating this element. This may occur for many reasons; for instance, attempting to modify an element that the caller does not have permission to modify. Exceptions thrown by implementations will be converted to exceptions in the script environment where possible.

Since:

BlackBerry API 5.0.0