Package org.web3d.x3d.sai

Interface X3DExecutionContext

All Known Subinterfaces:

X3DScene

All Known Implementing Classes:

BaseExecutionContext

public interface X3DExecutionContext

Abstract representation of a complete X3D scene graph.

All queries to this interface return a snapshot of the current information. If the scene graph changes while the end user has a handle to an map, the map shall not be updated to reflect the new internal state. If the end user adds something to the maps, it shall not be representing in the underlying scene.

Version:

$Revision: 1.6 $

Author:

Justin Couch

Field Summary

Fields

Modifier and Type	Field	Description
static final int	ASCII_ENCODING	VRML 1.0 ASCII encoding
static final int	BIFS_ENCODING	MPEG-4 BIFS encoding
static final int	BINARY_ENCODING	Binary encoding
static final int	LAST_STD_ENCODING	The index to use for the start of a custom encoding representation if an end user wants to build their own custom parser.
static final int	NO_SCENE	The browser currently does not contain a scene
static final int	SCRIPTED_ENCODING	The scene was built from userland code using scripting
static final int	VRML_ENCODING	VRML97 classic encoding (UTF8)
static final int	XML_ENCODING	XML encoding

Method Summary

Modifier and Type	Method	Description
X3DRoute	addRoute(X3DNode fromX3DNode, String readableField, X3DNode toX3DNode, String writableField)	Add a route in this scene.
X3DNode	createNode(String name)	Create a new node in this scene.
X3DProtoInstance	createProto(String name)	Create a new proto instance in this scene.
ComponentInfo[]	getComponents()	Get the list of all the components declared in the scene.
int	getEncoding()	Get the encoding of the original file type.
X3DExternProtoDeclaration	getExternProtoDeclaration(String name)	Get the EXTERNPROTO declaration representing the given name.
String[]	getExternProtoNames()	Get the list of EXTERNPROTOs declared in this scene.
X3DNode	getImportedNode(String name)	Get the imported node instance represented by a given name.
X3DNode	getNamedNode(String name)	Get the node instance represented by the given name.
String[]	getNamedNodes()	Get a list of the nodes that have been named with DEF or imported using the IMPORT keyword in this scene.
ProfileInfo	getProfile()	Get the name of the profile used by this scene.
X3DProtoDeclaration	getProtoDeclaration(String name)	Get the PROTO declaration representing the given name.
String[]	getProtosNames()	Get the list of ordinary PROTO's declared in this scene.
X3DNode[]	getRootNodes()	Get the list of current root nodes in the scene.
X3DRoute[]	getRoutes()	Get the list of ROUTEs in this scene.
String	getSpecificationVersion()	Get the specification version name that was used to describe this scene.
String	getWorldURL()	Get the fully qualified URL of this scene.
void	removeExternProtoDeclaration(String name)	Remove the externproto declaration registered under the given name.
void	removeImportedNode(String importName)	Remove the IMPORT statement associated with a given local import name.
void	removeNamedNode(String name)	Calling this method removes any existing mapping between a given literal name and any X3D nodes.
void	removeProtoDeclaration(String name)	Remove the proto declaration registered under the given name.
void	removeRoute(X3DRoute route)	Delete the route from this scene.
void	updateExternProtoDeclaration(String name, X3DExternProtoDeclaration externproto)	Add the EXTERNPROTO declaration representing the given name.
void	updateImportedNode(String exportedName, String importedName, X3DNode inline)	Create or modify an IMPORT from the specified inline node to a given import name.
void	updateNamedNode(String nodeName, X3DNode node)	Calling this method creates an association between a literal name and a node.
void	updateProtoDeclaration(String name, X3DProtoDeclaration proto)	Add the PROTO declaration representing the given name.

Field Details

NO_SCENE

static final int NO_SCENE

The browser currently does not contain a scene

See Also:

• Constant Field Values

SCRIPTED_ENCODING

static final int SCRIPTED_ENCODING

The scene was built from userland code using scripting

See Also:

• Constant Field Values

ASCII_ENCODING

static final int ASCII_ENCODING

VRML 1.0 ASCII encoding

