com.sun.sgs.impl.service.session
Class ClientSessionServiceImpl

java.lang.Object
  com.sun.sgs.impl.util.AbstractService
      com.sun.sgs.impl.service.session.ClientSessionServiceImpl

All Implemented Interfaces:

ClientSessionService, Service

public final class ClientSessionServiceImpl
extends AbstractService
implements ClientSessionService

Manages client sessions.

The constructor requires the com.sun.sgs.app.name configuration property and supports these public configuration properties. It also supports the following additional properties:

Property: "com.sun.sgs.impl.service.session.server.port"
Default: 0

Specifies the port for the ClientSessionService's internal server.

Property: "com.sun.sgs.impl.service.session.buffer.write.max"
Default: 131072

Specifies the approximate write buffer capacity per client session.

Property: "com.sun.sgs.impl.service.session.events.per.txn"
Default: 1

Specifies the number of client session events to process per transaction.

Property: "com.sun.sgs.impl.service.session.allow.new.login"
Default: false

If false, any connecting client with the same username as an already connected client will not be permitted to login. If true, the user's existing session will be disconnected and the new login is allowed to proceed.

Property: "com.sun.sgs.impl.service.session.login.high.water"
Default: Integer.MAX_VALUE / 2

Specifies the login high water. When the number of logins reaches the high water, the service's health is set to Node.Health.YELLOW. If the number of logins exceeds 10% above the high water the service's health is set to Node.Health.ORANGE. Legal values are between 0 and Integer.MAX_VALUE.

Property: "com.sun.sgs.impl.service.session.protocol.acceptor"
Default: "com.sun.sgs.impl.protocol.simple.SimpleSgsProtocolAcceptor"

Specifies the name of the class which will be used as the protocol acceptor. The default value uses an acceptor based on the SimpleSgsProtocol. Other values should specify the fully qualified name of a non-abstract class that implements ProtocolAcceptor.

Property: "com.sun.sgs.impl.service.session.relocation.key.length"
Default: 16

Specifies the length, in bytes, of a relocation key.

Property: "com.sun.sgs.impl.service.session.relocation.timeout"
Default: 10000L

Specifies the timeout, in milliseconds, for client session relocation.

Nested Class Summary

(package private) static interface	ClientSessionServiceImpl.Action An action to perform during commit.
(package private) class	ClientSessionServiceImpl.Context

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

AbstractService.State, AbstractService.Version

Field Summary

(package private) static String	ALLOW_NEW_LOGIN_PROPERTY The name of the allow new login property.
(package private) boolean	allowNewLogin The flag that indicates how to handle same user logins.
(package private) static int	DEFAULT_EVENTS_PER_TXN The default events per transaction.
(package private) static String	DEFAULT_PROTOCOL_ACCEPTOR The default protocol acceptor class.
(package private) static int	DEFAULT_RELOCATION_KEY_LENGTH The default length of a relocation key, in bytes.
(package private) static int	DEFAULT_SERVER_PORT The default server port.
(package private) static int	DEFAULT_WRITE_BUFFER_SIZE The default write buffer size: 131072
(package private) static String	EVENTS_PER_TXN_PROPERTY The events per transaction property.
(package private) int	eventsPerTxn The maximum number of session events to service per transaction.
(package private) static String	LOGIN_HIGH_WATER_PROPERTY The name of the login high water property.
(package private) NodeMappingService	nodeMapService The node mapping service.
(package private) static String	PROTOCOL_ACCEPTOR_PROPERTY The protocol acceptor property name.
(package private) static String	RELOCATION_KEY_LENGTH_PROPERTY The relocation key length property.
(package private) int	relocationKeyLength The session relocation key length.
(package private) long	relocationTimeout The session relocation timeout.
(package private) static String	SERVER_PORT_PROPERTY The name of the server port property.
(package private) ClientSessionServiceStats	serviceStats Our JMX exposed statistics.
(package private) TaskService	taskService The task service.
(package private) WatchdogService	watchdogService The watchdog service.
(package private) static String	WRITE_BUFFER_SIZE_PROPERTY The name of the write buffer size property.

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, maxIoAttempts, retryWaitTime, taskOwner, taskScheduler, transactionScheduler, txnProxy

Constructor Summary

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

Method Summary

