Package org.jcsp.net.cns

# Class CNSService

java.lang.Object
org.jcsp.net.cns.CNSService

All Implemented Interfaces:
  `CNSUser`, `Service`

public class CNSService extends Object implements Service, CNSUser

This class is the Channel Name Server's main client process class.

One instance of this class needs to be instantiated at each Node wishing to interact with a Channel Name Server.

At present only one instance of this service class should be installed at each Node, however, it is envisaged that it may be desirable to be able to use multiple Channel Name servers. This functionality has been partially implemented and eventually multiple instances of this service will be able to be installed. Each instance would be given a separate name.

A default instance of this class can be held. Interaction with this default instance is facilitated through the static methods of the `CNS` class.

Once constructed, an instance of the object can be installed into the Node's service manager in the same way as any other `Service` (see ``ServiceManager``). Alternatively, the one of the static install methods may be used (see ``install(NodeKey, NodeAddressID)``, ``install(NodeKey, NodeAddressID, String)``).

Author:
  Quickstone Technologies Limited
See Also:
  - `CNS`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`CNS_DEFAULT_SERVICE_NAME`
Constant specifying the default name of this service.
`static final String`
`CNS_SETTING_NAME_ADDRESS`
Constant specifying the setting name for CNS address.
`static final String`
`CNS_SETTING_NAME_ADMIN_CHANNEL_LABEL`
Constant specifying the setting name for server's admin channel.
`static final String`
`CNS_SETTING_NAME_SERVICE_NAME`
Constant specifying the setting name for setting the service name.

## Constructor Summary

Constructors
Constructor
Description
`CNSService()`
Default constructor that does not supply any of the necessary settings for initializing the CNS.
`CNSService(NodeAddressID cnsAddress)`
Constructor which takes an address of the Node hosting the Channel Name Server.
`CNSService(NodeAddressID cnsAddress, boolean start)`
Constructor which takes an address of the Node hosting the Channel Name Server as well as a `boolean` indicating whether or not the service should be started.
`CNSService(NodeAddressID cnsAddress, String adminChannelLabel)`
Constructor which takes an address of the Node hosting the Channel Name Server as well as the label of the Channel Name Server's admin channel.
`CNSService(NodeAddressID cnsAddress, String adminChannelLabel, boolean start)`
Constructor which takes an address of the Node hosting the Channel Name Server, the label of the Channel Name Server's admin channel and a `boolean` indicating whether the service should be started.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`deregisterChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey)`
This deregisters a Channel name from the Channel Name Server.
`ServiceUserObject`
`getUserObject()`
This returns a `ServiceUserObject` which implements the `Resolver` interface.
`boolean`
`init(ServiceSettings settings)`
Initializes the this instance of the `CNSService`.
`static CNSService`
`install(NodeKey key, NodeAddressID cnsAddress)`
Installs and starts a Channel Name Server client service on the local Node.
`static CNSService`
`install(NodeKey key, NodeAddressID cnsAddress, String serviceName)`
Installs and starts a Channel Name Server client service on the local Node.
`boolean`
`isRunning()`
This returns whether the service is running.
`ChannelNameKey`
`leaseChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey)`
Leases the channel name within the specified name space from the Channel Name Server.
`ChannelNameKey`
`register(NetChannelLocation ownerLocation, String name, NameAccessLevel accessLevel, ChannelNameKey key)`
This method allows a channel's location to be registered against a name in the Channel Name Server.
`ChannelNameKey`
`register(Networked owner, String name)`
This method allows a channel (or any instance of a class implementing ``Networked``) to be registered with the Channel Name Server.
`ChannelNameKey`
`register(Networked owner, String name, ChannelNameKey key)`
This method allows a channel (or any instance of a class implementing ``Networked``) that has previously been registered with the to be reregistered with the Channel Name Server.
`ChannelNameKey`
`register(Networked owner, String name, NameAccessLevel accessLevel)`
This method allows a channel (or any instance of a class implementing ``Networked``) to be registered with the Channel Name Server.
`ChannelNameKey`
`register(Networked owner, String name, NameAccessLevel accessLevel, ChannelNameKey key)`
This method allows a channel (or any instance of a class implementing ``Networked``) that has previously been registered to be reregistered with the Channel Name Server.
`NetChannelLocation`
`resolve(String name)`
This method resolves a channel name into a `NetChannelLocation` object.
`NetChannelLocation`
`resolve(String name, NameAccessLevel accessLevel)`
This method resolves a channel name into a `NetChannelLocation` object.
`boolean`
`start()`
This checks to see if the service is already running, if it is not then it starts it.
`boolean`
`stop()`
This checks to see if the service is running, if it is then it stops it.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### CNS_SETTING_NAME_ADDRESS

