org.jcsp.net
Class Node

java.lang.Object
  org.jcsp.net.Node

public class Node
extends Object

This class that is used for initializing and managing the local JCSP.NET Node. A JCSP Node is a Java Virtual Machine that has been initialized to form part of a JCSP.NET network. By this definition, only one instance of this class is ever required on any JVM. Therefore this class is a singleton class.To obtain the instance of this class, use the getInstance() method.

Node Initialization

Before any JCSP.NET constructs can be used, the Node must be initialized. There are several init() methods for initializing the Node in different ways.

In order for a Node to be initialized, there are various settings that are required and others which are useful to have. A key facility of a Node is to be able to communicate with other Nodes. This requires at least one communications protocol to be installed and also ideally an address on which to listen for incoming connections. As well as protocols, there are various services that a user might want to start when ever the Node is initialized. Technically the Node could be initialized and have its protocols, addresses and services set up manually by the user. This would, however, be rather cumbersome.

The JCSP.NET infrastructure is not dependent upon any one network protocol. The org.jcsp.net.tcpip package is provided but could easily be replaced by an alternate protocol implementation. In the real world, TCP/IP is likely to suit many uses and so this class assumes this as a default protocol. With this assumption, it is possible to initialize the Node without any further information. A Node can be initialized which installs TCP/IP as a protocol and listens on all local IP addresses. This is precisely the bahaviour of the init() method with no parameters.

One of the facilities that most JCSP.NET users are likely to use is the Channel Name Server. This requires a server process to be running on a JCSP.NET Node and client services on all Nodes that wish to use the server. Assuming that a Channel Name Server is running, then at the time of Node initialization, the knowledge of this server's address is required.

The TCPIPNodeFactory has knowledge of the Channel Name Server and has code for starting the client service on a Node. It provides a constructor which takes the address of the channel name server. An instance of the class can be created with this constructor and passed to the init(NodeFactory) method. If the parameterless init() is used, then an instance of the factory is created using its instantiate method which takes no settings. This tries to determine the address of the Channel Name Service through other means (including system properties and the preferences API etc.). See TCPIPNodeFactory for more information on this.

Another NodeFactory class provided with JCSP.NET is the XMLNodeFactory. This reads its settings from an XML-like config file. This is not a full XML file as JCSP.NET provides its own parser. This saves pre Java 1.4 users from obtaining an XML parsing package. See XMLNodeFactory for full documentation on how to use this.

As well as initialization methods which take NodeFactory objects, there are also methods which take protocol settings directly. See the init(NodeAddressID), init(NodeAddressID[]) and init(NodeAddressID[], Hashtable[]) methods.

All of the Node init methods return a NodeKey object which is required for Node management methods.

Node Management

Once initialized, JCSP Nodes can have their settings altered. There are two manager classes of which each Node has an instance; ServiceManager and ProtocolManager. These instances can be obtained from the local Node object by calling their respective accessors (getServiceManager(org.jcsp.net.NodeKey) and getProtocolManager(org.jcsp.net.NodeKey)). Each of these accessors takes a NodeKey object as a parameter. This is for security reasons. Any process can obtain a reference to the local Node object. Without this key parameter, any process could therefore perform Node management operations. This key allows gives control of access to these methods to the process which initialized the Node. This process can decide who it trusts.

See ServiceManager and ProtocolManager for more information.

Logging

The Node class provides two static Logger objects for programs to log information. info provides facilities for logging information messages. err provides facilities for logging error messages. The output from these logging objects can be enabled or disabled. See Logger for more information.

Author:

Quickstone Technologies Limited

Nested Class Summary

static interface

Node.Attributes An interface for exposing access to the private attributes.

Field Summary

static Logger	err A Logger for logging error messages.
static Logger	info A Logger for logging information messages..

Method Summary

