Interface Scheduler
-
public interface Scheduler
Scheduler is the central interface for managing and creating tasks.Instances of a Scheduler are defined using the administrative console, and located by performing a lookup in the WebSphere JNDI name space. For example:
InitialContext ic = new InitialContext(); Scheduler scheduler = (Scheduler)ic.lookup("java:comp/env/Scheduler");
(A resource reference to a scheduler is assumed to be bound to the name 'java:comp/env/Scheduler' here)Each Scheduler has an associated daemon thread that is responsible for executing tasks created within it's scope using the
Scheduler.create
method. Once tasks are created, the same application can then use the task's ID (retrieved from the create method's resultingTaskStatus
) to cancel, suspend, resume or purge the task. Since all tasks are persistent, if the application server is restarted, the daemon for the Scheduler will automatically start and begin executing the tasks. Likewise, you can continue to lookup tasks previously created and view their status or alter their state.- Since:
- 5.0
- Version:
- 5.0
-
-
Method Summary
Methods Modifier and Type Method and Description TaskStatus
cancel(java.lang.String taskId, boolean purgeAlso)
Cancels a task.TaskStatus
create(TaskInfo taskInfo)
Creates a task in the persistent store based upon the data found in the TaskInfo.BeanTaskInfo
createBeanTaskInfo()
Deprecated.Use thecreateTaskInfo
method.MessageTaskInfo
createMessageTaskInfo()
Deprecated.Use thecreateTaskInfo
method.java.lang.Object
createTaskInfo(java.lang.Class taskInfoInterface)
Creates an instance of the specified TaskInfo interface class.java.util.Iterator
findTasksByName(java.lang.String name)
Finds all TaskInfo records with a specified name that were created by the caller's application.TaskInfo[]
findTasksByName(java.lang.String name, int beginIndex, int endIndex)
Returns the subset of TaskInfo records between beginIndex and endIndex (0-based) that match the specified name and were created by the caller's application.java.util.Iterator
findTaskStatusByName(java.lang.String name)
Finds all TaskStatus records which have the specified name and were created by the caller's application.TaskStatus[]
findTaskStatusByName(java.lang.String name, int beginIndex, int endIndex)
Returns the subset of TaskStatus records between beginIndex and endIndex that match the specified name and were created by the caller's application.TaskStatus
getStatus(java.lang.String taskId)
Retrieves the current status of a task.TaskInfo
getTask(java.lang.String taskId)
Retrieves the current task.TaskStatus
purge(java.lang.String taskId)
Deletes a completed or cancelled task from the persistent store.TaskStatus
resume(java.lang.String taskId)
Resumes a suspended task.TaskStatus
suspend(java.lang.String taskId)
Suspends a task.
-
-
-
Method Detail
-
create
TaskStatus create(TaskInfo taskInfo) throws TaskInvalid, UserCalendarSpecifierInvalid, UserCalendarInvalid, SchedulerNotAvailableException, UserCalendarPeriodInvalid, NotificationSinkInvalid, NotificationException
Creates a task in the persistent store based upon the data found in the TaskInfo. When the task is created, use theTaskStatus.getTaskId
method to retrieve the task id for using with the other methods on theScheduler
.- Parameters:
taskInfo
- information describing the task.- Returns:
- the
TaskStatus
status of the task when created. - Throws:
SchedulerNotAvailableException
- Transaction is rolled-back or marked to roll-back. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. Thrown when the task has invalid parameters.UserCalendarInvalid
- No transaction rollback occurs. Thrown when the UserCalendar specified is not a valid UserCalendar bean.UserCalendarSpecifierInvalid
- No transaction rollback occurs. Thrown when the UserCalendar specifier is not valid for the set UserCalendar.UserCalendarPeriodInvalid
- No transaction rollback occurs. Thrown when the UserCalendar period is not valid for the set UserCalendar.NotificationSinkInvalid
- No transaction rollback occurs. Thrown when the NotificationSink specified is not a valid NotificationSink bean.NotificationException
- No transaction rollback occurs. Thrown when the NotificationSink fails to fire due to an exception.- Since:
- 5.0
- See Also:
BeanTaskInfo
,MessageTaskInfo
,TaskStatus.getTaskId()
-
createBeanTaskInfo
BeanTaskInfo createBeanTaskInfo()
Deprecated. Use thecreateTaskInfo
method.Creates an instance of BeanTaskInfo. Once created, use the BeanTaskInfo interface methods to configure the BeanTaskInfo and use the Scheduler.create method to schedule the BeanTaskInfo task.- Since:
- 5.0
- See Also:
createTaskInfo(java.lang.Class)
,BeanTaskInfo
-
createMessageTaskInfo
MessageTaskInfo createMessageTaskInfo()
Deprecated. Use thecreateTaskInfo
method.Creates an instance of MessageTaskInfo. Once created, use the MessageTaskInfo interface methods to configure the MessageTaskInfo and use the Scheduler.create method to schedule the MessageTaskInfo task.- Since:
- 5.0
- See Also:
createTaskInfo(java.lang.Class)
,MessageTaskInfo
-
createTaskInfo
java.lang.Object createTaskInfo(java.lang.Class taskInfoInterface) throws TaskInfoInvalid
Creates an instance of the specified TaskInfo interface class. Once created, use the associated methods on the interface to configure the TaskInfo and use the Scheduler.create method to schedule the task.For example:
BeanTaskInfo myTask = (BeanTaskInfo)scheduler.createTaskInfo(BeanTaskInfo.class); myTask.setTaskHandler(myHandlerHome); scheduler.create(myTask);
- Parameters:
taskInfoInterface
- the interface of the TaskInfo implementation you would like to create.- Returns:
- the instance of the specified interface.
- Throws:
TaskInfoInvalid
- the specified TaskInfo interface class is not available or registered.
-
cancel
TaskStatus cancel(java.lang.String taskId, boolean purgeAlso) throws SchedulerNotAvailableException, TaskInvalid, TaskPending, NotificationException
Cancels a task. When a task is cancelled, it remains in the persistent store until purged. In addition to the declared exceptions, it is also possible for this method to raise SchedulerRuntimeException, in which case the transaction is rolled back.- Parameters:
taskId
- The Task ID of the task which is to be canceled.purgeAlso
- Specifies that the task should be purged immediately.- Returns:
- the current
TaskStatus
of the task. - Throws:
SchedulerNotAvailableException
- Transaction is rolled-back or marked to roll-back. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.TaskPending
- No transaction rollback occurs. Thrown when another thread is currently modifying this row.NotificationException
- No transaction rollback occurs. Thrown when the NotificationSink fails to fire due to an exception.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
suspend
TaskStatus suspend(java.lang.String taskId) throws SchedulerNotAvailableException, TaskInvalid, TaskPending, IllegalTaskState, NotificationException
Suspends a task. A suspended task will not run until it has been resumed using the resume method. If the task is already in the suspended state, this has no effect.- Parameters:
taskId
- The Task ID of the task to be suspended.- Returns:
- the current
TaskStatus
of the task. - Throws:
SchedulerNotAvailableException
- Transaction is rolled-back or marked to roll-back. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.TaskPending
- No transaction rollback occurs. Thrown when another thread is currently modifying this row.IllegalTaskState
- No transaction rollback occurs. The task has been cancelled or completed. Cancelled and completed tasks cannot be suspended.NotificationException
- No transaction rollback occurs. Thrown when the NotificationSink fails to fire due to an exception.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
resume
TaskStatus resume(java.lang.String taskId) throws SchedulerNotAvailableException, TaskInvalid, TaskPending, IllegalTaskState, NotificationException
Resumes a suspended task.When a non-repeating task is resumed and the task fire time has elapsed, it will run immediately. If the fire time did not elapse, it will run at the scheduled time.
When a repeating task is resumed, it will not fire immediately, but at the next scheduled fire time based on the previous scheduled fire time. If a custom UserCalendar is used, the UserCalendar will be called continually until a date greater or equal to the current time is generated.
For example: A task is to run every hour using the SIMPLE calendar. The task's next fire time is 2:05, but was suspended at 1:30. If the task was resumed a week later at 5:30, the task would run at 6:05.
- Parameters:
taskId
- The Task ID of the task to be suspended.- Returns:
- the current
TaskStatus
of the task. - Throws:
SchedulerNotAvailableException
- Transaction is rolled-back or marked to roll-back. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.TaskPending
- No transaction rollback occurs. Thrown when another thread is currently modifying this row.IllegalTaskState
- No transaction rollback occurs. The task has been cancelled or completed. Only suspended tasks can be resumed.NotificationException
- No transaction rollback occurs. Thrown when the NotificationSink fails to fire due to an exception.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
purge
TaskStatus purge(java.lang.String taskId) throws SchedulerNotAvailableException, TaskInvalid, TaskPending, IllegalTaskState, NotificationException
Deletes a completed or cancelled task from the persistent store.- Parameters:
taskId
- The ID of the task to be deleted.- Returns:
- the current
TaskStatus
of the task. - Throws:
SchedulerNotAvailableException
- Transaction is rolled-back or marked to roll-back. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.TaskPending
- No transaction rollback occurs. Thrown when another thread is currently modifying this row.IllegalTaskState
- No transaction rollback occurs. The task has not been cancelled or completed. Only cancelled or completed tasks can be purged.NotificationException
- No transaction rollback occurs. Thrown when the NotificationSink fails to fire due to an exception.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
getStatus
TaskStatus getStatus(java.lang.String taskId) throws SchedulerNotAvailableException, TaskInvalid
Retrieves the current status of a task.- Parameters:
taskId
- the Task ID of the task that was assigned when created.- Returns:
- the current
TaskStatus
of the task. - Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
getTask
TaskInfo getTask(java.lang.String taskId) throws SchedulerNotAvailableException, TaskInvalid
Retrieves the current task.- Parameters:
taskId
- the Task ID of the task that was assigned when created.- Returns:
- the
TaskInfo
of the task. - Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.TaskInvalid
- No transaction rollback occurs. The task id is invalid or has been purged.- Since:
- 5.0
- See Also:
TaskStatus.getTaskId()
-
findTasksByName
java.util.Iterator findTasksByName(java.lang.String name) throws SchedulerNotAvailableException
Finds all TaskInfo records with a specified name that were created by the caller's application.The name can include SQL wildcards (depending on the database platform). Common wildcards include:
- '%' - Match all characters
- '?' - Match one character.
"AR_01_Sales" and "AR_ZZ_Sales", but not "AR_AAA_Sales"A name such as "AR_%" would return all names that begin with "AR_".
- Parameters:
name
- the name of the task to be found.- Returns:
- An iterator that can be used to retrieve the TaskInfo for the found tasks.
- Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.- Since:
- 5.0
-
findTaskStatusByName
java.util.Iterator findTaskStatusByName(java.lang.String name) throws SchedulerNotAvailableException
Finds all TaskStatus records which have the specified name and were created by the caller's application.See the
findTasksByName(java.lang.String name)
method for a more detailed description of thename
parameter.- Parameters:
name
- the name of the task to be found.- Returns:
- An iterator that can be used to retrieve the TaskStatus for the found tasks. These TaskStatus records are the same as
those returned by the
Scheduler.getStatus
method. - Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.- Since:
- 5.0
-
findTasksByName
TaskInfo[] findTasksByName(java.lang.String name, int beginIndex, int endIndex) throws SchedulerNotAvailableException
Returns the subset of TaskInfo records between beginIndex and endIndex (0-based) that match the specified name and were created by the caller's application.
The name can include SQL wildcards (depending on the database platform). Common wildcards include:- '%' - Match all characters
- '?' - Match one character.
"AR_01_Sales" and "AR_ZZ_Sales", but not "AR_AAA_Sales"A name such as "AR_%" would return all names that begin with "AR_".
- Parameters:
name
- the name of the task to be found.beginIndex
- the beginning index of the tasks to retrieve (0 is the first element)endIndex
- the end index of the tasks to retrieve. If endIndex is greater than the total number of tasks, then the endIndex is ignored.- Returns:
- An array of TaskInfo records
- Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.java.lang.IndexOutOfBoundsException
- Thrown when the beginIndex or endIndex is negative or when the beginIndex is larger than the endIndex.- Since:
- 6.0
-
findTaskStatusByName
TaskStatus[] findTaskStatusByName(java.lang.String name, int beginIndex, int endIndex) throws SchedulerNotAvailableException
Returns the subset of TaskStatus records between beginIndex and endIndex that match the specified name and were created by the caller's application.
See thefindTasksByName(java.lang.String name)
method for a more detailed description of thename
parameter.- Parameters:
name
- the name of the task to be found.beginIndex
- the beginning index of the tasks to retrieve (0 is the first element)endIndex
- the end index of the tasks to retrieve. If endIndex is greater than the total number of tasks, then the endIndex is ignored.- Returns:
- An array of TaskStatus records.
These TaskStatus records are the same as
those returned by the
Scheduler.getStatus
method. - Throws:
SchedulerNotAvailableException
- No transaction rollback occurs. Thrown when there was a problem accessing the persistent store.- Since:
- 6.0
-
-