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

[Johannes Behr]

Hi,

> 
> 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

Agreed. makes sense. Can be implementation with some backwards compatible handling.

> prepended. To access the value of the inputOutput field, the name of the field itself shall be used without the _changed modifier.

Why? There is no conflict anymore with the set_ function prefix and the name of the variable could just stay. Otherwise is it very odd compared to initializeOnly data fields.

Best regards
Johannes

> 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
> 
> <Web3d2009X3dJavascriptFieldNamingConventions.jpg>

--
Dr. Johannes Behr
Abteilungsleiter Visual Computing System Technologies
Fraunhofer-Institut für Graphische Datenverarbeitung IGD
Fraunhoferstr. 5  |  64283 Darmstadt  |  Germany
Tel +49 6151 155-510  |  Fax +49 6151 155-196
johannes.behr at igd.fraunhofer.de  |  www.igd.fraunhofer.de