(package private) void	addHandler(BigInteger sessionRefId, ClientSessionHandler handler, Identity identity) Adds the handler for the specified session to the internal session handler map.
(package private) void	addServiceEventQueueTask(byte[] sessionId) Schedules a transactional task to service the event queue for the session with the specified sessionId.
void	addSessionStatusListener(ClientSessionStatusListener listener) Adds the specified status listener to be notified when a local session disconnects or is being prepared to relocate.
(package private) ClientSessionServiceImpl.Context	checkContext() Obtains information associated with the current transaction, throwing TransactionNotActiveException if there is no current transaction, and throwing IllegalStateException if there is a problem with the state of the transaction or if this service has not been initialized with a transaction proxy.
void	doReady() Performs ready operations.
void	doShutdown() Performs shutdown operations.
(package private) ChannelServiceImpl	getChannelService() Returns the channel service.
(package private) ClientSessionServer	getClientSessionServer(long nodeId) Returns the proxy for the client session server on the specified nodeId, or null if no server exists.
(package private) ClientSessionHandler	getHandler(BigInteger sessionRefId) Returns the ClientSessionHandler for the specified client session ID.
(package private) Node.Health	getHealth() Get the service's health.
(package private) static ClientSessionServiceImpl	getInstance() Returns the client session service relevant to the current context.
(package private) long	getLocalNodeId() Returns the local node's ID.
(package private) int	getLoginHighWater() Get the login high water.
(package private) int	getNumSessions() Get the number of connected sessions.
(package private) Set<ProtocolDescriptor>	getProtocolDescriptors(long nodeId) Returns a set of protocol descriptors for the specified nodeId, or null if there are no descriptors for the node.
SessionProtocol	getSessionProtocol(BigInteger sessionRefId) Returns a protocol for the local client session with the specified sessionRefId or null if the specified client session is not connected to the local node.
(package private) TaskScheduler	getTaskScheduler() Returns the task scheduler.
(package private) static TaskService	getTaskService() Returns the task service.
(package private) TransactionProxy	getTransactionProxy() Returns the transaction proxy.
(package private) int	getWriteBufferSize() Returns the size of the write buffer to use for new connections.
protected void	handleServiceVersionMismatch(AbstractService.Version oldVersion, AbstractService.Version currentVersion) Handles conversion from the oldVersion to the currentVersion.
boolean	isRelocatingToLocalNode(BigInteger sessionRefId) Returns true if the session with the specified sessionRefId is known to be relocating to the local node, and returns false otherwise.
(package private) void	notifyPrepareToRelocate(BigInteger sessionRefId, long newNodeId) Notifies each registered ClientSessionStatusListener that the session with the specified sessionRefId is moving to a new node (specified by newNodeId).
(package private) void	removeHandler(BigInteger sessionRefId, boolean isRelocating) Removes the specified session from the internal session handler map, cleans up other session-related transient data, and if isDisconnecting is true notifies all ClientSessionStatusListeners of the session's disconnection.
(package private) boolean	removeUserLogin(Identity identity, ClientSessionHandler handler) Notifies this service that the specified identity is no longer logged in using the specified handler so that internal bookkeeping can be adjusted accordingly.
(package private) void	runTransactionalTask(KernelRunnable task, Identity ownerIdentity) Runs the specified task immediately, in a transaction.
(package private) void	scheduleTask(KernelRunnable task, Identity ownerIdentity) Schedules a non-durable, transactional task using the given Identity as the owner.
(package private) void	scheduleTaskOnCommit(KernelRunnable task) Schedules a non-durable, transactional task using the task service.
(package private) void	setLoginHighWater(int highWater) Set the login high water.
(package private) boolean	validateUserLogin(Identity identity, ClientSessionHandler handler, boolean loggingIn) Validates the identity of the user logging in and returns true if the login is allowed to proceed, and false if the login is denied.

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

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

Methods inherited from class java.lang.Object

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

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

getName, ready, shutdown

Field Detail

SERVER_PORT_PROPERTY

static final String SERVER_PORT_PROPERTY

The name of the server port property.

See Also:

Constant Field Values

DEFAULT_SERVER_PORT

static final int DEFAULT_SERVER_PORT

The default server port.

See Also:

Constant Field Values

WRITE_BUFFER_SIZE_PROPERTY

static final String WRITE_BUFFER_SIZE_PROPERTY

The name of the write buffer size property.

See Also:

Constant Field Values

DEFAULT_WRITE_BUFFER_SIZE

static final int DEFAULT_WRITE_BUFFER_SIZE

The default write buffer size: 131072

See Also:

Constant Field Values

EVENTS_PER_TXN_PROPERTY

static final String EVENTS_PER_TXN_PROPERTY

The events per transaction property.

See Also:

Constant Field Values

DEFAULT_EVENTS_PER_TXN

static final int DEFAULT_EVENTS_PER_TXN

The default events per transaction.

See Also:

Constant Field Values

ALLOW_NEW_LOGIN_PROPERTY

