org.web3d.vrml.nodes.proto
Class PrototypeDecl

java.lang.Object
  org.web3d.vrml.nodes.proto.AbstractProto
      org.web3d.vrml.nodes.proto.PrototypeDecl

All Implemented Interfaces:

VRMLNodeTemplate, VRMLProtoDeclare

public class PrototypeDecl
extends AbstractProto
implements VRMLProtoDeclare

Denotes an ordinary prototype node declaration.

The prototype declaration has no concrete representation in the scenegraph. It is used as a data creator for when someone declares an instance of the proto within the current scenegraph.

The proto can act in either VRML97 mode or VRML3.0 mode. The primary difference is the handling of IS values when mapping fields. To catch errors early, we check IS access type mapping as they are being inserted, rather than at runtime. The handling of this is defined in VRML97 Part 1, Section 4, Table 4.4. For VRML 3.0 all field access is expected to be exposedField so we can add an IS from any field to any declaration field. Of course, when being added, we do check for fields types and field names being valid too.

Version:

$Revision: 1.25 $

Author:

Justin Couch

Field Summary

Fields inherited from class org.web3d.vrml.nodes.proto.AbstractProto

BAD_NODE_MSG, errorReporter, FIELD_CLASH_MSG, fieldDeclList, fieldIndexMap, fieldLocalData, isVrml97, nodeName, protoCreator, VRML97_FIELD_MSG, vrmlMajorVersion, vrmlMinorVersion

Constructor Summary

PrototypeDecl(java.lang.String name, int majorVersion, int minorVersion, NodeTemplateToInstanceCreator creator)
Create a new instance of a proto that has the given name that may have its IS semantics defined according to the different specification models.

Method Summary

void	addFieldNodeValue(int index, VRMLNodeType node) Used to set the field value where the field represents a SFNode or MFNode.
void	addImportDecl(java.lang.String name, ImportNodeProxy node) The IMPORT node proxy to be registered with the node declaration at this level.
void	addIS(java.lang.String declFieldName, VRMLNodeType destNode, int destField) Register an IS setup between the incoming field and the destination node.
void	addPrototypeDecl(VRMLNodeTemplate proto) Add a nested proto or externproto declaration to this proto.
void	addRouteDecl(ProtoROUTE route) The route declaration to be registered with the node declaration at this level.
VRMLNode	createNewInstance(VRMLNode root, boolean isStatic) Create a new instance of a real node from this template.
VRMLGroupingNodeType	getBodyGroup() Get the grouping node that represents the body of the proto.
java.util.Map	getDEFMap() Fetch the internal mapping of DEF names to nodes.
VRMLFieldData	getFieldValue(int index) Get the value of a field.
java.util.Map	getImportDecls() Return the internal mapping of the import proxy nodes mapped from their name.
java.util.Map	getISMaps() Get the IS mappings for this proto declaration.
int	getPrimaryType() Get the primary type of this node.
java.util.List<VRMLNodeTemplate>	getPrototypeDecls() Fetch the list of all proto declarations in this proto.
java.util.Set	getRouteDecls() Get the set of the current route declarations that are available for this definitions.
void	setDEFMap(java.util.Map map) Update the internal DEF map collection with the contents of this map.
void	setValue(int index, boolean value) Set the value of the field at the given index as an boolean.
void	setValue(int index, boolean[] value, int numValid) Set the value of the field at the given index as an array of boolean.
void	setValue(int index, double value) Set the value of the field at the given index as an double.
void	setValue(int index, double[] value, int numValid) Set the value of the field at the given index as an array of doubles.
void	setValue(int index, float value) Set the value of the field at the given index as a float.
void	setValue(int index, float[] value, int numValid) Set the value of the field at the given index as an array of floats.
void	setValue(int index, int value) Set the value of the field at the given index as an integer.
void	setValue(int index, int[] value, int numValid) Set the value of the field at the given index as an array of integers.
void	setValue(int index, long value) Set the value of the field at the given index as an long.
void	setValue(int index, long[] value, int numValid) Set the value of the field at the given index as an array of longs.
void	setValue(int index, java.lang.String value) Set the value of the field at the given index as a string.
void	setValue(int index, java.lang.String[] value, int numValid) Set the value of the field at the given index as an array of strings.

Methods inherited from class org.web3d.vrml.nodes.proto.AbstractProto

addNodeListener, appendField, checkNodeType, deleteField, deleteField, fireFieldChanged, getAllFields, getFieldCount, getFieldDeclaration, getFieldIndex, getNumFields, getVRMLNodeName, isVRML97, removeNodeListener, setErrorReporter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.web3d.vrml.lang.VRMLNodeTemplate

appendField, deleteField, deleteField, getAllFields, getFieldCount, getFieldDeclaration, getFieldIndex, getNumFields, getVRMLNodeName, setErrorReporter

Constructor Detail

PrototypeDecl

public PrototypeDecl(java.lang.String name,
                     int majorVersion,
                     int minorVersion,
                     NodeTemplateToInstanceCreator creator)

Create a new instance of a proto that has the given name that may have its IS semantics defined according to the different specification models.

Parameters:

name - The name of the proto to use

