com.ibm.websphere.scheduler
Interface Scheduler


public interface Scheduler

The central object for managing and creating tasks.

Instances of a Scheduler are defined using the admin 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 resulting TaskStatus object) 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
 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 object.
 BeanTaskInfo createBeanTaskInfo()
          Deprecated. Use the createTaskInfo method.
 MessageTaskInfo createMessageTaskInfo()
          Deprecated. Use the createTaskInfo 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 objects with a specified name that were created by the caller's application.
 TaskInfo[] findTasksByName(java.lang.String name, int beginIndex, int endIndex)
          Finds all TaskInfo objects with a specified name that were created by the caller's application.
 java.util.Iterator findTaskStatusByName(java.lang.String name)
          Finds all TaskStatus objects with a specified name that were created by the caller's application.
 TaskStatus[] findTaskStatusByName(java.lang.String name, int beginIndex, int endIndex)
          Finds all TaskStatus objects with a specified name that 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

public 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 object. When the task is created, use the TaskStatus.getTaskId method to retrieve the task id for using with the other methods on the Scheduler.

Parameters:
taskInfo - any object that implements the TaskInfo interface.
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

public BeanTaskInfo createBeanTaskInfo()
Deprecated. Use the createTaskInfo method.

Creates a BeanTaskInfo instance object. 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

public MessageTaskInfo createMessageTaskInfo()
Deprecated. Use the createTaskInfo method.

Creates a MessageTaskInfo instance object. 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

public 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 object 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:
Object the object instance of the specified interface.
Throws:
TaskInfoInvalid - the specified TaskInfo interface class is not available or registered.

cancel

public 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. If any exception is thrown besides the ones below then the transaction is rolledbacked. Such an exception is wrapped in a SchedulerRuntimeException and then thrown.

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

public 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

public 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

public 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

public 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

public 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

public java.util.Iterator findTasksByName(java.lang.String name)
                                   throws SchedulerNotAvailableException
Finds all TaskInfo objects 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:

For example: a name such as "AR_??_Sales" would return names like:
"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

public java.util.Iterator findTaskStatusByName(java.lang.String name)
                                        throws SchedulerNotAvailableException
Finds all TaskStatus objects with a specified name that were created by the caller's application.

See the findTasksByName(java.lang.String name) method for details for valid the name parameter values.

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 objects 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

public TaskInfo[] findTasksByName(java.lang.String name,
                                  int beginIndex,
                                  int endIndex)
                           throws SchedulerNotAvailableException
Finds all TaskInfo objects with a specified name that were created by the caller's application. Returns only a subset of the TaskInfo objects between beginIndex and endIndex (0-based).

The name can include SQL wildcards (depending on the database platform). Common wildcards include:

For example: a name such as "AR_??_Sales" would return names like:
"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 objects
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 larget than the endIndex.
Since:
6.0

findTaskStatusByName

public TaskStatus[] findTaskStatusByName(java.lang.String name,
                                         int beginIndex,
                                         int endIndex)
                                  throws SchedulerNotAvailableException
Finds all TaskStatus objects with a specified name that were created by the caller's application.

See the findTasksByName(java.lang.String name) method for details for valid the name parameter values.

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 objects. These TaskStatus objects 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