public static final String CNS_SETTING_NAME_ADDRESS
Constant specifying the setting name for CNS address.

See Also:
  - Constant Field Values

### CNS_SETTING_NAME_SERVICE_NAME

public static final String CNS_SETTING_NAME_SERVICE_NAME
Constant specifying the setting name for setting the service name.

See Also:
  - Constant Field Values

### CNS_SETTING_NAME_ADMIN_CHANNEL_LABEL

public static final String CNS_SETTING_NAME_ADMIN_CHANNEL_LABEL
Constant specifying the setting name for server's admin channel.

See Also:
  - Constant Field Values

### CNS_DEFAULT_SERVICE_NAME

public static final String CNS_DEFAULT_SERVICE_NAME
Constant specifying the default name of this service.

See Also:
  - Constant Field Values

## Constructor Details

### CNSService

public CNSService()

Default constructor that does not supply any of the necessary settings for initializing the CNS. The `init(ServiceSettings)` method must be called if this constructor is used.

### CNSService

public CNSService(NodeAddressID cnsAddress)

Constructor which takes an address of the Node hosting the Channel Name Server.

In order to connect to the Channel Name Server, this service must know the label of the server's admin channel. By default this is given the value of the `CNS.CNS_CHANNEL_LABEL` constant. This constructor assumes that this label has been used. It is equivalent to calling the constructor which takes `(NodeAddressID, String)` parameters.

Parameters:
  `cnsAddress` - the address of channel name server to use.
See Also:
  - `CNSService(NodeAddressID,String)`

### CNSService

public CNSService(NodeAddressID cnsAddress, boolean start)

Constructor which takes an address of the Node hosting the Channel Name Server as well as a `boolean` indicating whether or not the service should be started.

In order to connect to the Channel Name Server, this service must know the label of the server's admin channel. By default this is given the value of the `CNS.CNS_CHANNEL_LABEL` constant. This constructor assumes that this label has been used. It is equivalent to calling the constructor which takes `(NodeAddressID, String,boolean)` parameters.

Parameters:
  `cnsAddress` - the address of channel name server to use.
  `start` - indicates whether the service should be started. Should be `true` to start service.
See Also:
  - `CNSService(NodeAddressID,String,boolean)`

### CNSService

public CNSService(NodeAddressID cnsAddress, String adminChannelLabel)

Constructor which takes an address of the Node hosting the Channel Name Server as well as the label of the Channel Name Server's admin channel.

This is equivalent to using the construtor with `(NodeAddressID, String, boolean)` parameters with the `boolean` equal to `false`.

Parameters:
  `cnsAddress` - the address of channel name server to use.
  `adminChannelLabel` - the label of server's admin channel.
See Also:
  - `CNSService(NodeAddressID,String,boolean)`

### CNSService

public CNSService(NodeAddressID cnsAddress, String adminChannelLabel, boolean start)

Constructor which takes an address of the Node hosting the Channel Name Server, the label of the Channel Name Server's admin channel and a `boolean` indicating whether the service should be started.

If the service is started, there is no need to initialize and start the service separately.

Parameters:
  `cnsAddress` - the address of channel name server to use.
  `adminChannelLabel` - the label of server's admin channel.
  `start` - indicates whether the service should be started. Should be `true` to start service.
See Also:
  - `NodeAddressID`

## Method Details

### init

public boolean init(ServiceSettings settings)

Initializes the this instance of the `CNSService`.

If the default constructor was used to construct the instance of this class, then a name of the instance must be supplied along with at least one address of a channel name server. The admin channel label of the server may also be supplied. The keys to use in the `ServiceSettings` are held as constants in this class (`CNS_SETTING_NAME_ADDRESS`, `CNS_SETTING_NAME_SERVICE_NAME`, `CNS_SETTING_NAME_ADMIN_CHANNEL_LABEL`).

This need only be called if the no-arg constructor is used.

Specified by:
  `init` in interface `Service`
Parameters:
  `settings` - A ``ServiceSettings`` object that holds the settings for this service.
Returns:
  `true` if this request to initialize the service succeeds.

### start

public boolean start()
This checks to see if the service is already running, if it is not then it starts it.

Specified by:
  `start` in interface `Service`
Returns:
  true iff the service is running once this method has returned.

### stop

public boolean stop()
This checks to see if the service is running, if it is then it stops it.

Specified by:
  `stop` in interface `Service`
Returns:
  true if the service is NOT running.

### isRunning

