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

3 Concepts

--- X3D separator bar ---

cube 3.1 Introduction and table of contents

3.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 defined in this part of ISO/IEC 19777 to the abstract definitions specified in Part 2 of ISO/IEC 19775, Scene access interface (SAI).

3.1.2 Topics

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

Table 3.1 — Topics in this clause

3.1.3 Conventions

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.

--- X3D separator bar ---

3.2 General concepts

3.2.1 Scope of specification

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.

3.2.2 Conformance

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.

3.2.3 Implementation dependencies

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.

3.2.4 Types of Java browsers

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.

--- X3D separator bar ---

cube 3.3 Language specific concepts

3.3.1 General

3.3.1.1 Introduction

This 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.

3.3.1.2 Provision of classes

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.

3.3.1.3 Required Java version

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.

3.3.1.4 Package structure

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

3.3.1.5 Robustness and error handling

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.

3.3.2 Sessions

3.3.2.1 Introduction

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.

3.3.2.2 Component

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.

3.3.2.3 Web browser plug-in

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.

3.3.3 Identifiers

3.3.3.1 Identifier equivalence

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.

3.3.3.2 Data storage

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);

3.3.3.3 Serialization

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.

3.3.4 Relative URLs

3.3.4.1 Introduction

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.

3.3.4.2 Java applications

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);

3.3.4.3 Applets

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.

3.3.4.4 Remote applications

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.

3.3.5 Field access

3.3.5.1 NULL nodes

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.

3.3.5.2 External interactions

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.

3.3.5.3 Setting MFNode fields

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.

3.3.5.4 Array representations

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.

3.3.5.5 set1Value

3.3.5.5.1 General

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.

3.3.5.5.2 Internal Interactions

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.

3.3.5.5.3 External Interactions

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.

3.3.6 Disposing of resources

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.

--- X3D separator bar ---