Class CNS
This class is the Channel Name Server's main server process class.
This class should only be instantiated at Nodes wishing to run
a server process. Although this class does not need to be used
by clients wishing to interact with a server, it does
provide some convenient static methods for client code to use. There
are static versions of the methods provided in CNSService
and there are also static factory methods for constructing CNS
registered channel objects.
Server Installation
Channel Name Servers may be run either on a dedicated Node or else on
the same Node as one of the user Nodes. The former approach is recommended
for most sitations but for smaller scale use, the latter approach may
suffice. The service implements the
org.jcsp.net.Service
interface and can be installed
in the same way as any other other service by using the service manager
(ServiceManager
). Alternatively, the
service provides install methods which handle the service manager
interaction directly.
The following example initializes a Node and installs a Channel Name Server. It then proceeds to install a CNS client service and creates and resolves a channel. The example does not proceed to do anything else but could be used as the framework for an application wishing to host its own Channel Name Server.
import org.jcsp.lang.*; import org.jcsp.net.*; import org.jcsp.net.cns.*; import org.jcsp.net.tcpip.*; import java.io.IOException; public class CNSInSameJVM implements CSProcess { //main method for running example public static void main(String[] args) { CNSInSameJVM proc = new CNSInSameJVM(); proc.run(); } public void run() { NodeKey key = null; NodeID localNodeID = null; try { //Initialize a Node that does not have a CNS client key = Node.getInstance().init(new XMLNodeFactory("nocns.xml")); localNodeID = Node.getInstance().getNodeID(); //Initialize the CNS Server Process CNS.install(key); //Dedicated server code could stop here //Initialize the CNS client //use the first address of the local Node as CNS address NodeAddressID cnsAddress = localNodeID.getAddresses()[0]; CNSService.install(key, cnsAddress); //creating Channel named "in" NetChannelInput in = CNS.createNet2One("in"); //resolve the channel NetChannelOutput out = CNS.createOne2Net("in"); //could now use these channels for something!! //but this is only a test so will terminate } catch (NodeInitFailedException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } Node.info.log(this, "Done."); } }
This is the contents of the nocns.xml file:
<JCSP-CONFIG><PROTOCOLS>
<PROTOCOL id="TCPIP" name="TCP/IP" idclass="org.jcsp.net.tcpip.TCPIPProtocolID">
</PROTOCOL>
</PROTOCOLS>
<ADDRESSES>
<ADDRESS protocolid="TCPIP" value="127.0.0.1:7896" unique="FALSE">
</ADDRESS>
</ADDRESSES>
</JCSP-CONFIG>
The above code can be copied into a file named CNSInSameJVM.java and compiled an run in same directory as the nocns.xml file.
Channel Factory Methods
In order to construct a ChannelInput
object which can be
resolved by other users of a channel name server, a client simply needs
to to do this:
NetChannelInput in = CNS.createNet2One("Fred");
Another process using the same channel name server can create a
ChannelOutput
that will send objects to this channel
by do this:
NetChannelOutput out = CNS.createOne2Net("Fred");
When these factory methods are called, various resources are used
within the JCSP infrastructure. A channel name will be registered
and held in the channel name server. These resources are taken for
the duration of the JCSP Node's runtime unless the user manually
frees the resources. When channel ends are constructed with these
factory methods, the destroyChannelEnd(***)
methods
can be used to free all resources. It is only really necessary to
do this if channels are being created for short term use within
a long-lived Node.
This is an example "Hello World" program which contains two inner classes with main methods, each of which can be run in separate JVMs.
import org.jcsp.lang.*; import org.jcsp.net.*; import org.jcsp.net.cns.*; public class TestCNS { public static class Rx { public static void main(String[] args) { try { Node.getInstance().init(); NetChannelInput in = CNS.createNet2One("rx.in"); System.out.println(in.read()); CNS.destroyChannelEnd(in); } catch (NodeInitFailedException e) { e.printStackTrace(); } } } public static class Tx { public static void main(String[] args) { try { Node.getInstance().init(); NetChannelOutput out = CNS.createOne2Net("rx.in"); out.write("Hello World"); CNS.destroyChannelEnd(out); } catch (NodeInitFailedException e) { e.printStackTrace(); } } } }
This code can be compiled and then the following run at two command prompts:
java TestCNS$Rx
java TestCNS$Tx
The programs will connect to a default channel name server. The
Rx program will create a NetChannelInput
and wait
for a message on the channel. Once it has received the message,
it prints it, destroys its channel and then terminates.
The Tx program creates a NetChannelOutput
that will
send to the Rx program's input channel. It sends a "Hello World"
message. Once this has been accepted by the Rx process, it
destoys its output channel and terminates.
CNS Client Methods
The following code functions the same as the above code but does not use the CNS class' factory methods. The code uses the CNS client methods and manually registers and resolves the channel with the channel name server.
import org.jcsp.lang.*; import org.jcsp.net.*; import org.jcsp.net.cns.*; public class TestCNS { public static class Rx { public static void main(String[] args) { try { Node.getInstance().init(); NetChannelInput in = NetChannelEnd.createNet2One(); ChannelNameKey key = CNS.register(in, "rx.in"); System.out.println(in.read()); CNS.deregisterChannelName("rx.in", null, key); } catch (NodeInitFailedException e) { e.printStackTrace(); } } } public static class Tx { public static void main(String[] args) { try { Node.getInstance().init(); NetChannelLocation loc = CNS.resolve("rx.in"); NetChannelOutput out = NetChannelEnd.createOne2Net(loc); out.write("Hello World"); out.destroyWriter(); } catch (NodeInitFailedException e) { e.printStackTrace(); } } } }
The CNS client methods provide the programmer with greater control
over how the Channel Name Server is used. Interaction with the
server need not be performed at the same time as construction of
the channel. A channel can be registered with a Channel Name Server
at any time after construction of its input end. A channel can be resolved
at any time before construction of an output end. This allows one process
to resolve a name into a NetChannelLocation
object and
then pass this object on for another process to use in constructing the
channel.
The Channel Name Server will allow a channel to be registered multiple
times with different names and/or in different name spaces. Channel
implementations that make direct use of the Channel Name Server may
forbid this, so the behaviour of channel implemenations should be checked
before this is carried out
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
A data structure for holding a channel name and access level.private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static CNSChannelEndManager
private long
private Hashtable
The registered channel names and indexes.(package private) static final String
static final String
private final int
private Hashtable
private Hashtable
The registered channel names and indexes.private Hashtable
This holds NameAndLevel objects as the keys that map to the associated ChannelNameKey objects.private boolean
private One2OneChannel
private Any2OneChannel
private Hashtable
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic NetSharedChannelOutput
createAny2Net
(String name) static NetSharedChannelOutput
createAny2Net
(String name, NameAccessLevel accessLevel) static NetSharedChannelInput
createNet2Any
(String name) static NetSharedChannelInput
createNet2Any
(String name, NameAccessLevel nameAccessLevel) static NetAltingChannelInput
createNet2One
(String name) static NetAltingChannelInput
createNet2One
(String name, NameAccessLevel nameAccessLevel) static NetChannelOutput
createOne2Net
(String name) static NetChannelOutput
createOne2Net
(String name, NameAccessLevel accessLevel) private boolean
deregisterChannel
(String channelName, NameAccessLevel nameAccessLevel, ChannelNameKey channelKey) Deregisters a channel name and nameAccessLevel if a channel matches or removes a matching lease.static boolean
deregisterChannelName
(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) This deregisters a Channel name with the CNS.static void
destroyChannelEnd
(NetChannelInput chanInEnd) static void
destroyChannelEnd
(NetChannelOutput chanOutEnd) private NetChannelLocation
getChannel
(String channelName, NameAccessLevel nameAccessLevel) Get a ChannelID for a channel with a name that matches the supplied name and whose name is within the supplied scope.Returns anull
reference as this method has no use with this service.private void
private void
private void
handleLinkDropped
(NodeID nodeID) private void
private void
private void
boolean
init
(ServiceSettings settings) This method does not need to be called for the Channel Name Server.static CNS
Installs and starts a Channel Name Server on the local Node.static CNS
Installs and starts a Channel Name Server on the local Node.boolean
Returns whether the service is running.static ChannelNameKey
leaseChannelName
(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) static ChannelNameKey
register
(NetChannelLocation ownerLocation, String name, NameAccessLevel accessLevel, ChannelNameKey key) static ChannelNameKey
static ChannelNameKey
register
(Networked owner, String name, ChannelNameKey key) static ChannelNameKey
register
(Networked owner, String name, NameAccessLevel accessLevel) static ChannelNameKey
register
(Networked owner, String name, NameAccessLevel accessLevel, ChannelNameKey key) private ChannelNameKey
registerChannel
(String channelName, NameAccessLevel nameAccessLevel, NetChannelLocation channelLoc, ChannelNameKey channelKey) Register a Channel in the database.static NetChannelLocation
static NetChannelLocation
resolve
(String name, NameAccessLevel accessLevel) void
run()
This defines the actions of the process.boolean
start()
This starts the channel name server.boolean
stop()
Stops the channel name server.
-
Field Details
-
CNS_DEFAULT_SERVICE_NAME
- See Also:
-
CNS_CHANNEL_LABEL
- See Also:
-
INPUT_BUFFER_SIZE
private final int INPUT_BUFFER_SIZE- See Also:
-
running
private boolean running -
stopChan
-
toClientChans
-
channelKeyCount
private long channelKeyCount -
startedReplyChan
-
channels
The registered channel names and indexes. This is a hashtable where the key is a NameAndLevel object and the value is the ChannelID. -
leasedChannelKeys
-
registeredChannelKeys
This holds NameAndLevel objects as the keys that map to the associated ChannelNameKey objects. -
pendingResolves
The registered channel names and indexes. This is a hashtable where the key is the channel name and the value is the ChannelID. -
CHAN_FACTORY
-
-
Constructor Details
-
CNS
A public constructor which takes aNodeKey
as a parameter which should be the key for the local Node.- Parameters:
nodeKey
- aNodeKey
object that should match the local Node'sNodeKey
.- Throws:
IllegalStateException
- if the local Node has not been initialized.SecurityException
- if the suppliedNodeKey
object cannot be verified by the local Node.
-
-
Method Details
-
start
public boolean start()This starts the channel name server. -
stop
public boolean stop()Stops the channel name server. -
init
This method does not need to be called for the Channel Name Server. It returnstrue
. -
isRunning
public boolean isRunning()Returns whether the service is running. At the moment this always returns false. This will probably change in the future. Early JCSP.NET applications always had the CNS process running in its own JVM. -
getUserObject
Returns anull
reference as this method has no use with this service.- Specified by:
getUserObject
in interfaceService
- Returns:
null
.- Throws:
SecurityException
- if the calling Thread does not have access to the object.
-
run
public void run()Description copied from interface:CSProcess
This defines the actions of the process. -
resolve
-
resolve
-
register
-
register
-
register
-
register
public static ChannelNameKey register(Networked owner, String name, NameAccessLevel accessLevel, ChannelNameKey key) -
register
public static ChannelNameKey register(NetChannelLocation ownerLocation, String name, NameAccessLevel accessLevel, ChannelNameKey key) -
leaseChannelName
public static ChannelNameKey leaseChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) throws ChannelNameException, NameAccessLevelException -
deregisterChannelName
public static boolean deregisterChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) This deregisters a Channel name with the CNS. If the CNS Service is not running, this method will block until it is running. A boolean is returned to indicate whether deregistration was successful. This is also returned if the link to the CNS is lost.- Parameters:
name
- the name of the channel as a String.channelKey
- the ChannelNameKey to use to deregister the Channel name.nameAccessLevel
- the nameAccessLevel of the channel.- Returns:
- a boolean indicating success.
-
handleLogonMessage
-
handleRegisterRequest
-
handleResolveRequest
-
handleLeaseRequest
-
handleDeregisterRequest
-
handleLinkDropped
-
registerChannel
private ChannelNameKey registerChannel(String channelName, NameAccessLevel nameAccessLevel, NetChannelLocation channelLoc, ChannelNameKey channelKey) Register a Channel in the database. Fails if the channel has already been registered to a different location. (Re-registering to the same ChannelID is allowed) or if it has been leased and the supplied key does not match the leased channel name's key.- Parameters:
channelName
- The channel's name.channelId
- The channel's ChannelID.- Returns:
- a ChannelNameKey on successful database update, null if the name is already registered elsewhere.
-
getChannel
Get a ChannelID for a channel with a name that matches the supplied name and whose name is within the supplied scope.- Parameters:
channelName
- The channel's name.nameAccessLevel
- the channel's nameAccessLevel- Returns:
- a ChannelID if one can be found that matches the name and nameAccessLevel, otherwise returns null.
-
deregisterChannel
private boolean deregisterChannel(String channelName, NameAccessLevel nameAccessLevel, ChannelNameKey channelKey) Deregisters a channel name and nameAccessLevel if a channel matches or removes a matching lease.- Parameters:
channelName
- the channel's name.nameAccessLevel
- the channel's nameAccessLevel- Returns:
- true iff a matching channel is not registered after returning.
-
createNet2One
- See Also:
-
createNet2One
- See Also:
-
createNet2Any
- See Also:
-
createNet2Any
- See Also:
-
createOne2Net
- See Also:
-
createOne2Net
- See Also:
-
createAny2Net
- See Also:
-
createAny2Net
- See Also:
-
destroyChannelEnd
-
destroyChannelEnd
-
install
Installs and starts a Channel Name Server on the local Node. The service is installed with the default service name as specified byCNS.CNS_DEFAULT_SERVICE_NAME
. This method needs to be supplied with the local Node'sNodeKey
. This is required in order to obtain access to the Node's service manager.- Parameters:
key
- the local Node'sNodeKey
.- Returns:
- the
CNS
object installed. - Throws:
ServiceInstallationException
- if installation fails.
-
install
Installs and starts a Channel Name Server on the local Node. The service is installed with the specified service name. This method needs to be supplied with the local Node'sNodeKey
. This is required in order to obtain access to the Node's service manager.- Parameters:
key
- the local Node'sNodeKey
.name
- the name to give the service.- Returns:
- the
CNS
object installed. - Throws:
ServiceInstallationException
- if installation fails.
-