com.sun.sgs.service
Interface NodeMappingService

All Superinterfaces:

Service

public interface NodeMappingService
extends Service

The Node Mapping Service has the following responsibilities:

• maintain mapping of active identities to nodes, and vice versa
• decide when the mapping should change (e.g. when a new client joins the system, a client account is canceled, an AI object is created, node failure, load balancing, an identity is quiescent)
• notify interested services of changes in the mapping

While decisions about changes to the map will be made outside a transaction, the actual mapping change will occur inside a transaction. Services can assume the mapping has not changed during one of their own transactions.

On initial client login, the ClientSessionService will get a node assignment via assignNode. If the assigned node is the current node (as determined by the nodeId), the client will proceed with the login protocol. Otherwise, the client will get a login response indicating a redirection, and the client code should attempt to log in at the redirected node.

Mappings will be removed when the system believes an identity has become quiescent, for example when a client logs out and there are no more durable tasks to be run for that client's identity. In order to determine whether an identity is quiescent, services which manage resources being used on an identity's behalf inform this mapping service when the identity is active or inactive on a node by calling setStatus. The node mapping service will use this information for a simple reference counting garbage collection scheme within the map. Status is tracked per node, so services should consider only their local node state when calling setStatus.

TODO We might want a transactional method that returns true if an identity is both assigned to the local node and the local node is alive, as a convenience to other services.

TODO A variation of "assignNode" which adds hints for identities the input might want to colocate with will probably be added later.

Method Summary

void	addIdentityRelocationListener(IdentityRelocationListener listener) Adds a listener to be notified when an identity has been selected to be relocated off the local node.
void	addNodeMappingListener(NodeMappingListener listener) Adds a listener to be notified when the identity mapping for this node is modified.
long	assignNode(Class service, Identity identity) Assigns the identity to a node and adds the assignment to the map.
Iterator<Identity>	getIdentities(long nodeId) Returns an Iterator for the set of identities assigned to a node.
Node	getNode(Identity identity) Returns the live node to which the identity is assigned.
void	setStatus(Class service, Identity identity, boolean active) Inform the NodeMappingService that a service instance has observed a change in status of an identity on this node.

Methods inherited from interface com.sun.sgs.service.Service

getName, ready, shutdown

Method Detail

assignNode

long assignNode(Class service,
                Identity identity)

Assigns the identity to a node and adds the assignment to the map. If the identity has no node assignment, or the current assignment is not to a live node, a node is selected for it; otherwise, no action is performed.

Additionally (and atomically), notes that the service considers the identity to be active, as though setStatus(service, identity, true) had been called on the assigned node.

This method should not be called while in a transaction, as this method call could entail remote communication.

The returned node ID might not match the ID of the node returned from an immediate call to getNode in a transaction because an identity's node assignment may change at any time.

Parameters:

service - the class of the caller

identity - the identity to assign to a node

Returns:

the ID of the node that the identity was assigned to, or -1 if the assignment failed

Throws:

IllegalStateException - if this method is called while in a transaction

setStatus

void setStatus(Class service,
               Identity identity,
               boolean active)
               throws UnknownIdentityException

Inform the NodeMappingService that a service instance has observed a change in status of an identity on this node. When all services which have previously noted an identity as active set the status to false, the identity can be removed from the map. If a node fails or the node mapping service initiates a mapping change (for load balancing), all status votes for the failing or old node are implicitly set to inactive.

This method should not be called while in a transaction, as this method call could entail remote communication.

Parameters:

service - the class of the calling service

identity - the identity for which service has observed a state change

active - true if the identity is active, false if the identity is inactive

Throws:

UnknownIdentityException - if the identity is not in the map

IllegalStateException - if this method is called while in a transaction

getNode

Node getNode(Identity identity)
             throws UnknownIdentityException

Returns the live node to which the identity is assigned.

This method must be called from within a transaction.

Parameters:

identity - the identity

Returns:

node information for the specified identity

Throws:

UnknownIdentityException - if the identity is not in the map

TransactionException - if the operation failed because of a problem with the current transaction

getIdentities

Iterator<Identity> getIdentities(long nodeId)
                                 throws UnknownNodeException

Returns an Iterator for the set of identities assigned to a node. The set will be empty if no identities are assigned to the node.

The remove operation of the returned iterator is not supported and will throw UnsupportedOperationException if invoked.

This method should only be called within a transaction, and the returned iterator should only be used within that transaction.

Parameters:

nodeId - a node ID

Returns:

an iterator for all identities assigned to this node

Throws:

UnknownNodeException - if the nodeId is unknown

IllegalArgumentException - if the specified nodeId is not within the range of valid IDs

TransactionException - if the operation failed because of a problem with the current transaction

addIdentityRelocationListener

void addIdentityRelocationListener(IdentityRelocationListener listener)

Adds a listener to be notified when an identity has been selected to be relocated off the local node. The listener will be invoked outside of a transaction.

If a Service needs to take actions before an identity is moved, it should register one (or more) listener objects when constructed. The order of callbacks to listener objects is not specified, and the callbacks will occur asynchronously.

The identity will be moved, and the mapping modified, when all listener objects have completed their work, or after a time delay in case a listener does not respond that it is finished.

Parameters:

listener - a listener to be notified prior to an identity moving from the local node

addNodeMappingListener

void addNodeMappingListener(NodeMappingListener listener)

Adds a listener to be notified when the identity mapping for this node is modified. This method is not performed under a transaction; listeners are held locally on nodes.

If a Service needs to take actions when identities are added to or removed from a local node, it should register one (or more) listener objects when it is constructed. The order of callbacks to listener objects is not specified, and the callbacks will occur asynchronously.

Parameters:

listener - a listener to be notified of local changes to the map