See Also:

• Constant Field Values

VRML_ENCODING

static final int VRML_ENCODING

VRML97 classic encoding (UTF8)

See Also:

• Constant Field Values

XML_ENCODING

static final int XML_ENCODING

XML encoding

See Also:

• Constant Field Values

BINARY_ENCODING

static final int BINARY_ENCODING

Binary encoding

See Also:

• Constant Field Values

BIFS_ENCODING

static final int BIFS_ENCODING

MPEG-4 BIFS encoding

See Also:

• Constant Field Values

LAST_STD_ENCODING

static final int LAST_STD_ENCODING

The index to use for the start of a custom encoding representation if an end user wants to build their own custom parser.

See Also:

• Constant Field Values

Method Details

getSpecificationVersion

String getSpecificationVersion()

Get the specification version name that was used to describe this scene. The version is a string that is relative to the specification used and is in the format "X.Y" where X and Y are integer values describing major and minor versions, respectively.

Returns:

The version used for this scene

getEncoding

int getEncoding()

Get the encoding of the original file type.

Returns:

The encoding description

getProfile

ProfileInfo getProfile()

Get the name of the profile used by this scene. If the profile is not set, will return null.

Returns:

The name of the profile, or null

getComponents

ComponentInfo[] getComponents()

Get the list of all the components declared in the scene. If there were no components registered, this will return null.

Returns:

The components declared or null

getWorldURL

String getWorldURL()
            throws InvalidBrowserException

Get the fully qualified URL of this scene. This returns the entire URL including any possible arguments that might be associated with a CGI call or similar mechanism. If the world was created programmatically, this will return null.

Returns:

A string of the URL or null if not supported.

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

getRoutes

X3DRoute[] getRoutes()

Get the list of ROUTEs in this scene. This gives all of the top level routes in the scene in the order that they are declared.

Returns:

The list of ROUTE instances in this scene

addRoute

X3DRoute addRoute(X3DNode fromX3DNode,
 String readableField,
 X3DNode toX3DNode,
 String writableField)
           throws InvalidBrowserException,
InvalidReadableFieldException,
InvalidWritableFieldException,
InvalidNodeException

Add a route in this scene. The route is considered to be part of this scene regardless of whether the two end points are or not. The route will remain valid as long as both nodes are live and this scene is live. If this scene becomes invalid (eg a loadURL call is successful) then the route will no longer exist and there shall be no connection between the two nodes.

Parameters:

fromX3DNode - The source node for the route

readableField - The readable field source of the route

toX3DNode - The destination node of the route

writableField - The writable field destination of the route

Returns:

an X3DRoute between two points

Throws:

InvalidReadableFieldException - if the named readable field does not exist

InvalidWritableFieldException - if the named writable field does not exist.

InvalidNodeException - The nominated destination or source node has been disposed of

InvalidBrowserException - The dispose method has been called on this browser reference.

ConnectionException - An error occurred in the connection to the browser.

removeRoute

void removeRoute(X3DRoute route)
          throws InvalidBrowserException

Delete the route from this scene. If the route is not part of this scene an exception is generated.

Parameters:

route - The route reference to delete

Throws:

InvalidBrowserException - The dispose method has been called on this browser reference.

getProtosNames

String[] getProtosNames()

Get the list of ordinary PROTO's declared in this scene. EXTERNPROTOs are not included in this list.

Returns:

The list of proto instances in this scene

getProtoDeclaration

X3DProtoDeclaration getProtoDeclaration(String name)

Get the PROTO declaration representing the given name.

Parameters:

name - The name of the proto to fetch

Returns:

an X3DProtoDeclaration

updateProtoDeclaration

void updateProtoDeclaration(String name,
 X3DProtoDeclaration proto)

Add the PROTO declaration representing the given name. If an existing declaration for 'name' exists, it will be replaced by the new declaration.

Parameters:

name - The name to use for the declaration

proto - The declaration for the name

removeProtoDeclaration

void removeProtoDeclaration(String name)

Remove the proto declaration registered under the given name.

Parameters:

name - The name of the proto to fetch

getExternProtoNames