public boolean isRunning()
This returns whether the service is running. If the service is currently starting or stopping, this method will block until the state change is complete.

Specified by:
  `isRunning` in interface `Service`
Returns:
  true iff the service is running.

### getUserObject

public ServiceUserObject getUserObject() throws SecurityException
This returns a `ServiceUserObject` which implements the `Resolver` interface. This allows processes to obtain a reference to an installed CNS Service without having admin privileges. A `SecurityException` may be thrown if the calling process does not have permission to obtain the `ServiceUserObject`.

Specified by:
  `getUserObject` in interface `Service`
Returns:
  a `Resolver` which can be used to resolve names using this `CNSService`.
Throws:
  `SecurityException` - if the calling process does not have permission to obtain the `ServiceUserObject`.
See Also:
  - `CNSUser`

### install

public static CNSService install(NodeKey key, NodeAddressID cnsAddress)

Installs and starts a Channel Name Server client service on the local Node. The service is installed with the default service name as specified by `CNSService.CNS_DEFAULT_SERVICE_NAME`. This method needs to be supplied with the local Node's `NodeKey`. This is required in order to obtain access to the Node's service manager.

Parameters:
  `key` - the local Node's `NodeKey`.
  `cnsAddress` - the address of the Channel Name Server to use.
Returns:
  the `CNS` object installed.
Throws:
  `ServiceInstallationException` - if installation fails.

### install

public static CNSService install(NodeKey key, NodeAddressID cnsAddress, String serviceName)

Installs and starts a Channel Name Server client service on the local Node. The service is installed with the specified service name. This method needs to be supplied with the local Node's `NodeKey`. This is required in order to obtain access to the Node's service manager.

Parameters:
  `key` - the local Node's `NodeKey`.
  `cnsAddress` - the address of the Channel Name Server to use.
  `name` - the name to give the service.
Returns:
  the `CNS` object installed.
Throws:
  `ServiceInstallationException` - if installation fails.
See Also:
  - `NodeAddressID`

### resolve

public NetChannelLocation resolve(String name)

This method resolves a channel name into a `NetChannelLocation` object. The name is assumed to be in the global name space (see `NameAccessLevel.GLOBAL_ACCESS_LEVEL`).

This method is safe to be called by concurrent processes.

Specified by:
  `resolve` in interface `CNSUser`
Parameters:
  `name` - the name of channel to resolve.
Returns:
  the location to which the name resolved.

### resolve

public NetChannelLocation resolve(String name, NameAccessLevel accessLevel)

This method resolves a channel name into a `NetChannelLocation` object. The name must exist in the specified name space.

The name space is specified by passing in a ``NameAccessLevel`` object. A name space includes itself and any name space higher up in the hierarchy. The global name space is the highest level of name space.

This method is safe to be called by concurrent processes.

Specified by:
  `resolve` in interface `CNSUser`
Parameters:
  `name` - the name of channel to resolve.
  `accessLevel` - the name space in which to resolve the channel name.
Returns:
  the location to which the name resolved.

### register

public ChannelNameKey register(Networked owner, String name)

This method allows a channel (or any instance of a class implementing ``Networked``) to be registered with the Channel Name Server. The name will be registered in the global name space.

A name will stay registered with the Channel Name Server until it has been leased, deregistered or the Node that registered the name has shut down.

This method is safe to be called by concurrent processes.

Specified by:
  `register` in interface `CNSUser`
Parameters:
  `owner` - the `Networked` object whose location should be registered.
  `name` - the name against which to register the channel.
Returns:
  the `ChannelNameKey` needed for managing the name registration or `null` if registration failed.

### register

public ChannelNameKey register(Networked owner, String name, NameAccessLevel accessLevel)

This method allows a channel (or any instance of a class implementing ``Networked``) to be registered with the Channel Name Server.

The name will be registered in the specified name space. This is specified by passing in a ``NameAccessLevel`` object.

A name will stay registered with the Channel Name Server until it has been leased, deregistered or the Node that registered the name has shut down.

This method is safe to be called by concurrent processes.

Specified by:
  `register` in interface `CNSUser`
Parameters:
  `owner` - the `Networked` object whose location should be registered.
  `name` - the name against which to register the channel.
  `accessLevel` - the name space in which to register the channel name.
Returns:
  the `ChannelNameKey` needed for managing the name registration or `null` if registration failed.
See Also:
  - `NameAccessLevel`

### register

public ChannelNameKey register(Networked owner, String name, ChannelNameKey key)

