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