Package org.jcsp.net.cns

# Interface CNSUser

All Known Implementing Classes:
  `CNSService`

public interface CNSUser
Interface that a class can implement to indicate that instances allow channel names within a naming service to be managed.

Author:
  Quickstone Technologies Limited
See Also:
  - `CNSService`
  - `CNSService.getUserObject()`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`deregisterChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey)`
This deregisters a registered or leased Channel name from the Naming Service implementation.
`ChannelNameKey`
`leaseChannelName(String name, NameAccessLevel accessLevel, ChannelNameKey channelKey)`
Leases the channel name within the specified name space from the Naming Service Implemenation.
`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 Naming Service implementation.
`ChannelNameKey`
`register(Networked owner, String name)`
This method allows a channel (or any instance of a class implementing ``Networked``) to be registered with a Naming Service Implementation.
`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 a Naming Service implementation.
`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 a Naming Service Implementation.
`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 Naming Service implementation.
`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.

## Method Details

### resolve

NetChannelLocation resolve(String name)

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

Parameters:
  `name` - the name of channel to resolve.
Returns:
  the location to which the name resolved.

### resolve

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.

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

ChannelNameKey register(Networked owner, String name)

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

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

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 a Naming Service Implementation.

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

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

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 a Naming Service implementation. 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.

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

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 Naming Service implementation. 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.

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

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 Naming Service implementation. 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)`` ).

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

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

Leases the channel name within the specified name space from the Naming Service Implemenation. 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.

Depending on the implementation, leases may expire, however, they may be renew by recalling this mehtod. Leases can be given up by deregistering the name. Leases should 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 should be no danger of another party managing to obtain the name as transfering a registered name into a lease should be an atomic action.

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

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

This deregisters a registered or leased Channel name from the Naming Service implementation. A boolean is returned to indicate whether deregistration was successful.

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.