Package 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

Nested Classes
Modifier and Type
Class
Description
`static interface`
`Node.Attributes`
An interface for exposing access to the private attributes.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Logger`
`err`
A ``Logger`` for logging error messages.
`static final Logger`
`info`
A ``Logger`` for logging information messages..

## Method Summary

Modifier and Type
Method
Description
`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 Details

### 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 Details

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