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 */