static Node	getInstance() Returns the instance of this singleton class.
AltingChannelInput	getLinkLostEventChannel() This method allows users to obtain notification of link failure.
ApplicationID	getNewApplicationID()
NodeID	getNodeID() Method for obtaining a clone of this Node's NodeID.
org.jcsp.net.Specification[]	getNodeSpecifications() Returns an array of Specification objects to which this Node conforms.
ProtocolManager	getProtocolManager(NodeKey nodeKey) Accessor for obtaining a reference to the local Node's ProtocolManager object.
ServiceManager	getServiceManager(NodeKey nodeKey) Accessor for obtaining a reference to the local Node's ServiceManager object.
ServiceUserObject	getServiceUserObject(String name) Obtains a ServiceUserObject from a named Service and returns a reference to it.
NodeKey	init() Initializes the Node with the current static NodeFactory.
NodeKey	init(NodeAddressID localAddress) This method functions the same as calling init(NodeAddressID[]) with a single element in the array.
NodeKey	init(NodeAddressID[] localAddresses) This method is functionally equivalent to calling init(NodeAddressID[], HashTable) with the HashTable parameter being supplied as null.
NodeKey	init(NodeAddressID[] localAddresses, Hashtable[] protocolSettings) Initializes the local Node and starts LinkServer listening on each of the supplied NodeAddressID objects.
NodeKey	init(NodeFactory factory) Initializes the Node with the specified NodeFactory object.
boolean	isInitialized() Returns true if the node has already been initialized, false otherwise.
boolean	isThisNode(NodeID nodeID) This method allows a NodeID to be checked to see whether it represents the local Node.
boolean	linkExists(NodeID otherNode) This method tests whether a link currently exists to a specified remote Node.
static void	setNodeFactory(NodeFactory fac)
boolean	verifyKey(NodeKey nodeKey) Verifies that the supplied key matches the local Node's key.

Methods inherited from class java.lang.Object

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

Field Detail

info

public static final Logger info

A Logger for logging information messages..

err

public static final Logger err

A Logger for logging error messages.

Method Detail

getInstance

public static Node getInstance()

Returns the instance of this singleton class.

Returns:

the instance of Node.

setNodeFactory

public static void setNodeFactory(NodeFactory fac)

init

public NodeKey init(NodeAddressID localAddress)
             throws IllegalStateException,
                    IllegalArgumentException,
                    NodeInitFailedException

This method functions the same as calling init(NodeAddressID[]) with a single element in the array.

Parameters:

localAddress - an address on which to start a LinkServer process.

Returns:

the NodeKey required for Node management.

Throws:

IllegalStateException - if the local Node has already been initialized.

IllegalArgumentException - if no addresses are supplied.

NodeInitFailedException - if the Node is not able to initialize.

init

public NodeKey init(NodeAddressID[] localAddresses)
             throws IllegalStateException,
                    IllegalArgumentException,
                    NodeInitFailedException

This method is functionally equivalent to calling init(NodeAddressID[], HashTable) with the HashTable parameter being supplied as null.

Parameters:

localAddresses - the addresses on which to start LinkServer processes.

Returns:

the NodeKey required for Node management.

Throws:

IllegalStateException - if the local Node has already been initialized.

IllegalArgumentException - if no addresses are supplied.

NodeInitFailedException - if the Node is not able to initialize.

init

public NodeKey init(NodeAddressID[] localAddresses,
                    Hashtable[] protocolSettings)
             throws IllegalStateException,
                    IllegalArgumentException,
                    NodeInitFailedException

Initializes the local Node and starts LinkServer listening on each of the supplied NodeAddressID objects. The protocols that match each address are also installed in the local protocol manager. If protocol settings are supplied, then these are used when the protocols are installed.

A key is returned that needs to be supplied to certain management methods.

Parameters:

localAddresses - the addresses on which to start LinkServer processes.

protocolSettings - an array of HashTable objects each containing settings for the protocols to be installed. Each HashTable is passed to the protocol's ProtocolID object's getLinkBuilder(HashTable) method. No restriction is placed on protocol implementations as to how this HashTable object be used. See the documentation for whatever protocol implementation is being used.

Returns:

the NodeKey required for Node management.

Throws:

IllegalStateException - if the local Node has already been initialized.

IllegalArgumentException - if no addresses are supplied.

NodeInitFailedException - if the Node is not able to initialize.

init

public NodeKey init()
             throws NodeInitFailedException

