com.sun.sgs.impl.service.nodemap
Class NodeMappingServiceImpl

java.lang.Object
  com.sun.sgs.impl.util.AbstractService
      com.sun.sgs.impl.service.nodemap.NodeMappingServiceImpl

All Implemented Interfaces:

NodeMappingService, Service

public class NodeMappingServiceImpl
extends AbstractService
implements NodeMappingService

Maps Identities to Nodes.

The constructor supports the following properties:

Property: com.sun.sgs.impl.service.nodemap.server.host
Default: the value of the com.sun.sgs.server.host property, if present, or localhost if this node is starting the server

The name of the host running the NodeMappingServer.

Property: com.sun.sgs.impl.service.nodemap.server.port
Default: 44535

The network port for the NodeMappingServer. This value must be no less than 0 and no greater than 65535. The value 0 can only be specified if the com.sun.sgs.node.type property is not appNode, and means that an anonymous port will be chosen for running the server.

Property: com.sun.sgs.impl.service.nodemap.client.port
Default: 0 (anonymous port)

The network port for the this service for receiving node mapping changes on this node from the NodeMapppingServer. This value must be no less than 0 and no greater than 65535.

This class uses the Logger named com.sun.sgs.impl.service.nodemap to log information at the following logging levels:

• SEVERE - Initialization failures
• CONFIG - Construction information
• WARNING - Errors
• FINEST - Trace operations

Nested Class Summary

Nested classes/interfaces inherited from class com.sun.sgs.impl.util.AbstractService

AbstractService.State, AbstractService.Version

Field Summary

(package private) static String

SERVER_HOST_PROPERTY The property name for the server host.

Fields inherited from class com.sun.sgs.impl.util.AbstractService

appName, dataService, IO_TASK_PROPERTY_PREFIX, IO_TASK_RETRIES_PROPERTY, IO_TASK_WAIT_TIME_PROPERTY, logger, maxIoAttempts, retryWaitTime, taskOwner, taskScheduler, transactionScheduler, txnProxy

Constructor Summary

NodeMappingServiceImpl(Properties properties, ComponentRegistry systemRegistry, TransactionProxy txnProxy)
Constructs an instance of this class with the specified properties.

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.
(package private) boolean	assertValid(Identity identity) Check the validity of the data store for a particular identity.
long	assignNode(Class service, Identity identity) Assigns the identity to a node and adds the assignment to the map.
protected void	doReady() Performs ready operations.
protected void	doShutdown() Performs shutdown operations.
Iterator<Identity>	getIdentities(long nodeId) Returns an Iterator for the set of identities assigned to a node.
String	getName() Returns the name used to identify this service.
Node	getNode(Identity id) Returns the live node to which the identity is assigned.
protected void	handleServiceVersionMismatch(AbstractService.Version oldVersion, AbstractService.Version currentVersion) Handles conversion from the oldVersion to the currentVersion.
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.
String	toString() Returns a string representation of this instance.

Methods inherited from class com.sun.sgs.impl.util.AbstractService

callFinished, callStarted, checkNonTransactionalContext, checkServiceVersion, createTaskQueue, getDataService, getState, isAlive, isInInitializedState, isRetryableException, ready, runIoTask, shutdown, shuttingDown

Methods inherited from class java.lang.Object

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

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

ready, shutdown

Field Detail

SERVER_HOST_PROPERTY

static final String SERVER_HOST_PROPERTY

The property name for the server host.

See Also:

Constant Field Values

Constructor Detail

NodeMappingServiceImpl

public NodeMappingServiceImpl(Properties properties,
                              ComponentRegistry systemRegistry,
                              TransactionProxy txnProxy)
                       throws Exception

Constructs an instance of this class with the specified properties.

The application context is resolved at construction time (rather than when AbstractService.ready() is called), because this service does not use Managers and will not run application code. Managers are not available until ready is called.

Parameters:

properties - the properties for configuring this service

systemRegistry - the registry of available system components

txnProxy - the transaction proxy

Throws:

Exception - if an error occurs during creation

Method Detail

getName

public String getName()

Returns the name used to identify this service.

Specified by:

getName in interface Service

Overrides:

getName in class AbstractService

Returns:

the service's name

handleServiceVersionMismatch

protected void handleServiceVersionMismatch(AbstractService.Version oldVersion,
                                            AbstractService.Version currentVersion)

Handles conversion from the oldVersion to the currentVersion. This method is invoked by checkServiceVersion if a version mismatch is detected and is invoked from within a transaction.

Specified by:

handleServiceVersionMismatch in class AbstractService

Parameters:

oldVersion - the old version

currentVersion - the current version

doReady

protected void doReady()

Performs ready operations. This method is invoked by the ready method only once so that the subclass can perform any operations necessary during the "ready" phase.

Specified by:

doReady in class AbstractService

doShutdown

protected void doShutdown()

Performs shutdown operations. This method is invoked by the shutdown method only once so that the subclass can perform any operations necessary to shutdown the service.

Specified by:

doShutdown in class AbstractService

assignNode

public 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.

If the identity is not associated with a client (i.e., if it is an AI object), it will be assigned to the local node. Otherwise, a remote call will be made to determine a node assignment.

Specified by:

assignNode in interface NodeMappingService

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

setStatus

public 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.

The local node makes the status change, avoiding a remote call where possible. However, if it appears that an identity might be ready for garbage collection, it tells the server, which will perform the deletion.

Specified by:

setStatus in interface NodeMappingService

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

getNode

public Node getNode(Identity id)
             throws UnknownIdentityException

Returns the live node to which the identity is assigned.

This method must be called from within a transaction.

Specified by:

getNode in interface NodeMappingService

Parameters:

id - the identity

Returns:

node information for the specified identity

Throws:

UnknownIdentityException - if the identity is not in the map

getIdentities

public 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.

Specified by:

getIdentities in interface NodeMappingService

Parameters:

nodeId - a node ID

Returns:

an iterator for all identities assigned to this node

Throws:

UnknownNodeException - if the nodeId is unknown

addIdentityRelocationListener

public 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.

Specified by:

addIdentityRelocationListener in interface NodeMappingService

Parameters:

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

addNodeMappingListener

public 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.

Specified by:

addNodeMappingListener in interface NodeMappingService

Parameters:

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

toString

public String toString()

Returns a string representation of this instance.

Overrides:

toString in class Object

Returns:

a string representation of this instance

assertValid

boolean assertValid(Identity identity)
              throws Exception

Check the validity of the data store for a particular identity. Used for testing.

Parameters:

identity - the identity

Returns:

true if all is well, false if there is a problem

Throws:

Exception - if any error occurs