Extensible 3D (X3D) language bindings
Part 2: Java
3 Concepts
3.1 Introduction and table of contentsThis clause describes key concepts in this part of ISO/IEC 19777. This includes conformance criteria and abstract concepts of the binding defined in this part of ISO/IEC 19777 to the abstract definitions specified in Part 2 of ISO/IEC 19775, Scene access interface (SAI).
See Table 3.1 for the table of contents for this clause.
Table 3.1 — Topics in this clause
The following type-setting conventions are used to indicate a particular meaning to the text in this document.
Table 3.2 — Type-setting Conventions in this clause
name |
Words written in monospaced font are direct description of a particular Java class, field or property. This text may also provide a link to the specific documentation (provided in javadoc style documentation) to provide greater definition of the information |
methodName() |
Indicates a particular java method call. This may be representative of the general method name (where there are overloaded versions of the method) or just the method. No arguments definitions are provided unless needed in context to define the particular method specifically. The capitalization of the method name exactly follows the name of the method |
ClassName.methodName() |
The first word indicates the name of the class and is qualified with the method name. The capitalization of the class name follows the exact naming of the class. The method argument presentation is the same as that for the plain method name. |
package.name.ClassName |
All words up to the class name represent the package definition that the class belongs to. Referred to as the fully qualified class name. The last word is the name of the class. Capitalization follows the exact definition of the class and package. |
The Java platform provides an implementation of the SAI specification. It provides a complete binding to the specification within the restrictions and implementation specific capabilities as defined in this standard. The specification provides a browser implementation independent way of accessing the browser capabilities through the Java language.
Java support is not required for a conforming implementation of the SAI. A
browser supporting a Java language interface for the SAI shall conform to 7
Conformance of Part 2 of ISO/IEC 19775-2
and shall conform to the provisions of this part of ISO/IEC 19777.
An implementation shall not modify the classes and interfaces defined in this
part of ISO/IEC 19777 with specific methods or additional methods defined by the
implementation.
Implementation dependent for the scope of this annex is defined to be the browser writer implementation of the Java classes and how they interact with the environment and the X3D browser.
The listing of the implementation of all Java classes, interfaces and exceptions used for binding to the services is provided in Annex A, Compilation Order.
A browser implementation may supplement the specification defined in this annex with further classes, exceptions and interfaces. The browser implementation shall not directly modify these classes, exceptions and interfaces, but may extend them using the standard Java language facilities, within the rules defined by 3.3.1.4, Package Structure.
A X3D browser that can be accessed through a Java API can take one of
two forms. The first form is as a plugin to a web browser. The Java code
exists as an applet and accesses the plugin. The second form is a component
that is available to be directly embedded in the Java framework.
This form will subclass the Java Component class found
in java.awt.Component.
3.3 Language specific conceptsThis specification provides a set of implementation independent base classes and interfaces (hereafter known simply as classes) that represent the possible interactions with the X3D scene through the SAI. Browser specific implementation dependencies shall to remain hidden to the general user. Where classes are declared to be abstract, it is expected that the browser specific implementation shall derive from these classes as required.
An implementation shall not modify these base classes and interfaces with their own specific methods or additional methods.
The difference between the two forms of the browser is limited to how to initially obtain the browser reference. Once this has been obtained, the services provided shall not differ. The term application is used to describe the Java code that wishes to access the X3D browser, regardless of how the initial reference to the browser was obtained.
A browser that supports the SAI Java implementation may supply the base classes as part of the distribution. The design of the classes is such that only one copy of the classes defined by this application needs to be placed on the machine although multiple copies are permitted. Implementation dependent classes need only to be supplied with the browser and accessed by setting the CLASSPATH to point to the appropriate implementation dependent classes.
It is recommended that the implementation of the classes defined by
this specification are placed in either a zip file or Java Archive (JAR
file) under the $java.home/lib/ext directory.
The minimum required version of the Java Virtual Machine and associated libraries is version 1.3 (formally known as Java 2 Version 1.3). It is recommended that browsers support version 1.4 or later to fully support built-in XML processing as part of the core libraries.
The Java bindings to the SAI shall be provided under the org.web3d.x3d.sai
package structure. All classes, interfaces and exceptions defined in this
Annex shall be assumed to be a member of this package unless explicitly stated
otherwise. General concepts such as field types, exceptions, and types that
represent the core data types shall be defined in this package.
Interfaces that represent the concrete node types shall be defined in a sub-package named after that component. The sub-package name shall be the short, formal form of the component as used in the COMPONENT statement. For example:
org.web3d.x3d.sai.group
org.web3d.x3d.sai.ext_shadow
org.web3d.x3d.sai.mybrowser_overlay
User code may generate unexpected and uncaught errors at times, particularly unchecked exceptions derived from java.lang.RuntimeException.
A browser implementation shall be aware of this and behave appropriately.
An exception generated in user code shall not be treated as fatal. The browser
shall catch the exception, optionally log it somewhere (e.g., the browser console),
and then continue as though nothing happened.
There shall be one exception to this rule. Exceptions generated during the initialization phase of the script shall be treated as fatal. The exception shall be caught, reported, the class unloaded after which the browser implementation shall move on to loading the next URL.
A session for Java based communications is dependent on the type of handle established: applet or component.
The difference between the two forms of the browser is limited to how to initially obtain the browser reference. Once this has been obtained, the services provided shall not differ. The term application is used to describe the Java code that wishes to access the X3D browser, regardless of how the initial reference to the browser was obtained.
An X3D browser is established by creating a new instance of the X3D component class. Options on the createBrowser service reference as defined in 6.2.3, createBrowser in Part 2 of ISO/IEC 19775 may be used to control the properties of the browser. For example a property can be used to ask for a SWING-based component rather than AWT, or for a software off-screen renderer rather on-screen. Definitions of the standardized properties that may be used are defined in 6.2.3, createBrowser.
A browser implementation may also add their own additional properties.
At the point where the browser object is instantiated, it contains no
scene graph. To load the initial scene the loadURL() method is
called or the user code creates a new, empty scene and populates it with nodes.
If the application has registered as a listener for browser events, it shall
receive the initialize event as specified in
Part 2 of ISO/IEC 19775.
Components that define on-screen renderers follow the normal rules for any
class derived from java.awt.Component.
It may be freely added to any container and have extra components added
that may partially or completely obscure the area of the window that is
being used to render the X3D world. At no time shall the actions of other
components that partially or complete obscure the X3D browser cause execution
of the X3D event model to suspend or complete.
Note that this allows application code to draw over the top of the X3D window
and attach any java.awt.event listener as it requires without
modifying the functionality of the X3D browser and vice versa.
When the X3D browser exists as an element embedded in a HTML page to which a Java applet has access, it shall use the underlying web browser APIs to access the plugin. The session is defined to last as long as that particular plugin instance is associated with a currently active page. A factory class shall be provided to obtain a reference to a X3D browser plugin in an implementation independent manner.
The browser shall also provide notification to the listening applications of when the world is no longer displayed on the page. When the browser is removed from visibility it shall generate a shutdown event to all registered listeners. If the browser becomes visible again an initialized event shall be generated. If a new page is loaded with a X3D browser as part of it, it will contain a different Browser reference and hence the applet will not receive any such notification of its presence.
Due to the nature of Java to native code interaction, it is possible that
two instances of a Java class may refer to the same node or field inside
the X3D scene (that is, using the == comparison will be false).
For this reason, an identifier of a node or field cannot be implied to
mean the same instance reference of the class representation. The representation
of an Identifier in Java classes is implementation dependent. However,
class instances may be checked for equivalence by calling the equals()
method of the appropriate class. Implementations of the classes shall override
the equals() method so that comparing two nodes, fields or other
classes that require an identifier will return the correct result.
In the class structure, it is possible to associate user definable data references with each field of a node and with the node itself. If one reference to a node has data associated with it, this information shall be available to all references to that node at all times. For example, if a field has data associated with it, is then disposed and a later application references that node, the data shall still remain (if that other application is Java based). There is no requirement to store this information if the node/field is no longer referenced by external applications or the internal scene graph, or if the external application is not Java based.
Within a single function call the identifier shall be identical. This ensures that the following semantics seem logical to the end user:
O1 = new SFVec3f(0, 0, 0); O2 = new SFVec3f(2, 4, 0); O1.setX(6); // O1 is (0, 6, 0) O2.setX(O1.getX()); // O2 is (2, 6, 0) myTranslationField.setValue(02). //call translation.setValue(2, 6, 0);
Java serialization may be used to either store the state of the scene graph
(for example in a database or file) or communicate between two applications/applets
interfacing with the same browser. Because serialization does not maintain
the same Java reference, calls to the equals() method shall produce
the correct result. The specification has not defined classes to be serializable.
This is implementation dependent.
Due to the different environments in which a Java-based X3D may find itself, this binding defines the following additional behaviour for Java implementations apply to processing of relative URLs.
For standalone Java applications, the current working directory is determined
by using the user.dir system property of the application. If a
RURL is passed to the browser, it shall be resolved in equivalent terms
to the following statements:
String url_base = System.getProperty("user.dir");
String complete_url = "file://" + url_base + <relative_url>;
java.net.URL url = new URL(complete_url);
The base document of the browser is considered to be the web page in which the browser is embedded if the X3D Browser does not have a X3D world loaded.
If the applet also creates a component-based X3D browser, the base document determination shall be treated in exactly the same manner as 3.3.4.2 Java applications if there is not a base world already loaded. Note that this normally will produce different base documents if an applet accesses both a plug-in and a component-based browser simultaneously.
If a browser is located remotely to the application using it (for example using an RMI implementation), the base url is considered to be the base URL of the world. If no world URL has yet been set, the appropriate action shall be either of the previous two sections depending on how the browser was started.
The Java null reference to an object shall be treated as the equivalent
of the X3D NULL value. Where an SFNode field has its value set
to null, this shall clear the field of the node reference causing
the default behaviour defined by the parent node to be used for that field.
When reading a value of an SFNode field where it is empty, the return value
shall be null.
If beginUpdate() has been called and multiple individual
setValue actions have been performed on a single field, the result when
endUpdate() is called shall be a single event with all of the
individual values set. If two calls are made to set a particular array index,
the last value written shall be used.
If beginUpdate()has not been called,
the result shall be an event that
contains the entire field value with the individual value changed.
Multiple setValue actions on the field object shall result in the equivalent
number of events being generated inside the X3D browser.
MFNodes are represented as an array of Node instances. It is possible that during the creation of the array some or all of contents may contain null references. The browser shall maintain nulls and keep them in the order. This is equivalent to saying that there is nothing to render for this index.
In MF fields, arrays are used to represent the data contained in the X3D field. Setting the value of that field with an array of length zero shall result in the contents of the field being cleared and is the equivalent of the X3D text file declaration of:
SomeNode {
MFField []
}
An empty MF field shall return an array of length zero if queried about
its value. The size() method of the MFField base
class shall return a value of 0.
Attempting to set the value of the field with null shall generate
an IllegalArgumentException.
MFField classes contain a set1Value() method for setting an individual
value in the field. The behaviour is dependent on whether the call is made
from an internal interaction or an external interaction.
Multiple set1Value() calls to the field shall result in the all
of the changes being aggregated together in a single event. This event is
propagated when the user code returns control to the browser and the browser
continues with the event cascade processing.
When the browser is processing a new event cascade all of the changes made up until this current cascade evaluation are aggregated into a single event and sent. This allows asynchronous scripts to use the set1Value() call and aggregate a collection of changes together. However, note that there is no guarantee or notification of when a browser implementation may choose to evaluate the new event cascade generated in such a circumstance and user code shall take precautions to assure their desired effect.
If beginUpdate() has been called and multiple set1Value()
methods have been called on that field, the result when endUpdate()
is called shall be a single event with all of the individual values set. If two
calls are made to set a particular array index, the last value written shall be used.
If beginUpdate()has not been called, the result shall be an event that
contains the entire field value with the individual value changed. Multiple set1Value()
calls to the field shall result in the equivalent number of events
being generated inside the X3D browser.
Of particular concern to Java implementations is the disposal of resources
used by the Java environment. The garbage collection environment creates
problems when dealing with native code implementations of the X3D browser.
An explicit dispose() method is provided with all classes
representing X3D entities so that the application can explicitly dispose of the resources
used by the browser implementation.
For safety purposes, where a class defines a dispose() method,
it shall also override the default finalize() method provided
by java.lang.Object and call the dispose() method. This
shall ensure that even if the user has not explicitly called dispose on
objects, when the object reference goes out of scope, all resources shall
be freed regardless avoiding potential memory leaks.
Once a node has had the dispose method of, method calls on the node
shall generate an InvalidNodeException.