org.web3d.vrml.nodes
Interface VRMLScriptNodeType

All Superinterfaces:

FrameStateListener, VRMLChildNodeType, VRMLExternalNodeType, VRMLNode, VRMLNodeType, VRMLSingleExternalNodeType, VRMLWorldRootChildNodeType

public interface VRMLScriptNodeType
extends VRMLChildNodeType, VRMLSingleExternalNodeType

Shell representation of a script node.

The script is different to all the other nodes. While it represents a script, it doesn't have the normal content of a node. This will be an interface to interact between the script and an external scripting engine. Quite how we are going to do this remains an interesting thing to consider.

When implementing this interface, the coder must be aware of how scripts fit into the larger event model picture. A script cannot act just on the content alone. It has certain other notification responsibilities that require extra hoops to be jumped through. In particular, there are the following requirements:

• A script does not call initialize() immediately that the content is set. It must wait for the appropriate call as the timing of this is defined by the event model specification.
• When a setUrl() call is made where there is already content set, the implementation should not call shutdown or delete the reference to the user script code. It must wait for the appropriate external call.
• When the node is being deleted from the scene graph, it will be told when to call shutdown on the nodes. It should not override the updateRefCount() method to determine when to do it.

Version:

$Revision: 1.14 $

Author:

Justin Couch

Field Summary

Fields inherited from interface org.web3d.vrml.nodes.VRMLExternalNodeType

LOAD_COMPLETE, LOAD_FAILED, LOADING, NOT_LOADED

Method Summary

int	appendField(VRMLFieldDeclaration field) Append a field declaration to this node.
void	eventsProcessed() Notification by the route manager that an event cascade is complete.
java.util.List	getAllFields() Make a listing of all fields that are currently registered in this node.
VRMLExecutionSpace	getExecutionSpace() Get the execution space that this script is operating under.
int	getFieldCount() Get the count of the number of fields currently registered.
void	initialize(double timestamp) Notification that the script can now call the initialize() method on the user script code.
void	prepareEvents(double timestamp) Notification to call the prepare-events for scripts at the start of the timestamp.
void	processEvents() Notification by the route manager that an event cascade is complete.
void	setExecutionSpace(VRMLExecutionSpace space) Set the execution space to be this new value.
void	shutdown() Call shutdown on the user content now.
void	shutdownAll() Completely shutdown this script node.

Methods inherited from interface org.web3d.vrml.nodes.VRMLNodeType

addNodeListener, clearRemovedLayerIds, getFieldValue, getLayerIds, getMetadataObject, getRefCount, getRemovedLayerIds, hasFieldChanged, isSetupFinished, notifyExternProtoLoaded, removeNodeListener, sendRoute, setDEF, setFrameStateManager, setMetadataObject, setupFinished, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, updateRefCount

Methods inherited from interface org.web3d.vrml.lang.VRMLNode

getFieldDeclaration, getFieldIndex, getNodeFieldIndices, getNumFields, getPrimaryType, getSecondaryType, getUserData, getVRMLNodeName, isDEF, setErrorReporter, setUserData, setVersion

Methods inherited from interface org.web3d.vrml.nodes.FrameStateListener

allEventsComplete

Methods inherited from interface org.web3d.vrml.nodes.VRMLSingleExternalNodeType

checkValidContentType, getLoadState, getUrl, setContent, setLoadedURI, setLoadState, setUrl

Methods inherited from interface org.web3d.vrml.nodes.VRMLExternalNodeType

addContentStateListener, addUrlListener, getWorldUrl, removeContentStateListener, removeUrlListener, setWorldUrl

Method Detail

getFieldCount

int getFieldCount()

Get the count of the number of fields currently registered.

Returns:

The number of fields available

appendField

int appendField(VRMLFieldDeclaration field)
                throws FieldExistsException

Append a field declaration to this node. This is added to the current list on the end. If the field already exists with the given name but different values exception will be generated. If the field has exactly the same signature it will silently ignore the request.

Parameters:

field - The new field to add

Returns:

The index that this field was added at

Throws:

FieldExistsException - A conflicting field of the same name already exists for this node

getAllFields

java.util.List getAllFields()

Make a listing of all fields that are currently registered in this node. The list contains instances of VRMLFieldDeclaration.

Returns:

A list of the current field declarations

setExecutionSpace

void setExecutionSpace(VRMLExecutionSpace space)

Set the execution space to be this new value. Usually set at some time after the initial loading of the class, but before content is set. A value of null will clear the current space.

Parameters:

space - The space that this script is operating in

getExecutionSpace

VRMLExecutionSpace getExecutionSpace()

Get the execution space that this script is operating under. If there is none, this will return null.

Returns:

The current execution space or null

prepareEvents

void prepareEvents(double timestamp)

Notification to call the prepare-events for scripts at the start of the timestamp. For scripts that are in an X3D world, this will also call the prepareEvents SAI service. This method will be called every frame.

Parameters:

timestamp - The time of the current frame in VRML time

processEvents

void processEvents()

Notification by the route manager that an event cascade is complete. This should allow the underlying scripting engine to call processEvents() (or equivalent) on the script code.

eventsProcessed

void eventsProcessed()

Notification by the route manager that an event cascade is complete. This should allow the underlying scripting engine to call eventsProcessed() on the script code.

initialize

void initialize(double timestamp)

Notification that the script can now call the initialize() method on the user script code. If this is called accidentally when there is no user code set, silently ignore the request.

Parameters:

timestamp - The VRML time that the initialisation occured at

shutdown

void shutdown()

Call shutdown on the user content now. It will no longer be needed. This does not shut down the entire node. It is assumed that content will be forcoming shortly.

shutdownAll

void shutdownAll()

Completely shutdown this script node. There's no life left in this one so might as well clean up everything. The user code shutdown will be guaranteed to be called before this method.