001    /*
002     * Packet.java
003     *
004     * Developed for the "Rethinking CS101" project. See http://www.cs101.org, the
005     * CS101 homepage or email las@olin.edu.
006     *
007     * Created on February 24, 2003, 8:20 AM
008     * Please do not redistribute without obtaining permission.
009     */
010    
011    package nodenet;
012    
013    import java.util.Vector;
014    
015    /**
016     * An object that can be sent across the network. Currently all code
017     * ignores the fact that packets are more than Objects, but in future versions
018     * the destination and the list of visited nodes may become significant.
019     *
020     * @author Patrick G. Heck, gus.heck@olin.edu
021     * $Id: Packet.java,v 1.6 2004/01/14 21:43:17 gus Exp $
022     */
023    public class Packet implements Cloneable {
024        
025        private String dest;
026        private Vector visited = new Vector();
027        
028        /** Creates a new instance of Packet */
029        public Packet(String dest) {
030            this.dest = dest;
031        }
032        
033        
034        /**
035         * Find out where the packet is headed.
036         *
037         * @return the destination set for this packet if any
038         */
039        public String getDest() {
040            return this.dest;
041        }
042        
043        /**
044         * Return a clone of the Packet. The cloned object is guaranteed to
045         * be an independant copy of the current object and not share any
046         * instances of mutable classes with the parent object. Immutable
047         * classes may or may not be shared. Client code should not rely on
048         * sharing of immutable classes since this may break in future
049         * implementations.
050         *
051         * @return a clone of the object.
052         */
053        public Object clone() {
054            Packet tmp;
055            try {
056                tmp = (Packet) super.clone();
057            } catch (CloneNotSupportedException cnse) {
058                // The language actually guarantees this won't happen,
059                // but we must catch it anyway
060                throw new Error("Java is broken! Arghhhhhh... run for your life!");
061            }
062            
063            tmp.visited = getVisitList();
064            return tmp;
065        }
066        
067        /**
068         * Record that a node was visited.
069         *
070         * @param nodeName the name of the node to be reocorded
071         */
072        
073        public void logVisit(String nodeName) {
074            visited.add(nodeName);
075        }
076        
077        /**
078         * Get a list of the nodes visited, if they have been recorded.
079         * For this to be useful, the NodeBehaviors must invoke
080         * {@link #logVisit(String)} when they handle a packet.
081         *
082         * @return A <em>copy</em> of the list of the nodes visited.
083         */
084        public final Vector getVisitList() {
085            Vector tmp = new Vector();
086            for (int i=0; i<visited.size();i++) {
087                // NOTE: casting to String below, to ensure that any attempt to
088                // store something other than strings in visited (in later
089                // versions) is forced to read this comment, and is aware that
090                // this method is used in the clone method. This means that
091                // the line below will need to clone objects in the vector
092                // to avoid having 2 vectors pointing to the same objects,
093                // or use immutable classes (pointing to the same
094                // instance of an immutable class is not a problem).
095                //
096                // The current implementation is acceptable because String is
097                // an immutable class.
098                tmp.add(((String)visited.get(i)));
099            }
100            return tmp;
101        }
102    }
103    
104    /*
105     * $Log: Packet.java,v $
106     * Revision 1.6  2004/01/14 21:43:17  gus
107     * more javadoc, plus reformat
108     *
109     * Revision 1.5  2004/01/14 21:04:16  gus
110     * More javadoc fixes
111     *
112     * Revision 1.4  2004/01/14 20:23:21  gus
113     * Javadoc and comment cleanup
114     *
115     * Revision 1.3  2003/02/24 17:48:50  gus
116     * Add the ability for packets to remember where they have been.
117     *
118     * Revision 1.2  2003/02/24 16:27:47  gus
119     * added Log comment
120     *
121     */