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 (VRML) Functional specification and UTF-8 encoding. 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 ISO/IEC 14772-1 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 ISO/IEC 14772-1, 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 ISO/IEC 14772-1. 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 ISO/IEC 14772-1 and this part of ISO/IEC 19775 is the definition of the event model. ISO/IEC 14772-1 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 ISO/IEC 14772-1 script shall be executed.
When user content defines internal interaction code that includes ISO/IEC 14772-1-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.
ISO/IEC 14772-1 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 ISO/IEC 14772-1.
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 ISO/IEC 14772-1.
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 ISO/IEC 14772-1 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. 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 ISO/IEC 14772-1-defined objects to a script that uses the ecmascript: protocol.
The MIME type for ISO/IEC 14772-1 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 ISO/IEC 14772-1 backwards compatibility for the Java language in the script node, they shall do so in conformance with Annex B Java platform scripting reference in ISO/IEC 14772-1.
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 ISO/IEC
14772-1 shall extend the base
class vrml.node.Script. If a script class file extends the
ISO/IEC
14772-1 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
ISO/IEC
14772-1 or objects that conform to ISO/IEC
14772-1. It is recommended that a browser issue a warning
when it detects such a situation.