[x3d-public] X3DJSAIL: command line options for conversion, standalone "fat jar" now working

[Don Brutzman]

Much effort and apparent succress on X3DJSAIL command line support:  standalone capabilities now available in full.jar (hooray!) and minimalist code for linking found in classes.jar.

Format conversions from .x3d to various alternatives now supported via command line (or Ant or presumably Maven) if X3DJSAIL.3.3.full.jar files are found in CLASSPATH.

http://www.web3d.org/specifications/java/X3dJavaSceneAuthoringInterface.html#CommandLine
========================================================================================
Command line invocation is feasible through use of the org.x3d.jsail.CommandLine class.

* Invocation of standalone .jar

     java -classpath path/X3DJSAIL.3.3.full.jar [-help | sourceModel.x3d] [-tofile [resultFile.*]] [-toX3D | -toXML | -toClassicVrml | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE]

     Example:    java -classpath path/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine -help

     Example:    java -classpath path/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toVRML97 -toFile

* Invocation using local libraries

   - Prerequisite: CLASSPATH correctly containing X3DJSAIL.3.3.classes.jar plus Saxon stylesheet engine saxon9he.jar

         Example CLASSPATH confirmation: % echo $CLASSPATH
         CLASSPATH='C:\x3d-code\www.web3d.org\x3d\stylesheets\java\jars\X3DJSAIL.3.3.classes.jar;C:\x3d-code\www.web3d.org\x3d\stylesheets\java\lib\saxon9he.jar'

   - Invocation: java org.web3d.x3d.jsail.CommandLine [-help | sourceModel.x3d] [-tofile [resultFile.*]] [-toX3D | -toXML | -toClassicVrml | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE]

         Example:    java org.web3d.x3d.jsail.CommandLine -help

         Example:    java org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toClassicVRML

Model validation is always performed as part of X3DJSAIL operations.
========================================================================================

Turns out there is a lot of difficulty (or at least wide difference of opinion) in handling "jars within jars" in Java.  Sounds trivial, but there are issues with JVM class loaders and Java support.  Horrifying overview:

	https://dzone.com/articles/what-is-jar-hell

For this challenge, the key fact was that Class-Path inside a jar is not portable since it points to external relative paths outside the jar, _not_ files inside the jar as one might expect.

So I tried a few approaches and finally landed on "fat jar" for X3DJSAIL.3.3.full.jar, which means that other dependency jars (such as saxon9he.jar) get unzipped/unsigned and placed next to the original classes so that all internal class visibility is direct.  Then the whole shebang is wrapped back up in a single .jar file result.  Care must be taken to do this correctly!  The result is "sealed" as an all-or-nothing approach, which should protect internal classes from getting overridden or cross-threaded by other versions of the classes that might appear in the user environment.

The "Uber jar" approach is also interesting but looks to be a regularization of that same approach using Maven; X3DJSAIL simply uses Ant.  So that wasn't used, but information about it was helpful.

Loads of links and summaries for relevant Java esoterica can be found in stylesheets/build.xml in the target named create.X3DJSAIL.jars.

Anyway it now appears to work. Test reports welcome.

Have fun with X3DJSAIL on the command line and in other applications!  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