Extensible 3D (X3D) language bindings
Part 2: Java
5 Type definitions
5.1 Introduction and table of contentsThe X3D Scene Authoring Interface (see 2.[I19775]) defines a set of fundamental abstract data types. This clause specifies the mapping from those data types to the data types defined in this binding. All implementation-dependent data types are defined after all implementation independent data types in each category.
See Table 5.1 for the table of contents for this clause.
Table 5.1 — Topics in this clause
The action type is dependent on the method used. Table 5.2 defines the mapping between each service, the valid action types for that service and the Java implementation of that action. Actions are mapped as method names describing the action.
Table 5.2 — SAIAction to Java implementation mapping
| Service | Action Type | Java Implementation |
|---|---|---|
| dynamicRouteHandling | Add Route | X3DExecutionContext.addRoute() |
| Delete Route | X3DExecutionContext.deleteRoute() |
|
| updateControl | Begin Update | ExternalBrowser.beginUpdate() |
| End Update | ExternalBrowser.endUpdate() |
|
| registerBrowserInterest | Add | Browser.addBrowserListener() |
| Remove | Browser.removeBrowserListener() |
|
| registerFieldInterest | Add | X3DField.addFieldEventListener() |
| Remove | X3DField.removeFieldEventListener() |
|
| shareWorld | share | ExternalBrowser.shareBrowser()
|
| unshare | ExternalBrowser.unshareBrowser() |
|
| getNode | DEF node | X3DExecutionContext.getNamedNode() |
| IMPORT node | X3DExecutionContext.getImportNode() |
|
| EXPORT node | X3DScene.getExportNode() |
|
| namedNodeHandling | add/update DEF node | X3DScene.updateNamedNode() |
| remove DEF node | X3DScene.removeNamedNode() |
|
| add/update IMPORT node | X3DScene.updateExportedNode() |
|
| remove IMPORT node | X3DScene.removeExportedNode() |
|
| add/update EXPORT node | X3DScene.updateImportedNode() |
|
| remove EXPORT node | X3DScene.removeImportedNode() |
|
| protoDeclarationHandling | add/update Proto | X3DScene.updateProtoNode() |
| remove Proto | X3DScene.removeProtoNode() |
|
| externprotoDeclarationHandling | add/update ExternProto | X3DScene.updateExternProtoNode() |
| remove ExternProto | X3DScene.removeExternProtoNode() |
|
| rootNodeHandling | add root node | X3DScene.addRootNode() |
| remove root node | X3DScene.removeRootNode() |
|
| changeViewpoint | next | Browser.nextViewpoint() |
| previous | Browser.previousViewpoint() |
|
| first | Browser.firstViewpoint() |
|
| last | Browser.lastViewpoint() |
The data type is implemented as the interface X3DComponent.
The capability to obtain a SAIBrowserRef is implemented in the getBrowser()
method which returns an instance of the ExternalBrowser class.
The data type is implemented as a java.lang.String.
The browser reference type is defined to be an instance of the Browser
interface. This is the base representation used for both internal and external
interaction. For external-only interactions, a derived
interface of the Browser class is used: ExternalBrowser.
The data type is implemented as a java.lang.String. The NULL value
is defined as the Java null primitive type.
The component declaration is represented by the ComponentInfo
class. This class presents a read-only view of a component and it's information.
The component ID is represented as two separate objects. The name of the component
is defined using java.lang.String and the level is represented
using the standard Java int primitive type.
The execution context is represented by
the X3DExecutionContext interface.
Field access is driven by the state of the field object. It shall have two methods to
determine if it is readable (isReadable()) and Writable (isWritable())
These methods shall return true if the field is readable or writable
respectively at the current state in time. Note that for a given field the
return value for a particular SAIFieldID may change over time dependent on
the current state in the life cycle.
The field declaration is represented by the class
X3DFieldDefinition class.
The field identifier is represented as an instance of the class X3DField.
For each specific X3D field type, there shall be a derived class that represents
the field type, and includes strong type checking for the values. An implementation
is not required to return the same instance of Field for every query, but
shall ensure that equivalence checking is correct through the implementation
of the equals() method.
The name of the field is implemented as a java.lang.String.
The field type may be represented in two alternative fashions.
The first alternative is provided through getType()
method provided in the X3DField class. This returns an int which
has one of the values defined by the constant types also defined in that class
as shown in Table 5.3.
Constant int values are provided and all implementations shall use these
values. This will ensure that classes compiled with one set of implementation
classes will run with all browsers as the compiler will inline these constants.
The end user is strongly advised not to use the direct numerical values,
and use only the types definitions. The types are defined in the
X3DFieldTypes
interface. If a component defines new field types then the numerical values
assigned shall not override the values already defined.
Table 5.3 — Mapping of X3D Field type to Java representation
| X3D Field type | Java representation | Value |
|---|---|---|
| SFBool | static final int SFBool |
1 |
| MFBool | static final int MFBool |
2 |
| MFColor | static final int MFColor |
25 |
| SFColor | static final int SFColor |
26 |
| MFColorRGBA | static final int MFColorRGBA |
27 |
| SFColorRGBA | static final int SFColorRGBA |
28 |
| SFDouble | static final int SFDouble |
9 |
| MFDouble | static final int MFDouble |
10 |
| SFFloat | static final int SFFloat |
7 |
| MFFloat | static final int MFFloat |
8 |
| SFImage | static final int SFImage |
29 |
| MFImage | static final int MFImage |
30 |
| SFInt32 | static final int SFInt32 |
4 |
| MFInt32 | static final int MFInt32 |
3 |
| SFLong | static final int SFLong |
5 |
| MFLong | static final int MFLong |
6 |
| SFNode | static final int SFNode |
13 |
| MFNode | static final int MFNode |
14 |
| SFRotation | static final int SFRotation |
24 |
| MFRotation | static final int MFRotation |
23 |
| SFString | static final int SFString |
31 |
| MFString | static final int MFString |
32 |
| SFTime | static final int SFTime |
11 |
| MFTime | static final int MFTime |
12 |
| SFVec2f | static final int SFVec2f |
15 |
| MFVec2f | static final int MFVec2f |
16 |
| SFVec2d | static final int SFVec2d |
17 |
| MFVec2d | static final int MFVec2d |
18 |
| SFVec3f | static final int SFVec3f |
19 |
| MFVec3f | static final int MFVec3f |
20 |
| SFVec3d | static final int SFVec3d |
21 |
| MFVec3d | static final int MFVec3d |
22 |
The second alternative is provided by the class
hierarchy. The X3DField class is derived to provide implementations
of the exact field type. These classes are defined in the same package
(org.web3d.x3d.sai) package.
The field value is defined on a per class and per field type instance. See the definitions of the individual field type classes for the exact definition of each type. As a general rule, the X3D data type maps the the equivalent Java primitive type using the mapping in Table 5.4
Table 5.4 — Mapping of X3D data types to Java primitive data types
| X3D Field Type | Java Primitive Type |
|---|---|
| Bool | boolean |
| Int32 | int |
| Long | long |
| Float, Vec2f, Vec3f, Rotation | float |
| Double, Vec2d, Vec3d | double |
| Color | float |
| String | String |
| Time | double |
| Image | int |
The data type is implemented as the Java primitive type float. A
null value is defined as the value 0.0f.
The load state is implemented as an integer primitive value. The values for each state are defined
in Table 5.5. The definitions of the values can be
found in the X3DLoadStateTypes interface.
Table 5.5 — Load state type value defintions
| State | Java Constant | Value |
|---|---|---|
| NOT_STARTED | static final int LOAD_NOT_STARTED |
1 |
| IN_PROGRESS | static final int LOAD_IN_PROGRESS |
2 |
| COMPLETE | static final int LOAD_COMPLETE |
3 |
| FAILED | static final int LOAD_FAILED |
4 |
It is strongly recommended that the end user does not use the direct int values. They should be using the defined constant types.
The data type is implemented as the Java primitive type float. A
null value is defined as the value 0.0f.
The node identifier is represented as an instance of X3DNode.
The node type is represented as a java.lang.String.
The data type is represented by the values in the Table 5.6. The table defines the services that use the data type, the method of the BrowserFactory class and the lists of argument types that method takes.
Table 5.6 — Mapping of SAIParameterList to Java parameter lists
| Service | method | Java Parameters |
|---|---|---|
| getBrowser | getBrowser() |
java.applet.Applet |
getBrowser() |
java.applet.Applet, String, int |
|
getBrowser() |
java.net.InetAddress, int |
|
| createBrowser | createVrmlComponent() |
None |
The component declaration is represented by the ProfileInfo class.
This class presents a read-only view of a profile and it's information.
The data type is implemented as an array of java.lang.String.
Key/Value pairs are represented using the java.util.Map abstract data
structure.
The proto declaration is represented by two separate interfaces - one each
for PROTO and EXTERNPROTOs. For PROTOs, the interface is
X3DProtoDeclaration. For EXTERNPROTOs the interface is
X3DExternProtoDeclaration.
The requestor ID is represented as an instance of one of two classes depending on what information is being requested.
The requestor ID is an instance of the class implementing the interface
BrowserListener when the service request is registerBrowserInterest
as specified in
6.3.20, registerBrowserInterest of ISO/IEC 19775-2 (see
2.[I19775]).
The requestor ID is an instance of the class implementing the interface
X3DEventListener when the service request is registerFieldInterest
as specified in 6.7.7 registerFieldInterest of ISO/IEC 19775-2 (see
2.[I19775]).
Routes are represented by the immutable data interface org.web3d.x3d.sai.X3DRoute.
This allows fetching of all the route information, but it may not be changed.
Browser's shall not expose to the end user extended versions of this class
that allow direct modification of the route.
This is the external, containing node representation of the script that is
passed to the script implementation class during the initialisation phase.
It shall be represented by the abstract interface type
X3DScriptNode. This represents the abstract node type as there
may be more than one script node type.
The script implementation is marked by the interface X3DScriptImplementation.
This marker interface must be present on the user class that is defined in
the URL of the Script node. If it is not present, an error shall be generated,
the URL ignored and the next URL in the list loaded.
The scene is represented by the interface X3DScene that extends
the X3DExecutionContext interface. The
scene interface holds all the methods that represent the Scene Services.
A full definition of the interface and all its methods is in
6.5 Scene Services.
The string is implemented as a java.lang.String.
The URL is implemented as a java.lang.String.
Java implementations of the errors rely on a set of derived classes based on the SAIError type.
The error type is implemented as the exception class X3DException.
This exception is in turn derived from the standard Java error type of
java.lang.RuntimeException. All exceptions (errors) defined in
this specification shall be derived from X3DException.
The error type is implemented as the exception
class NoSuchBrowserException.
The error type is implemented as the exception
class ConnectionException.
The error type is implemented as two separate dual purpose exception classes depending on their scope.
InvalidBrowserException is used to indicate that an
SAIBrowserRef has been disposed.
InvalidExecutionContextException is used to indicate that an
SAIExecutionContextID has been disposed.
InvalidNodeException
is used to indicate that an SAINodeID has been disposed.
InvalidRouteException
is used to indicate that an SAIRouteID has been disposed.
InvalidProtoException
is used to indicate that an SAIProtoDeclaration
has been disposed.
The error type is implemented as the exception class
InvalidImportException.
The error type is implemented as the exception class
InsufficientCapabilitiesException.
The error type is implemented as two separate exceptions based on the implementation
of SAINodeID and the rules defined in
Table 5.2. These classes also
derive from InvalidFieldException.
InvalidWritableFieldException
is used to indicate the named field is not accessible as a writable field when
attempting to create a route with the X3DScene.addRoute() method.
InvalidReadableFieldException
is used to indicate the named field is not accessible as a readable field when
attempting to create a route with the X3DScene.addRoute() method.
The error type is implemented as the exception class
InvalidBrowserException.
The error type is implemented as the exception class
InvalidDocumentException.
The error type is implemented as the exception class
InvalidFieldException.
Note that there are two derived classes from this class
(InvalidWritableFieldException
and InvalidReadableFieldException) that may be used at times where
this error may be generated.
The error type is expressed as different exceptions dependent on the situation.
The X3DExecutionContext.getNamedNode(),
X3DScene.getExportedNode() and
X3DExecutionContext.getImportedNode() methods use the
InvalidNodeException. When accessing fields of a node, the error is
expressed as an InvalidFieldException.
The error type is implemented as the exception
class InvalidNodeException.
The error type is implemented as the exception
class InvalidOperationTimingException.
The error type is implemented as the exception
class InvalidURLException.
The error type is implemented as the exception
class InvalidX3DException.
The error type is implemented as the exception
class NodeUnavailableException.
The error type is implemented as the exception
class NodeInUseException.
The error type is implemented as the exception
class BrowserNotSharedException.
The error type is implemented as the exception
class NotSupportedException.
The error type is implemented as the exception
class URLUnavailableException.
The Java implementation of the event handling and types is based around the Java AWT event listener model. A single event class is used to encapsulate the type of event and then parameters defining the actual event item that occurred.
All event classes are derived from java.util.EventObject.
The getSource()
method of that class is employed to return the source that generated the
event. When the event comes from a field, the return value of getSource()
may be cast to X3DField or one of its derived types. If
the event come from the browser, the source may be cast to
Browser or ExternalBrowser.
The event type is implemented in the class BrowserEvent.
Each of the individual events are expressed as actions that the event then
passes to the registered listeners. The action type of the individual event
is available through the getID() method.
The event type is implemented as
the CONNECTION_ERROR
value for the browser event ID.
The event type is implemented as the INITIALIZED
value for the browser event ID.
The event type is implemented as the SHUTDOWN
value for the browser event ID.
The event type is implemented as the URL_ERROR
value for the browser event ID.
The event type is implemented as the class X3DFieldEvent.
This class contains methods for obtaining the source of the event, the time
(in X3D time) and any user defined data that occurred with the event.