001    /*
002     * Registrar.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 20, 2003, 10:29 AM
008     */
009    
010    package nodenet.registrar;
011    
012    import nodenet.Node;
013    import java.beans.VetoableChangeListener;
014    
015    /**
016     * A Registrar is an object that can track and validate the names of nodes.
017     * A registrar can also provide a legal name for a node. Current Node Names
018     * can be both registered and unregistered so that names can be reused if
019     * nodes are deleted. The  * registrar may also provide access to a listing
020     * of registered names, and access to a node via it's name, but
021     * implementations may choose to throw an
022     * <code>UnsupportedOperationException</code> instead of providing these
023     * facilities. <p>
024     *
025     * Implicit in the design of this interface is the assumed existance of a
026     * <code>public String getNodeName()</code> and a
027     * <code>public void setNodeName(String)</code> or similar method on
028     * <code>Node</code> objects.
029     *
030     * @author  Patrick G, Heck, gus.heck@olin.edu
031     * @version $Id: NodeNameRegistrar.java,v 1.5 2004/01/14 21:43:17 gus Exp $
032     */
033    public interface NodeNameRegistrar extends VetoableChangeListener {
034        
035        /**
036         * Tests a name to see if it is currently legal. The legality of the name is
037         * not guaranteed to remain invariant for all time. This is particularly
038         * true if the policy implemented by the <code>Registrar</code> requires
039         * names to be unique.
040         *
041         * @param   aName   The node name to be tested.
042         * @return <code>true</code> if the name is legal, <code>false</code>
043         *          otherwise.
044         */
045        public boolean isLegalName(String aName);
046        
047        /**
048         * Provides a name that is currently legal. The legality of the name is
049         * not guaranteed to remain legal for all time. This is particularly true
050         * if the policy implemented by the <code>Registrar</code> requires names
051         * to be unique. The implementation of this method should make a reasonable
052         * attempt not to give out names that will become illegal quickly, either
053         * due to temporal relevance of the name, or due to copetition between
054         * names given out to the clients. For example, this method should not
055         * give out the same node name on consecutive invocations if uniqueness is
056         * a qualification for legality.
057         *
058         * @return A name that is currently legal, and should remain legal for a
059         *          reasonable period of time, if possible.
060         */
061        public String getLegalName();
062        
063        /**
064         * Provides a list of currently registered node names. This method is
065         * optional, but if it is not implemented it should throw an
066         * <code>UnsupportedOperationException</code> rather than returning
067         * a bogus list or null.
068         *
069         * @return An array of node names currently in use.
070         */
071        public String[] getRegisteredNames() throws UnsupportedOperationException;
072        
073        /**
074         * Provides access to nodes via their registred name. This method is
075         * optional, but if it is not implemented it should throw an
076         * <code>UnsupportedOperationException</code> rather than returning
077         * a bogus node or null.
078         *
079         * @param aName   The name of the node to look for.
080         * @return        A reference to the node if found, null otherwise.
081         */
082        public Node getNode(String aName) throws UnsupportedOperationException;
083        
084        /**
085         * Attempt to register a node. This method proposes to register a node
086         * with an existing name. The node will be rejected if and only if it
087         * contains a name that would currently generate a false response
088         * from {@link #isLegalName(String)}. If the name contained in the node
089         * is rejected, The node is not registered or tracked in any way and an
090         * <code>IllegalArgumentException</code> will be thrown.
091         *
092         * @param aNode The node that wishes to register itself.
093         */
094        public void register(Node aNode) throws IllegalArgumentException;
095        
096        /**
097         * Ensures that the specified node is nolonger registered. If the node
098         * was never registred, it simply returns with no side effects.
099         *
100         * @param aNode the node to unregister
101         */
102        public void unregister(Node aNode);
103        
104        /**
105         * Tests to see if a node has been registered.
106         *
107         * @param aNode The node to test
108         * @return <code>true</code> if the node is registered <code>false</code>
109         *         otherwise.
110         */
111        public boolean isRegistered(Node aNode);
112        /**
113         * Tests to see if a name belongs to a registered node. For obvious reasons
114         * the results of this test are only valid while the client has a lock
115         * on the registry.
116         *
117         * @param aName The node name to test
118         * @return <code>true</code> if the name is registered <code>false</code>
119         *         otherwise.
120         */
121        public boolean isRegistered(String aName);
122        
123        /**
124         * Gives the node a legal name and registers the node in one step. This
125         * method guarantees that the node will be registered, and no exceptions
126         * should be thrown. The node to be registered must expose a method
127         * with the signature setName(String).
128         */
129        public void nameAndRegister(Node aNode);
130        
131    }
132    
133    /*
134     * $Log: NodeNameRegistrar.java,v $
135     * Revision 1.5  2004/01/14 21:43:17  gus
136     * more javadoc, plus reformat
137     *
138     * Revision 1.4  2004/01/14 21:04:16  gus
139     * More javadoc fixes
140     *
141     * Revision 1.3  2004/01/14 20:23:21  gus
142     * Javadoc and comment cleanup
143     *
144     * Revision 1.2  2003/02/25 22:35:18  gus
145     * adding log comment
146     *
147     */