org.web3d.vrml.nodes.proto
Class ProtoInstancePlaceHolder

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

All Implemented Interfaces:

VRMLExecutionSpace, VRMLNode, VRMLNodeTemplate, FrameStateListener, VRMLNodeType, VRMLProtoInstance

public class ProtoInstancePlaceHolder
extends AbstractProto
implements VRMLProtoInstance

A placeholder instance of a Prototype used when declaring and then using a nested proto instance.

The idea of this class is to fake being a real prototype instance when the code stubs a nested proto instance. A nested proto instance is of the form

 PROTO Outer [] {
   PROTO Inner [] { Box {} }
   Inner {}
 }
 

In this case, when we are storing the definition of Inner then we really don't want to expand the internal prototype definition at this point. The expansion should only take place when we create an instance of Outer. This class is used as a placeholder in this definition for this scenario. The idea is that when the code is traversing the definition, it will be replaced by a real runtime version.

Version:

$Revision: 1.45 $

Author:

Justin Couch

Field Summary

protected int[]	layerIds The list of layer IDs that reference this node.
protected int[]	refCounts The current number of references to this node.

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

ProtoInstancePlaceHolder(VRMLNodeTemplate proto, int major, int minor, boolean staticNodes, NodeTemplateToInstanceCreator creator)
Create a new instance place holder that represents the given proto declaration.

Method Summary

void	allEventsComplete() Ignored by this implementation.
void	clearRemovedLayerIds() Clear the current removed layer ID list.
VRMLNode	createNewInstance(VRMLNode root, boolean isStatic) Create a new instance of a real node from this template.
VRMLNodeType[]	getBodyNodes() Get the list of all the body nodes in this proto instance.
BasicScene	getContainedScene() Get the contained scene graph that this instance has.
VRMLFieldData	getFieldValue(int index) Get the value of a field.
VRMLNodeType	getImplementationNode() Get the first node declared in the proto as that defines just how we we can add this into the scenegraph.
int[]	getLayerIds() Get a listing of the current layer IDs that are directly or indirectly referencing this node.
VRMLNodeType	getMetadataObject() Get the currently registered metadata object instance.
int[]	getNodeFieldIndices() Get the list of indices that correspond to fields that contain nodes ie MFNode and SFNode).
int	getPrimaryType() Get the primary type of this node.
VRMLNodeTemplate	getProtoDefinition() Get the PROTO/EXTERNPROTO definition used by this place holder.
int	getRefCount(int layer) Ask for the current number of references to this object in the given layer.
int[]	getRemovedLayerIds() Get the list of layer IDs that this node has just been removed from.
int[]	getSecondaryType() Get the secondary type of this node.
java.lang.Object	getUserData(int index) Fetch the stored user data for a given field index.
boolean	hasFieldChanged(int index) Check to see if the given field has changed since we last checked.
boolean	isDEF() Check to see if this node has been DEFd.
boolean	isSetupFinished() Check to see if setupFinished() has already been called on this node.
void	notifyExternProtoLoaded(int index, VRMLNodeType node) Notify a node that an ExternProto has resolved.
void	sendRoute(double time, int srcIndex, VRMLNodeType destNode, int destIndex) Send a routed value from this node to the given destination node.
void	setDEF() Notify this node that is has been DEFd.
void	setFrameStateManager(FrameStateManager mgr) Ignored by this implementation.
void	setMetadataObject(VRMLNodeType data) Set the X3DMetadataObject that is associated with this node.
void	setupFinished() Notification that the construction phase of this node has finished.
void	setUserData(int index, java.lang.Object data) Set arbitrary data for a given field.
void	setValue(int index, boolean value) Set the value of the field at the given index as an booleaneger.
void	setValue(int index, boolean[] value, int numValid) Set the value of the field at the given index as an array of booleanegers.
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.
void	setValue(int index, VRMLNodeType child) Set the value of the field at the given index as a node.
void	setValue(int index, VRMLNodeType[] children, int numValid) Set the value of the field at the given index as an array of nodes.
void	setVersion(int major, int minor, boolean isStatic) Set the version of VRML that this node should represent.
void	updateRefCount(int layer, boolean add) Change the reference count up or down by one for a given layer ID.

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.nodes.VRMLProtoInstance

getAllFields, getFieldCount

Methods inherited from interface org.web3d.vrml.nodes.VRMLNodeType

addNodeListener, removeNodeListener

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

getFieldDeclaration, getFieldIndex, getNumFields, getVRMLNodeName, setErrorReporter

Field Detail

refCounts

protected int[] refCounts

The current number of references to this node. This is for informational purposes only and should never be touched by derived classes.

layerIds

protected int[] layerIds

The list of layer IDs that reference this node. Should correspond 1:1 to the counts in refCounts. If none, this is null.

Constructor Detail

ProtoInstancePlaceHolder

