nodenet.registrar
Interface NodeNameRegistrar

All Superinterfaces:

java.util.EventListener, java.beans.VetoableChangeListener

All Known Implementing Classes:

NodeNameRegistry, UniqueNodeNamePolicy

public interface NodeNameRegistrar

extends java.beans.VetoableChangeListener

A Registrar is an object that can track and validate the names of nodes. A registrar can also provide a legal name for a node. Current Node Names can be both registered and unregistered so that names can be reused if nodes are deleted. The * registrar may also provide access to a listing of registered names, and access to a node via it's name, but implementations may choose to throw an UnsupportedOperationException instead of providing these facilities.

Implicit in the design of this interface is the assumed existance of a public String getNodeName() and a public void setNodeName(String) or similar method on Node objects.

Version:

$Id: NodeNameRegistrar.java,v 1.5 2004/01/14 21:43:17 gus Exp $

Author:

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

Method Summary

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	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	unregister(Node aNode) Ensures that the specified node is nolonger registered.

Methods inherited from interface java.beans.VetoableChangeListener

vetoableChange

Method Detail

isLegalName

public boolean isLegalName(java.lang.String aName)

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.

Parameters:

aName - The node name to be tested.

Returns:

true if the name is legal, false otherwise.

getLegalName

public java.lang.String getLegalName()

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.

Returns:

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

getRegisteredNames

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

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.

Returns:

An array of node names currently in use.

Throws:

java.lang.UnsupportedOperationException

getNode

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

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.

Parameters:

aName - The name of the node to look for.

Returns:

A reference to the node if found, null otherwise.

Throws:

java.lang.UnsupportedOperationException

register

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

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 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.

Parameters:

aNode - The node that wishes to register itself.

Throws:

java.lang.IllegalArgumentException

unregister

public void unregister(Node aNode)

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

Parameters:

aNode - the node to unregister

isRegistered

public boolean isRegistered(Node aNode)

Tests to see if a node has been registered.

Parameters:

aNode - The node to test

Returns:

true if the node is registered false otherwise.

isRegistered

public boolean isRegistered(java.lang.String aName)

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.

Parameters:

aName - The node name to test

Returns:

true if the name is registered false otherwise.

nameAndRegister

public void nameAndRegister(Node aNode)

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).