[x3d-public] browser importDocument SAI service

Don Brutzman brutzman at nps.edu
Sat Oct 22 09:47:28 PDT 2016


Thanks for this important question, Andreas.  Apologies for delayed response.

Impression: it feels like we are just getting to the point where we can begin cross-verifying
- Abstract SAI specification
- SAI language binding specifications for EcmaScript, Java
- working codebases

... so it is important that we pay close attention to these kinds of questions and track them in Mantis.  This will of course further help us in the coming year, satisfactory correlation checks will greatly simplify the SAI language-binding specification drafting and matching code autogeneration for C++ and Python.

Further strategic benefit for X3D: reconciling support for SAI interface methods is the path towards consistent programming patterns for toolsets and for X3D scene programmers.  When successful, such a state of affairs is also known as "pretty easy" and "it works." 8)

So indeed this is quite important, and not so easy to accomplish, and certainly necessary.

Back to your question, let's see how Cobweb (javascript) and Xj3D (Java) compare.  I checked the current Xj3D build and found the following.

=============================================
Found 11 matches of importDocument in 5 files.	
| X3DCommonBrowser.java
|     /** Transformation handler when dealing with importDocument */      [position 79:50]
|     /** The holder of the scene after parsing from the importDocument */      [position 82:56]
|     /** Representation of the SAX output from importDocument */      [position 85:47]
|      * Implementation of the importDocument optional capabilities.      [position 289:30]
|     public VRMLScene importDocument(Node domNode)      [position 293:22]
|
| Browser.java	
|         functionNames.add("importDocument");      [position 116:28]
|
| SAIBrowser.java
|     public X3DScene importDocument(Node aDocument) {      [position 1035:21]
|             VRMLScene scene = browserImpl.importDocument(aDocument);      [position 1039:43]
|
| InternalBrowser.java	
|     public X3DScene importDocument(Node element)      [position 782:21]
|         VRMLScene scene = realBrowser.importDocument(element);      [position 790:39]
|
| Browser.java	
|     X3DScene importDocument(Node element)      [position 336:14]
=============================================

Further information about Xj3D 2.1 availability and resources can be found at

	https://savage.nps.edu/Savage/developers.html#Xj3D

	https://sourceforge.net/projects/xj3d

Drilling down further.  Of the 11 search matches above, two are implementation oriented while the rest are interfaces or usages.

Source links and excerpts (for the email archive record) follow.

X3DCommonBrowser.java
https://sourceforge.net/p/xj3d/code/HEAD/tree/trunk/src/java/org/web3d/vrml/scripting/browser/X3DCommonBrowser.java
=============================================
     /**
      * Implementation of the importDocument optional capabilities.
      * @param domNode
      * @return
      */
     public VRMLScene importDocument(Node domNode)
         throws NotSupportedException {

         if(!(domNode instanceof Document))
             throw new NotSupportedException("Xj3D does not support importing " +
                                             "anything other than a Document yet");

         Source dom_src = new DOMSource(domNode);

         if(domErrorHandler == null) {
             SceneBuilderFactory b_fac =
                 loaderManager.getBuilderFactory(core.getRendererType());
             sceneBuilder = b_fac.createBuilder();
             sceneBuilder.setFrameStateManager(stateManager);
             sceneBuilder.setErrorReporter(errorReporter);

             domErrorHandler = new X3DErrorHandler();
             domErrorHandler.setErrorReporter(errorReporter);

             X3DSAVAdapter adap = new X3DSAVAdapter();
             adap.setContentHandler(sceneBuilder);
             adap.setProtoHandler(sceneBuilder);
             adap.setRouteHandler(sceneBuilder);
             adap.setScriptHandler(sceneBuilder);

             // Need a better way todo this
             String path = System.getProperty("user.dir");
             path = "file://" + path.substring(3);
             adap.setLoadState(path, "DOM", true);

             xmlResolver = new X3DEntityResolver();

             try {
                 TransformerFactory t_fac = TransformerFactory.newInstance();
                 transformer = t_fac.newTransformer();
             } catch(TransformerConfigurationException te) {
                 errorReporter.warningReport("Error creating transformer: ", te);
             }

             saxOutput = new SAXResult(adap);
         }

         VRMLScene parsed_scene = null;

         try {
             sceneBuilder.reset();
             transformer.transform(dom_src, saxOutput);

             parsed_scene = sceneBuilder.getScene();
             sceneBuilder.releaseScene();
         } catch(TransformerException te) {
             errorReporter.warningReport("Error importing document", te);
         }

         return parsed_scene;
     }
=============================================

InternalBrowser.java
https://sourceforge.net/p/xj3d/code/HEAD/tree/trunk/src/java/org/web3d/vrml/scripting/sai/InternalBrowser.java
=============================================
     /**
      * A utility request to import a W3C DOM document or document fragment and
      * convert it to an X3D scene. The method only performs a conversion
      * process and does not display the resulting scene. The scene may then be
      * used as the argument for the replaceWorld service. When the conversion
      * is made, there is no lasting connection between the DOM and the
      * generated scene. Each request shall be a one-off conversion attempt
      * (the conversion may not be successful if the DOM does not match the X3D
      * scene graph structure).
      *
      * @param element The root element to convert
      * @return A scene representation corresponding to the document
      * @throws InvalidBrowserException The dispose method has been called on
      *    this browser reference.
      * @throws InvalidDocumentException The document structure cannot be
      *    converted to an X3D scene for some reason
      */
     @Override
     public X3DScene importDocument(Node element)
         throws InvalidBrowserException,
                InvalidDocumentException,
                NotSupportedException {

         if(realBrowser == null)
             throw new InvalidBrowserException(INVALID_BROWSER_MSG);

         VRMLScene scene = realBrowser.importDocument(element);

         VRMLExecutionSpace space = (VRMLExecutionSpace)scene.getRootNode();
         SceneMetaData md = scene.getMetaData();
         String name = md.getProfileName();

         ProfileInfo profile = nameToProfileMap.get(name);
         X3DScene  ret_val = new WorldScene(space,
                                            routeManager,
                                            stateManager,
                                            profile,
                                            fieldQueue,
                                            fieldFactory,
                                            fieldAccessListener,
                                            baseNodeFactory);

         return ret_val;
     }
=============================================

The Java SAI language binding has to entries for importDocument that are simple but seem to be sufficient.  Links and relevant excerpts:

Table 4.6 — Browser services listed alphabetically by abstract name
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/tables.html#t-BrowserSerivesToJavaMapping
(bug report submitted to fix spelling error in bookmark)
row 14:
>	importDocument 	X3DScene importDocument(org.w3c.dom.Node)

6 Function definitions
6.3.12 importDocument
http://www.web3d.org/documents/specifications/19777-2/V3.0/Part2/functions.html#importDocument
> 6.3.12 importDocument
> X3DScene Browser.importDocument(org.w3c.dom.Node)
>     throws InvalidBrowserException,
>            InvalidOperationTimingException,
>            InvalidDocumentException
>
> A document described by the standard DOM classes is converted to an X3D scene.

Next.  The recent X3D Java SAI Library does not include the importDocument method.  There is a BrowserFactory approach and no Browser class, per se.  Also present are ExternalBrowser interface and BrowserFactoryImpl concrete class.

	http://www.web3d.org/specifications/java/javadoc/
	http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/ExternalBrowser.html
	http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/BrowserFactory.html
	http://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/BrowserFactoryImpl.html

So I have added support for importDocument and other Browser services on the TODO list for that nascent library.

	http://www.web3d.org/specifications/java/X3dJavaSceneAuthoringInterface.html
	http://www.web3d.org/specifications/java/X3dJavaSceneAuthoringInterface.html#TODO

Hope this helps with the current task, again thanks for your efforts.


On 10/13/2016 11:30 AM, Andreas Plesch wrote:
> No examples for browser.importDocument(dom) anywhere ?
>
> On Fri, Oct 7, 2016 at 1:22 PM, Andreas Plesch <andreasplesch at gmail.com <mailto:andreasplesch at gmail.com>> wrote:
>
>     The SAI defines a browser importDocument service:
>
>     http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#importDocument <http://www.web3d.org/documents/specifications/19775-2/V3.3/Part02/servRef.html#importDocument>
>
>     and
>
>     http://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#t-FunctionsBrowserObject <http://www.web3d.org/documents/specifications/19777-1/V3.3/Part1/functions.html#t-FunctionsBrowserObject>
>
>     Is there somewhere a code example of how this service is used in detail ?
>
>     The abstract SAI language reads like this js code pattern should be used:
>
>     ...
>     var newScene = browser.importDocument(dom);
>     browser.replaceWorld(newScene);
>
>     The js SAI spec. does not elaborate.
>
>     cobweb had a slightly different interpretation but now changed to the interpretation above and I would like to confirm that this pattern is the intended use.
>
>     Thanks, Andreas

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



More information about the x3d-public mailing list