public ProtoInstancePlaceHolder(VRMLNodeTemplate proto,
                                int major,
                                int minor,
                                boolean staticNodes,
                                NodeTemplateToInstanceCreator creator)

Create a new instance place holder that represents the given proto declaration.

Parameters:

proto - The prototype declaration to base this placeholder on

major - The major version number of this scene

minor - The minor version number of this scene

staticNodes - Whether this node is will be modified

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

getImplementationNode

public VRMLNodeType getImplementationNode()

Get the first node declared in the proto as that defines just how we we can add this into the scenegraph. If this is an empty prototype implementation, or represents an Extern proto that has not been loaded yet then this will return null.

Specified by:

getImplementationNode in interface VRMLProtoInstance

Returns:

The node instance that represents the first node

getProtoDefinition

public VRMLNodeTemplate getProtoDefinition()

Get the PROTO/EXTERNPROTO definition used by this place holder.

Returns:

The proto definition used by the node

getBodyNodes

public VRMLNodeType[] getBodyNodes()

Get the list of all the body nodes in this proto instance. Nodes are defined in declaration order. Index 0 is always the same value as that returned by getImplementationNode(). This should be called sparingly. It is really only of use to something that needs to traverse the entire scene graph or for scripting to provide access to the root of the scene.

Specified by:

getBodyNodes in interface VRMLProtoInstance

Returns:

The list of nodes from the body

getContainedScene

public BasicScene getContainedScene()

Get the contained scene graph that this instance has. This represents everything about the internal scene that the node declaration wraps. This is a real-time representation so that if it the nodes contains a script that changes the internal representation then this instance will be updated to reflect and changes made.

Specified by:

getContainedScene in interface VRMLExecutionSpace

Returns:

The scene contained by this node instance

allEventsComplete

public void allEventsComplete()

Ignored by this implementation.

Specified by:

allEventsComplete in interface FrameStateListener

notifyExternProtoLoaded

public void notifyExternProtoLoaded(int index,
                                    VRMLNodeType node)
                             throws InvalidFieldValueException

Notify a node that an ExternProto has resolved. This will verify the objects type and add it to the render sceneGraph.

Specified by:

notifyExternProtoLoaded in interface VRMLNodeType

Parameters:

index - The field index

node - The node resolved

Throws:

InvalidFieldValueException - If the proto contains he wrong type

getRefCount

public int getRefCount(int layer)

Ask for the current number of references to this object in the given layer. If this node represents a layer node itself, then the value returned for that ID should always be one. If the layer requested does not have a reference to this node, return zero.

Specified by:

getRefCount in interface VRMLNodeType

Parameters:

layer - The id of the layer to get the ref count for

Returns:

The number of references to this node

updateRefCount

public void updateRefCount(int layer,
                           boolean add)

Change the reference count up or down by one for a given layer ID. If there is no reference to the given layer ID previously, add one now. A listing of the layer IDs that reference this node can be retrieved through getLayerIds().

Specified by:

updateRefCount in interface VRMLNodeType

Parameters:

layer - The id of the layer to modify the ref count on

add - true to increment the reference count, false to decrement

getLayerIds

public int[] getLayerIds()

Get a listing of the current layer IDs that are directly or indirectly referencing this node. If this layer is not part of a live scene graph (eg held by a script code, but not by the script itself) then this will will return a null value. The array will always be exactly equal in length to the number of IDs that reference this node.

Specified by:

getLayerIds in interface VRMLNodeType

Returns:

An array of all the IDs referencing this node or null if none

getRemovedLayerIds

public int[] getRemovedLayerIds()

Get the list of layer IDs that this node has just been removed from. If it currently has not been removed from anything, this will return null. This will remain updated until the next clearRemovedLayerIds() call.

Specified by:

getRemovedLayerIds in interface VRMLNodeType

Returns:

An array of all the IDs this is delete from or null if none

clearRemovedLayerIds

public void clearRemovedLayerIds()

Clear the current removed layer ID list. If there is nothing removed, this method does nothing.

Specified by:

clearRemovedLayerIds in interface VRMLNodeType

setFrameStateManager

public void setFrameStateManager(FrameStateManager mgr)

Ignored by this implementation.

Specified by:

setFrameStateManager in interface VRMLNodeType

Parameters:

mgr - The manager instance to use

setDEF

public void setDEF()

Notify this node that is has been DEFd. This method shall only be called before setupFinished(). It is an error to call it any other time. It is also guaranteed that this call will be made after construction, but before any of the setValue() methods have been called.

Specified by:

setDEF in interface VRMLNodeType

Throws:

java.lang.IllegalStateException - The setup is finished.

isDEF

public boolean isDEF()

Check to see if this node has been DEFd. Returns true if it has and the user should ask for the shared representation rather than the normal one.

Specified by:

isDEF in interface VRMLNode

Returns:

true if this node has been DEFd

getPrimaryType

public int getPrimaryType()

Get the primary type of this node. Replaces the instanceof mechanism for use in switch statements.

Specified by:

