Xj3D VRML/X3D Code API

org.web3d.vrml.lang
Interface VRMLNodeFactory

All Known Implementing Classes:
DefaultNodeFactory

public interface VRMLNodeFactory

Representation of a factory that can produce instances of VRMLNode implementations.

This interface is primarily provided to allow an independence of the factory implementation from the factory functionality. Classes that need to create instances of VRMLNodes would just be passed this interface rather than the full factory. That then allows a single parser to be passed different factories generating different output as needed. For example one factory might use it to write info to a serialised network stream while another uses it as a layer over a rendering API such as Java3D or OpenGL.

The factory has a form of filtering mechanism in built for profile support. It acts as a form of filtering when requesting nodes. If the requested node is not part of the set profile list then the create calls would return null.

Node Creation Behaviour

In order to create a node, the factory has to be told what profile and any optional components the nodes are to come from. Then, the createVRMLNode() calls work on this information to determine whether it is legal or not to create the node. If it is not, then an UnsupportedNodeException is generated naming the node that is in error.

Because Xj3D is also permanently "in development", we have to also recognise that not all components will be completely implemented. For these, the loaded file should not fail with an undefined node message when the node really is valid for that component but we haven't implemented it yet. In that case, the createVRMLNode() methods will return a null. Users should check for this and make sure to understand the difference between this case and that of the invalid node, which generates the exception. In this later case, the user should continue to process the rest of the stream, while issuing a notification message about the missing node implementation.

Version:
$Revision: 1.6 $
Author:
Justin Couch

Field Summary
static int ANY_LEVEL
          Flag to say that the component level can be whatever is available
 
Method Summary
 ComponentInfo addComponent(java.lang.String name, int level)
          Add a component level requirement to the factory nodes.
 java.lang.Object clone()
          Create a clone of this factory.
 VRMLNode createVRMLNode(java.lang.String nodeName, boolean staticNode)
          Create a new node instance from the given node name.
 VRMLNode createVRMLNode(java.lang.String component, java.lang.String nodeName, boolean staticNode)
          Create a new node instance of the given node that exists in the given profile.
 VRMLNode createVRMLNode(VRMLNode node, boolean staticNode)
          Create a new node instance that is a cloned copy of the given node.
 void disableComponent(int[] specVersion, java.lang.String componentName, int level)
          Disable a component.
 ComponentInfo[] getAvailableComponents()
          List all of the available components that this factory is capable of supporting.
 java.lang.String[] getAvailableProfileNames()
          Convenience method to get just the names all the available profiles that this factory is capable of supporting.
 ProfileInfo[] getAvailableProfiles()
          List the all the available profiles that this factory is capable of supporting.
 int[] getMaxSupportedSpecVersion()
          Get the maximum supported spec version.
 void setErrorReporter(ErrorReporter reporter)
          Register an error reporter with the engine so that any errors generated by the loading of script code can be reported in a nice, pretty fashion.
 void setProfile(java.lang.String profile)
          Set the profile that is to be supported for the following nodes.
 void setSpecVersion(int major, int minor)
          Set the spec version that this node factory should be setting it's profile information for.
 

Field Detail

ANY_LEVEL

public static final int ANY_LEVEL
Flag to say that the component level can be whatever is available

See Also:
Constant Field Values
Method Detail

setErrorReporter

public void setErrorReporter(ErrorReporter reporter)
Register an error reporter with the engine so that any errors generated by the loading of script code can be reported in a nice, pretty fashion. Setting a value of null will clear the currently set reporter. If one is already set, the new value replaces the old.

Parameters:
reporter - The instance to use or null

setSpecVersion

public void setSpecVersion(int major,
                           int minor)
                    throws UnsupportedSpecVersionException
Set the spec version that this node factory should be setting it's profile information for.

Parameters:
major - The major version of the VRML/X3D spec to use
minor - The minor version of the VRML/X3D spec to use
Throws:
UnsupportedSpecVersionException - The profile is not unsupported by this implementation

getMaxSupportedSpecVersion

