This package provides a Java3D SceneGraph IO capability.


Interface Summary
SceneGraphIO Implement this interface in any classes that subclass a Java3D SceneGraphObject in order to have your class handled correctly by
SceneGraphObjectReferenceControl Provides and resolves references to SceneGraphObjects to enable persistant references in user defined SceneGraphObjects implementing the SceneGraphIO interface.
SceneGraphStateProvider This interface allows developers to provide their own custom IO control for subclasses of SceneGraphObjects.

Class Summary
SceneGraphFileReader Read Java3D BranchGraphs and/or Universe from a file.
SceneGraphFileWriter Write a (set) of Java3D BranchGraphs and/or Universe to a file.
SceneGraphStreamReader Read and create a (set) of Java3D BranchGraphs or Universe from a Java Stream.
SceneGraphStreamWriter Writes a Java3D SceneGraph to a Java OutputStream.
UnresolvedBehavior This Behavior is used in place of any behaviors which can not be instantiated when a scene graph is read.

Exception Summary
NamedObjectException An error has occurred while processing a named object
ObjectNotLoadedException The named object has not been loaded so it's instance can not be returned
UnsupportedUniverseException Thrown if the VirtualUniverse subclass is not supported by the writeUniverse calls.

Package Description

This package provides a Java3D SceneGraph IO capability. The API supports IO of a scenegraph to and from a Java Stream and/or RandomAccessFile. The features offered for these two io systems are somewhat different.

The SceneGraphFileReader and SceneGraphFileWriter classes provide IO to and from a RandomAccessFile. They allow a universe and/or multiple BranchGraphs to be written to the file with Node's and NodeComponent's shared between the separate graphs. The graphs can be read in any order.

SceneGraphStreamReader and SceneGraphStreamWriter classes provide IO to and from a Stream. These classes allow a universe and/or multiple BranchGraphs to be passed over stream. In contrast to the FileReader/Writer sharing of Node's is NOT supported between graphs by the API. Sharing of node components is supported. If your application requires references to Nodes in other graphs (such as SharedGroups) the application must handle the references using the namedObjects constructs.

Note : If you use SceneGraphStreamWriter class to write to a FileOutputStream the resulting file cannot be read using the SceneGraphFileReader, the converse is also true, you can not use a FileInputStream to load a file written by SceneGraphFileWriter.

The package supports the IO of all the Java3D 1.3 core classes and many of the utilities. It also includes interfaces which can be implemented to allow user defined subclasses of SceneGraphObjects to be stored. Information on the extensibility can be found here

The package has a number of properties which can be used to control the IO behavior when this property is present the load operation will attempt to avoid failure if Scene Graph nodes are not present in the classpath. For example if a developer has subclassed BranchGroup with a class called MyBG but has not implemented the SceneGraphIO interface when the API saves the graph the superclass (ie BranchGroup) data will be stored. When the scene is loaded normally MyBG must be in the classpath otherwise the load will fail. If this property is set then the superclass node (ie BranchGroup) will be instantiated when MyBG is missing. Obviously, if MyBG contained any state information then this will be lost. this can be set to None, GZIP, JPEG and tells the IO system to compress images in the .j3f file using the prescribed technique. In the future this will be extended to support all the formats available in javax.imageio in JDK 1.4.