Class Node
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
method.
getInstance()
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
method with no parameters.
init()
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
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 TCPIPNodeFactory
method.
If the parameterless init(NodeFactory)
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
init()
for
more information on this.
TCPIPNodeFactory
Another NodeFactory
class provided with JCSP.NET is the
. 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.
XMLNodeFactory
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;
and ServiceManager
.
These instances can be obtained from the local ProtocolManager
Node
object by
calling their respective accessors (
and getServiceManager(org.jcsp.net.NodeKey)
). Each of these accessors takes
a getProtocolManager(org.jcsp.net.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.
NodeKey
See
and
ServiceManager
for more information.
ProtocolManager
Logging
The Node class provides two static
objects for
programs to log information. Logger
provides
facilities for logging information messages. info
provides facilities for logging error messages. The output from these
logging objects can be enabled or disabled. See err
for more information.
Logger
- Author:
- Quickstone Technologies Limited
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
An interface for exposing access to the private attributes. -
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionstatic Node
Returns the instance of this singleton class.This method allows users to obtain notification of link failure.Method for obtaining a clone of this Node'sNodeID
.org.jcsp.net.Specification[]
Returns an array ofSpecification
objects to which this Node conforms.getProtocolManager
(NodeKey nodeKey) Accessor for obtaining a reference to the local Node'sProtocolManager
object.getServiceManager
(NodeKey nodeKey) Accessor for obtaining a reference to the local Node'sServiceManager
object.getServiceUserObject
(String name) Obtains aServiceUserObject
from a named Service and returns a reference to it.init()
Initializes the Node with the current staticNodeFactory
.init
(NodeAddressID localAddress) This method functions the same as callinginit(NodeAddressID[])
with a single element in the array.init
(NodeAddressID[] localAddresses) This method is functionally equivalent to callinginit(NodeAddressID[], HashTable)
with theHashTable
parameter being supplied asnull
.init
(NodeAddressID[] localAddresses, Hashtable[] protocolSettings) Initializes the local Node and startsLinkServer
listening on each of the suppliedNodeAddressID
objects.init
(NodeFactory factory) Initializes the Node with the specified
object.NodeFactory
boolean
Returnstrue
if the node has already been initialized,false
otherwise.
boolean
isThisNode
(NodeID nodeID) This method allows aNodeID
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
boolean
Verifies that the supplied key matches the local Node's key.
-
Field Details
-
Method Details
-
getInstance
Returns the instance of this singleton class.- Returns:
- the instance of Node.
-
setNodeFactory
-
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 aLinkServer
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 theHashTable
parameter being supplied asnull
.- Parameters:
localAddresses
- the addresses on which to startLinkServer
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 suppliedNodeAddressID
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 startLinkServer
processes.protocolSettings
- an array ofHashTable
objects each containing settings for the protocols to be installed. EachHashTable
is passed to the protocol'sProtocolID
object'sgetLinkBuilder(HashTable)
method. No restriction is placed on protocol implementations as to how thisHashTable
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
Initializes the Node with the current static
NodeFactory
. This can be set by calling the
method.setNodeFactory(NodeFactory)
This default factory is currently the
. This is instantiated with itsTCPIPNodeFactory
instantiate()
method.- Returns:
- the
NodeKey
required for Node management. - Throws:
NodeInitFailedException
- if the Node is not able to initialize.- See Also:
-
init
Initializes the Node with the specified
object.NodeFactory
This invokes the factory's
initNode(Node, Node.Attributes)
method to actually perform the initialization.This package provides an
which instantiates the Node from settings read from an XML-like config file.XMLNodeFactory
- Returns:
- the
NodeKey
required for Node management. - Throws:
NodeInitFailedException
- if the Node is not able to initialize.
-
isThisNode
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 localNodeID
object being cloned.- Parameters:
nodeID
- aNodeID
to check against the local Node'sNodeID
.- 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
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
-
getProtocolManager
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'sNodeKey
.- Returns:
- the local Node's
ProtocolManager
ornull>
if an incorrect key is supplied.
-
getServiceManager
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'sNodeKey
.- Returns:
- the local Node's
ServiceManager
ornull>
if an incorrect key is supplied.
-
getServiceUserObject
Obtains a
ServiceUserObject
from a named Service and returns a reference to it. This method callsgetService(String)
on aService
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
Verifies that the supplied key matches the local Node's key.
- Parameters:
nodeKey
- aNodeKey
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
This method tests whether a link currently exists to a specified remote Node.
- Parameters:
otherNode
- TheNodeID
of a remote Node to check the existance- Returns:
true
iff a link currently exists to the specified remote Node.
-
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 receiveNodeID
objects which signigy the remote Nodes at the other end of links which have been dropped.- Returns:
- the
AltingChannelInput
event channel.
-