Extensible 3D (X3D) language bindings
Part 2:  Java

6 Function definitions

--- X3D separator bar ---

cube 6.1 Introduction and topics

6.1.1 Introduction

This clause describes key concepts in this part of ISO/IEC 19777. This includes conformance criteria and abstract concepts of the binding specified in this part of ISO/IEC 19777 to the abstract definitions specified in ISO/IEC 19775-2 (see 2.[19775]).

6.1.2 Topics

See Table 6.1 for the table of contents for this clause.

Table 6.1 — Topics in this clause

--- X3D separator bar ---

6.2 Browser services and connections

6.2.1 BrowserFactory

The following scenarios are possible when creating a reference to an X3D browser:

  1. Java applet to X3D plug-in in a web browser,
  2. server application talking to a browser on a separate machine, or
  3. a component in a standalone Java application.

Each of these requires a separate solution in order to maintain implementation dependence.

The method of access to an X3D browser shall be through a single factory style class. This class contains methods for each type of access. To provide implementation independence, the BrowserFactoryImpl interface for the implementation dependent parts is defined. Browsers shall subclass this interface to provide the necessary dependent code. This interface is loaded by the X3D browser factory using dynamic methods or by having the code explicitly set.

A properties file called x3d.properties, if resident in the user's CLASSPATH, shall be used to determine the name of the class to be loaded. The name of the property in the properties file shall be:

org.web3d.x3d.sai.factory.class

which shall be set to the fully qualified name of the browser factory class implementation to be loaded. The implementation of this class shall not reside within the org.web3d.* class hierarchy but shall reside in the browser writer's own class hierarchy. The browser factory shall also contain a setBrowserFactoryImpl() method to allow an explicit setting of the factory implementation. If this method is the first method called of all the factory methods, it shall be used as the factory implementation. If any other method is called prior to calling this method, the name of the factory implementation shall be drawn from the properties file and loaded. Any attempt to call the set implementation method shall result in a X3DException being generated.

The factory implementation shall return the appropriate subclasses for each of the methods. If the implementation does not support the particular connection requested, it shall generate a NotSupportedException. If it is supported, it shall return the appropriate subclass of the object for that method.

6.2.2 getBrowser

6.2.2.1 Web plug-in browser

ExternalBrowser BrowserFactory.getBrowser(Applet)
    throws NotSupportedException,
           NoSuchBrowserException,
           ConnectionException

ExternalBrowser BrowserFactory.getBrowser(Applet, String, int)
    throws NotSupportedException,
           NoSuchBrowserException,
           ConnectionException

A browser that operates as part of a web browser requires a number of different parameters for correct determination of the plug-in to access. Due to the nature of web pages, it is possible that an applet on one page may access either more that one X3D plug-in or that the plug-in exists in another HTML frame. The applet form of the getBrowser() method requires a reference to the accessing applet, the name of the frame and the index of the frame in the nominated frame. The frame name is a string representing the name of the frame. The index is the number of the X3D browser in the page (where there might be more than one) starting from 0.

6.2.2.2 Remote browser

ExternalBrowser BrowserFactory.getBrowser(java.net.InetAddress, int)
    throws NotSupportedException,
           NoSuchBrowserException,
           java.net.UnknownHostException,
           ConnectionException

An application server may wish to access browsers on client machines. The third variant of the getBrowser request requires an IP address (or machine name) and a port number. The server application requests the browser reference of the remote machine. Once the browser reference is returned, the server application may manipulate the browser contents like any other SAI using application.

The port number of the protocol may be any port number. There is no defined default port to which a browser will listen. The protocol between the application and the browser is also not defined.

6.2.3 createBrowser

X3DComponent BrowserFactory.createX3DComponent(java.util.Map)
    throws NotSupportedException

The component browser is required to fit into the standard java.awt.Component model and is implemented as a subclass of X3DComponent. It shall derive from java.awt.Component and also provide a getBrowser() method that returns a reference to a standard Browser object. The component implementation may implement the component in any manner it requires. Both lightweight components (all rendering performed in Java) and heavyweight components (with peer interfaces extending from java.awt.peer.ComponentPeer) are permitted. These details shall be hidden within the implementation specific classes and not accessible to the general API user.

The factory class shall include a method that generates an instance of this component class. Each call to the component shall result in a new independent instance of a X3D browser capable of running as a component. The browser shall be capable of running either within a web browser environment (e.g., Java applet window with a X3D browser in it) or in standalone applications with the restrictions appropriate to the underlying environment. It shall also use whatever hints are supported in the parameter argument passed to it. These hints are in the same form as those passed to loadURL.

--- X3D separator bar ---

6.3 Browser services

6.3.1 getName

String Browser.getName()
    throws InvalidBrowserException

The name returned is a String representing the name of the browser. If this is not supported, null shall be returned.

6.3.2 getVersion

String Browser.getVersion()
    throws InvalidBrowserException

The version returned is a String representing the version number of the browser. If this is not supported, null shall be returned.

6.3.3 getCurrentSpeed

