com.sun.sgs.impl.util
Class AbstractService

java.lang.Object
  com.sun.sgs.impl.util.AbstractService

All Implemented Interfaces:

Service

Direct Known Subclasses:

ChannelServiceImpl, ClientSessionServiceImpl, NodeMappingServerImpl, NodeMappingServiceImpl, SimpleSgsProtocolAcceptor, TaskServiceImpl, WatchdogServerImpl, WatchdogServiceImpl

public abstract class AbstractService
extends Object
implements Service

An abstract implementation of a service. It manages state transitions (i.e., initialized, ready, shutting down, shutdown), in progress call tracking for services with embedded remote servers, and shutdown support.

The getName method invokes the instance's toString method, so a concrete subclass of AbstractService should provide an implementation of the toString method. An AbstractService(java.util.Properties, com.sun.sgs.kernel.ComponentRegistry, com.sun.sgs.service.TransactionProxy, com.sun.sgs.impl.sharedutil.LoggerWrapper) supports the following properties:

Property: com.sun.sgs.io.retries Default: 5 retries Specifies how many times an IO task should be retried before performing failure procedures.

Property: com.sun.sgs.impl.util.io.task.max.retries
Default: 5 retries
Specifies how many times an IoRunnable task should be retried before performing failure procedures. The value must be greater than or equal to 0.

Property: com.sun.sgs.impl.util.io.task.wait.time
Default: 100 milliseconds
Specifies the wait time between IoRunnable task retries. The value must be greater than or equal to 0.

Nested Class Summary

protected static class	AbstractService.State Service state.
static class	AbstractService.Version An immutable class to hold the current version of the keys and data persisted by a service.

Field Summary

protected String	appName The application name.
protected DataService	dataService The data service.
static String	IO_TASK_PROPERTY_PREFIX Prefix for io task related properties.
static String	IO_TASK_RETRIES_PROPERTY An optional property that specifies the maximum number of retries for IO tasks in services.
static String	IO_TASK_WAIT_TIME_PROPERTY An optional property that specifies the wait time between successive IO task retries.
protected LoggerWrapper	logger The logger for the subclass.
protected int	maxIoAttempts The maximum number of retry attempts for IO operations.
protected int	retryWaitTime The time (in milliseconds) to wait between retries for IO operations.
protected Identity	taskOwner The task owner.
protected TaskScheduler	taskScheduler The task scheduler.
protected TransactionScheduler	transactionScheduler The transaction scheduler.
protected static TransactionProxy	txnProxy The transaction proxy, or null if configure has not been called.

Constructor Summary

protected

AbstractService(Properties properties, ComponentRegistry systemRegistry, TransactionProxy txnProxy, LoggerWrapper logger) Constructs an instance with the specified properties, systemRegistry, txnProxy, and logger.

Method Summary

protected void	callFinished() Decrements the in progress call count, and if this server is shutting down and the count reaches 0, then notifies the waiting shutdown thread that it is safe to continue.
protected void	callStarted() Increments the number of calls in progress.
void	checkNonTransactionalContext() Checks that the current thread is not in a transactional context and throws IllegalStateException if the thread is in a transactional context.
protected void	checkServiceVersion(String versionKey, int majorVersion, int minorVersion) Checks the service version.
TaskQueue	createTaskQueue() Creates a TaskQueue for dependent, transactional tasks.
protected abstract void	doReady() Performs ready operations.
protected abstract void	doShutdown() Performs shutdown operations.
DataService	getDataService() Returns the data service.
String	getName() Returns the name used to identify this service.
protected AbstractService.State	getState() Returns this service's state.
protected abstract void	handleServiceVersionMismatch(AbstractService.Version oldVersion, AbstractService.Version currentVersion) Handles conversion from the oldVersion to the currentVersion.
boolean	isAlive(long nodeId) Runs a transactional task to query the status of the node with the specified nodeId and returns true if the node is alive and false otherwise.
protected boolean	isInInitializedState() Returns true if this service is in the initialized state but is not yet ready to run.
static boolean	isRetryableException(Exception e) Returns true if the specified exception is retryable, and false otherwise.
void	ready() Notifies this Service that the application is fully configured and ready to start running.
boolean	runIoTask(IoRunnable ioTask, long nodeId) Executes the specified ioTask by invoking its run method.
void	shutdown() Shuts down this service.
boolean	shuttingDown() Returns true if this service is shutting down.

