Task management methods using a scheduler

The scheduler provides several task management methods.

When a task is created by calling the create() method on a scheduler, a TaskStatus object is returned to the caller. The TaskStatus object contains the task ID, which is a unique identifier. The Scheduler API and WASScheduler MBean define several additional methods that pertain to the management of tasks, each of which accepts the task ID as a parameter. The following task management methods are defined:

suspend(): Suspends a task. The task does not run until it has been resumed.
resume(): Resumes a previously suspended task.
cancel(): Cancels a task. The task is not run and cannot be resumed.
purge(): Permanently deletes a cancelled task from the persistent store.
getStatus(): Returns the current status of the task.

Use the following API example to create and cancel a task:

//Create the task. 
TaskInfo taskInfo = ...
TaskStatus status = scheduler.create(taskInfo);

//Get the task ID
String taskId = status.getTaskId();

//Cancel the task. Specify the purgeAlso flag so that the task does not remain in the persistent store
scheduler.cancel(taskId,true);

Use the following Jython command operations in the wsadmin tool to cancel and delete a task:

sch = AdminControl.completeObjectName('type=WASScheduler,name=xxxxx,*')
schName = AdminControl.makeObjectName(sch)

Where xxxxx is the scheduler name

To cancel the task:

AdminControl.invoke_jmx(schName, "cancel", ["yyyy", java.lang.Boolean("false")], ["java.lang.String", "java.lang.Boolean"])

To delete the task:

AdminControl.invoke_jmx(schName, "purge", ["yyyy"], ["java.lang.String"])

Where yyyy is the task ID

Transactionality. All methods of the Scheduler API are transactional. If a global transactional context is present, it is used to perform the operation. If an unexpected exception is thrown, the transaction is marked to roll back, and the caller must handle it appropriately. If an expected or declared exception is thrown, the transaction remains intact and the caller must choose to roll back or to commit the transaction. If the transaction is rolled back at some point, all scheduler operations performed within the transaction are also rolled back.

If a local transactional context is present, it is suspended and a new global transactional context begins. Likewise, if no transactional context is active, a global transactional context begins. In both cases, if an unexpected exception is thrown, the transaction rolls back. If a declared exception is thrown, the transaction is committed.

If another thread is concurrently modifying the task in question, a TaskPending exception is thrown. This is because schedulers lock the database optimistically. The calling application can then retry the operation.

Task management functions may block if the task is currently running. Because the scheduler guarantees that each task will run only once, the task must be locked for the duration of a running task. Likewise, if a task is changed using one of the management functions but the global transaction is not committed, any other management functions issued from another transaction for that task will be blocked.

A stateless session bean task’s TaskHandler.process() method can change it’s own state. However, the task must be running within the same transaction as the scheduler. Therefore, a running task can only modify itself if it is using the Required or Mandatory container managed transaction types. If the Requires New transaction type is specified on the process() method, all management functions will deadlock.

All methods defined by the Scheduler API are described in the API documentation.