[X3D-Public] Mantis 525: Ecmascript method naming for inputOutput fields

[Don Brutzman]

http://www.web3d.org/membership/login/mantis/view.php?id=525

Here is the issue in the Mantis tracker.  It is a complicated writeup but a simple resolution.
Minutes to follow.

Description
Problem statement: field accessor methods need to have a different name than the field itself. Some javascript implementations confound the field object and the method object when the names are the same.

Fix summary:
a. Set methods for a field should be called set_fieldName.
b. If an output event is sent, it is called fieldName_changed.
c. Within the script, current value is referred to as fieldName.

Reportedly InstantReality and Octaga and Xj3D implement the desired behavior. Need to confirm that all browsers are matching this approach.

Image attached from prior Web3D 2009 Conference in Darmstadt that documents the consensus approach. Unfortunately this correction was not specified previous in the 19777-1 specification itself.

Offending statement from 4.3.5.4:
If the function represents an inputOutput field, the name of the function shall be the same name as the field declaration, without the set_ or _changed modifiers.

Proposed correction sentences:
If a function represents an inputOutput field, the name of the corresponding function shall be the same name as the field declaration with the set_ modifier prepended. To access the value of the inputOutput field, the name of the field itself shall be used without the _changed modifier.

Original 19777-1 specification prose can be found at
http://www.web3d.org/files/specifications/19777-1/V3.0/Part1/concepts.html#ReceivingEvents

We will also change and test the example in this paragraph from

EXAMPLE The following Script node has one writable field whose name is start:
Script {
    eventIn SFBool start
    url "ecmascript: function start(value, timestamp) { ... }"
}

to something like

EXAMPLE The following Script node has two fields capable of receiving events:
Script {
    inputOnly SFBool startMeUp
    inputOutput SFBool started false
    url "ecmascript:
    function startMeUp(value, timestamp)
    {
        started = true; // etc.
    }
    function set_started(value, timestamp)
    {
        // this step gets handled automatically by browser upon event receipt:
        // started = value;

        // additional code can go here
        if (started) Browser.println ('here we go');
    }
    "
}

Likely specification additions to prevent pathological cases:

It is an error to simultaneously define fields that result in overloaded (i.e. duplicated) method names.

EXAMPLE The following is erroneous:
Script {
    inputOnly SFBool set_overloadedField
    inputOutput SFBool overloadedField false
}

Similarly, it is also an error to simultaneously define a method that directly matches and overloads an inputOutput field name. To do so overloads definitions for the method object and the field object.

EXAMPLE The following is erroneous, the method should instead be named set_overloadedField2:
Script {
    inputOutput SFBool overloadedField2 false
    url "ecmascript: function overloadedField2 (value, timestamp) { ... }"
}

	InstantReality reports that there is an internal X3D browser workaround for JavaScript that they have achieved which allows authors to use either approach. This opens the possibility that we should not revise the X3D language-binding specification, as proposed here, for better clarity and unambiguous implementation design.

However, other implementations may have trouble implementing this approach, so we should look at it. This includes implementations available today, and possibly future implementations which might run in lightweight browsers.

There may also be security implications if a malicious author might be able to modify a function that gets run by the X3D browser. There is likely a similar security design issue for Javascript running inside an HTML sandbox. We should probably also look in HTML-browser-writer best practices and security considerations to see if there are any appropriate lessons to consider. If there is no added security vulnerability with either approach, then we don't have to worry about that factor.

I have created an example that reports which of the two method names is used by a browser, by implementing both of them and sending a trace message to the browser console. The field name is traceValue, the corresponding method names are:
    set_traceValue
or
    traceValue

Testing this example shows that BS Contact and Xj3D use the older style, and that InstantReality will crash -- probably due to the already-noted hazard which is prompting this proposed change to the specification: to avoid simultaneous overloaded definitions of function and variable names.

The behavior of the example scene is fairly simple. When the first viewpoint (at a high-above vantage point) is bound, a corresponding NavigationInfo with EXAMINE navigation is bound. Similarly, when that viewpoint is unbound, a different NavigationInfo with FLY navigation is bound.

Example browser console output:
===============================
Script method traceValue invoked, which is now handing off to traceValueHandler()...
Trace_ROUTE_ViewOverhead.isBound_TO_NavigationExamineMode.set_bind type=SFBool value=1
User navigation should be EXAMINE
Script method traceValue invoked, which is now handing off to traceValueHandler()...
Trace_ROUTE_ViewOverhead.isBound_TO_NavigationExamineMode.set_bind type=SFBool value=0
User navigation should be FLY
===============================

Example scene is online at
https://savage.nps.edu/Savage/Locations/MontereyPeninsulaCollege/PoolMontereyPeninsulaCollegeUsingBoxes.x3d [^]

Script excerpt:
        <!-- ======= ROUTE Trace ============================================== -->
        <Script DEF='Trace_ROUTE_ViewOverhead.isBound_TO_NavigationExamineMode.set_bind' mustEvaluate='true'>
          <!-- Trace ROUTEd values on X3D browser console -->
          <field accessType='initializeOnly' appinfo='Sampling frequency in seconds (0 means all values)' name='reportInterval' type='SFTime' value='1.0'/>
          <field accessType='inputOnly' name='traceValue' type='SFBool'/>
          <field accessType='initializeOnly' name='timeStampPreviousReport' type='SFTime' value='-1'/>
          <![CDATA[
  ecmascript:
    function set_traceValue (eventValue, timeStamp)
    {
        Browser.println ('Script method set_traceValue invoked, which is now handing off to traceValueHandler()...');
        traceValueHandler (eventValue, timeStamp);
    }
    function traceValue (eventValue, timeStamp)
    {
        Browser.println ('Script method traceValue invoked, which is now handing off to traceValueHandler()...');
        traceValueHandler (eventValue, timeStamp);
    }
    function traceValueHandler (eventValue, timeStamp)
    {
      // input eventValue received for trace field
etc.

I hope that this test helps us get to implementation consistency and specification-change closure on this important issue.


Len and I had an interesting discussion with Yvonne today.

She informed us that X3DOM likely performs a step during parsing, to insert "set_" and "_changed" in ROUTE statements prior to loading. Such a check can ensure that the X3D ROUTEs are compatible with HTML requirements. This approach might also be used by some other X3D players already.

This is very interesting because it shows a good technique for any player, and any tool, to detect and fix problems in content prior to loading them in Ecmascript. Such corrections can occur at scene-loading time prior to creation of data structures and scripts in memory. Such corrections can also occur as part of offline content review by tools and quality assurance (QA) checking - for example, the X3D Validator.
http://www.web3d.org/x3d/content/examples/X3dResources.html#QualityAssurance [^]
https://savage.nps.edu/X3dValidator [^]

This approach can also work when creating ROUTES dynamically at run time, to ensure that Script setter and getter methods are properly working.

It appears that this additional solution confirms that we should amend the specification to ensure that overloading problems are always avoidable. As already noted, we will include rules both for what is specifically allowed and for what is specifically not allowed.

I think that this specification problem is serious - we are not changing backwards compatibility, but rather fixing an issue that prevents consistent and repeatable implementations. So, by this reasoning, we must proceed with the specification change.



all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman at nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Web3d2009X3dJavascriptFieldNamingConventions.jpg
Type: image/jpeg
Size: 178904 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20120627/83b3e674/attachment-0001.jpg>