Methods inherited from class java.lang.Object

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

Field Detail

txnProxy

protected static volatile TransactionProxy txnProxy

The transaction proxy, or null if configure has not been called.

appName

protected final String appName

The application name.

logger

protected final LoggerWrapper logger

The logger for the subclass.

dataService

protected final DataService dataService

The data service.

taskScheduler

protected final TaskScheduler taskScheduler

The task scheduler.

transactionScheduler

protected final TransactionScheduler transactionScheduler

The transaction scheduler.

taskOwner

protected final Identity taskOwner

The task owner.

IO_TASK_PROPERTY_PREFIX

public static final String IO_TASK_PROPERTY_PREFIX

Prefix for io task related properties.

See Also:

Constant Field Values

IO_TASK_RETRIES_PROPERTY

public static final String IO_TASK_RETRIES_PROPERTY

An optional property that specifies the maximum number of retries for IO tasks in services.

See Also:

Constant Field Values

IO_TASK_WAIT_TIME_PROPERTY

public static final String IO_TASK_WAIT_TIME_PROPERTY

An optional property that specifies the wait time between successive IO task retries.

See Also:

Constant Field Values

retryWaitTime

protected final int retryWaitTime

The time (in milliseconds) to wait between retries for IO operations.

maxIoAttempts

protected final int maxIoAttempts

The maximum number of retry attempts for IO operations.

Constructor Detail

AbstractService

protected AbstractService(Properties properties,
                          ComponentRegistry systemRegistry,
                          TransactionProxy txnProxy,
                          LoggerWrapper logger)

Constructs an instance with the specified properties, systemRegistry, txnProxy, and logger. It initializes the appName field to the value of the com.sun.sgs.app.name property and sets this service's state to INITIALIZED.

Parameters:

properties - service properties

systemRegistry - system registry

txnProxy - transaction proxy

logger - the service's logger

Throws:

IllegalArgumentException - if the com.sun.sgs.app.name property is not defined in properties

Method Detail

getName

public String getName()

Returns the name used to identify this service.

Specified by:

getName in interface Service

Returns:

the service's name

ready

public void ready()
           throws Exception

Notifies this Service that the application is fully configured and ready to start running. This means that all other Services associated with this application have been successfully created. If the method throws an exception, then the application will be shutdown.

If this service is in the INITIALIZED state, this method sets the state to READY and invokes the doReady method. If this service is already in the READY state, this method performs no actions. If this service is shutting down, or is already shut down, this method throws IllegalStateException.

Specified by:

ready in interface Service

Throws:

Exception - if a problem occurs

IllegalStateException - if this service is shutting down or is already shut down

doReady

protected abstract 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.

Throws:

Exception - if a problem occurs

shutdown

public void shutdown()

Shuts down this service. Any call to this method will block until the shutdown has completed. If a shutdown has been completed already, this method will return immediately.

This method does not require a transaction, and should not be called from one because this method will typically not succeed if there are outstanding transactions.

When this method returns, it is assumed that the service has been shutdown.

Callers should assume that, in a worst case, this method may block indefinitely, and so should arrange to take other action (for example, calling System.exit) if the call fails to complete successfully in a certain amount of time.

If this service is in the INITIALIZED state or READY state, this method sets the state to SHUTTING_DOWN, waits for all calls in progress to complete, starts a thread to invoke the doShutdown method, waits for that thread to complete, and returns. If this service is in the SHUTTING_DOWN state, this method will block until the shutdown is complete. If this service is in the SHUTDOWN state, then it will return immediately. Any retries or interruption handling should be done in the service's implementation of the doShutdown method.