static final String ALLOW_NEW_LOGIN_PROPERTY

The name of the allow new login property.

See Also:

Constant Field Values

LOGIN_HIGH_WATER_PROPERTY

static final String LOGIN_HIGH_WATER_PROPERTY

The name of the login high water property.

See Also:

Constant Field Values

PROTOCOL_ACCEPTOR_PROPERTY

static final String PROTOCOL_ACCEPTOR_PROPERTY

The protocol acceptor property name.

See Also:

Constant Field Values

DEFAULT_PROTOCOL_ACCEPTOR

static final String DEFAULT_PROTOCOL_ACCEPTOR

The default protocol acceptor class.

See Also:

Constant Field Values

RELOCATION_KEY_LENGTH_PROPERTY

static final String RELOCATION_KEY_LENGTH_PROPERTY

The relocation key length property.

See Also:

Constant Field Values

DEFAULT_RELOCATION_KEY_LENGTH

static final int DEFAULT_RELOCATION_KEY_LENGTH

The default length of a relocation key, in bytes.

See Also:

Constant Field Values

watchdogService

final WatchdogService watchdogService

The watchdog service.

nodeMapService

final NodeMappingService nodeMapService

The node mapping service.

taskService

final TaskService taskService

The task service.

eventsPerTxn

final int eventsPerTxn

The maximum number of session events to service per transaction.

allowNewLogin

final boolean allowNewLogin

The flag that indicates how to handle same user logins. If true, then if the same user logs in, the existing session will be disconnected, and the new login is allowed to proceed. If false, then if the same user logs in, the new login will be denied.

relocationKeyLength

final int relocationKeyLength

The session relocation key length.

relocationTimeout

final long relocationTimeout

The session relocation timeout.

serviceStats

final ClientSessionServiceStats serviceStats

Our JMX exposed statistics.

Constructor Detail

ClientSessionServiceImpl

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

Constructs an instance of this class with the specified properties.

Parameters:

properties - service properties

systemRegistry - system registry

txnProxy - transaction proxy

Throws:

Exception - if a problem occurs when creating the service

Method Detail

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

public void doReady()
             throws Exception

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

Throws:

Exception - if a problem occurs

doShutdown

public 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

getClientSessionServer

ClientSessionServer getClientSessionServer(long nodeId)

Returns the proxy for the client session server on the specified nodeId, or null if no server exists.

Parameters:

nodeId - a node ID

Returns:

the proxy for the client session server on the specified nodeId, or null

addSessionStatusListener

public void addSessionStatusListener(ClientSessionStatusListener listener)

Adds the specified status listener to be notified when a local session disconnects or is being prepared to relocate. This method is non-transactional and should be called outside of a transaction.

Specified by:

addSessionStatusListener in interface ClientSessionService

Parameters:

listener - a listener to notify when a session disconnects or is being prepared to relocate

getSessionProtocol

public SessionProtocol getSessionProtocol(BigInteger sessionRefId)

Returns a protocol for the local client session with the specified sessionRefId or null if the specified client session is not connected to the local node.

The sessionRefId is the ID obtained by invoking getId on a ManagedReference to the associated ClientSession.

This method is non-transactional. However, the method may be invoked inside or outside of a transaction. The SessionProtocol returned from this method is used to communicate with a client, so it should only be used outside of a transaction.

Specified by:

getSessionProtocol in interface ClientSessionService

Parameters:

sessionRefId - a client session ID, as a BigInteger

Returns:

a protocol, or null

isRelocatingToLocalNode

public boolean isRelocatingToLocalNode(BigInteger sessionRefId)

Returns true if the session with the specified sessionRefId is known to be relocating to the local node, and returns false otherwise.

Specified by:

isRelocatingToLocalNode in interface ClientSessionService

Parameters:

sessionRefId - a client session ID, as a BigInteger

Returns:

true if the session with the specified sessionRefId is known to be relocating to the local node, and returns false otherwise

getTransactionProxy

TransactionProxy getTransactionProxy()

Returns the transaction proxy.

getLocalNodeId

long getLocalNodeId()

Returns the local node's ID.

Returns:

the local node's ID

getWriteBufferSize

int getWriteBufferSize()

Returns the size of the write buffer to use for new connections.

Returns:

the size of the write buffer to use for new connections

getHandler

ClientSessionHandler getHandler(BigInteger sessionRefId)

Returns the ClientSessionHandler for the specified client session ID.

Parameters:

sessionRefId - a client session ID

Returns:

the handler

getNumSessions

int getNumSessions()

Get the number of connected sessions.

Returns:

the number of connected sessions

getLoginHighWater

int getLoginHighWater()

Get the login high water.

