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 example JACL script operations in wsadmin.sh to create and cancel a task:
set jndiName sched/MyScheduler
# Map the JNDI name to the mbean name. The mbean name is
# formed by replacing the / in the jndi name with . and prepending
# Scheduler_
regsub -all {/} $jndiName "." jndiName
set mbeanName Scheduler_$jndiName
puts "Looking-up Scheduler MBean $mbeanName"
set sched [$AdminControl queryNames WebSphere:*,type=WASScheduler,name=$mbeanName]
puts $sched
# Get the ObjectName format of the Scheduler MBean
set schedO [$AdminControl makeObjectName $sched]
# Create a TaskInfo object
# (Some code excluded)
set params [java::new {java.lang.Object[]} 1]
$params set 0 $taskInfo
set sigs [java::new {java.lang.String[]} 1]
$sigs set 0 com.ibm.websphere.scheduler.TaskInfo
set taskStatus [java::cast com.ibm.websphere.scheduler.TaskStatus [$AdminControl invoke_jmx $schedO
create $params $sigs]]
set taskID [$taskStatus getTaskId]
puts "Task Created. TaskID= $taskID"
# Cancel the task using the Task ID from the TaskStatus object returned during create.
set params [java::new {java.lang.Object[]} 1]
$params set 0 false
set sigs [java::new {java.lang.String[]} 1]
$sigs set 0 java.lang.boolean
set taskStatus [java::cast com.ibm.websphere.scheduler.TaskStatus [$AdminControl invoke_jmx $schedO
cancel $params $sigs]]
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.
Related tasks
Concept topic