The Javatm platform is an object-oriented, hardware and operating system independent, multi-threaded, general-purpose application environment developed by Sun Microsystems, Inc. The Java platform consists of the language, the virtual machine, and a set of core class libraries. A conforming Java platform implements all three components according to their specifications. See 2.[JAVA] for a description of the language, the virtual machine, and the three core classes java.lang, java.util, and java.io. The other core class libraries, which are not used in this annex, are described in ISO/IEC 14772-1 E.[JAPI].
For historical reasons, the Java language binding to the EAI does not
implement the full set of capabilities defined in the main specification.
It implements the minimum requirements (see 7.3
Minimum Support Requirements). Restrictions imposed by this implementation
on the services specification are noted individually in B.5
Services Binding.
| 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 docuementation) 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 capitalisation 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 capitalisation 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. Capitalisation follows the exact definition of the class and package. |
An implementation shall not modify the classes defined in this specification with their own specific methods or additional methods. The Java reflection APIs shall be used to test this aspect of conformance.
This specification does not implement the full capabilities of the EAI specification. Additional capabilites may be be provided by individual implementations but shall not form part of the standard vrml.eai or vrml.external package hierarchy and classes as defined in this specification. Any implementation dependent provision of these capabilities shall be provided under a non vrml package such as the vendor's own hierarchy. The listing of the implementation of all java classes used for binding to the services are provided in B.6 Java Class Heirarchy.
| Service | Action Type | Java Implementation |
|---|---|---|
| Dynamic Route Handling | Add Route | Browser.addRoute() |
| Delete Route | Browser.deleteRoute() | |
| Update Control | Begin Update | Browser.beginUpdate() |
| End Update | Browser.endUpdate() | |
| Register Browser Interest | Add | Browser.addBrowserListener() |
| Remove | Browser.removeBrowserListener() | |
| Register Event Interest | Add | EventOut.addVrmlEventListener() |
| Remove | EventOut.removeVrmlEventListener() |
There is a distinct difference between the access type of the underlying
field that was retrieved from the node and how it is represented by the
subclasses. A request is made of the node to access any field to be viewed
as either an eventIn (see Node.getEventIn())
or and eventOut (see Node.getEventOut()).
The node implementation then either returns the type or generates an error
condition. The acceptable conditions for succesful completion of the request
are defined in Table B.3
|
|
|||
|
|
|
||
| VRML Field Types | field |
|
|
| eventIn |
|
|
|
| eventOut |
|
|
|
| exposedField |
|
|
|
The following example illustrates the correct behaviour associated with this. The node reference has been obtained to a transform node.
same_event_in = set_translation.equals(translation_changed);
System.out.println("Checking set translation equals " +
"translation changed: " +
same_event_in);
// now check the reverse case
same_event_in = translation_changed.equals(set_translation);
System.out.println("Checking translation changed equals " +
"set translation: " +
same_event_in);
Checking set translation equals translation changed: true
Checking translation changed equals set translation: true
The first alternative is provided through getType()
method provided in the BaseField class. This returns an int which
has one of the values defined by the constant
types also defined in that class.
The second alternative is provided by the class hierarchy. The EventIn and EventOut classes are further derived to provide implementations of the exact field type. These classes are defined in the vrml.eai.field package. A list of all the classes for each field type and access type is provided in B.5.4 Field Services.
| Service | method | Java Parameters |
|---|---|---|
| getBrowser | getBrowser() | java.applet.Applet |
| getBrowser() | java.applet.Applet, String, int | |
| getBrowser() | java.net.InetAddress, int | |
| createBrowser | createVrmlComponent() | None |
The following are considered valid values (as well as permutations of the given examples):
The requestor ID is an instance of the a class implementing the interface vrml.eai.event.BrowserListener when the service request is browser_event_interest.
The requestor ID is an instance of the a class implementing the interface vrml.eai.event.VrmlEventListener when the service request is field_event_interest.
The error type is implemented as the class vrml.eai.VrmlException. 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 VrmlException.
vrml.eai.InvalidBrowserException
is used to indicate an EAIBrowserRef has been disposed
of.
vrml.eai.InvalidNodeException
is used to indicate an EAINodeID has been disposed
of.
vrml.eai.field.InvalidEventInException is used to indicate the named field is not accessable as an eventIn from the Node.getEventIn() method.
vrml.eai.field.InvalidEventOutException is used to indicate the named field is not accessable as an eventOut from the Node.getEventOut() method.
The event type is implemented in the class vrml/eai/event/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.
An implementation shall not modify these base classes 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 VRML browser, regardless of how the initial reference to the browser was obtained.
This document shall be used in combination with the class and method definitions defined in B.7 Package, Class and Method Definitions to provide the full specification of the behaviour of the Java language EAI binding. The javadoc documentation provides individual class specific information on how each class is to behave with regards to all types of inputs.
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 <JAVAHOME>/lib directory.
VRML Browsers that operate as a plugin to general purpose web browsers may support whatever version of Java that the web browser supports. In the case where the web browser does not support any java, or multiple versions, the minimum of version 1.1 shall be required.
| vrml.eai | The basic working classes for the interface to the browser and nodes. |
| vrml.eai.event | Event classes and listener interfaces |
| vrml.eai.field | Classes for accessing fields |
The classes in the following packages shall have all classes marked with the @deprecated tag.
vrml.external
vrml.external.exception
vrml.external.field
An implementation is not required to provide the backwards compatible class implementation. This specification does not define the behaviour of the backwards compatible classes apart from providing a javadoc outline of the classes.
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 VRML browser, regardless of how the initial reference to the browser was obtained.
At the point where the browser object is instantiated, it contains no scene graph. To load the initial scene the loadURL method is called. If the application has registered as a listener for browser events, it shall receive the initialize event as specified in the EAI specification.
Components 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 VRML world. At no time shall the actions of other components that partially or complete obscure the VRML browser cause execution of the VRML event model to suspend or complete.
Note that this allows application code to draw over the top of the VRML window and attach any java.awt.event listener as it requires without modifiying the functionality of the VRML browser and vice versa.
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 VRML 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.
String url_base = System.getSystemProperty("user.dir");
String complete_url = "file://" + url_base + <relative_url> ;
java.net.URL url = new URL(complete_url);
If the applet also creates a component-based VRML browser, the base document determination shall be treated in exactly the same manner as B.4.5.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 plugin and a component-based browser simultaneously.
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.
If beginUpdate has been called and multiple set1Values 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. Mutliple set1Value calls to the field shall result in the equivalent number of events being generated inside the VRML browser.
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.
Creating a reference to a VRML browser must deal with a number of different scenarios: Java applet to VRML plugin in a web browser, server application talking to a browser on a separate machine or a component in a standalone java application. Each of these requires a separate solution in order to maintain implementation dependence.
The method of access a VRML browser shall be through a single factory style class. This class contains methods for each type of access. To provide implementation independence the vrml.eai.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 vrml browser factory using dynamic methods or by having the code explicitly set.
A properties file called vrml.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
vrml.external.factory.classwhich 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 vrml.* 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 vrml.eai.VrmlException 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 vrml.eai.NotSupportedException. If it is supported, it shall return the appropriate subclass of the object for that method.
A browser that operates as part of a web browser requires a number of different parameters for correct determination of the plugin to access. Due to the nature of web pages, it is possible that an applet on one page may access either more that one VRML plugin or that the plugin exists in another HTML frame. The applet form of the get browser 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 vrml browser in the page (where there might be more than one) starting from 0.
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 then the server application may manipulate the browser contents like any other EAI 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.
The component browser is required to fit into the standard java.awt.Component model and is implemented as a subclass of vrml.eai.VrmlComponent. It shall derive from java.awt.Component and also provide a getBrowser() method that returns a reference to a standard vrml/eai/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.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 VRML browser capable of running as a component.
The browser shall be capable of running either within a web browser environment
(eg java applet window with a VRML 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.
The name returned is a String representing the name of the browser. If this is not supported, null shall be returned.
The version returned is a String representing the version number of the browser. If this is not supported, null shall be returned.
The speed value returned shall be a floating point number or 0.0 if is not supported.
The frame rate value shall be a floating point number or 0.0 if it is not supported.
The world URL shall be a string indicating the complete world URL as defined in 6.3.6 getWorldURL.
The parameter shall be an array of Node instances which shall be used to replace the currently loaded world. If one or more of the node instances have been disposed of, an IllegalArgumentException shall be generated.
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 then
the action is to replace the world in the current browser. The properties
defined in Table B.6 are standard values that shall
be supported.
This service sets the description string of the browser. If the browser is running as a plugin, this shall set the title of the page (if the containing web browser supports this). For component browsers the result shall be implementation dependent.
The parameter shall be a string that contains legal syntax as defined in ISO/IEV 14772-1. The only difference is that the file header #VRML V2.0 utf8 need not be present as the first line in the string. If the string does not contain legal VRML97 syntax, an InvalidVrmlException shall be generated. Returned is an array of the top level Nodes in the order that they are declared in the string parameter.
The parameter list shall consist of an array of Strings describing the list of URLs, a reference to a destination Node and a String which is the name of the eventIn to send the loaded URL nodes to. 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.
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 eventOut. Third and forth parameters are the destination node reference and the eventIn 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 eventIn/eventOut, an InvalidEventIn/EventOutException shall be generated appropriately.
This service is split into two separate methods beginUpdate and endUpdate. The functionality remains as described in 6.3.13 Update Control.
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 asyncrhonous error messages must be 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 must not have values below the figure defined by LAST_IDENTIFIER.
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.
Dispose shall notify the browser that the java implementation is no longer interested in the VRML browser. Any further requests to methods of this instance of the browser interface shall generate an InvalidBrowserException.
The ability to list all of the fields of a node reference and their values is not available as part of the standard implementation. It is not possible to get the name of the node. The implementation of the node services is implemented as the class vrml.eai.Node.
The 6.4.3 getType and 6.4.2 getName services are combined into a single method request getType() that returns the name of the node as a String.
6.4.4 getField service is implemented as two separate methods getEventIn() and getEventOut() which allows access to eventIns and eventOuts but not to fields. An exposedField may be accessed as either the eventIn or eventOut portion separately through these two methods. The normal field name or with the set_ modifier may be used with the getEventIn method. The normal field name or the _changed modifier may be used with the getEventOut method.
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.
The java implementation of the field services does not directly follow the model outlined in 6.5 Field Services. 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 vrml.eai.field package.
The following outlines how the Java binding conforms to the requirements of the EAI.
EventIn trans = some_transform.getEventIn("set_translation");will return an EventIn class reference. From this the implication is that the access type of this field is an eventIn.
The getType() method of vrml.eai.field.BaseField returns an identifier of the type of field that the instance of the class represents. The list of legal type identifiers is included as public final variables in the class. The return value of the getType() method shall be one of these values.
The class instance is also used as an alternative type of representation of the node type. There shall be one class for each type of VRML field, one derived from EventIn and one derived from EventOut. The class reference returned from a call to Node.getEventIn() or Node.getEventOut() shall return an instance of one of these classes respectively.
The getValue method returns values in a format appropriate to the individual field type. If the method returns an array of values then the array shall be guaranteed to be created on each call. The implementation shall not re-use return value references between calls to the methods. This is to guarantee thread-safe data integrity.
To provide similarity to ISO/IEC 14772-1 B Java platform scripting reference, a get1Value method is provided for MF 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 eventOut, a java.lang.ArrayIndexOutOfBoundsException shall be generated. Each time the getValue method is called, a new instance of the returned array shall be generated.
An alternate form of the getValue and get1Value methods shall be available for the MF eventOuts. These forms shall take arrays as parameters that can be used to write values in. See the javadoc outline of each class for proper definitions of what methods are to be provided.
To provide similarity with ISO/IEC 14772-1 B Java platform scripting reference, a set1Value method is provided for MFFields. 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 eventIn, a java.lang.ArrayIndexOutOfBoundsException shall be generated. See B.4.6.4 set1Value for other behavioural aspects of this method.
The shall be no capabilities to attach listeners to eventIns. Listening to eventOuts is available. This restriction is implemented as part of the Java API implementation which has separate classes for eventIn and eventOut representation. Where a field is declared to be an exposedField, listeners can only be attached to the eventOut portion.
Package vrml.eai +- vrml.eai.Browser +- vrml.eai.BrowserFactory +- vrml.eai.Node +- vrml.eai.BrowserFactoryImpl +- vrml.eai.VrmlComponent +- vrml.eai.VrmlException +- vrml.eai.InvalidBrowserException +- vrml.eai.InvalidVrmlException +- vrml.eai.InvalidNodeException +- vrml.eai.InvalidURLException +- vrml.eai.NoSuchBrowserException +- vrml.eai.NotSupportedException +- vrml.eai.URLUnavailableException Package vrml.eai.event +- vrml.eai.event.BrowserListener +- vrml.eai.event.BrowserEvent +- vrml.eai.event.VrmlEvent +- vrml.eai.event.VrmlEventListener Package vrml.eai.field +- vrml.eai.field.BaseField +- vrml.eai.field.EventIn | +- vrml.eai.field.EventInMFColor | +- vrml.eai.field.EventInMFFloat | +- vrml.eai.field.EventInMFInt32 | +- vrml.eai.field.EventInMFNode | +- vrml.eai.field.EventInMFRotation | +- vrml.eai.field.EventInMFString | +- vrml.eai.field.EventInMFTime | +- vrml.eai.field.EventInMFVec2f | +- vrml.eai.field.EventInMFVec3f | +- vrml.eai.field.EventInSFBool | +- vrml.eai.field.EventInSFColor | +- vrml.eai.field.EventInSFFloat | +- vrml.eai.field.EventInSFImage | +- vrml.eai.field.EventInSFInt32 | +- vrml.eai.field.EventInSFNode | +- vrml.eai.field.EventInSFRotation | +- vrml.eai.field.EventInSFString | +- vrml.eai.field.EventInSFTime | +- vrml.eai.field.EventInSFVec2f | +- vrml.eai.field.EventInSFVec3f +- vrml.eai.field.EventOut +- vrml.eai.field.EventOutMField +- vrml.eai.field.EventOutMFColor +- vrml.eai.field.EventOutMFFloat +- vrml.eai.field.EventOutMFInt32 +- vrml.eai.field.EventOutMFNode +- vrml.eai.field.EventOutMFRotation +- vrml.eai.field.EventOutMFString +- vrml.eai.field.EventOutMFTime +- vrml.eai.field.EventOutMFVec2f +- vrml.eai.field.EventOutMFVec3f +- vrml.eai.field.EventOutSFBool +- vrml.eai.field.EventOutSFColor +- vrml.eai.field.EventOutSFFloat +- vrml.eai.field.EventOutSFInt32 +- vrml.eai.field.EventOutSFNode +- vrml.eai.field.EventOutSFRotation +- vrml.eai.field.EventOutSFString +- vrml.eai.field.EventOutSFTime +- vrml.eai.field.EventOutSFVec2f +- vrml.eai.field.EventOutSFVec3f +- vrml.eai.VrmlException +- vrml.eai.field.FieldException +- vrml.eai.field.InvalidEventInException +- vrml.eai.field.InvalidEventOutException
http://www.vrml.org/Specifications/VRML97/part2/javaBind.html