atg.service.scheduler
Class SingletonSchedulableService

java.lang.Object
  extended by atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      extended by atg.nucleus.GenericService
          extended by atg.service.scheduler.SchedulableService
              extended by atg.service.scheduler.SingletonSchedulableService
All Implemented Interfaces:
NameContextBindingListener, NameContextElement, NameResolver, AdminableService, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, Schedulable, java.util.EventListener
Direct Known Subclasses:
AbandonedOrderService, atg.commerce.catalog.CMSService, ScheduledOrderService, SitemapGeneratorService, SitemapWriterService

public abstract class SingletonSchedulableService
extends SchedulableService

This class extends SchedulableService to allow multiple Dynamo servers to run the same scheduled service, while guaranteeing that only one instance of the service will perform the scheduled task at any given time. This provides a degree of protection from server failures, since the loss of any single Dynamo server will not prevent the scheduled service from running on some other Dynamo server.

SingletonSchedulableService is an appropriate choice for any scheduled service that must run exactly once for a given set of input data. Periodic report generation is one example: each report should be generated once and only once, but report generation should not fail if a single Dynamo server is down. Processing scheduled orders in a commerce application is another example: orders must be processed regardless of the status of any particular Dynamo server, but it is vital that each order be placed exactly once.

SingletonSchedulableService relies on a lock manager to ensure exclusive operation. Each service is configured with a reference to a client lock manager and a lock name. The client lock managers on all Dynamo hosts are configured to refer to the same server lock manager. When a SingletonSchedulableService's performScheduledTask method is called, it attempts to obtain a global write lock from the lock manager.

If the lock is obtained successfully, the service calls its own doScheduledTask method. If the lock is not obtained, the service assumes that some other instance of the service is currently running and waits until the next time the scheduler calls it.

Unlike subclasses of SchedulableService, which implement application specific functionality by implementing the performScheduledTask method, subclasses of SingletonSchedulableService implement functionality by implementing doScheduledTask.

See Also:
SchedulableService

Field Summary
static java.lang.String CLASS_VERSION
           
 
Fields inherited from class atg.service.scheduler.SchedulableService
mJobId
 
Fields inherited from class atg.nucleus.GenericService
SERVICE_INFO_KEY
 
Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging
DEFAULT_LOG_TRACE_STATUS
 
Fields inherited from interface atg.nucleus.logging.ApplicationLogging
DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS
 
Constructor Summary
SingletonSchedulableService()
           
 
Method Summary
protected  boolean acquireLock()
          The method will attempt to acqure an exclusive write lock.
abstract  void doScheduledTask(Scheduler pScheduler, ScheduledJob pJob)
          Perform the scheduled task for this service.
 ClientLockManager getClientLockManager()
          Get the ClientLockManager used to ensure that only one instance of the service is running at any given time.
 java.lang.String getLockName()
          Get the name of the global write lock that identifies this service.
 long getLockTimeOut()
          Get the maximum time we wait for a lock, in milliseconds.
 void performScheduledTask(Scheduler pScheduler, ScheduledJob pJob)
          The method will be called by the scheduler according to its schedule.
protected  void releaseLock()
          This method will release the lock, using the ClientLockManager
 void setClientLockManager(ClientLockManager pClientLockManager)
          Set the ClientLockManager used to ensure that only one instance of the service is running at any given time.
 void setLockName(java.lang.String pLockName)
          Set the name of the global write lock that identifies this service.
 void setLockTimeOut(long pLockTimeOut)
          Set the maximum time we wait for a lock, in milliseconds.
 
Methods inherited from class atg.service.scheduler.SchedulableService
doStartService, doStopService, getJobDescription, getJobId, getJobName, getSchedule, getScheduler, getThreadMethod, isTransactional, setJobDescription, setJobName, setSchedule, setScheduler, setThreadMethod, setTransactional, startScheduledJob, stopScheduledJob
 
Methods inherited from class atg.nucleus.GenericService
addLogListener, createAdminServlet, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService
 
Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION
Constructor Detail

SingletonSchedulableService

public SingletonSchedulableService()
Method Detail

setClientLockManager

public void setClientLockManager(ClientLockManager pClientLockManager)
Set the ClientLockManager used to ensure that only one instance of the service is running at any given time.


getClientLockManager

public ClientLockManager getClientLockManager()
Get the ClientLockManager used to ensure that only one instance of the service is running at any given time.


setLockName

public void setLockName(java.lang.String pLockName)
Set the name of the global write lock that identifies this service.


getLockName

public java.lang.String getLockName()
Get the name of the global write lock that identifies this service.


setLockTimeOut

public void setLockTimeOut(long pLockTimeOut)
Set the maximum time we wait for a lock, in milliseconds.


getLockTimeOut

public long getLockTimeOut()
Get the maximum time we wait for a lock, in milliseconds. The default value is zero, meaning wait forever for the lock if necessary.


acquireLock

protected boolean acquireLock()
The method will attempt to acqure an exclusive write lock. It tries to get a global lock named lockName from the client lock manager specified by ClientLockManager.

If the lock is obtained this method return true; If the lock is not obtained, or is not a global lock, the method returns false.

Note: If the client lock manager is configured with its useLockServer property set to false it means that global locking is not enabled for that lock manager. In that case, acquireLock will accept a local lock instead.


releaseLock

protected void releaseLock()
This method will release the lock, using the ClientLockManager


performScheduledTask

public void performScheduledTask(Scheduler pScheduler,
                                 ScheduledJob pJob)
The method will be called by the scheduler according to its schedule. It calls acquireLock

If the lock is obtained this method will call doScheduledTask. If the lock is not obtained the call to doScheduledTask will be skipped. In either case, the lock will be released before this method returns by calling releaseLock

Specified by:
performScheduledTask in interface Schedulable
Specified by:
performScheduledTask in class SchedulableService
Parameters:
pScheduler - the scheduler managing this job
pJob - the scheduled job associated with this service

doScheduledTask

public abstract void doScheduledTask(Scheduler pScheduler,
                                     ScheduledJob pJob)
Perform the scheduled task for this service. Subclasses should override this method to perform their application-specific work.