public int[] getMaxSupportedSpecVersion()
Get the maximum supported spec version.

Returns:
An int array of major, minor version.

disableComponent

public void disableComponent(int[] specVersion,
                             java.lang.String componentName,
                             int level)
Disable a component. Typically done when something finds out it cannot support the component.

Parameters:
specVersion - The spec version. Major, Minor.
componentName - The component name
level - The component level and higher to disable

setProfile

public void setProfile(java.lang.String profile)
                throws UnsupportedProfileException
Set the profile that is to be supported for the following nodes. Calling this method will clear all previously set profile and components.

Parameters:
profile - The profile name to use
Throws:
UnsupportedProfileException - The profile is not unsupported by this implementation

addComponent

public ComponentInfo addComponent(java.lang.String name,
                                  int level)
                           throws UnsupportedComponentException
Add a component level requirement to the factory nodes. If that component or level is not supported, an exception is thrown. If the level is ANY_LEVEL then that says to find the highest supported component.

Parameters:
name - The name of the component
level - The level of the component to support
Returns:
The component information declaration matching the input
Throws:
UnsupportedComponentException - The component is not unsupported by this implementation

getAvailableProfiles

public ProfileInfo[] getAvailableProfiles()
List the all the available profiles that this factory is capable of supporting. It is not the list of set profiles to filter for.

Returns:
A list of the supported profiles

getAvailableProfileNames

public java.lang.String[] getAvailableProfileNames()
Convenience method to get just the names all the available profiles that this factory is capable of supporting. It is not the list of set profiles to filter for.

Returns:
A list of the supported profile names

getAvailableComponents

public ComponentInfo[] getAvailableComponents()
List all of the available components that this factory is capable of supporting.

Returns:
The definition of all the available components

createVRMLNode

public VRMLNode createVRMLNode(java.lang.String nodeName,
                               boolean staticNode)
                        throws UnsupportedNodeException
Create a new node instance from the given node name. A best guess is made to the node's profile that it belongs to. This means that it could occasionally get it wrong if there are conflicting node names. If the node does not exist in the set profile + component then an exception is thrown. If it is part of the profile, but has not yet been implemented then null is returned.

Parameters:
nodeName - The name of the node instance to create
staticNode - Whether this node is will be modified
Returns:
An instance of the node, uninitialised or null.
Throws:
UnsupportedNodeException - The node is not part of the declared profile and components

createVRMLNode

public VRMLNode createVRMLNode(java.lang.String component,
                               java.lang.String nodeName,
                               boolean staticNode)
                        throws UnsupportedComponentException,
                               UnsupportedNodeException
Create a new node instance of the given node that exists in the given profile. If the node does not exist in that profile then an exception is thrown. If it is part of the profile, but has not yet been implemented then null is returned.

Parameters:
component - The name of the component to create the name for
nodeName - The name of the node instance to create
staticNode - Whether this node is will be modified
Returns:
An instance of the node, uninitialised or null.
Throws:
UnsupportedComponentException - The component is not in the list of usable components currently set
UnsupportedNodeException - The node is not part of the declared profile and components

createVRMLNode

public VRMLNode createVRMLNode(VRMLNode node,
                               boolean staticNode)
Create a new node instance that is a cloned copy of the given node. The copy shall be a shallow copy. All of the node's direct field data has full copies of the values made, but any referenced child nodes are not included in the copy.

The primary use of this method is in generating proto instances from a set of template nodes. The parser of the proto will be responsible for making sure the children scene graphs are correctly built by sucessive calls to this method. Note that this implies the source node may well be from a different renderer implementation to the output form.

Parameters:
node - The node instance to create a copy of
staticNode - Whether this node is will be modified
Returns:
An instance of the node initialised to the values or null.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Create a clone of this factory. The clone will have the same profile and component mix already constructed.

Returns:
A cloned copy of this instance
Throws:
java.lang.CloneNotSupportedException - Was not able to clone the object

Xj3D VRML/X3D Code API

Copyright © 2001 - 2005 Web3D Consortium