Package org.web3d.vrml.renderer.common.nodes

Class AbstractDynamicFieldNode

java.lang.Object

org.web3d.vrml.renderer.common.nodes.AbstractDynamicFieldNode

All Implemented Interfaces:

VRMLNode, FrameStateListener, VRMLNodeType

Direct Known Subclasses:

BaseScript

public abstract class AbstractDynamicFieldNode
extends Object
implements VRMLNodeType

Common functionality that represents a node that has its fields dynamically assigned.

Dynamic node structures are used in two places - scripts and protos. This class provides the common functionality for managing dynamically assigned fields.

The implementation does not handle deletion of fields particularly well at this point in time. Works fine if the node is not realised yet, but doesn't work well if the node is live.

Version:

$Revision: 1.22 $

Author:

Justin Couch

Field Summary

Fields

Modifier and Type	Field	Description
protected static final String	BAD_NODE_MSG	A standard message for when the supplied node is wrong.
protected org.j3d.util.ErrorReporter	errorReporter	Reporter instance for handing out errors
protected static final String	FIELD_CLASH_MSG	When the same field is defined twice, but with different types
protected int	fieldCount	The count of the last added field index
protected final List<VRMLFieldDeclaration>	fieldDeclList	List of the field maps registered in order for their definitions.
protected final Map<String,Integer>	fieldIndexMap	Data mapping holding the field name -> index (Integer) mapping
protected final ThreadLocal<VRMLFieldData>	fieldLocalData	Scratch class var for returning field data.
protected boolean	inSetup	Is this node still being setup/parsed.
protected boolean	isVrml97	Flag indicating this node is following VRML97 rules
protected int[]	layerIds	The list of layer IDs that reference this node.
protected static final String	METADATA_NODE_MSG	Message for when the node in setValue() is not a Metadata
protected static final String	METADATA_PROTO_MSG	Message for when the proto is not a Metadata
protected final String	nodeName	The name of the node.
protected VRMLProtoInstance	pMetadata	proto representation of the metadata node
protected int[]	refCounts	The current number of references to this node.
protected int[]	removedLayerIds	The list of IDs that have been marked as being removed.
protected FrameStateManager	stateManager	State manager for propagating updates
protected VRMLNodeType	vfMetadata	SFNode metadata NULL

Constructor Summary

Constructors

Constructor	Description
AbstractDynamicFieldNode(String name)	Create a new instance of a proto that has the given name.

Method Summary

