Why and when to perform this task
When a task is created by calling the create() method on a scheduler instance, a TaskStatus object is returned to the caller. The status object contains the task ID, which is a unique identifier. The scheduler API defines 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:
For example, the following code creates and cancels 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);
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. 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 were 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.
All methods defined by the scheduler API are described in Javadoc .