nodenet.registrar
Class NodeNameRegistry

java.lang.Object
  nodenet.registrar.NodeNameRegistry

All Implemented Interfaces:

java.util.EventListener, NodeNameRegistrar, java.beans.VetoableChangeListener

public final class NodeNameRegistry

extends java.lang.Object

implements NodeNameRegistrar

Tracks all nodes and ensures that they have legal names. Besides providing legal names via the nameAndRegister(nodenet.Node) method it listens for changes to node names and vetos any attempt to create am illegal node name. To avoid multiple registry problems, this class is uses the sigleton pattern, and the one true NodeNameRegistrar can be obtained via the static method getInstance().

This implementation only checks for uniquenes of names, and accomodates up to Integer.MAX_VALUE nodes, wich is limited by the Vector class used to store node references. There is also a limit of Integer.MAX_VALUE name requests during the lifetime of this registrar object, as unique names are generated in the format "Node X" where X is replaced by an integer. If a node name is changed to "Node Y" where Y is an integer.

Version:

$Id: NodeNameRegistry.java,v 1.5 2004/01/14 21:04:16 gus Exp $

Author:

Patrick G. Heck, gus.heck@olin.edu

Method Summary

static NodeNameRegistry	getInstance() Factory method to get the one true NodeNameRegistrar.
java.lang.String	getLegalName() Provides a name that is currently legal.
Node	getNode(java.lang.String aName) Provides access to nodes via their registred name.
java.lang.String[]	getRegisteredNames() Provides a list of currently registered node names.
boolean	isLegalName(java.lang.String aName) Tests a name to see if it is currently legal.
boolean	isPolicySet() Check to see if the policy has been set for this registry.
boolean	isRegistered(Node aNode) Tests to see if a node has been registered.
boolean	isRegistered(java.lang.String aName) Tests to see if a name belongs to a registered node.
void	nameAndRegister(Node aNode) Gives the node a legal name and registers the node in one step.
void	register(Node aNode) Attempt to register a node.
void	setPolicy(NodeNameRegistrar policy) Set the registrartion policy one time only.
void	unregister(Node aNode) Ensures that the specified node is nolonger registered.
void	vetoableChange(java.beans.PropertyChangeEvent pce)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static NodeNameRegistry getInstance()

Factory method to get the one true NodeNameRegistrar.

Returns:

the registrar object.

setPolicy

public void setPolicy(NodeNameRegistrar policy)

Set the registrartion policy one time only. This method may not be invoked more than once. Subsequent invocations will throw an IllegalStateException. This is necessary to prevent the registered nodes from being lost. In the future a changePolicy method may be provided for "graceful" transition between policies. Note that "graceful" may include deletion of existing nodes.

Parameters:

policy - An naming policy implemented as a NodeNameRegistrar.

isPolicySet

public boolean isPolicySet()

Check to see if the policy has been set for this registry.

Returns:

true if the policy has been set, false otherwise

vetoableChange

public void vetoableChange(java.beans.PropertyChangeEvent pce)
                    throws java.beans.PropertyVetoException

Specified by:

vetoableChange in interface java.beans.VetoableChangeListener

Throws:

java.beans.PropertyVetoException

getLegalName

public java.lang.String getLegalName()

Description copied from interface: NodeNameRegistrar

Provides a name that is currently legal. The legality of the name is not guaranteed to remain legal for all time. This is particularly true if the policy implemented by the Registrar requires names to be unique. The implementation of this method should make a reasonable attempt not to give out names that will become illegal quickly, either due to temporal relevance of the name, or due to copetition between names given out to the clients. For example, this method should not give out the same node name on consecutive invocations if uniqueness is a qualification for legality.

Specified by:

getLegalName in interface NodeNameRegistrar

Returns:

A name that is currently legal, and should remain legal for a reasonable period of time, if possible.

getNode

public Node getNode(java.lang.String aName)
             throws java.lang.UnsupportedOperationException

Description copied from interface: NodeNameRegistrar

Provides access to nodes via their registred name. This method is optional, but if it is not implemented it should throw an UnsupportedOperationException rather than returning a bogus node or null.

Specified by:

getNode in interface NodeNameRegistrar

Parameters:

aName - The name of the node to look for.

Returns:

A reference to the node if found, null otherwise.

Throws:

java.lang.UnsupportedOperationException

getRegisteredNames

public java.lang.String[] getRegisteredNames()
                                      throws java.lang.UnsupportedOperationException

Description copied from interface: NodeNameRegistrar

Provides a list of currently registered node names. This method is optional, but if it is not implemented it should throw an UnsupportedOperationException rather than returning a bogus list or null.

Specified by:

getRegisteredNames in interface NodeNameRegistrar

Returns:

An array of node names currently in use.

Throws:

java.lang.UnsupportedOperationException

isLegalName

public boolean isLegalName(java.lang.String aName)

Description copied from interface: NodeNameRegistrar

Tests a name to see if it is currently legal. The legality of the name is not guaranteed to remain invariant for all time. This is particularly true if the policy implemented by the Registrar requires names to be unique.

Specified by:

isLegalName in interface NodeNameRegistrar

Parameters:

aName - The node name to be tested.

Returns:

true if the name is legal, false otherwise.

isRegistered

public boolean isRegistered(java.lang.String aName)

Description copied from interface: NodeNameRegistrar

Tests to see if a name belongs to a registered node. For obvious reasons the results of this test are only valid while the client has a lock on the registry.

Specified by:

isRegistered in interface NodeNameRegistrar

Parameters:

aName - The node name to test

Returns:

true if the name is registered false otherwise.

isRegistered

public boolean isRegistered(Node aNode)

Description copied from interface: NodeNameRegistrar

Tests to see if a node has been registered.

Specified by:

isRegistered in interface NodeNameRegistrar

Parameters:

aNode - The node to test

Returns:

true if the node is registered false otherwise.

nameAndRegister

public void nameAndRegister(Node aNode)

Description copied from interface: NodeNameRegistrar

Gives the node a legal name and registers the node in one step. This method guarantees that the node will be registered, and no exceptions should be thrown. The node to be registered must expose a method with the signature setName(String).

Specified by:

nameAndRegister in interface NodeNameRegistrar

register

public void register(Node aNode)
              throws java.lang.IllegalArgumentException

Description copied from interface: NodeNameRegistrar

Attempt to register a node. This method proposes to register a node with an existing name. The node will be rejected if and only if it contains a name that would currently generate a false response from NodeNameRegistrar.isLegalName(String). If the name contained in the node is rejected, The node is not registered or tracked in any way and an IllegalArgumentException will be thrown.

Specified by:

register in interface NodeNameRegistrar

Parameters:

aNode - The node that wishes to register itself.

Throws:

java.lang.IllegalArgumentException

unregister

public void unregister(Node aNode)

Description copied from interface: NodeNameRegistrar

Ensures that the specified node is nolonger registered. If the node was never registred, it simply returns with no side effects.

Specified by:

unregister in interface NodeNameRegistrar

Parameters:

aNode - the node to unregister