updateNodeReferences method called by the
* cloneTree method.
* The NodeReferenceTable maps nodes from the original subgraph
* to the new nodes in the cloned subgraph. This information
* can then be used to update any cloned leaf node references
* to reference nodes in the cloned subgraph.
*
* During a cloneTree call, after all nodes have been duplicated,
* each SceneGraphObject's updateNodeReferences method is called.
* This method takes a NodeReferenceTable object as a parameter. The
* SceneGraphObject's updateNodeReferences method can then use the
* getNewObjectReference method from this object to get updated
* references to objects that have been duplicated in the new cloneTree
* sub-graph. If a match is found, a
* reference to the corresponding SceneGraphObject in the newly cloned sub-graph
* is returned. If no corresponding reference is found, either a
* DanglingReferenceException is thrown by the cloneTree
* method or a reference to the original
* SceneGraphObject is returned depending on the value of the
* allowDanglingReferences parameter passed in the
* cloneTree call.
* @see SceneGraphObject#updateNodeReferences
* @see Node#cloneTree
* @see DanglingReferenceException
*/
public class NodeReferenceTable extends Object {
Hashtable objectHashtable;
boolean allowDanglingReferences;
/**
* Constructs an empty NodeReferenceTable.
* @since Java 3D 1.2
*/
public NodeReferenceTable() {
}
// Constructor - this is NOT public!
NodeReferenceTable(boolean allowDanglingReferences,
Hashtable objectHashtable) {
set(allowDanglingReferences, objectHashtable);
}
void set(boolean allowDanglingReferences,
Hashtable objectHashtable) {
this.objectHashtable = objectHashtable;
this.allowDanglingReferences = allowDanglingReferences;
}
/**
* This method is used in conjunction with the cloneTree
* method. It can be used by the updateNodeReferences
* method to see if a SceneGraphObject that is being referenced has been duplicated
* in the new cloneTree sub-graph.
*
* A SceneGraphObject's updateNodeReferences method would use this
* method by calling it with the reference to the old (existed before
* the cloneTree operation) object. If the object has been duplicated
* in the cloneTree sub-graph, the corresponding object in the cloned
* sub-graph is returned. If no corresponding reference is found, either
* a DanglingReferenceException is thrown or a reference to the original
* SceneGraphObject is returned depending on the value of the
* allowDanglingReferences parameter passed in the
* cloneTree call.
*
* @param oldReference the reference to the object in
* the original sub-graph.
*
* @return A reference to the corresponding object in the cloned
* sub-graph. If no corresponding object exists, either a
* DanglingReferenceException will be generated by the
* cloneTree method or a reference to the original object
* is returned depending on the value of the
* allowDanglingReferences parameter passed in the
* cloneTree call.
*
* @see SceneGraphObject#updateNodeReferences
* @see Node#cloneTree
* @see DanglingReferenceException
*/
public final SceneGraphObject
getNewObjectReference(SceneGraphObject oldReference) {
// look up original SceneGraphObject in hash table
SceneGraphObject newObject =
(SceneGraphObject)objectHashtable.get(oldReference);
if (newObject != null) {
// found new reference
return newObject;
}
// dangling reference found!
if (allowDanglingReferences == true) {
return oldReference;
}
// dangling references not allowed
throw new DanglingReferenceException();
}
}