Returns:

the login high water

setLoginHighWater

void setLoginHighWater(int highWater)

Set the login high water. This call may cause the service's health to change.

Parameters:

highWater - the login high water

getHealth

Node.Health getHealth()

Get the service's health.

Returns:

the service's health

checkContext

ClientSessionServiceImpl.Context checkContext()

Obtains information associated with the current transaction, throwing TransactionNotActiveException if there is no current transaction, and throwing IllegalStateException if there is a problem with the state of the transaction or if this service has not been initialized with a transaction proxy.

getInstance

static ClientSessionServiceImpl getInstance()

Returns the client session service relevant to the current context.

Returns:

the client session service relevant to the current context

validateUserLogin

boolean validateUserLogin(Identity identity,
                          ClientSessionHandler handler,
                          boolean loggingIn)

Validates the identity of the user logging in and returns true if the login is allowed to proceed, and false if the login is denied.

A user with the specified identity is allowed to log in if one of the following conditions holds:

• the identity is not currently logged in and is not relocating to the current node, or
• the identity is logged in, and the com.sun.sgs.impl.service.session.allow.new.login property is set to true.

In the latter case (new login allowed), the existing user session logged in with identity is forcibly disconnected.

If this method returns true, the removeUserLogin(com.sun.sgs.auth.Identity, com.sun.sgs.impl.service.session.ClientSessionHandler) method must be invoked when the user with the specified identity is disconnected.

Parameters:

identity - the user identity

handler - the client session handler

loggingIn - if true session with specified identity is loggingIn; otherwise it is relocating

Returns:

true if the user is allowed to log in with the specified identity, otherwise returns false

removeUserLogin

boolean removeUserLogin(Identity identity,
                        ClientSessionHandler handler)

Notifies this service that the specified identity is no longer logged in using the specified handler so that internal bookkeeping can be adjusted accordingly.

Parameters:

identity - the user identity

handler - the client session handler

addHandler

void addHandler(BigInteger sessionRefId,
                ClientSessionHandler handler,
                Identity identity)

Adds the handler for the specified session to the internal session handler map. This method is invoked by the handler once the client has successfully logged in or has successfully relocated. If the client has relocated, the identity should be non-null, otherwise, the identity should be null.

Parameters:

sessionRefId - the session ID, as a BigInteger

handler - the client session handler to cache

identity - if the session has been relocated, a non-null identity to be removed from the incomingRelocatingIdentities cache

removeHandler

void removeHandler(BigInteger sessionRefId,
                   boolean isRelocating)

Removes the specified session from the internal session handler map, cleans up other session-related transient data, and if isDisconnecting is true notifies all ClientSessionStatusListeners of the session's disconnection. This method is invoked by the handler (in order to clean up the session's transient data structures) when the session is disconnecting its connection due to session termination or session relocation. If a session is disconnecting because the session relocating to another node, then isDisconnecting will be false.

addServiceEventQueueTask

void addServiceEventQueueTask(byte[] sessionId)

Schedules a transactional task to service the event queue for the session with the specified sessionId. If there is no locally-connected session with the specified sessionId, then no action is taken.

This method should be invoked outside of a transaction.

Parameters:

sessionId - a session ID

notifyPrepareToRelocate

void notifyPrepareToRelocate(BigInteger sessionRefId,
                             long newNodeId)

Notifies each registered ClientSessionStatusListener that the session with the specified sessionRefId is moving to a new node (specified by newNodeId). The specified completion handler should be notified (via its completed method), when all listeners are finished preparing for relocation.

Parameters:

sessionRefId - the ID for the relocating client session

newNodeId - the ID of the new node for the client session

scheduleTask

void scheduleTask(KernelRunnable task,
                  Identity ownerIdentity)

Schedules a non-durable, transactional task using the given Identity as the owner.

scheduleTaskOnCommit

void scheduleTaskOnCommit(KernelRunnable task)

Schedules a non-durable, transactional task using the task service.

runTransactionalTask

void runTransactionalTask(KernelRunnable task,
                          Identity ownerIdentity)
                    throws Exception

Runs the specified task immediately, in a transaction.

Throws:

Exception

getTaskService

static TaskService getTaskService()

Returns the task service.

getTaskScheduler

TaskScheduler getTaskScheduler()

Returns the task scheduler.

Returns:

the task scheduler

getChannelService

ChannelServiceImpl getChannelService()

Returns the channel service.

getProtocolDescriptors

Set<ProtocolDescriptor> getProtocolDescriptors(long nodeId)

Returns a set of protocol descriptors for the specified nodeId, or null if there are no descriptors for the node. This method must be run outside a transaction.