float Browser.getCurrentSpeed()
    throws InvalidBrowserException

The speed value returned shall be a floating point number. A value of 0.0 shall be returned if currentSpeed is not supported.

6.3.4 getCurrentFrameRate

float Browser.getCurrentFrameRate()
    throws InvalidBrowserException

The frame rate value shall be a floating point number. A value of 0.0 shall be returned if currentFrameRate is not supported.

6.3.5 getSupportedProfiles

ProfileInfo[] Browser.getSupportedProfiles()
    throws InvalidBrowserException

The returned array will always contain at least one item and will be exactly the number of profiles that this browser supports.

6.3.6 getProfile

ProfileInfo Browser.getProfile(String)
    throws InvalidBrowserException,
           NotSupportedException

The profile declaration that corresponds to the named profile is returned if the browser supports that profile. If the browser does not support the profile, the NotSupportedException shall be thrown.

6.3.7 getSupportedComponents

ComponentInfo[] Browser.getSupportedComponents()
    throws InvalidBrowserException

A list of the component declarations for all components that are supported is returned with their respective support levels.

6.3.8 getComponent

ComponentInfo Browser.getComponent(String, int)
    throws InvalidBrowserException,
           NotSupportedException

The component declaration that corresponds to the named component and level is returned if the browser supports that capability. If the browser does not support the named component and the requested level, the NotSupportedException shall be thrown.

6.3.9 getExecutionContext

X3DExecutionContext Browser.getExecutionContext()
    throws InvalidBrowserException,
           InvalidOperationTimingException

If the execution context is the full scene rather than inside a PROTO instance, the X3DExecutionContext instance returned will be an instance of the derived X3DScene interface. User code may test for this using the instanceof operator.

6.3.10 createScene

X3DScene Browser.createScene(ProfileInfo, ComponentInfo[])
    throws InvalidBrowserException,
           InvalidOperationTimingException

A new, empty scene is created that represents the given profile and component collection. The profile shall always be specified and, if no supplementary components are desired, the second parameter shall be null.

6.3.11 replaceWorld

void Browser.replaceWorld(X3DScene)
    throws InvalidBrowserException,
           InvalidOperationTimingException

The world is replaced with the new scene. If the parameter is null, the existing scene is cleared and the browser is left with no scene and no activity; nothing shall be rendered.

6.3.12 importDocument

X3DScene Browser.importDocument(org.w3c.dom.Node)
    throws InvalidBrowserException,
           InvalidOperationTimingException,
           InvalidDocumentException

A document described by the standard DOM classes is converted to an X3D scene.

6.3.13 loadURL

void Browser.loadURL(String[], java.util.Map)
    throws InvalidBrowserException,
           InvalidOperationTimingException,
           InvalidURLException

The parameters shall be an array of strings for the URL list and an array of Strings for the parameters. If the browser determines that it cannot load any of the URLs passed, the browser event listener shall receive an event notifying it of an error.

If the parameters list is a zero length array or is null, the action is to replace the world in the current browser. The properties defined in Table 6.2 are standard values that shall be supported in addition to the other required values (see ISO/IEC 19775-1 9.2.4 Browser Options).

Table 6.2 — Property list for loadURL

Key Value Description of Function
replace true Replaces the entire page that browser is embedded in. If the browser is a standalone browser this shall have no effect.
false The browser shall replace the contents of the currently loaded world with the new world specified by the URL argument. The same effect as providing no value to the parameters argument.
target <frameName> The name of the frame shall be used to load the browser as the contents of the named HTML frame.

Individual browser implementations may support extra property definitions.

6.3.14 setDescription

void Browser.setDescription(String)
    throws InvalidBrowserException,
           InvalidOperationTimingException,

This service sets the description string of the browser. If the browser is running as a plug-in, this shall set the title of the page (if the containing web browser supports this). For component browsers the result shall be implementation dependent.

6.3.15 createX3DFromString

X3DScene Browser.createX3DFromString(String)
    throws InvalidBrowserException,
           InvalidX3DException,
           InvalidOperationTimingException,
           NotSupportedException

An X3DScene instance corresponding to the given string is returned. The parameter shall be a string that contains legal syntax as defined in this specification. The string may be any one of the formal encodings defined by this specification.

The header statement need not be present as the first line in the string. If the string does not contain legal X3D syntax, an InvalidX3DException shall be generated. If the encoding of the given string is not supported, the NotSupportedException shall be generated.

6.3.16 createX3DFromStream

X3DScene Browser.createX3DFromStream(java.io.InputStream)
    throws InvalidBrowserException,
           InvalidX3DException,
           InvalidOperationTimingException,
           NotSupportedException,
           java.io.IOException

An X3DScene instance corresponding to the given stream is returned. The parameter shall be an already established stream that contains legal syntax as defined in this specification. The string may be any one of the formal encodings defined by this specification.

The header statement need not be present as the first line in the stream. If the stream does not contain legal X3D syntax, an InvalidX3DException shall be generated. If the encoding of the given stream is not supported, the NotSupportedException shall be generated.

