[x3d-public] second release: X3DJSAIL Java translations, javadoc in X3D Examples Archives

[Don Brutzman]

With some effort, have added two more of the X3D Example Archives to include Java support using X3DJSAIL.

	VRML 2 Sourcebook (415 Models)
	http://www.web3d.org/x3d/content/examples/Vrml2Sourcebook
	http://www.web3d.org/x3d/content/examples/Vrml2Sourcebook/javadoc
	http://www.web3d.org/x3d/content/examples/Vrml2Sourcebook/build.java.out.txt

	Conformance Nist (732 Models)
	http://www.web3d.org/x3d/content/examples/ConformanceNist/
	http://www.web3d.org/x3d/content/examples/ConformanceNist/javadoc
	http://www.web3d.org/x3d/content/examples/ConformanceNist/build.java.out.txt

The biggest task was to ensure that directory names and scene names met naming conventions for Java packages and classes.  In other words no hyphens, cannot start with a numeral, etc.  More on those rules can be found at

	X3D Scene Authoring Hints: Naming Conventions
	http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions

Some improvements made and posted to X3dToJava.xslt stylesheet and X3DJSAIL library.  Testing and upgrades are continuing.

	X3D Java Scene Access Interface Library (X3DJSAIL)
	http://www.web3d.org/specifications/java/X3DJSAIL.html


On 4/9/2017 2:07 PM, Don Brutzman wrote:
> Am happy to report that second release of more than a thousand published X3DJSAIL Java translations for X3D programs is now online in the Web3D Example Archives.
> 
>      http://www.web3d.org/specifications/java/X3DJSAIL.html
>      http://www.web3d.org/x3d/content/examples/X3dResources.html#Examples
> 
> Current support includes Basic Examples, X3dForWebAuthors and X3dForAdvancedModeling archives.  Also included are console logs when building the java versions of each example.
> 
>      http://www.web3d.org/x3d/content/examples/Basic (776 Models)
>      http://www.web3d.org/x3d/content/examples/Basic/javadoc
>      http://www.web3d.org/x3d/content/examples/Basic/build.out.java.txt
> 
>      http://x3dgraphics.com/examples/X3dForWebAuthors (260 Models)
>      http://x3dgraphics.com/examples/X3dForWebAuthors/javadoc
>      http://x3dgraphics.com/examples/X3dForWebAuthors/build.java.out.txt
> 
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling (83 Models)
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/javadoc
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/build.java.out.txt
> 
> As described in the X3DJSAIL documentation, the archives build process uses the X3dToJava.xslt stylesheet for conversions.  Each index page for each example model has links to corresponding java and javadoc (as well as .x3d .x3dv .json x3dom cobweb html etc. of course) for comparison.
> 
> Of note: in addition to compilation, the build process also executes each java version to reveal execution success or executions.  In other words we are *producing unit tests that also test themselves* - pretty cool!  Run-time testing isn't often a part of automated graphics testing, so this appears to be a significant step forward. The capabilities demonstrated by each example really help us with ongoing testing and improvement of X3DJSAIL API and X3D Java programs.  Rephrased: we are certainly finding and fixing a lot of bugs!  The latest greatest bugs can be found in the build logs above.
> 
>      X3D Java Scene Access Interface Library (X3DJSAIL)
>      http://www.web3d.org/specifications/java/X3DJSAIL.html
> 
> A lot of improvements have been made to the X3dToJava.xslt stylesheet as part of debugging efforts - plus a few touchups for X3dToJson.xslt as well.
> 
> Let's again look at one model as an example, the BoxSwitch.x3d scene:
> 
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/Animation/BoxSwitchIndex.html
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/Animation/BoxSwitch.java
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/javadoc/index.html?X3dForAdvancedModeling/Animation/BoxSwitch.html
>      http://x3dgraphics.com/examples/X3dForAdvancedModeling/Animation/BoxSwitch.json
> 
> Console excerpt:
> ================
> C:\x3d-code\www.web3d.org\x3d\content\examples\X3dForAdvancedModeling/Animation/BoxSwitch.java produced from BoxSwitch.x3d
> [Large tuple found: PositionInterpolator keyValue, $tupleCount=37, $tupleSplitSize=10, string-length=480]
> Compiling 1 source file to C:\x3d-code\www.web3d.org\x3d\content\examples\X3dForAdvancedModeling\classes
> now run and validate the java model
> java -classpath classes;../../../stylesheets/java/jars/X3DJSAIL.3.3.full.jar;C:\x3d-code\www.web3d.org\x3d\tools\jar/saxon9he.jar X3dForAdvancedModeling.Animation.BoxSwitch
> BoxSwitch self-validation test results: success
> ================
> 
> Java coders can look at the main() and validateSelf() methods in the .java source to see how each autogenerated class is internally checking for correctness when run.  Most functionality (such as strong-typing checks for attribute values and allowed child nodes) is built into X3DJSAIL for generality, and the per-scene exemplar code simply shows how to invoke it.
> 
> As before, one challenge encountered during this process was the need to rename directories and file names to omit hyphen and period characters - those are not allowed as Java package or class names.  A number of rename fixes were made for Basic archive as well.  Next up is the VRML 2 Sourcebook, lots of renaming is necessary for this to work.  Naming conventions can be found in the X3D Scene Authoring Hints at
> 
>      http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions
> 
> As an example of debugging strength, this publishing process revealed a number of utilization problems that are independent of X3DJSAIL codebase itself.  All discovered deficiencies fixed in the converter, no major new bugs have been found on X3DJSAIL, changes are deployed every 1-2 days and checked in steadily, further progress expected.
> 
> A table summary of different conversion capabilities (available and planned) is now found at
> 
>      http://www.web3d.org/specifications/java/X3DJSAIL.html#Conversions
> 
> Finally, have improved documentation further and am highlighting X3dToJava.xslt issues with a TODO subsection on the web page:
> 
> ====================================
> X3DJSAIL: TODO Planned Work
> http://www.web3d.org/specifications/java/X3DJSAIL.html#TODO
> 
> * Continued testing and improvement with conversion of .x3d source models in the X3D Examples Archive.
> * Continued resolution of issue reports on x3d-public at web3d.org mailing list (_archives_).
> * Handle too-large initialization methods (greater than 64K compiled) by splitting off arrays portions as separate data structures, when needed, rather than pipelined functional-style instantiations.
> * Prototypes: check IS/connect support, improve ProtoInstance handling without needing containerField
> ====================================
> 
> Special thanks still for continuing superlative efforts by John Carlson in testing and debugging this codebase, as well as innovative design patterns for usage.  We'll continue highlighting issues of interest on the x3d-public mail list, those mails represent just a portion of much work going on in the background.
> 
> Looking ahead:  "Object Model for X3D (OM4X3D) and Scene Access Interface (SAI) for X3D, including JSONLD and X3DJSAIL" by John, Roy and myself was accepted to the tutorial program of Web3D 2017.  Looking forward to showing people how to use these production-ready X3D codebases there.
> 
>      Web3D 2017 Conference
>      Brisbane Australia, 3-5 June 2017
>      http://web3d2017.web3d.org
> 
> So, onward we continue.  Have fun with X3D Java!  8)

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