This method allows a channel (or any instance of a class implementing ``Networked``) that has previously been registered with the to be reregistered with the Channel Name Server. The name should have been leased (see ``leaseChannelName(String, NameAccessLevel, ChannelNameKey)`` ). It is necessaray to supply the key that was obtained when the name was leased. If the channel name has not previously been registered, then the key can be specified as `null`.

The name will be registered in the in the global name space.

A name will stay registered with the Channel Name Server until it has been leased, deregistered or the Node that registered the name has shut down.

This method is safe to be called by concurrent processes.

Specified by:
  `register` in interface `CNSUser`
Parameters:
  `owner` - the `Networked` object whose location should be registered.
  `name` - the name against which to register the channel.
  `accessLevel` - the name space in which to register the channel name.
Returns:
  the `ChannelNameKey` needed for managing the name registration or `null` if registration failed.

### register

public ChannelNameKey register(Networked owner, String name, NameAccessLevel accessLevel, ChannelNameKey key)

This method allows a channel (or any instance of a class implementing ``Networked``) that has previously been registered to be reregistered with the Channel Name Server. The name should have been leased (see ``leaseChannelName(String, NameAccessLevel, ChannelNameKey)`` ). It is necessaray to supply the key that was obtained when the name was leased. If the channel name has not previously been registered, then the key can be specified as `null`.

The name will be registered in the specified name space. This is specified by passing in a ``NameAccessLevel`` object.

A name will stay registered with the Channel Name Server until it has been leased, deregistered or the Node that registered the name has shut down.

This method is safe to be called by concurrent processes.

Specified by:
  `register` in interface `CNSUser`
Parameters:
  `owner` - the `Networked` object whose location should be registered.
  `name` - the name against which to register the channel.
  `accessLevel` - the name space in which to register the channel name.
  `key` - the `ChannelNameKey` returned when the name was leased.
Returns:
  the `ChannelNameKey` needed for managing the name registration or `null` if registration failed.
See Also:
  - `NameAccessLevel`

### register

public ChannelNameKey register(NetChannelLocation ownerLocation, String name, NameAccessLevel accessLevel, ChannelNameKey key)

This method allows a channel's location to be registered against a name in the Channel Name Server. It differs from the other register methods in that it takes a `NetChannelLocation` object instead of a `Networked` object. This can be obtained from a `Networked` object by invoking its `#getChannelLocation()` method (see ``Networked.getChannelLocation()``).

The name will be registered in the specified name space. This is specified by passing in a ``NameAccessLevel`` object.

This method also allows a leased channel name to be registered against an actual location (see ``register(Networked, String, NameAccessLevel, ChannelNameKey)`` ).

A name will stay registered with the Channel Name Server until it has been leased, deregistered or the Node that registered the name has shut down.

This method is safe to be called by concurrent processes.

Specified by:
  `register` in interface `CNSUser`
Parameters:
  `ownerLocation` - the location of a channel to be registered against the name.
  `name` - the name against which to register the channel.
  `accessLevel` - the name space in which to register the channel name.
  `key` - the `ChannelNameKey` returned when the name was leased.
Returns:
  the `ChannelNameKey` needed for managing the name registration or `null` if registration failed.
See Also:
  - `register(Networked, String, NameAccessLevel, ChannelNameKey)`
  - `NameAccessLevel`

### leaseChannelName

public ChannelNameKey leaseChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) throws ChannelNameException, NameAccessLevelException

Leases the channel name within the specified name space from the Channel Name Server. Once a name has been leased, a channel cannot be registered with that name without supplying the key returned by the call to this method.

Currently, leases are infinite; they never expire. This is likely to change in the future so that leases have to be renewed. Leases can be given up by deregistering the name. Leases will remain even after the obtaining Node has shut down. This allows a channel to move its registered location to another channel on a different Node. There is no danger of another party managing to obtain the name as transfering a registered name into a lease is an atomic action. Although leases are currently infinite, there is no reason why a program cannot renew the lease by recalling this method.

A name may be leased without first registering a channel against it.

This method is safe to be called by concurrent processes.

Specified by:
  `leaseChannelName` in interface `CNSUser`
Parameters:
  `name` - the name to lease.
  `accessLevel` - the name space in which to lease the name.
  `channelKey` - the key to use if the name is currently registered or leased.
Returns:
  a new `ChannelNameKey` needed for managing the lease or `null` if leasing failed.
Throws:
  `ChannelNameException` - if the channel name is invalid.
  `NameAccessLevelException` - if the specifed name space is invalid.

### deregisterChannelName

public boolean deregisterChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey)

This deregisters a Channel name from the Channel Name Server. 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.

This method is safe to be called by concurrent processes.

Specified by:
  `deregisterChannelName` in interface `CNSUser`
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.