Extensible 3D (X3D)
Part 2: Scene access interface (SAI)
This annex provides a detailed description of how an X3D compliant application may provide support for backwards compatibility for scripting code originally designed and implemented for ISO/IEC 14772-1 Virtual Reality Modeling Language (VRML97). It is provided for backwards-compatibility purposes only and shall not be required for any browser to implement if they do not conform to part 1 of ISO/IEC 14772.
The VRML event and scripting model had a number of flaws and incompatibilities even between languages. It is strongly recommended that this annex not be implemented by browsers that do not claim to support I14772-1 Virtual Reality Modeling Language (VRML97) in addition to ISO/IEC 19775-1.
Table A.1 lists the topics for this annex.
This annex specifies the requirements for browsers that wish to conform to this specification and also support the ability to run scripts written for the programmatic interfaces and event model semantics defined in I14772-1 Virtual Reality Modeling Language (VRML97), within an X3D environment. That is, the URL in the Script node specified in 29.4.1 Script in ISO/IEC 19775-1 defines content that uses one of the interfaces defined in this part of ISO/IEC 19775.
A browser shall not be conformant to this specification if it only supports scripting interface defined in I14772-1 Virtual Reality Modeling Language (VRML97). A conformant browser to this Annex shall also support the full requirements of this part of ISO/IEC 19775 including all required language bindings.
The main difference between I14772-1 Virtual Reality Modeling Language (VRML97)and this part of ISO/IEC 19775 is the definition of the event model. I14772-1 Virtual Reality Modeling Language (VRML97) leaves many decisions up to the browser implementer and therefore a lot of Script node content can be incompatible. The major issue is dealing with the way scene graph changes are propagated when the user code writes to the field. In the Java language annex values need to be delivered immediately, yet the ECMAScript language annex said they are to be deferred until the user code has exited execution. Such incompatibilities mean supporting direct backwards compatibility is an optional-only feature.
Determination of the supported script capabilities shall follow the rules specified in 9 Networking Component in ISO/IEC 19775-1. The browser shall attempt to load the URIs in the required order, determining whether an individual script file is supported. Rejection of unsupported script types shall be based on the rules defined in the corresponding annexes of ISO/IEC 14772-2. A browser shall not preferentially support one specification over another beyond the preference order defined by the script node definition. For example, if the user content defines a ISO/IEC 14772-1 conformant script code in the url field before a ISO/IEC 19775-1 conformant script code, and the browser implementation supports backwards compatibility in a language as defined in this Annex, then the I14772-1 Virtual Reality Modeling Language (VRML97) script shall be executed.
When user content defines internal interaction code that includes I14772-1 Virtual Reality Modeling Language (VRML97)-conformant scripts and the browser implementation does not support backwards compatibility, or does not support backwards compatibility in that language, the browser shall ignore that script and move to the next item in the url listings. This is the same behaviour as not being able to locate a file or the code is not in a language supported by the browser.
I14772-1 Virtual Reality Modeling Language (VRML97) does not permit the use of read and write fields (i.e., exposedFields). The use of such fields is permitted in this part of ISO/IEC 19775. It is possible, though a highly discouraged practice, to define a scripting node with an exposedField and define the user code conformant to I14772-1 Virtual Reality Modeling Language (VRML97).
In this situation, the browser shall treat the exposedField as a separate set of eventIn, eventOut and field objects. When the exposedField is written from the event model, the user code shall be notified like a normal eventIn notification. After this point, the rules for reading and writing the value of the exposedField semantics defined in 4.8.3.8 inputOutput fields and the containing node shall be followed.
If a browser intends to support ISO/IEC 14772 backwards compatibility for the ECMAScript language in the script node, it shall do so in conformance with Annex C ECMAScript language binding in I14772-1 Virtual Reality Modeling Language (VRML97).
A browser shall determine which version of the specification is supported through the use of the protocol definition or MIME type given with the external file. No other indicators shall be used.
Browsers supporting the ECMAScript backwards compatibility shall support the use of inlined script nodes through the use of the customized protocol definition javascript. The support specified in 7 Conformance and minimum support requirements in I14772-1 Virtual Reality Modeling Language (VRML97) is required in addition to the other required protocols for the ECMAScript specification as specified in Annex C ECMAScript scripting reference in ISO/IEC 14772-1 Virtual Reality Modeling Language (VRML97). An example of the inlined script definition is:
Script {
url "javascript: function foo() { ... }"
}
The url field may contain multiple URL's referencing either a remote file or
in-line code as shown in the following example:
Script {
url [
"http://foo.com/myScript.js",
"javascript: function foo( ) { ... }"
]
}
The use of the javascript protocol shall require the browser to support the objects and semantics defined in the Annex A specification. It shall be an error for a browser that conforms to this part of ISO/IEC 19775 to support the javascript protocol with script content that uses Objects defined in Annex A of this part of ISO/IEC 19775.
The use of the ecmascript: protocol shall indicate the script conforms to Annex A of this part of ISO/IEC 19775. A browser shall not provide I14772-1 Virtual Reality Modeling Language (VRML97)-defined objects to a script that uses the ecmascript: protocol.
The MIME type for I14772-1 Virtual Reality Modeling Language (VRML97) ECMAScript source code is defined as follows:
application/javascript
For backwards compatibility with old web servers, it is recommended browsers also support the following mime type:
application/x-javascript
The use of the application/ecmascript or
application/x-ecmascript MIME types shall indicate the script
conforms to Annex A of this specification. A browser shall not provide VRML-defined
objects to a script that uses these MIME types.
If a browser intends to support I14772-1 Virtual Reality Modeling Language (VRML97) backwards compatibility for the Java language in the script node, they shall do so in conformance with Annex B Java platform scripting reference in I14772-1 Virtual Reality Modeling Language (VRML97).
As it is impossible to predetermine which set of classes and interfaces a Java
class file implements through the use of the URL protocol or MIME type, a browser
shall determine which version of the specification is supported
by examining the base class or interfaces implemented by the user code.
Determination of this may be made through the language introspection capabilities
or using the instanceof operator.
A Java script that claims to support
I14772-1 Virtual Reality Modeling Language (VRML97)
shall extend the base
class vrml.node.Script. If a script class file extends the
I14772-1 Virtual Reality Modeling Language (VRML97)
base class and implements the
org.web3d.x3d.sai.X3DScriptImplementation interface then the browser
shall use the X3D SAI semantics and execution and is not required to support
I14772-1 Virtual Reality Modeling Language (VRML97)
or objects that conform to
I14772-1 Virtual Reality Modeling Language (VRML97).
It is recommended that a browser issue a warning
when it detects such a situation.