Initializes the Node with the current static NodeFactory. This can be set by calling the setNodeFactory(NodeFactory) method.

This default factory is currently the TCPIPNodeFactory. This is instantiated with its instantiate() method.

Returns:

the NodeKey required for Node management.

Throws:

NodeInitFailedException - if the Node is not able to initialize.

See Also:

init(NodeFactory)

init

public NodeKey init(NodeFactory factory)
             throws NodeInitFailedException

Initializes the Node with the specified NodeFactory object.

This invokes the factory's initNode(Node, Node.Attributes) method to actually perform the initialization.

This package provides an XMLNodeFactory which instantiates the Node from settings read from an XML-like config file.

Returns:

the NodeKey required for Node management.

Throws:

NodeInitFailedException - if the Node is not able to initialize.

isThisNode

public boolean isThisNode(NodeID nodeID)
                   throws IllegalStateException

This method allows a NodeID to be checked to see whether it represents the local Node. It is provided as a more efficient way of performing this check than obtaining the local node and checking manually. This would result in the local NodeID object being cloned.

Parameters:

nodeID - a NodeID to check against the local Node's NodeID.

Returns:

boolean indicating whether the address supplied is local.

Throws:

IllegalStateException - if the local Node has not been initialized.

isInitialized

public boolean isInitialized()

Returns true if the node has already been initialized, false otherwise.

Returns:

a true iff Node has been initialized.

getNodeID

public NodeID getNodeID()
                 throws IllegalStateException

Method for obtaining a clone of this Node's NodeID.

This method does not expose the actual underlying object as it is not immutable.

Returns:

this Node's NodeID. A clone of the one held by this class.

Throws:

IllegalStateException - if this Node has not been initialized.

getNewApplicationID

public ApplicationID getNewApplicationID()

getProtocolManager

public ProtocolManager getProtocolManager(NodeKey nodeKey)

Accessor for obtaining a reference to the local Node's ProtocolManager object. The local Node's key must be supplied in order to obtain this reference. This prevents any unauthorized code from managing the local Node's communication protocols.

Parameters:

nodeKey - the local Node's NodeKey.

Returns:

the local Node's ProtocolManager or null> if an incorrect key is supplied.

getServiceManager

public ServiceManager getServiceManager(NodeKey nodeKey)

Accessor for obtaining a reference to the local Node's ServiceManager object. The local Node's key must be supplied in order to obtain this reference. This prevents any unauthorized code from managing the local Node's services.

Parameters:

nodeKey - the local Node's NodeKey.

Returns:

the local Node's ServiceManager or null> if an incorrect key is supplied.

getServiceUserObject

public ServiceUserObject getServiceUserObject(String name)

Obtains a ServiceUserObject from a named Service and returns a reference to it. This method calls getService(String) on a Service object and will therefore obey the rules implemented in the requested Service.

Generally, services are expected to check whether the requesting process has permission to access the user object and throw a SecurityException if access is denied.

Returns:

a ServiceUserObject object.

verifyKey

public boolean verifyKey(NodeKey nodeKey)

Verifies that the supplied key matches the local Node's key.

Parameters:

nodeKey - a NodeKey to check against that of the local Node's.

Returns:

true iff the supplied key matches the local Node's key.

getNodeSpecifications

public org.jcsp.net.Specification[] getNodeSpecifications()

Returns an array of Specification objects to which this Node conforms.

Returns:

the set of defined Specification objects for this Node.

linkExists

public boolean linkExists(NodeID otherNode)

This method tests whether a link currently exists to a specified remote Node.

Parameters:

otherNode - The NodeID of a remote Node to check the existance

Returns:

true iff a link currently exists to the specified remote Node.

getLinkLostEventChannel

public AltingChannelInput getLinkLostEventChannel()

This method allows users to obtain notification of link failure.

The API surrounding these events is new and will possibly change. Users should be aware of this and only use if stricly necessary.

This returns an AltingChannelInput which will receive events signifying that a link to a particular Node has be been dropped. This will receive NodeID objects which signigy the remote Nodes at the other end of links which have been dropped.

Returns:

the AltingChannelInput event channel.