6.3.17 createX3DFromURL

X3DScene Browser.createX3DFromURL(String[])
    throws InvalidBrowserException,
           InvalidX3DException,
           InvalidOperationTimingException,
           NotSupportedException,
           java.io.IOException

The parameter list shall consist of an array of Strings describing the list of URLs. If the browser determines that it cannot load any of the URLs passed, the browser event listener shall receive an event notifying it of an error and the return value shall be null.

The header statement need not be present as the first line in the content identified by the URL. If the content identified by the URL does not contain legal X3D syntax, an InvalidX3DException shall be generated. If the encoding of the given content is not supported, the NotSupportedException shall be generated.

6.3.18 updateControl

void ExternalBrowser.beginUpdate()
    throws InvalidBrowserException

void ExternalBrowser.endUpdate()
    throws InvalidBrowserException

This service is split into two separate methods beginUpdate and endUpdate. The functionality is as described in 6.3.19, Update Control of ISO/IEC 19775-2 (see 2.[I19775]).

6.3.19 registerBrowserInterest

void Browser.addBrowserListener(BrowserListener)
    throws InvalidBrowserException

void Browser.removeBrowserListener(BrowserListener)
    throws InvalidBrowserException

Registering interest in browser events is through a browser event listener. The listener is an interface which is passed browser events when the state of the browser changes or asynchronous error messages is sent (for example, inability to load any of the requested URLs). Methods shall be provided to allow listeners to be added and removed dynamically. A separate event class shall be used to indicate the event information. This class has a predefined number of events although specific browser implementations may send more events than the defined values. The toString() method shall be overridden in this case to provide more information to the user in determining the extra event types to deal with them. Any extra event types shall not have values below the figure defined by LAST_IDENTIFIER.

The signature for BrowserListener shall be:

public interface BrowserListener extends java.util.EventListener
public void BrowserListener.browserChanged(BrowserEvent evt)

The signature for BrowserEvent shall be:

public class BrowserEvent extends java.util.EventObject
public int BrowserEvent.getID()

The Browser object that generated the event shall be the return value of the getSource() method of the base java.util.EventObject interface.

6.3.20 getRenderingProperties

java.util.Map Browser.getRenderingProperties()
    throws InvalidBrowserException,
           InvalidOperationTimingException

The map will contain key/value pairs for all the available rendering properties that may be set. A table of the standard properties is defined in Table 9.2 Browser properties of ISO/IEC 19775-1 (see 2.[I19775]). All keys shall be java.lang.String instances that name the property. Values may be of the Java class wrapper type representing the primitive value. For example, numerical values will be returned as instances of java.lang.Number.

If the property does not exist in the table, it shall be interpreted as not being supported by the browser implementation.

The map shall be immutable. It shall be an error for the user to attempt to insert or change the existing properties.

6.3.21 getBrowserProperties

java.util.Map Browser.getBrowserProperties()
    throws InvalidBrowserException,
           InvalidOperationTimingException

The map will contain key/value pairs for all the available rendering properties that may be set. A table of the standard properties is defined in Table 9.2 Browser properties of ISO/IEC 19775-1 (see 2.[I19775]). All keys shall be java.lang.String instances that name the property. Values may be of the Java class wrapper type representing the primitive value. For example, numerical values will be returned as instances of java.lang.Number.

Where the properties represents the extensions of the browser interface available, the key shall be the SAI extension name, and the value will be a java.lang.Boolean representing true or false values. If the browser supports the extended interface, there shall be an entry with a true value. If an entry has a false value, or there is no entry at all for the named extension, then that shall be treated as the browser not supporting that extension.

The map shall be immutable. It shall be an error for the user to attempt to insert or change the existing properties.

6.3.22 changeViewpoint

void Browser.nextViewpoint()
    throws InvalidBrowserException

void Browser.previousViewpoint()
    throws InvalidBrowserException

void Browser.firstViewpoint()
    throws InvalidBrowserException

void Browser.lastViewpoint()
    throws InvalidBrowserException

Change the viewpoint to the position given. All details are in accordance with the actions defined for this service request.

6.3.23 print

void Browser.print(Object)
    throws InvalidBrowserException

void Browser.println(Object)
    throws InvalidBrowserException

Print information directly to the console of the browser. The browser has the option of redirecting the System.out and System.err InputStreams to wherever considered appropriate, but shall always have these two methods print directly to the console. Note that the definition provided expands slightly on the abstract requirements which is just for a java.lang.String. Since java.lang.Object is the base object type for all types in Java, including strings, the conformance requirements are already met.

6.3.24 dispose

void Browser.dispose()
    throws InvalidOperationTimingException

Dispose shall notify the browser that the Java implementation is no longer interested in the X3D browser. Any further requests to methods of this instance of the browser interface shall generate an InvalidBrowserException.

--- X3D separator bar ---

6.4 Execution context services

6.4.1 getSpecificationVersion