majorVersion - The major version number of this scene

minorVersion - The minor version number of this scene

creator - The node creator for generating instances of ourself

Method Detail

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.

Specified by:

createNewInstance in interface VRMLNodeTemplate

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

addFieldNodeValue

public void addFieldNodeValue(int index,
                              VRMLNodeType node)
                       throws InvalidFieldException,
                              InvalidFieldValueException

Used to set the field value where the field represents a SFNode or MFNode. The behavior of this call is dependent on whether the field is single or multiple.

Specified by:

addFieldNodeValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

node - The node to set or add to this field

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

getFieldValue

public VRMLFieldData getFieldValue(int index)
                            throws InvalidFieldException

Get the value of a field. The return value will either be a String or String[] representing the raw value of the field. The prototype declaration does not bother attempting to parse and validate the field values, so we only deal with raw items here.

Specified by:

getFieldValue in interface VRMLProtoDeclare

Parameters:

index - The index of the field to change.

Returns:

The class representing the field value

Throws:

InvalidFieldException - The field index is not known

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.

Specified by:

getPrimaryType in interface VRMLNodeTemplate

Returns:

The primary type

addPrototypeDecl

public void addPrototypeDecl(VRMLNodeTemplate proto)

Add a nested proto or externproto declaration to this proto.

Parameters:

proto - The prototype declaration to add

getPrototypeDecls

public java.util.List<VRMLNodeTemplate> getPrototypeDecls()

Fetch the list of all proto declarations in this proto. This includes both externprotos and protos.

addRouteDecl

public void addRouteDecl(ProtoROUTE route)

The route declaration to be registered with the node declaration at this level. Nested routes inside nested proto declarations are not held here.

Parameters:

route - The route representation to store

getRouteDecls

public java.util.Set getRouteDecls()

Get the set of the current route declarations that are available for this definitions.

Specified by:

getRouteDecls in interface VRMLProtoDeclare

Returns:

The set of routes registered

addImportDecl

public void addImportDecl(java.lang.String name,
                          ImportNodeProxy node)

The IMPORT node proxy to be registered with the node declaration at this level. Nested routes inside nested proto declarations are not held here.

Parameters:

name - The local name this is imported as

node - The proxy instance representing that node

getImportDecls

public java.util.Map getImportDecls()

Return the internal mapping of the import proxy nodes mapped from their name.

Returns:

A map keyed by the name string to their ImportNodeProxy

setDEFMap

public void setDEFMap(java.util.Map map)

Update the internal DEF map collection with the contents of this map. A complete copy of the map is made.

Parameters:

map - The new map to copy

getDEFMap

public java.util.Map getDEFMap()

Fetch the internal mapping of DEF names to nodes.

Returns:

A map of the name strings to nodes

getBodyGroup

public VRMLGroupingNodeType getBodyGroup()

Get the grouping node that represents the body of the proto. This is implicitly created by the proto but does not represent the abstract type of the proto that would allow it to be used in a scenegraph.

Specified by:

getBodyGroup in interface VRMLProtoDeclare

Returns:

A grouping node suitable for adding content to during parsing

addIS

public void addIS(java.lang.String declFieldName,
                  VRMLNodeType destNode,
                  int destField)
           throws InvalidFieldException,
                  InvalidFieldConnectionException

Register an IS setup between the incoming field and the destination node.

Parameters:

declFieldName - The name of the field we are copying in the proto declaration

destNode - Reference to the node containing the field

destField - Index of the recieving field

Throws:

InvalidFieldException - Something is not valid in the fields defs

InvalidFieldConnectionException - The types of the field don't match or access doesn't match in VRML97 mode

getISMaps

public java.util.Map getISMaps()

Get the IS mappings for this proto declaration. This should only be used when building a new node instance so that the runtime instance correctly maps the IS declaration to runtime nodes. The key of the map is an Integer representation of the public field index. The value is an instance of a List where the list contains all the matching ProtoFieldInfo instances.

Returns:

A map containing the field index as the key and a list of output fields

setValue

public void setValue(int index,
                     int value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an integer. This would be used to set SFInt32 field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     int[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of integers. This would be used to set MFInt32 field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     boolean value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an boolean. This would be used to set SFBool field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     boolean[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of boolean. This would be used to set MFBool field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     float value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as a float. This would be used to set SFFloat field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     float[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of floats. This would be used to set MFFloat, SFVec2f, SFVec3f and SFRotation field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     long value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an long. This would be used to set SFTime field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     long[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of longs. This would be used to set MFTime field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     double value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an double. This would be used to set SFDouble field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     double[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of doubles. This would be used to set MFDouble, SFVec2d and SFVec3d field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     java.lang.String value)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as a string. This would be used to set SFString field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field

setValue

public void setValue(int index,
                     java.lang.String[] value,
                     int numValid)
              throws InvalidFieldException,
                     InvalidFieldValueException

Set the value of the field at the given index as an array of strings. This would be used to set MFString field types.

Specified by:

setValue in interface VRMLProtoDeclare

Parameters:

index - The index of destination field to set

value - The new value to use for the node

numValid - The number of valid values to copy from the array

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is not in range or not appropriate for this field