A.1 Introduction and table of contents

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 VRML in addition to X3D.

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 VRML and this specification is the definition of the event model. The VRML specification left many decisions up to the browser implementer and therefore a lot of content was incompatible. The major issue was dealing with the way scene graph changes were propagated when the user code wrote to the field. In the Java language annex values would 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 annexes defined in this Part. 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 VRML97 conformant script code in the url field before a X3D conformant script code, and the browser implementation supports backwards compatibility in a language as defined in this Annex, then the VRML97 script shall be executed.

When user content defines internal interaction code that includes VRML-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

The VRML specification does not permit the use of read and write fields (i.e., exposedFields). The use of such fields is permitted in this specification. 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 VRML 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 customize 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 A ECMAScript language binding 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 VRML97 specification. It shall be an error for a browser that conforms to this specification to support the javascript protocol with script content that uses Objects defined in Annex A of this specification.

The use of the ecmascript: protocol shall indicate the script conforms to Annex A of this specification. A browser shall not provide VRML97 defined objects to a script that uses the ecmascript: protocol.

A.3.3.2 MIME types

The MIME type for VRML 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 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 ISO/IEC 14772-1.

A.4.2 Determination of required specification

As it is impossible to pre-determine 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 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 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.