getPrimaryType in interface VRMLNode

Specified by:

getPrimaryType in interface VRMLNodeTemplate

Returns:

The primary type

getSecondaryType

public int[] getSecondaryType()

Get the secondary type of this node. Replaces the instanceof mechanism for use in switch statements.

Specified by:

getSecondaryType in interface VRMLNode

Returns:

The secondary type

hasFieldChanged

public boolean hasFieldChanged(int index)

Check to see if the given field has changed since we last checked. Always returns false as this is a placeholder node, not a runtime version.

Specified by:

hasFieldChanged in interface VRMLNodeType

Parameters:

index - The index of the field to change.

Returns:

true if the field has changed since last read

getNodeFieldIndices

public int[] getNodeFieldIndices()

Get the list of indices that correspond to fields that contain nodes ie MFNode and SFNode). Empty for the proto body group node.

Specified by:

getNodeFieldIndices in interface VRMLNode

Returns:

null

getFieldValue

public VRMLFieldData getFieldValue(int index)
                            throws InvalidFieldException

Get the value of a field. If the field is a primitive type, it will return a class representing the value. For arrays or nodes it will return the instance directly.

Specified by:

getFieldValue in interface VRMLNodeType

Parameters:

index - The index of the field to change.

Returns:

The class representing the field value

Throws:

InvalidFieldException - The field index is not known

setMetadataObject

public void setMetadataObject(VRMLNodeType data)
                       throws InvalidFieldValueException

Set the X3DMetadataObject that is associated with this node. Ignored because proto body nodes don't take metadata.

Specified by:

setMetadataObject in interface VRMLNodeType

Parameters:

data - The node to register as the metadata

Throws:

InvalidFieldValueException - The object instance provided does not implment VRMLMetadataNodeType or is not a proto instance that encapsulates it as it's primary type

getMetadataObject

public VRMLNodeType getMetadataObject()

Get the currently registered metadata object instance. If none is set then return null. Ignored because because proto body nodes don't take metadata.

Specified by:

getMetadataObject in interface VRMLNodeType

Returns:

The current metadata object or null

sendRoute

public void sendRoute(double time,
                      int srcIndex,
                      VRMLNodeType destNode,
                      int destIndex)

Send a routed value from this node to the given destination node. This method always does nothing as it is a placeholder only, not a runtime class.

Specified by:

sendRoute in interface VRMLNodeType

Parameters:

time - The time that this route occurred (not necessarily epoch time. Should be treated as a relative value only)

srcIndex - The index of the field in this node that the value should be sent from

destNode - The node reference that we will be sending the value to

destIndex - The index of the field in the destination node that the value should be sent to.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

setValue

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

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

Specified by:

setValue in interface VRMLNodeType

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 out of range for the field type.

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 booleanegers. This would be used to set MFBool field types.

Specified by:

setValue in interface VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

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 VRMLNodeType

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 out of range for the field type.

setValue

public void setValue(int index,
                     VRMLNodeType child)
              throws InvalidFieldException,
                     InvalidFieldValueException

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

Specified by:

setValue in interface VRMLNodeType

Parameters:

index - The index of destination field to set

child - The new value to use for the node

Throws:

InvalidFieldException - The field index is not known

InvalidFieldValueException - The value provided is out of range for the field type.

setValue

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

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

Specified by:

setValue in interface VRMLNodeType

Parameters:

index - The index of destination field to set

children - 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 out of range for the field type.

setUserData

public void setUserData(int index,
                        java.lang.Object data)
                 throws InvalidFieldException

Set arbitrary data for a given field. Provided primarily to help the EAI fullfil its requirements, but may be useful elsewhere.

Specified by:

setUserData in interface VRMLNode

Parameters:

index - The index of destination field to set

data - The item to store for the field

Throws:

InvalidFieldException - The field index is not known

getUserData

public java.lang.Object getUserData(int index)
                             throws InvalidFieldException

Fetch the stored user data for a given field index. If nothing is registered, null is returned.

Specified by:

getUserData in interface VRMLNode

Parameters:

index - The index of destination field to set

Returns:

The item stored for the field or null

Throws:

InvalidFieldException - The field index is not known

isSetupFinished

public boolean isSetupFinished()

Check to see if setupFinished() has already been called on this node.

Specified by:

isSetupFinished in interface VRMLNodeType

Returns:

true if setupFinished() has been called

setupFinished

public void setupFinished()

Notification that the construction phase of this node has finished. If the node would like to do any internal processing, such as setting up geometry, then go for it now.

Specified by:

setupFinished in interface VRMLNodeType

setVersion

public void setVersion(int major,
                       int minor,
                       boolean isStatic)

Set the version of VRML that this node should represent. Different versions have different capabilities, even within the same node.

Specified by:

setVersion in interface VRMLNode

Parameters:

major - The major version number of this scene

minor - The minor version number of this scene

isStatic - true if this node is under a static group and won't change after the setup is finished