A.1 Introduction and topics

A.1.1 Introduction

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.

A.1.2 Topics

Table A.1 lists the topics for this annex.

A.2 Concepts

A.2.1 Introduction

A.2.1.1 Requirements for backwards compatibility

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.

A.2.1.2 Differences between VRML and X3D

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.

A.2.2 Behaviour for unsupported scripting

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.

A.2.3 Behaviour on encountering exposedFields

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.

A.3 ECMAScript language binding

A.3.1 Requirements

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.3.2 Determination of required specification

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.

A.3.3 Supported script URLs

A.3.3.1 Inline script definition

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() { ... }"
}

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.

A.3.3.2 MIME types

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.

A.4 Java language binding

A.4.1 Requirements

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.

A.4.2 Determination of required specification

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.