Specified by:

shutdown in interface Service

doShutdown

protected abstract 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.

checkServiceVersion

protected final void checkServiceVersion(String versionKey,
                                         int majorVersion,
                                         int minorVersion)

Checks the service version. If a version is not associated with the given versionKey, then a new Version object (constructed with the specified majorVersion and minorVersion) is bound in the data service with the specified key.

If an old version is bound to the specified key and that old version is not equal to the current version (as specified by majorVersion/minorVersion), then the handleServiceVersionMismatch method is invoked to convert the old version to the new version. If the handleVersionMismatch method returns normally, the old version is removed and the current version is bound to the specified key.

This method must be called within a transaction.

Parameters:

versionKey - a key for the version

majorVersion - a major version

minorVersion - a minor version

Throws:

TransactionException - if there is a problem with the current transaction

IllegalStateException - if handleVersionMismatch is invoked and throws a RuntimeException

handleServiceVersionMismatch

protected abstract 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.

Parameters:

oldVersion - the old version

currentVersion - the current version

Throws:

IllegalStateException - if the old version cannot be upgraded to the current version

getState

protected AbstractService.State getState()

Returns this service's state.

Returns:

this service's state

callStarted

protected void callStarted()

Increments the number of calls in progress. This method should be invoked by remote methods to both increment in progress call count and to check the state of this server. When the call has completed processing, the remote method should invoke callFinished before returning.

Throws:

IllegalStateException - if this service is shutting down

callFinished

protected void callFinished()

Decrements the in progress call count, and if this server is shutting down and the count reaches 0, then notifies the waiting shutdown thread that it is safe to continue. A remote method should invoke this method when it has completed processing.

shuttingDown

public boolean shuttingDown()

Returns true if this service is shutting down.

Returns:

true if this service is shutting down

isInInitializedState

protected boolean isInInitializedState()

Returns true if this service is in the initialized state but is not yet ready to run.

Returns:

true if this service is in the initialized state

isAlive

public boolean isAlive(long nodeId)

Runs a transactional task to query the status of the node with the specified nodeId and returns true if the node is alive and false otherwise.

This method must be called from outside a transaction or IllegalStateException will be thrown.

Parameters:

nodeId - a node ID

Returns:

true if the node with the associated ID is considered alive, otherwise returns false

Throws:

IllegalStateException - if this method is invoked inside a transactional context

createTaskQueue

public TaskQueue createTaskQueue()

Creates a TaskQueue for dependent, transactional tasks.

Returns:

the task queue

runIoTask

public boolean runIoTask(IoRunnable ioTask,
                         long nodeId)

Executes the specified ioTask by invoking its run method. If the specified task throws an IOException, this method will retry the task for a fixed number of times. The method will stop retrying if the node with the given nodeId is no longer alive. The number of retries and the wait time between retries are configurable properties.

This method must be called from outside a transaction or IllegalStateException will be thrown.

Parameters:

ioTask - a task with IO-related operations

nodeId - the node that is the target of the IO operations

Returns:

true if the task was successfully executed and false if the specified node is no longer alive

Throws:

IllegalStateException - if this method is invoked within a transactional context

getDataService

public DataService getDataService()

Returns the data service.

Returns:

the data service

isRetryableException

public static boolean isRetryableException(Exception e)

Returns true if the specified exception is retryable, and false otherwise. A retryable exception is one that implements ExceptionRetryStatus and invoking its shouldRetry method returns true.

Parameters:

e - an exception

Returns:

true if the specified exception is retryable, and false otherwise

checkNonTransactionalContext

public void checkNonTransactionalContext()

Checks that the current thread is not in a transactional context and throws IllegalStateException if the thread is in a transactional context.