org.web3d.vrml.lang
Interface VRMLNodeTemplate

All Known Subinterfaces:

VRMLExternProtoDeclare, VRMLProtoDeclare

All Known Implementing Classes:

AbstractProto, ExternalPrototypeDecl, PrototypeDecl

public interface VRMLNodeTemplate

Denotes a node which allows it's fields to be defined in code - namely scripts and protos.

This interface allows a node to add and remove nodes from it's definition. The interface compliments an ordinary node type. The normal nodes will allow you to set the values of a field, this allows you to change their definition rather than set or query the values.

Due to the assumptions of the event model implementation of using index to name a given field. Deleting a field just removes it from the index. An index value cannot be reused by placing another field at that position. Adding fields appends them to the list. If an API to this allows the insertion of nodes then it must layer that capability over this node keeping track of logical versus actual index lists.

Version:

$Revision: 1.8 $

Author:

Justin Couch

Method Summary

int	appendField(VRMLFieldDeclaration field) Append a field declaration to this node.
VRMLNode	createNewInstance(VRMLNode root, boolean isStatic) Create a new instance of a real node from this template.
void	deleteField(int index) Delete the field at the given index.
void	deleteField(VRMLFieldDeclaration field) Delete the named field.
java.util.List	getAllFields() Make a listing of all fields that are currently registered in this node.
int	getFieldCount() Get the count of the number of fields currently registered.
VRMLFieldDeclaration	getFieldDeclaration(int index) Get the declaration of the field at the given index.
int	getFieldIndex(java.lang.String fieldName) Get the index of the given field name.
int	getNumFields() Get the number of fields defined for this node.
int	getPrimaryType() Get the primary type of this node.
java.lang.String	getVRMLNodeName() Get the name of this node as a string.
void	setErrorReporter(ErrorReporter reporter) Register an error reporter with the engine so that any errors generated by the node's internals can be reported in a nice, pretty fashion.

Method Detail

setErrorReporter

public void setErrorReporter(ErrorReporter reporter)

Register an error reporter with the engine so that any errors generated by the node's internals 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

createNewInstance

public VRMLNode createNewInstance(VRMLNode root,
                                  boolean isStatic)
                           throws InvalidNodeTypeException

Create a new instance of a real node from this template. This will ensure that all the internals are created as needed, based on the current state of the node. Note that sometimes, creating an instance of this template may result in an invalid node construction. Cases where this could occur is when there's no node definition yet loaded or that the loaded definition does not match this template.

Parameters:

root - The node that represents the root node of the VRMLExecutionSpace that we're in.

isStatic - true if this is created within a StaticGroup

Returns:

A new node instance from this template

Throws:

InvalidNodeTypeException - The root node is not a node capable of representing a root of a scene graph

See Also:

VRMLProtoInstance, VRMLWorldRootNodeType

getVRMLNodeName

public java.lang.String getVRMLNodeName()

Get the name of this node as a string. The name is the name the template would appear as in a VRML file that was requesting an instance of this node.

Returns:

The name of the node

getPrimaryType

public int getPrimaryType()

Get the primary type of this node. Replaces the instanceof mechanism for use in switch statements and when trying to determine if the node has been used in the right place. If it is unknown (eg not yet loaded extern proto) then return -1.

Returns:

The primary type

getFieldIndex

public int getFieldIndex(java.lang.String fieldName)

Get the index of the given field name. If the name does not exist for this node then return a value of -1.

Parameters:

fieldName - The name of the field we want the index from

Returns:

The index of the field name or -1

getNumFields

public int getNumFields()

Get the number of fields defined for this node.

Returns:

The number of fields.

getFieldDeclaration

public VRMLFieldDeclaration getFieldDeclaration(int index)

Get the declaration of the field at the given index. This allows for reverse lookup if needed. If the field does not exist, this will give a value of null.

Parameters:

index - The index of the field to get information

Returns:

A representation of this field's information

getFieldCount

public int getFieldCount()

Get the count of the number of fields currently registered.

Returns:

The number of fields available

getAllFields

public java.util.List getAllFields()

Make a listing of all fields that are currently registered in this node. The list contains instances of VRMLFieldDeclaration.

Returns:

A list of the current field declarations

appendField

public int appendField(VRMLFieldDeclaration field)
                throws FieldExistsException,
                       InvalidFieldException

Append a field declaration to this node. This is added to the current list on the end. If the field already exists with the given name but different values exception will be generated. If the field has exactly the same signature it will silently ignore the request.

Parameters:

field - The new field to add

Returns:

The index that this field was added at

Throws:

FieldExistsException - A conflicting field of the same name already exists for this node

InvalidFieldException - The field type is not valid for this specification version.

deleteField

public void deleteField(int index)
                 throws InvalidFieldException,
                        java.lang.ArrayIndexOutOfBoundsException

Delete the field at the given index. This will not shuffle fields down from higher index values. That index just becomes invalid to set values to. If no field exists at that index or it is out of range, an exception will be generated.

Parameters:

index - The index of the field to delete

Throws:

InvalidFieldException - The field does not exist at the index

java.lang.ArrayIndexOutOfBoundsException - The index provided is out of range for the current field numbers

deleteField

public void deleteField(VRMLFieldDeclaration field)
                 throws InvalidFieldException,
                        java.lang.ArrayIndexOutOfBoundsException

Delete the named field. This will not shuffle fields down from higher index values. That index just becomes invalid to set values to. If no field exists at that index or it is out of range, an exception will be generated.

Parameters:

field - The field to delete

Throws:

InvalidFieldException - The named field does not exist

java.lang.ArrayIndexOutOfBoundsException - The index provided is out of range for the current field numbers