Class CNS

  • All Implemented Interfaces:
    CSProcess

    public class CNS
    extends java.lang.Object
    implements CSProcess

    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 situations but for smaller scale use, the latter approach may suffice.

    The following example initialises 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.net2.*;
    import org.jcsp.net2.cns.*;
    import org.jcsp.net2.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 TCPIPNodeAddress(7890));
    new ProcessManager(CNS.getInstance()).start();
    //Dedicated server code could stop here
    //Initialise the CNS client
    //use the local NodeID to connect to the CNS
    localNodeID = Node.getInstance().getNodeID();
    CNS.init(localNodeID);
    // creating Channel named "in"
    NetChannelInput in = CNS.net2one("in");
    //resolve the channel
    NetChannelOutput out = CNS.one2net("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.log.log(this, "Done."); } }

    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.net2one("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.one2net("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.

    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.net2.*;
     import org.jcsp.net2.cns.*;
     
     public class TestCNS
     {
         public static class Rx
         {
             public static void main(String[] args)
             {
                 try
                 {
                     Node.getInstance().init(new TCPIPNodeAddress(7890));
                     NetChannelInput in = CNS.net2one("rx.in");
                     System.out.println(in.read());
                 }
                 catch (Exception e)
                 {
                     e.printStackTrace();
                 }
             }
         }
     
         public static class Tx
         {
             public static void main(String[] args)
             {
                 try
                 {
                     Node.getInstance().init(new TCPIPNodeAddress(7890));
                     NetChannelOutput out = CNS.one2net("rx.in");
                     out.write("Hello World");
                 }
                 catch (Exception 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, 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 terminates.

    See Also:
    CNSService, Node
    • Field Detail

      • service

        private static CNSService service
        The internal service. This is used by the factory methods
      • initialised

        private static boolean initialised
        Flag used to denote whether the CNS has been initialised
      • instance

        private static final CNS instance
        Singleton instance of a CNS. Only one may be created on a Node
      • registeredChannels

        private final java.util.HashMap registeredChannels
        The map of registered channels, name->location
      • channelRegister

        private final java.util.HashMap channelRegister
        The map of channels registered to a Node; NodeID->
      • waitingResolves

        private final java.util.HashMap waitingResolves
        The map of currently waiting resolves; name->reply-location
      • loggedClients

        private final java.util.HashMap loggedClients
        The map of currently logged clients; NodeID->reply-channel
      • lostLink

        private final AltingChannelInput lostLink
        A channel used to receive incoming link lost notifications
    • Constructor Detail

      • CNS

        private CNS()
        Private empty constructor
    • Method Detail

      • getInstance

        public static CNS getInstance()
        Gets the singleton instance of the CNS
        Returns:
        The singleton instance of the CNS
      • initialise

        public static void initialise​(NodeID cnsNode)
                               throws JCSPNetworkException
        Initialises the factory methods to allow creation of channels with the CNS
        Parameters:
        cnsNode - The Node that the CNS is located on
        Throws:
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • initialise

        public static void initialise​(NodeAddress cnsNode)
                               throws JCSPNetworkException
        Initialises the factory methods to allow creation of channels with the CNS
        Parameters:
        cnsNode - The Node that the CNS is located on
        Throws:
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • run

        public void run()
        The run method for the CNS process
        Specified by:
        run in interface CSProcess
      • createNet2One

        public static NetAltingChannelInput createNet2One​(java.lang.String name)
                                                   throws java.lang.IllegalStateException,
                                                          java.lang.IllegalArgumentException
        Deprecated.
        Use net2one instead
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • createNet2Any

        public static NetSharedChannelInput createNet2Any​(java.lang.String name)
                                                   throws java.lang.IllegalStateException,
                                                          java.lang.IllegalArgumentException
        Deprecated.
        Use net2any instead
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • createOne2Net

        public static NetChannelOutput createOne2Net​(java.lang.String name)
                                              throws java.lang.IllegalStateException,
                                                     JCSPNetworkException
        Deprecated.
        Use one2net instead
        Creates a new NetChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • createAny2Net

        public static NetSharedChannelOutput createAny2Net​(java.lang.String name)
                                                    throws JCSPNetworkException,
                                                           java.lang.IllegalStateException
        Deprecated.
        Use one2net instead
        Creates a new NetSharedChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • net2one

        public static <T> NetAltingChannelInput<T> net2one​(java.lang.String name)
                                                    throws java.lang.IllegalStateException,
                                                           java.lang.IllegalArgumentException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2one

        public static <T> NetAltingChannelInput<T> net2one​(java.lang.String name,
                                                           int immunityLevel)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        immunityLevel - The immunity to poison the channel has
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2one

        public static <T> NetAltingChannelInput<T> net2one​(java.lang.String name,
                                                           NetworkMessageFilter.FilterRx filter)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        filter - The filter used to decode incoming messages
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2one

        public static <T> NetAltingChannelInput<T> net2one​(java.lang.String name,
                                                           int immunityLevel,
                                                           NetworkMessageFilter.FilterRx filter)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        immunityLevel - The immunity level to poison that the channel has
        filter - The filter used to decode incoming messages
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2any

        public static <T> NetSharedChannelInput<T> net2any​(java.lang.String name)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2any

        public static <T> NetSharedChannelInput<T> net2any​(java.lang.String name,
                                                           int immunityLevel)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        immunityLevel - The immunity level to poison that the channel has
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2any

        public static <T> NetSharedChannelInput<T> net2any​(java.lang.String name,
                                                           NetworkMessageFilter.FilterRx filter)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        filter - The filter used to decode incoming messages
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • net2any

        public static <T> NetSharedChannelInput<T> net2any​(java.lang.String name,
                                                           int immunityLevel,
                                                           NetworkMessageFilter.FilterRx filter)
                                                    throws java.lang.IllegalArgumentException,
                                                           java.lang.IllegalStateException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        immunityLevel - The immunity to poison that this channel has
        filter - The filter used to decode incoming messages
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2One

        public static <T> NetAltingChannelInput<T> numberedNet2One​(java.lang.String name,
                                                                   int index)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2One

        public static <T> NetAltingChannelInput<T> numberedNet2One​(java.lang.String name,
                                                                   int index,
                                                                   int immunityLevel)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        immunityLevel - The immunity level to poison that the channel has
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2One

        public static <T> NetAltingChannelInput<T> numberedNet2One​(java.lang.String name,
                                                                   int index,
                                                                   NetworkMessageFilter.FilterRx filter)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        filter - The filter used to decode incoming messages
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2One

        public static <T> NetAltingChannelInput<T> numberedNet2One​(java.lang.String name,
                                                                   int index,
                                                                   int immunityLevel,
                                                                   NetworkMessageFilter.FilterRx filter)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetAltingChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        immunityLevel - The immunity level to poison that the channel has
        filter - The filter used to decode incoming messages
        Returns:
        A new NetAltingChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2Any

        public static <T> NetSharedChannelInput<T> numberedNet2Any​(java.lang.String name,
                                                                   int index)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2Any

        public static <T> NetSharedChannelInput<T> numberedNet2Any​(java.lang.String name,
                                                                   int index,
                                                                   int immunityLevel)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        immunityLevel - The immunity to poison that this channel has
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2Any

        public static <T> NetSharedChannelInput<T> numberedNet2Any​(java.lang.String name,
                                                                   int index,
                                                                   NetworkMessageFilter.FilterRx filter)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        filter - The filter used to decode incoming messages
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • numberedNet2Any

        public static <T> NetSharedChannelInput<T> numberedNet2Any​(java.lang.String name,
                                                                   int index,
                                                                   int immunityLevel,
                                                                   NetworkMessageFilter.FilterRx filter)
                                                            throws java.lang.IllegalStateException,
                                                                   java.lang.IllegalArgumentException
        Creates a new NetSharedChannelInput registered with the given name
        Parameters:
        name - The name to register with the CNS
        index - The index to create the channel with
        immunityLevel - The immunity to poison that this channel has
        filter - The filter used to decode incoming messages
        Returns:
        A new NetSharedChannelInput registered with the given name
        Throws:
        java.lang.IllegalStateException - Thrown if the CNS has not been initialised
        java.lang.IllegalArgumentException - Thrown if the channel name is already registered
      • one2net

        public static <T> NetChannelOutput<T> one2net​(java.lang.String name)
                                               throws java.lang.IllegalStateException,
                                                      JCSPNetworkException
        Creates a new NetChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • one2net

        public static <T> NetChannelOutput<T> one2net​(java.lang.String name,
                                                      int immunityLevel)
                                               throws java.lang.IllegalStateException,
                                                      JCSPNetworkException
        Creates a new NetChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        immunityLevel - The immunity to poison that this channel has
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • one2net

        public static <T> NetChannelOutput<T> one2net​(java.lang.String name,
                                                      NetworkMessageFilter.FilterTx filter)
                                               throws java.lang.IllegalStateException,
                                                      JCSPNetworkException
        Creates a new NetChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        filter - The filter used to encode outgoing messages
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • one2net

        public static <T> NetChannelOutput<T> one2net​(java.lang.String name,
                                                      int immunityLevel,
                                                      NetworkMessageFilter.FilterTx filter)
                                               throws java.lang.IllegalStateException,
                                                      JCSPNetworkException
        Creates a new NetChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        immunityLevel - The immunity to poison that this channel has
        filter - The filter used to encode outgoing messages
        Returns:
        A new NetChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • any2net

        public static <T> NetSharedChannelOutput<T> any2net​(java.lang.String name)
                                                     throws java.lang.IllegalStateException,
                                                            JCSPNetworkException
        Creates a new NetSharedChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        Returns:
        A new NetSharedChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • any2net

        public static <T> NetSharedChannelOutput<T> any2net​(java.lang.String name,
                                                            int immunityLevel)
                                                     throws java.lang.IllegalStateException,
                                                            JCSPNetworkException
        Creates a new NetSharedChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        immunityLevel - The immunity to poison that this channel has
        Returns:
        A new NetSharedChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • any2net

        public static <T> NetSharedChannelOutput<T> any2net​(java.lang.String name,
                                                            NetworkMessageFilter.FilterTx filter)
                                                     throws java.lang.IllegalStateException,
                                                            JCSPNetworkException
        Creates a new NetSharedChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        filter - The filter used to encode outgoing messages
        Returns:
        A new NetSharedChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • any2net

        public static <T> NetSharedChannelOutput<T> any2net​(java.lang.String name,
                                                            int immunityLevel,
                                                            NetworkMessageFilter.FilterTx filter)
                                                     throws java.lang.IllegalStateException,
                                                            JCSPNetworkException
        Creates a new NetSharedChannelOutput connected to the input channel registered with the given name
        Parameters:
        name - The name to resolve
        immunityLevel - The immunity level to poison that this channel has
        filter - The filter used to encode outgoing messages
        Returns:
        A new NetSharedChannelOutput connected to the input with the registered name
        Throws:
        java.lang.IllegalStateException - Thrown if the connection to the CNS is not initialised
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture