public class CNSService
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 CNSService.install
,
CNSService.install
).
Modifiers | Name | Description |
---|---|---|
static String |
CNS_DEFAULT_SERVICE_NAME |
Constant specifying the default name of this service. |
static String |
CNS_SETTING_NAME_ADDRESS |
Constant specifying the setting name for CNS address. |
static String |
CNS_SETTING_NAME_ADMIN_CHANNEL_LABEL |
Constant specifying the setting name for server's admin channel. |
static String |
CNS_SETTING_NAME_SERVICE_NAME |
Constant specifying the setting name for setting the service name. |
Constructor and description |
---|
CNSService
() |
CNSService
(NodeAddressID cnsAddress) |
CNSService
(NodeAddressID cnsAddress, boolean start) |
CNSService
(NodeAddressID cnsAddress, String adminChannelLabel) |
CNSService
(NodeAddressID cnsAddress, String adminChannelLabel, boolean start) |
Type | Name and description |
---|---|
boolean |
deregisterChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) |
ServiceUserObject |
getUserObject() This returns a ServiceUserObject which implements the
Resolver interface. |
boolean |
init(ServiceSettings settings) |
static CNSService |
install(NodeKey key, NodeAddressID cnsAddress) |
static CNSService |
install(NodeKey key, NodeAddressID cnsAddress, String serviceName) |
boolean |
isRunning() This returns whether the service is running. |
ChannelNameKey |
leaseChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey) |
ChannelNameKey |
register(Networked owner, String name) |
ChannelNameKey |
register(Networked owner, String name, NameAccessLevel accessLevel) |
ChannelNameKey |
register(Networked owner, String name, ChannelNameKey key) |
ChannelNameKey |
register(Networked owner, String name, NameAccessLevel accessLevel, ChannelNameKey key) |
ChannelNameKey |
register(NetChannelLocation ownerLocation, String name, NameAccessLevel accessLevel, ChannelNameKey key) |
NetChannelLocation |
resolve(String name) |
NetChannelLocation |
resolve(String name, NameAccessLevel accessLevel) |
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. |
Constant specifying the default name of this service.
Constant specifying the setting name for CNS address.
Constant specifying the setting name for server's admin channel.
Constant specifying the setting name for setting the service name.
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.
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.
cnsAddress the
- address of channel name server to use.
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.
cnsAddress
- the address of channel name server to use.start
- indicates whether the service should be started.
Should be true
to start service.
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
.
cnsAddress the
- address of channel name server to use.adminChannelLabel
- the label of server's admin channel.
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.
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.
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.
name
- the name of the channel as a String.nameAccessLevel
- the nameAccessLevel of the channel.channelKey
- the ChannelNameKey to use to deregister the
Channel name. 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
.
ServiceUserObject
.Resolver
which can be used to resolve names
using this CNSService
.
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.
true
if this request to initialize the service
succeeds.settings
- A
ServiceSettings
object that holds the
settings for this service.
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.
CNS
object installed.key
- the local Node's NodeKey
.cnsAddress the
- address of the Channel Name Server to use.
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.
CNS
object installed.key
- the local Node's NodeKey
.cnsAddress the
- address of the Channel Name Server to use.name
- the name to give the service.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.
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.
ChannelNameKey
needed for managing the
lease or null
if leasing failed.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.
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.
ChannelNameKey
needed for managing
the name registration or null
if registration
failed.owner
- the Networked
object whose location
should be registered.name
- the name against which to register the channel.
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.
ChannelNameKey
needed for managing
the name registration or null
if registration
failed.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.
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.
ChannelNameKey
needed for managing
the name registration or null
if registration
failed.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.
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.
ChannelNameKey
needed for managing
the name registration or null
if registration
failed.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.
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()#getChannelLocation()
).
The name will be registered in the specified name space. This is
specified by passing in a NameAccessLevel
object.
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.
ChannelNameKey
needed for managing
the name registration or null
if registration
failed.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.
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.
name
- the name of channel to resolve.
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.
name
- the name of channel to resolve.accessLevel
- the name space in which to resolve
the channel name.This checks to see if the service is already running, if it is not then it starts it.
This checks to see if the service is running, if it is then it stops it.
JCSP for Java 1.8 generated 14-10-2016 by Jon Kerridge, Edinburgh Napier University - j dot kerridge at napier dot ac dot uk