Class Node
- java.lang.Object
-
- org.jcsp.net.Node
-
public class Node extends java.lang.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
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 theTCPIPNodeFactory
method. If the parameterlessinit(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.). Seeinit()
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. SeeXMLNodeFactory
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 theinit(NodeAddressID)
,init(NodeAddressID[])
andinit(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;
andServiceManager
. These instances can be obtained from the localProtocolManager
Node
object by calling their respective accessors (
andgetServiceManager(org.jcsp.net.NodeKey)
). Each of these accessors takes agetProtocolManager(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
andServiceManager
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. Seeerr
for more information.Logger
- 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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods 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'sNodeID
.org.jcsp.net.Specification[]
getNodeSpecifications()
Returns an array ofSpecification
objects to which this Node conforms.ProtocolManager
getProtocolManager(NodeKey nodeKey)
Accessor for obtaining a reference to the local Node'sProtocolManager
object.ServiceManager
getServiceManager(NodeKey nodeKey)
Accessor for obtaining a reference to the local Node'sServiceManager
object.ServiceUserObject
getServiceUserObject(java.lang.String name)
Obtains aServiceUserObject
from a named Service and returns a reference to it.NodeKey
init()
Initializes the Node with the current staticNodeFactory
.NodeKey
init(NodeAddressID localAddress)
This method functions the same as callinginit(NodeAddressID[])
with a single element in the array.NodeKey
init(NodeAddressID[] localAddresses)
This method is functionally equivalent to callinginit(NodeAddressID[], HashTable)
with theHashTable
parameter being supplied asnull
.NodeKey
init(NodeAddressID[] localAddresses, java.util.Hashtable[] protocolSettings)
Initializes the local Node and startsLinkServer
listening on each of the suppliedNodeAddressID
objects.NodeKey
init(NodeFactory factory)
Initializes the Node with the specified
object.NodeFactory
boolean
isInitialized()
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
setNodeFactory(NodeFactory fac)
boolean
verifyKey(NodeKey nodeKey)
Verifies that the supplied key matches the local Node's key.
-
-
-
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 java.lang.IllegalStateException, java.lang.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:
java.lang.IllegalStateException
- if the local Node has already been initialized.java.lang.IllegalArgumentException
- if no addresses are supplied.NodeInitFailedException
- if the Node is not able to initialize.
-
init
public NodeKey init(NodeAddressID[] localAddresses) throws java.lang.IllegalStateException, java.lang.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:
java.lang.IllegalStateException
- if the local Node has already been initialized.java.lang.IllegalArgumentException
- if no addresses are supplied.NodeInitFailedException
- if the Node is not able to initialize.
-
init
public NodeKey init(NodeAddressID[] localAddresses, java.util.Hashtable[] protocolSettings) throws java.lang.IllegalStateException, java.lang.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:
java.lang.IllegalStateException
- if the local Node has already been initialized.java.lang.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
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(NodeFactory)
-
init
public NodeKey init(NodeFactory factory) throws NodeInitFailedException
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
public boolean isThisNode(NodeID nodeID) throws java.lang.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 localNodeID
object being cloned.- Parameters:
nodeID
- aNodeID
to check against the local Node'sNodeID
.- Returns:
- boolean indicating whether the address supplied is local.
- Throws:
java.lang.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 java.lang.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:
java.lang.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'sNodeKey
.- Returns:
- the local Node's
ProtocolManager
ornull>
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'sNodeKey
.- Returns:
- the local Node's
ServiceManager
ornull>
if an incorrect key is supplied.
-
getServiceUserObject
public ServiceUserObject getServiceUserObject(java.lang.String name)
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
public boolean verifyKey(NodeKey nodeKey)
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
public boolean linkExists(NodeID otherNode)
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
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 receiveNodeID
objects which signigy the remote Nodes at the other end of links which have been dropped.- Returns:
- the
AltingChannelInput
event channel.
-
-