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

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 Detail

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.

nameAccessLevel - the nameAccessLevel of the channel.

channelKey - the ChannelNameKey to use to deregister the Channel name.

Returns:

a boolean indicating success.