001: /*
002: * $RCSfile: NodeReferenceTable.java,v $
003: *
004: * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:26 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.util.Hashtable;
035:
036: /**
037: * The NodeReferenceTable object is used by a leaf node's
038: * <code>updateNodeReferences</code> method called by the
039: * <code>cloneTree</code> method.
040: * The NodeReferenceTable maps nodes from the original subgraph
041: * to the new nodes in the cloned subgraph. This information
042: * can then be used to update any cloned leaf node references
043: * to reference nodes in the cloned subgraph.
044: * <P>
045: * During a <code>cloneTree</code> call, after all nodes have been duplicated,
046: * each SceneGraphObject's <code>updateNodeReferences</code> method is called.
047: * This method takes a NodeReferenceTable object as a parameter. The
048: * SceneGraphObject's <code>updateNodeReferences</code> method can then use the
049: * <code>getNewObjectReference</code> method from this object to get updated
050: * references to objects that have been duplicated in the new cloneTree
051: * sub-graph. If a match is found, a
052: * reference to the corresponding SceneGraphObject in the newly cloned sub-graph
053: * is returned. If no corresponding reference is found, either a
054: * DanglingReferenceException is thrown by the <code>cloneTree</code>
055: * method or a reference to the original
056: * SceneGraphObject is returned depending on the value of the
057: * <code>allowDanglingReferences</code> parameter passed in the
058: * <code>cloneTree</code> call.
059: * @see SceneGraphObject#updateNodeReferences
060: * @see Node#cloneTree
061: * @see DanglingReferenceException
062: */
063: public class NodeReferenceTable extends Object {
064:
065: Hashtable objectHashtable;
066: boolean allowDanglingReferences;
067:
068: /**
069: * Constructs an empty NodeReferenceTable.
070: * @since Java 3D 1.2
071: */
072: public NodeReferenceTable() {
073: }
074:
075: // Constructor - this is NOT public!
076: NodeReferenceTable(boolean allowDanglingReferences,
077: Hashtable objectHashtable) {
078: set(allowDanglingReferences, objectHashtable);
079: }
080:
081: void set(boolean allowDanglingReferences, Hashtable objectHashtable) {
082: this .objectHashtable = objectHashtable;
083: this .allowDanglingReferences = allowDanglingReferences;
084: }
085:
086: /**
087: * This method is used in conjunction with the <code>cloneTree</code>
088: * method. It can be used by the <code>updateNodeReferences</code>
089: * method to see if a SceneGraphObject that is being referenced has been duplicated
090: * in the new cloneTree sub-graph.
091: * <P>
092: * A SceneGraphObject's <code>updateNodeReferences</code> method would use this
093: * method by calling it with the reference to the old (existed before
094: * the cloneTree operation) object. If the object has been duplicated
095: * in the cloneTree sub-graph, the corresponding object in the cloned
096: * sub-graph is returned. If no corresponding reference is found, either
097: * a DanglingReferenceException is thrown or a reference to the original
098: * SceneGraphObject is returned depending on the value of the
099: * <code>allowDanglingReferences</code> parameter passed in the
100: * <code>cloneTree</code> call.
101: *
102: * @param oldReference the reference to the object in
103: * the original sub-graph.
104: *
105: * @return A reference to the corresponding object in the cloned
106: * sub-graph. If no corresponding object exists, either a
107: * DanglingReferenceException will be generated by the
108: * <code>cloneTree</code> method or a reference to the original object
109: * is returned depending on the value of the
110: * <code>allowDanglingReferences</code> parameter passed in the
111: * <code>cloneTree</code> call.
112: *
113: * @see SceneGraphObject#updateNodeReferences
114: * @see Node#cloneTree
115: * @see DanglingReferenceException
116: */
117: public final SceneGraphObject getNewObjectReference(
118: SceneGraphObject oldReference) {
119:
120: // look up original SceneGraphObject in hash table
121: SceneGraphObject newObject = (SceneGraphObject) objectHashtable
122: .get(oldReference);
123:
124: if (newObject != null) {
125: // found new reference
126: return newObject;
127: }
128:
129: // dangling reference found!
130: if (allowDanglingReferences == true) {
131: return oldReference;
132: }
133:
134: // dangling references not allowed
135: throw new DanglingReferenceException();
136: }
137:
138: }
|