String X3DExecutionContext.getSpecificationVersion()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The string shall represent the basic specification version used by the parsed file in decimal format. For example, a scene conforming to this specification will return the value "3.0".

6.4.2 getEncoding

int X3DExecutionContext.getEncoding()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The encoding constant is defined as a constant that is part of the X3DExecutionContext interface. The values for these are defined in Table 6.3.

Table 6.3 — Constants describing the encoding for current scene

Encoding Java Constant Value Comment
NO_SCENE static final int NO_SCENE 0 There is no scene defined. This value should never be seen directly.
SCRIPTED_ENCODING static final int SCRIPTED_ENCODING
1 The scene was created dynamically through scripting calls.
ASCII_ENCODING static final int ASCII_ENCODING
2 The scene described an original VRML 1.0 encoding.
CLASSIC_VRML_ENCODING static final int CLASSIC_VRML_ENCODING 3 The scene is encoded using the Classic VRML encoding. The scene may be VRML 97 or this specification.
XML_ENCODING static final int XML_ENCODING
4 The scene was encoding using the XML file format.
BINARY_ENCODING static final int BINARY_ENCODING
5 The scene was encoded using the binary format specified in ISO/IEC 19776-3.  It shall be an error to use this value to describe a browser-specific proprietary binary format.
BIFS_ENCODING static final int BIFS_ENCODING
6 The scene was encoded using the MPEG4 BIFS encoding.
LAST_STD_ENCODING static final int LAST_STD_ENCODING
100 A definition of the last constant used by the standard encodings. A browser is permitted to allow other, proprietary encoding mechanisms, and therefore any constant used to describe that shall use a value greater than this number. Code using these values shall not expect to be transportable across multiple browser implementations.

6.4.3 getProfile

ProfileInfo X3DExecutionContext.getProfile()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The profile declaration as defined for this scene is returned.

6.4.4 getComponents

ComponentInfo[] X3DExecutionContext.getComponents()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

A listing of the explicit components declared in this scene is returned. If the scene does not have any extra components declared, this function shall return null.

6.4.5 getWorldURL

String X3DExecutionContext.getWorldURL()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The URL used to specify the current scene is returned. The world URL shall be a string indicating the complete world URL as defined in 6.4.5, getWorldURL of ISO/IEC 19775-2 (see 2.[I19775]).

6.4.6 getNode

X3DNode X3DExecutionContext.getNamedNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           NodeNotAvailableException,
           InvalidNameException

X3DNode X3DExecutionContext.getImportedNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           NodeNotAvailableException,
           InvalidNameException

The return value is a Node reference. The parameter is a String defining the DEF name of the required node. If the browser cannot find the node name, an InvalidNodeException shall be generated.

6.4.7 createNode

X3DNode X3DExecutionContext.createNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

The return value is a X3DNode reference if it is part of the currently set profile. If the node is not available in the current profile and components, the browser shall generate InvalidNameException.

6.4.8 createProto