String[] getExternProtoNames()

Get the list of EXTERNPROTOs declared in this scene. The instances may or may not have been loaded at this point. Check with the interface declaration to see if this is the case.

Returns:

The list of EXTERNPROTO instances in this scene

getExternProtoDeclaration

X3DExternProtoDeclaration getExternProtoDeclaration(String name)

Get the EXTERNPROTO declaration representing the given name.

Parameters:

name - The name of the externproto to fetch

Returns:

and X3DExternProtoDeclaration

updateExternProtoDeclaration

void updateExternProtoDeclaration(String name,
 X3DExternProtoDeclaration externproto)

Add the EXTERNPROTO declaration representing the given name. If an existing declaration for 'name' exists, it will be replaced by the new declaration.

Parameters:

name - The name of the declaration

externproto - The declaration for the name

removeExternProtoDeclaration

void removeExternProtoDeclaration(String name)

Remove the externproto declaration registered under the given name.

Parameters:

name - The name of the externproto to fetch

getNamedNodes

String[] getNamedNodes()

Get a list of the nodes that have been named with DEF or imported using the IMPORT keyword in this scene. The map is keyed by the name string and the values are the X3DNode instances. If there are no nodes marked with DEF or IMPORT then the map will be empty.

Returns:

A map of the DEF'd nodes.

getNamedNode

X3DNode getNamedNode(String name)

Get the node instance represented by the given name.

Parameters:

name - The name of the DEF to fetch

Returns:

A node wrapper representing the node

getImportedNode

X3DNode getImportedNode(String name)

Get the imported node instance represented by a given name.

Parameters:

name - The name of the import to fetch

Returns:

A node wrapper representing the node

removeImportedNode

void removeImportedNode(String importName)

Remove the IMPORT statement associated with a given local import name. See 19777-2 6.4.9 namedNode handling.

Parameters:

importName - The local name used in the IMPORT

updateImportedNode

void updateImportedNode(String exportedName,
 String importedName,
 X3DNode inline)

Create or modify an IMPORT from the specified inline node to a given import name. If 'importName' has already been used as the local name for an import, the old value will be replaced by the new value. Otherwise the appropriate new IMPORT will be constructed. See 19777-2 6.4.9 namedNode handling

Parameters:

exportedName - The node name as exported from the inline

importedName - The name to use locally for the imported node

inline - The "DEF'd Inline" of the IMPORT (ISO 19775:2005).

updateNamedNode

void updateNamedNode(String nodeName,
 X3DNode node)

Calling this method creates an association between a literal name and a node. If there is already a mapping from a given literal name to some value, that mapping will be replaced by the new mapping. If a mapping for that literal name did not exist, one will be created. There may exist multiple literal names which map to a given X3D node.

Parameters:

nodeName - The literal name to change.

node - The node to map to.

removeNamedNode

void removeNamedNode(String name)

Calling this method removes any existing mapping between a given literal name and any X3D nodes.

Parameters:

name - The literal name of the mapping to remove.

getRootNodes

X3DNode[] getRootNodes()

Get the list of current root nodes in the scene. The array contains the items in the order they were added or declared in the initial file or added after the initial scene was created.

Returns:

The list of root nodes in the scene

createNode

X3DNode createNode(String name)

Create a new node in this scene. The node creation uses the pre-set profile and component information to ensure the validity of what the user wishes to create. If the named node is not in one of the defined profile or components then an exception is generated. This cannot be used to create nodes that are declared as protos or extern protos in this scene. You must use the proto-specific mechanisms for that.

Parameters:

name - The node's name to create

Returns:

The node pointer that represents the given name

Throws:

InvalidNodeException - The name does not represent a node in the given list of profile and components for this scene

createProto

X3DProtoInstance createProto(String name)

Create a new proto instance in this scene. The node creation uses the name space semantics to locate the appropriate proto. This may require the browser to first look in the local proto space and then walk backwards up the proto declaration spaces to find a match.

Parameters:

name - The proto's name to create

Returns:

The node pointer that represents the given proto

Throws:

InvalidNodeException - The name does not represent a known proto declaration in the available namespaces