Modifier and Type	Method	Description
void	addNodeListener(VRMLNodeListener l)	Add a listener to this node instance.
void	allEventsComplete()	Ignored by this implementation.
int	appendField(VRMLFieldDeclaration field)	Append a field declaration to this node.
protected void	checkNodeType(VRMLNodeType node)	Check to see if the supplied node type is the same as this node.
void	clearRemovedLayerIds()	Clear the current removed layer ID list.
void	deleteField(int index)	Delete the field at the given index.
void	deleteField(VRMLFieldDeclaration field)	Delete the named field.
protected void	fireFieldChanged(int index)	Send a notification to the registered listeners that a field has been changed.
List<VRMLFieldDeclaration>	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(String fieldName)	Get the index of the given field name.
int[]	getLayerIds()	Get a listing of the current layer IDs that are directly or indirectly referencing this node.
VRMLNodeType	getMetadataObject()	Get the currently registered vfMetadata object instance.
int[]	getNodeFieldIndices()	Get the list of indices that correspond to fields that contain nodes ie MFNode and SFNode).
int	getNumFields()	Get the number of fields.
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.
String	getVRMLNodeName()	Get the name of this node as a string.
boolean	isVRML97()	Check to see if the node is using VRML97 semantics
void	removeNodeListener(VRMLNodeListener l)	Remove a listener from this node instance.
void	setErrorReporter(org.j3d.util.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.
void	setFrameStateManager(FrameStateManager mgr)	Ignored by this implementation.
void	setMetadataObject(VRMLNodeType data)	Set the X3DMetadataObject that is associated with this node.
void	setupFinished()	Perform the setup completion routine.
void	updateRefCount(int layer, boolean add)	Change the reference count up or down by one for a given layer ID.

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.VRMLNode

getPrimaryType, getSecondaryType, getUserData, isDEF, setUserData, setVersion

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

getFieldValue, hasFieldChanged, isSetupFinished, notifyExternProtoLoaded, sendRoute, setDEF, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue

Field Details

BAD_NODE_MSG

protected static final String BAD_NODE_MSG

A standard message for when the supplied node is wrong. Just add the node name of the wrong type to the end.

See Also:

• Constant Field Values

METADATA_PROTO_MSG

protected static final String METADATA_PROTO_MSG

Message for when the proto is not a Metadata

See Also:

• Constant Field Values

METADATA_NODE_MSG

protected static final String METADATA_NODE_MSG

Message for when the node in setValue() is not a Metadata

See Also:

• Constant Field Values

FIELD_CLASH_MSG

protected static final String FIELD_CLASH_MSG

When the same field is defined twice, but with different types

See Also:

• Constant Field Values

errorReporter

protected org.j3d.util.ErrorReporter errorReporter

Reporter instance for handing out errors

fieldIndexMap

protected final Map<String,Integer> fieldIndexMap

Data mapping holding the field name -> index (Integer) mapping

fieldDeclList

protected final List<VRMLFieldDeclaration> fieldDeclList

List of the field maps registered in order for their definitions. When created, this list will have a null value in each index position for the size of the number of declared fields. This allows a user to set(int, object) the value if they want. However, it is recommended that you use the appendField(VRMLFieldDeclaration) method instead.

nodeName

protected final String nodeName

The name of the node. "Script" or the proto name.

fieldLocalData

protected final ThreadLocal<VRMLFieldData> fieldLocalData

Scratch class var for returning field data. Assigned at construction.

stateManager

protected FrameStateManager stateManager

State manager for propagating updates

fieldCount

protected int fieldCount

The count of the last added field index

isVrml97

protected boolean isVrml97

Flag indicating this node is following VRML97 rules

inSetup

protected boolean inSetup

Is this node still being setup/parsed. Cleared by setupFinished

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.

removedLayerIds

protected int[] removedLayerIds

The list of IDs that have been marked as being removed.

vfMetadata

protected VRMLNodeType vfMetadata

SFNode metadata NULL

pMetadata

protected VRMLProtoInstance pMetadata

proto representation of the metadata node

Constructor Details

AbstractDynamicFieldNode

public AbstractDynamicFieldNode(String name)

Create a new instance of a proto that has the given name.

Parameters:

name - The name of the proto to use

Method Details

allEventsComplete

public void allEventsComplete()

Ignored by this implementation.

Specified by:

allEventsComplete in interface FrameStateListener

setErrorReporter

public void setErrorReporter(org.j3d.util.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.

Specified by:

setErrorReporter in interface VRMLNode

Parameters:

reporter - The instance to use or null

getVRMLNodeName

public String getVRMLNodeName()

Get the name of this node as a string.

Specified by:

getVRMLNodeName in interface VRMLNode

Returns:

The name of the node

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

addNodeListener

public void addNodeListener(VRMLNodeListener l)

Add a listener to this node instance. If the listener is already added or null the request is silently ignored.

Specified by:

addNodeListener in interface VRMLNodeType

Parameters:

l - The listener instance to add

removeNodeListener

public void removeNodeListener(VRMLNodeListener l)

Remove a listener from this node instance. If the listener is null or not registered, the request is silently ignored.

Specified by:

removeNodeListener in interface VRMLNodeType

Parameters:

l - The listener to be removed

setFrameStateManager

public void setFrameStateManager(FrameStateManager mgr)

Ignored by this implementation.

Specified by:

setFrameStateManager in interface VRMLNodeType

Parameters:

mgr - The manager instance to use

setMetadataObject

public void setMetadataObject(VRMLNodeType data)
                       throws InvalidFieldValueException

Set the X3DMetadataObject that is associated with this node.

Specified by:

setMetadataObject in interface VRMLNodeType

Parameters:

data - The node to register as the vfMetadata

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 vfMetadata object instance. If none is set then return null.

Specified by:

getMetadataObject in interface VRMLNodeType

Returns:

The current vfMetadata object or null

setupFinished

public void setupFinished()

Perform the setup completion routine.

Specified by:

setupFinished in interface VRMLNodeType

getFieldIndex

public int getFieldIndex(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.

Specified by:

getFieldIndex in interface VRMLNode

Parameters:

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

Returns:

The index of the field name or -1

getNodeFieldIndices

public int[] getNodeFieldIndices()

Get the list of indices that correspond to fields that contain nodes ie MFNode and SFNode). Used for blind scene graph traversal without needing to spend time querying for all fields etc. If a node does not have any fields that contain nodes, this shall return null. The field list covers all field types, regardless of whether they are readable or not at the VRML-level.

Specified by:

getNodeFieldIndices in interface VRMLNode

Returns:

The list of field indices that correspond to SF/MFnode fields or null if none

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.

Specified by:

getFieldDeclaration in interface VRMLNode

Parameters:

index - The index of the field to get information

Returns:

A representation of this field's information

getNumFields

public int getNumFields()

Get the number of fields.

Specified by:

getNumFields in interface VRMLNode

Returns:

The number of fields.

checkNodeType

protected void checkNodeType(VRMLNodeType node)

Check to see if the supplied node type is the same as this node. It does a case sensitive string comparison based on thier node name. If they are not the same then an IllegalArgumentException is thrown. If the same, nothing happens.

Parameters:

node - The node to check

Throws:

IllegalArgumentException - The nodes are not the same

isVRML97

public boolean isVRML97()

Check to see if the node is using VRML97 semantics

Returns:

true if this is a VRML97 node

fireFieldChanged

protected void fireFieldChanged(int index)

Send a notification to the registered listeners that a field has been changed. If no listeners have been registered, then this does nothing, so always call it regardless.

Parameters:

index - The index of the field that changed

getFieldCount

public int getFieldCount()

Get the count of the number of fields currently registered.

Returns:

The number of fields available

appendField

public int appendField(VRMLFieldDeclaration field)
                throws FieldExistsException

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

deleteField

public void deleteField(int index)
                 throws InvalidFieldException,
IndexOutOfBoundsException

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

IndexOutOfBoundsException - The index provided is out of range for the current field numbers

deleteField

public void deleteField(VRMLFieldDeclaration field)
                 throws InvalidFieldException,
IndexOutOfBoundsException

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

IndexOutOfBoundsException - The index provided is out of range for the current field numbers

getAllFields

public List<VRMLFieldDeclaration> 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