X3DProtoInstance X3DExecutionContext.createProto(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

The return value is a proto instance reference if it can be found using the name spacing rule for protos. If the proto name cannot be found, the browser shall generate InvalidNameException.

6.4.9 namedNodeHandling

void X3DExecutionContext.updateNamedNode(String, X3DNode)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException,
           ImportedNodeException

void X3DExecutionContext.updateImportedNode(String, String, X3DNode)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException,
           ImportedNodeException


void X3DExecutionContext.removeNamedNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

void X3DExecutionContext.removeImportedNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

Separate method signatures are defined for each of the operation types. This allows for strong type safety.

6.4.10 getProtoDeclaration

X3DProtoDeclaration X3DExecutionContext.getProtoDeclaration(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

6.4.11 protoDeclarationHandling

void X3DExecutionContext.updateProtoDeclaration(String, X3DProtoDeclaration)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

void X3DExecutionContext.removeProtoDeclaration(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

6.4.12 getExternprotoDeclaration

X3DExternProtoDeclaration X3DExecutionContext.getExternProtoDeclaration(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException,
           URLUnavailableException

6.4.13 externprotoDeclarationHandling

void X3DExecutionContext.updateExternProtoDeclaration(String, X3DExternProtoDeclaration)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

void X3DExecutionContext.removeExternProtoDeclaration(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

6.4.14 getRootNodes

X3DNode[] X3DExecutionContext.getRootNodes()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

Get a listing of the root nodes in the current execution context. If this context is a proto, then this will list all of the top-level nodes of the proto. The order shall be maintained as declared in the source encoding. If there are no root level nodes, this shall return null.

6.4.15 getRoutes

X3DRoute[] X3DExecutionContext.getRoutes()
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

Show the list of routes currently available in the execution context. If there are no routes the method shall return null.

6.4.16 dynamicRouteHandling

X3DRoute X3DExecutionContext.addRoute(X3DNode, String, X3DNode, String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNodeException,
           InvalidFieldException

void X3DExecutionContext.deleteRoute(X3DRoute)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

This service is split into two separate methods: addRoute and deleteRoute. They both take the same argument list. The first parameter is a Node reference that the event will leave from. The second is a String describing the name of the output-capable field. Third and forth parameters are the destination node reference and the input-capable field as a String. If either of the Node references have been disposed of, an InvalidNodeException shall be generated. If either of the nodes do not contain the nominated input-capable / output-capable fields, an InvalidWritableFieldException / InvalidReadableFieldException shall be generated appropriately.

--- X3D separator bar ---

6.5 Scene services

6.5.1 General concepts

Scene services are implemented by the X3DScene interface, which extends from the X3DExecutionContext interface. The additional methods required by the extra services are described below.

6.5.2 getMetadata

String X3DScene.getMetaData(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The string describes a metadata key and the return value shall be the metadata value previously set. If no metadata value is set, the return value is null.

6.5.3 setMetadata

void X3DScene.setMetaData(String, String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

The metadata value specified by the metadata key is set or changed to the new metadata value. The first parameter is the metadata key and the second parameter is the metadata value to use. If the metadata value is null, it shall be treated as deleting any currently set item of metadata for that metadata key.

6.5.4 getNode

X3DNode X3DScene.getExportedNode(String)
    throws InvalidExecutionContext
           InvalidOperationTimingException,
           NodeNotAvailableException,
           InvalidNameException

The return value is a Node reference. The parameter is a String defining the DEF name of the required node. If the browser cannot find the node name, an InvalidNodeException shall be generated.

6.5.5 namedNodeHandling

void X3DScene.updateExportedNode(String, String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

void X3DScene.removeExportedNode(String)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           InvalidNameException

6.5.6 rootNodeHandling

void X3DScene.addRootNode(X3DNode)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException,
           NodeInUseException,
           InsufficientCapabilitiesException

void X3DScene.removeRootNode(X3DNode)
    throws InvalidExecutionContextException,
           InvalidOperationTimingException

--- X3D separator bar ---

6.6 Node services

6.6.1 Node representation

Node services are implemented as the class X3DNode. This is a base interface to represent any node in the system. Additional interfaces that extend the base X3DNode interface are defined as part of this specification and shall be supported. The additional interfaces represent each of the abstract node types as defined in ISO/IEC 19775-1 (see 2.[I19775]). An additional capability that a browser may support is to provide interfaces that represent the individual node types. If a browser supports this capability, it shall return TRUE for the browser property CONCRETE_NODES (see 6.3.24 getBrowserProperties).

6.6.2 getTypeName

String X3DNode.getNodeName()
    throws InvalidNodeException

The getTypeName service is implemented through the getNodeName method. For a built-in node the method shall return the node's specified type name. For an instance of a PROTO, the method shall return the name of the PROTO.

6.6.3 getType

int[] X3DNode.getType()
    throws InvalidNodeException

The getType service is implemented as the method getType(). The method shall return an array of int values that represent all of the base node types of which the node is composed. For example, a Group node would return an array of length two, with the two values X3DGroupingNode and X3DBoundedObject. The definition of the int values shall be found in the X3DNodeTypes interface as constants. The constants that shall be defined in the X3DNodeTypes interface is defined in Table 6.4.

Table 6.4 — Node type constant value definitions

Abstract Node Type Java Constant Value
X3DBoundedObject static final int X3DBoundedObject 1
X3DMetadataObject static final int X3DMetadataObject 2
X3DUrlObject static final int X3DUrlObject 3
X3DAppearanceNode static final int X3DAppearanceNode 10
X3DAppearanceChildNode static final int X3DAppearanceChildNode 11
X3DMaterialNode static final int X3DMaterialNode 12
X3DTextureNode static final int X3DTextureNode 13
X3DTexture2DNode static final int X3DTexture2DNode 14
X3DTextureTransformNode static final int X3DTextureTransformNode 16
X3DTextureTransform2DNode static final int X3DTextureTransform2DNode 17
X3DGeometryNode static final int X3DGeometryNode 18
X3DGeometricPropertyNode static final int X3DGeometricPropertyNode 19
X3DParametricGeometryNode static final int X3DParametricGeometryNode 20
X3DNurbsSurfaceGeometryNode static final int X3DNurbsSurfaceGeometryNode 21
X3DColorNode static final int X3DColorNode 22
X3DCoordinateNode static final int X3DCoordinateNode 23
X3DNormalNode static final int X3DNormalNode 24
X3DTextureCoordinateNode static final int X3DTextureCoordinateNode 25
X3DFontStyleNode static final int X3DFontStyleNode 26
X3DProtoInstance static final int X3DProtoInstance 27
X3DChildNode static final int X3DChildNode 28
X3DBindableNode static final int X3DBindableNode 29
X3DBackgroundNode static final int X3DBackgroundNode 30
X3DGroupingNode static final int X3DGroupingNode 31
X3DShapeNode static final int X3DShapeNode 32
X3DInterpolatorNode static final int X3DInterpolatorNode 33
X3DLightNode static final int X3DLightNode 34
X3DScriptNode static final int X3DScriptNode 35
X3DSensorNode static final int X3DSensorNode 36
X3DEnvironmentalSensorNode static final int X3DEnvironmentalSensorNode 37
X3DKeyDeviceSensorNode static final int X3DKeyDeviceSensorNode 38
X3DNetworkSensorNode static final int X3DNetworkSensorNode 39
X3DPointingDeviceSensorNode static final int X3DPointingDeviceSensorNode 40
X3DDragSensorNode static final int X3DDragSensorNode 41
X3DTouchSensorNode static final int X3DTouchSensorNode 42
X3DSequencerNode static final int X3DSequencerNode 43
X3DTimeDependentNode static final int X3DTimeDependentNode 44
X3DSoundSourceNode static final int X3DSoundSourceNode 45
X3DTriggerNode static final int X3DTriggerNode 46
X3DInfoNode static final int X3DInfoNode 47
X3DNurbsControlCurveNode static final int X3DNurbsControlCurveNode 48

Nodes types defined as standard extension types, but not formalized as part of this specification shall start with constant value of 100. Types that are browser-specific extensions to this interface shall have a starting constant value offset of 1000.

If this node instance represents a prototype instance, this method shall return an array of length one with the value X3DProtoInstance as the value. The implementation node type shall be made available through the X3DProtoInstance.getImplementationType() method.

6.6.4 getField

X3DField X3DNode.getField(String)
    throws InvalidNodeException,
           InvalidOperationTimingException,
           InvalidFieldException

The getField service is implemented as the method getField(String), which allows access to all field types. The normal field name or with the set_ or _changed modifier may be used to describe the writable and readable fields respectively or either form may be used to access a readable and writable field.

6.6.5 getFieldDefinitions

X3DFieldDefinition[] X3DNode.getFieldDefinitions()
    throws InvalidNodeException,
           InvalidOperationTimingException,

Fetch a list of all field defintions of a node. Nodes that do not contain any fields (for example a blank PROTO) shall return null.

6.6.6 dispose

void X3DNode.dispose()
    throws InvalidOperationTimingException

Dispose shall notify the browser that the Java implementation is no longer interested in this node instance and it is free to do as required with the node representation. Any further requests to methods of this instance of the node reference shall generate an InvalidNodeException. If two separate instances of the same class represent the same node (as defined by the equals() method returning true) and one has dispose called, this shall not effect the other instance.

--- X3D separator bar ---

6.7 Field services

6.7.1 Field representation

The Java implementation of the field services does not directly follow the model outlined in 6.7, Field Services of ISO/IEC 19775-2 (see 2.[I19775]). Instead, it makes heavy use of the object-oriented nature of Java to provide directly the capabilities suggested by the services specified. All the services are implemented in the classes provided in the org.web3d.x3d.sai package.

The basic field is defined by the interface X3DField. A derived interface of this, MField is used to represent the sub set of all field types that represent multiple-values. From these base interfaces, there shall be derived interfaces for each of the appropriate field types.

The following outlines how the Java binding conforms to the requirements of the SAI.

6.7.2 getAccessType

getAccessType is represented by two methods of the X3DField interface.

boolean X3DField.isWritable()
    throws InvalidOperationTimingException,
           InvalidFieldException

boolean X3DField.isReadable()
    throws InvalidOperationTimingException,
           InvalidFieldException

These methods describe whether the field is readable or writable at the time the method is called. The values that the methods return may change over time as the lifecycle of the node changes and can be determined from Table 4.2 — Permitted field access capabilities during the node lifecycle of ISO/IEC 19775-2 (see 2.[I19775]).

6.7.3 getType

int X3DFieldDefintion.getType()
    throws InvalidFieldException

The type of an X3DField is determined by the field definition class X3DFieldDefinition and it's method getType(). The getType() method returns an identifier of the type of field that the instance of the interface represents. The list of legal type identifiers is included as public final variables in the interface X3DFieldTypes. The return value of the getType() method shall be one of these values.

6.7.4 getName

String X3DFieldDefintion.getName()
    throws InvalidFieldException

The getName service is supported through the getName() method on the X3DFieldDefinition that accompanies the given field.

6.7.5 getValue

type X3DField.getValue()
    throws InvalidOperationTimingException,
           InvalidReadableFieldException,
           InvalidFieldException

void X3DField.getValue(type)
    throws InvalidOperationTimingException,
           InvalidReadableFieldException,
           InvalidFieldException

int MField.getSize()
    throws InvalidOperationTimingException,
           InvalidReadableFieldException,
           InvalidFieldException

The getValue() method returns values in a format appropriate to the individual field type. For single valued field types, the return value of the method is used to pass values to user code. If the method returns an array of value. The implementation may reuse return value references between calls to the methods. User code should not expect to have consistent data values if it holds an array value.

For multi-valued fields derived from the base interface MField, the getSize() method provides a number which is the number of elements currently set in that field. An element is the equivalent single value type. For example:

field MFFloat [ 0.5 0.2 14]

would return a size of three, where

field MFVec3f [ 0.5 0.2 14]

would return a size of one. The corresponding getValue() field defines void as the return type. The parameter takes a user provided array of the appropriate data type (see Table 5.4 — Mapping of X3D data types to Java primitive data types) into which the values shall be copied. If the array is not of sufficient length to contain all the field values, the browser implementation shall copy as many values in as possible, starting from the zeroth element of the underlying field value.

A get1Value() method is provided for all multi-valued fields. This allows access to a single value out of the many values. When an attempt is made to access a value at an index greater than the number of items in that field, a java.lang.ArrayIndexOutOfBoundsException shall be generated. The following example shows signature of this method for setting an MFInt32 field:

void MFInt32.set1Value(int index, int value)
    throws InvalidOperationTimingException,
           InvalidFieldValueException,
           InvalidWritableFieldException,
           InvalidFieldException,
		   ArrayIndexOutOfBoundsException

The SFImage/MFImage field types shall define an additional behaviour. The getValue service will be supplemented by the getImage() method. This shall return an instance of java.awt.image.WritableRenderedImage. Typically, the concrete class will be an instance of java.awt.image.BufferedImage, but this shall not be required. User code may make use of the instanceof operator to check for this. Drawing to this image shall have no effect on the visual output or the value of the field, until the corresponding setImage() method is called. (See B.4.18 MFImage for more details)

6.7.6 setValue

void X3DField.setValue(type)
    throws InvalidOperationTimingException,
           InvalidFieldValueException,
           InvalidWritableFieldException,
           InvalidFieldException,
           ImportedNodeException

A set1Value() method is provided for MFields. This allows the ability to change a single value of a field without having to re-create the entire array of values. When an attempt is made to set a value at an index greater than the number of items in that field, a java.lang.ArrayIndexOutOfBoundsException shall be generated.

To append a value to a value to an exising multi-valued field, an append() method shall be defined. This shall place the new value on the end of the existing array and increase the size by one.

To insert a value into a given position of an existing multi-valued field, an insertValue() method shall be defined. This method shall take the index of the value to be inserted and the value. All items from the index to the end of the array shall be moved up one index value and the new value copied into the now vacant index position. The size shall be increased by one. When an attempt is made to set a value at an index greater than the number of items in that field, a java.lang.ArrayIndexOutOfBoundsException shall be generated.

To completely clear a field, a clear() method shall be defined. When this is called, all values set in the field shall be removed and the size is set to zero.

To remove an individual value from a field, a remove() method shall be defined. This shall take the index of the item to be removed. The return value shall be null. All items above the given index shall move down one position in the underlying representation.

The SFImage/MFImage field types shall define an additional behaviour. The setValue service will be supplemented by setImage() methods. These shall have the following signature:

void SFImage.setImage(java.awt.image.RenderedImage)
    throws InvalidOperationTimingException,
           InvalidFieldValueException,
           InvalidWritableFieldException,
           InvalidFieldException

void SFImage.setSubImage(java.awt.image.RenderedImage, int, int, int, int, int, int)
    throws InvalidOperationTimingException,
           InvalidFieldValueException,
           InvalidWritableFieldException,
           InvalidFieldException

The former replaces the entire image with the new image. There shall be no restrictions and shall be treated the same as the integer-based SFImage. The second form copies the image as a sub-image region to replace a portion of the current image. The integer parameters, in order, are: source image width, source image height, source image x location offset, source image y location offset, destination image x location offset and destination y location offset. The sub image set shall not resize the base image representation and therefore performs an intersection clip of the provided image. The user provided image shall be of the same format (pixel depth, pixel representation) as the original image obtained through the getImage() method.

6.7.7 registerFieldInterest

void X3DField.addFieldEventListener(X3DFieldEventListener)
    throws InvalidOperationTimingException,
           InvalidFieldException

void X3DField.removeFieldEventListener(X3DFieldEventListener)
    throws InvalidOperationTimingException,
           InvalidFieldException

This specification only requires that there shall be listeners available for readable fields. Browser implementations may also permit adding listeners to writable fields. It shall be an error to register a listener with initialize-only fields.

The signature of the X3DFieldEventListener shall be:

public interface X3DFieldEventListener extends java.util.EventListener
void X3DFieldEventListener.readableFieldChanged(X3DFieldEvent evt)

The signature of the X3DFieldEvent object shall be:

public class X3DFieldEvent extends java.util.EventObject
public double X3DFieldEvent.getTime()
public Object X3DFieldEvent.getData()

The field that caused the listener to trigger shall be made available through the getSource() method of the java.util.EventObject base class.

6.7.8 dispose

void X3DField.dispose()
    throws InvalidOperationTimingException

--- X3D separator bar ---

6.8 Route services

6.8.1 Route representation

Route services are implemented as the interface X3DRoute. This interface has four methods as defined in the remainder of this subclause.

6.8.2 getSourceNode

X3DNode X3DRoute.getSourceNode()
    throws InvalidOperationTimingException,
           InvalidRouteException

The node representation that is used at the source of the ROUTE is returned.

6.8.3 getSourceField

String X3DRoute.getSourceField()
    throws InvalidOperationTimingException,
           InvalidRouteException

The name of the source field in the source node is returned.

6.8.4 getDestinationNode

X3DNode X3DRoute.getDestinationNode()
    throws InvalidOperationTimingException,
           InvalidRouteException

The node representation that is used at the source of the ROUTE is returned.

6.8.5 getDestinationField

String X3DRoute.getDestinationField()
    throws InvalidOperationTimingException,
           InvalidRouteException

The name of the destination field in the node is returned.

6.8.6 dispose

void X3Route.dispose()
    throws InvalidOperationTimingException

--- X3D separator bar ---

6.9 Prototype services

6.9.1 isExternproto

X3DProtoDeclaration
X3DExternProtoDeclaration

Protos are represented by the specific class for the capability. This service request is implemented by using the derived class types and the Java instanceof operator.

6.9.2 createInstance

X3DProtoInstance X3DProtoDeclaration.createInstance()
    throws InvalidOperationTimingException,
           InvalidProtoException

X3DProtoInstance X3DExternProtoDeclaration.createInstance()
    throws InvalidOperationTimingException,
           InvalidRouteException,
           InvalidNodeException

Both interfaces have a createInstance() method that instantiates a new prototype instance. If the EXTERNPROTO instance has not yet been fetched, the implementation shall throw InvalidNodeException.

6.9.3 getFieldDefinitions

X3DFieldDefinition[] X3DProtoDeclaration.getFieldDefinitions()
    throws InvalidOperationTimingException,
           InvalidProtoException

X3DFieldDefinition[] X3DExternProtoDeclaration.getFieldDefinitions()
    throws InvalidOperationTimingException,
           InvalidProtoException

6.9.4 checkLoadState

int X3DExternProtoDeclaration.getLoadState()
    throws InvalidOperationTimingException,
           InvalidProtoException

The values returned by this method are defined in Table 5.5 — Load state type value defintions.

6.9.5 requestImmediateLoad

void X3DExternProtoDeclaration.loadNow()
    throws InvalidOperationTimingException,
           InvalidProtoException

6.9.6 dispose

void X3DProtoDeclaration.dispose()
    throws InvalidOperationTimingException

void X3DExternProtoDeclaration.dispose()
    throws InvalidOperationTimingException

--- X3D separator bar ---

6.10 Script content services

6.10.1 implementationMarkerInterface

Java code that is to run as a script is marked by implementing the X3DScriptImplementation interface.

void X3DScriptImplementation.setBrowser(Browser browser)
void X3DScriptImplementation.setFields(X3DScriptNode externalView, java.util.Map fields)
void X3DScriptImplementation.initialize()
void X3DScriptImplementation.eventsProcessed()
void X3DScriptImplementation.shutdown()

6.10.2 prepareEvents notification

For efficiency reasons, a derived interface is defined for scripts that wish to know about pre-"event cascade" processing.  The derived interface shall be named X3DPerFrameObserverScript and extends X3DScriptImplementation. The additional method signature shall be:

void X3DPerFrameObserverScript.prepareEvents()

--- X3D separator bar ---

6.11 Matrix services

6.11.1 Description

The matrix services are provided by two specialized classes that represent a 3x3 and 4x4 matrix. The internal implementation of these classes are not defined. When initially constructed, both matrices default to an identity matrix.

6.11.2 Matrix3

public class Matrix3 {
	public Matrix3();
	public void setIdentity();
    public void set(int row, int column)
    public float get(int row, int column)
    public void setTransform(SFVec2f translation,
                             SFVec3f rotation,
                             SFVec2f scale,
                             SFVec3f scaleOrientation,
                             SFVec2f center)
    public void getTransform(SFVec2f translation,
                             SFVec3f rotation,
                             SFVec2f scale)
    public Matrix3 inverse()
    public Matrix3 transpose()
    public Matrix3 multiplyLeft(Matrix3 mat)
    public Matrix3 multiplyRight(Matrix3 mat)
    public Matrix3 multiplyRowVector(SFVec3f vec)
    public Matrix3 multiplyColVector(SFVec3f vec)
}

6.11.3 Matrix4

public class Matrix4 {
	public Matrix4();
	public void setIdentity();
    public void set(int row, int column)
    public float get(int row, int column)
    public void setTransform(SFVec3f translation,
                             SFRotation rotation,
                             SFVec3f scale,
                             SFRotation scaleOrientation,
                             SFVec3f center)
    public void getTransform(SFVec3f translation,
                             SFRotation rotation,
                             SFVec3f scale)
    public Matrix3 inverse()
    public Matrix3 transpose()
    public Matrix3 multiplyLeft(Matrix4 mat)
    public Matrix3 multiplyRight(Matrix4 mat)
    public Matrix3 multiplyRowVector(SFVec3f vec)
    public Matrix3 multiplyColVector(SFVec3f vec)
}

--- X3D separator bar ---