IBM WebSphere Application ServerTM
Release 7

com.ibm.websphere.scheduler
Interface TaskInfo

All Superinterfaces:
java.io.Serializable, TaskStatus
All Known Subinterfaces:
BeanTaskInfo, MessageTaskInfo

public interface TaskInfo
extends TaskStatus

Interface for all scheduled tasks.

Contains the data to be used when scheduling a task using the Scheduler.create(TaskInfo) method.

Since:
5.0
Version:
6.0.2

Field Summary
static int EXECUTION_DELAYEDUPDATE
          Delayed-update execution option.
static int QOS_ATLEASTONCE
          At-least-once quality of service.
static int QOS_ONLYONCE
          Only-once quality of service.
 
Fields inherited from interface com.ibm.websphere.scheduler.TaskStatus
CANCELLED, COMPLETE, INVALID, RUNNING, SCHEDULED, serialVersionUID, SUSPENDED
 
Method Summary
 java.lang.String getAuthenticationAlias()
          Retrieves the Authentication Alias set for this task.
 boolean getAutoPurge()
          Get the AutoPurge value for this task.
 int getExpectedDuration()
          Retrieves the expected duration of this task.
 java.lang.String getName()
          Get the name of the task.
 NotificationSinkHome getNotificationSink()
          Gets the NotificationSinkHome associated with this TaskInfo.
 java.lang.String getNotificationSinkJNDIName()
          Gets the JNDI name of the NotificationSink associated with this TaskInfo.
 int getNumberOfRepeats()
          Get the number of repeats that were set with setNumberOfRepeats.
 int getQOS()
          Retreives the quality of service for this task set with the setQOS method.
 java.lang.String getRepeatInterval()
          Get the UserCalendar repeat interval.
 java.lang.String getStartByInterval()
          Get the start-by interval that was set with setStartByInterval
 java.util.Date getStartTime()
          Get the start date and time for this task that was set with setStartTime.
 java.lang.String getStartTimeInterval()
          Get the UserCalendar start time interval that was set with setStartTime
 int getTaskExecutionOptions()
          Get the task's execution options.
 java.lang.String getUserCalendarJNDIName()
          Get the UserCalendar JNDI name
 java.lang.String getUserCalendarSpecifier()
          Get the UserCalendar specifier.
 void setAuthenticationAlias(java.lang.String alias)
          Set the Authentication Alias used for this task.
 void setAutoPurge(boolean purge)
          Specifies that upon completion, the task will be deleted from the persistent store.
 void setExpectedDuration(int seconds)
          Sets the expected duration of the task.
 void setInitialState(int initialState)
          Set the state that this task should default to when initially created.
 void setName(java.lang.String name)
          Set the name of the task.
 void setNotificationSink(NotificationSinkHome home)
          Specifies a callback which will be invoked for all events.
 void setNotificationSink(NotificationSinkHome home, int eventMask)
          Specifies a callback which will be invoked based upon the requested filter.
 void setNotificationSink(java.lang.String jndiName)
          Specifies a callback which will be invoked for all events.
 void setNotificationSink(java.lang.String jndiName, int eventMask)
          Specifies a callback which will be invoked based upon the requested filter.
 void setNumberOfRepeats(int repeatCount)
          Sets the number of times this task will be repeated.
 void setQOS(int QOS)
          Sets the quality of service for this task.
 void setRepeatInterval(java.lang.String userCalendarDelta)
          Specifies a UserCalendar interval which represents the time between firings.
 void setStartByInterval(java.lang.String userCalendarDelta)
          Specifies that if the task has not executed within the specified UserCalendar interval, the associated work should not be fired.
 void setStartTime(java.util.Date start)
          Sets the start date and time for this task.
 void setStartTimeInterval(java.lang.String userCalendarDelta)
          Sets the start time for the task given a UserCalendar interval.
 void setTaskExecutionOptions(int executionOptions)
          Set the task's execution options.
 void setUserCalendar(java.lang.String homeJNDIName, java.lang.String specifier)
          Set the UserCalendar for this task.
 void validate()
          Validates various attributes of a TaskInfo.
 
Methods inherited from interface com.ibm.websphere.scheduler.TaskStatus
getNextFireTime, getRepeatsLeft, getStatus, getTaskId, getTimeCreated
 

Field Detail

QOS_ONLYONCE

static final int QOS_ONLYONCE
Only-once quality of service. If set using the setQOS(int) method, the task is guaranteed to only execute one time in a single transactional context.

Since:
6.0.2
See Also:
Constant Field Values

QOS_ATLEASTONCE

static final int QOS_ATLEASTONCE
At-least-once quality of service. If set using the setQOS(int) method, the task may run more than one time if a failure occurs after the task has executed and prior to the persistent store update.

Since:
6.0.2
See Also:
Constant Field Values

EXECUTION_DELAYEDUPDATE

static final int EXECUTION_DELAYEDUPDATE
Delayed-update execution option. Used to reflect the TaskStatus.RUNNING state when the task is running.

If this option is set using the setTaskExecutionOptions(int) method, the persistent store is updated twice when the task fires. The first update occurs immediately when the task fires and sets the status of the task to TaskStatus.RUNNING. The second update stores the result of the task.

This execution option is always used when the quality of service is set to QOS_ATLEASTONCE.

If this option is not set and the quality of service is QOS_ONLYONCE, the persistent store will be updated one time when the task runs. This means that when a task is running, the Scheduler.getTask(String), Scheduler.getStatus(String) and find methods will show the next effective state of the task and will not show a state of TaskStatus.RUNNING.

Since:
6.0.2
See Also:
Constant Field Values
Method Detail

setStartByInterval

void setStartByInterval(java.lang.String userCalendarDelta)
Specifies that if the task has not executed within the specified UserCalendar interval, the associated work should not be fired. The next fire time will still be calculated and if applicable, the repeat count decremented.

Parameters:
userCalendarDelta - the UserCalendar interval used to apply to each calculated fire time.
Since:
5.0
See Also:
UserCalendar

getStartByInterval

java.lang.String getStartByInterval()
Get the start-by interval that was set with setStartByInterval

Returns:
String
Since:
5.0

setStartTime

void setStartTime(java.util.Date start)
Sets the start date and time for this task. The task will not run until this time elapses.

Parameters:
start - the Date to use for the start date and time.
Since:
5.0

getStartTime

java.util.Date getStartTime()
Get the start date and time for this task that was set with setStartTime.

Returns:
the start date and time.
Since:
5.0

setStartTimeInterval

void setStartTimeInterval(java.lang.String userCalendarDelta)
Sets the start time for the task given a UserCalendar interval. The actual time will be calculated during task creation using the UserCalendar associated with this task info, or if unspecified, the default calendar.

Parameters:
userCalendarDelta - the UserCalendar interval used to apply to the current time.
Since:
5.0
See Also:
UserCalendar

getStartTimeInterval

java.lang.String getStartTimeInterval()
Get the UserCalendar start time interval that was set with setStartTime

Returns:
get the UserCalendar start time interval.
Since:
5.0

setNumberOfRepeats

void setNumberOfRepeats(int repeatCount)
Sets the number of times this task will be repeated.
The default number of repeats is 1.

Parameters:
repeatCount - the total number of times to execute the task.
Since:
5.0

getNumberOfRepeats

int getNumberOfRepeats()
Get the number of repeats that were set with setNumberOfRepeats.

Returns:
the number of repeats that was set with setNumberOfRepeats.
Since:
5.0

setRepeatInterval

void setRepeatInterval(java.lang.String userCalendarDelta)
Specifies a UserCalendar interval which represents the time between firings. The UserCalendar used for calculations can be specified with the setUserCalendar and setUserCalendarSpecifier methods. If no calendar is specified, the DefaultUserCalendar calendar will be used. If this repeat interval is less than the scheduler's poll interval, then the repeat interval will be ignored and the poll interval will be used.

Parameters:
userCalendarDelta - the UserCalendar interval used to apply to each calculated fire time.
Since:
5.0
See Also:
UserCalendar

getRepeatInterval

java.lang.String getRepeatInterval()
Get the UserCalendar repeat interval.

Returns:
the current UserCalendar repeat interval.
Since:
5.0

setUserCalendar

void setUserCalendar(java.lang.String homeJNDIName,
                     java.lang.String specifier)
                     throws UserCalendarInvalid
Set the UserCalendar for this task. If not set, then the default UserCalendar bean is used without a specifier.

Parameters:
homeJNDIName - the JNDI name used to retrieve the Home interface of a UserCalendar implementation object. If null or an empty string, the DefaultUserCalendar is used.
specifier - optional name of an individual calendar within the UserCalendar bean.
Throws:
UserCalendarInvalid - The specified JNDI name for the UserCalendarHome could not be looked-up or is of the wrong type.
Since:
5.0
See Also:
UserCalendar

getUserCalendarJNDIName

java.lang.String getUserCalendarJNDIName()
Get the UserCalendar JNDI name

Returns:
the current UserCalendar JNDI name.
Since:
5.0

getUserCalendarSpecifier

java.lang.String getUserCalendarSpecifier()
Get the UserCalendar specifier.

Returns:
the current UserCalendar specifier.
Since:
5.0

setNotificationSink

void setNotificationSink(NotificationSinkHome home)
                         throws NotificationSinkInvalid
Specifies a callback which will be invoked for all events.

Parameters:
home - A stateless session bean which uses NotificationSink remote interface.
Throws:
NotificationSinkInvalid - The HomeHandle for the session bean cannot be retrieved or the home is null;
Since:
5.0
See Also:
NotificationSink, TaskNotificationInfo

setNotificationSink

void setNotificationSink(NotificationSinkHome home,
                         int eventMask)
                         throws NotificationSinkInvalid
Specifies a callback which will be invoked based upon the requested filter. The filter is an ORred list of TaskNotificationInfo constants.

Parameters:
home - A stateless session bean which uses NotificationSink remote interface.
eventMask - the events to monitor for. To monitor multiple events, you can OR the event types together. The default is to be notified on all events.
Throws:
NotificationSinkInvalid - The HomeHandle for the session bean cannot be retrieved or the home is null;
Since:
5.0
See Also:
NotificationSink, TaskNotificationInfo

getNotificationSink

NotificationSinkHome getNotificationSink()
                                         throws NotificationSinkInvalid
Gets the NotificationSinkHome associated with this TaskInfo.

Returns:
the Home of the NotificationSink bean.
Throws:
NotificationSinkInvalid - The HomeHandle for the session bean cannot be retrieved or the home is null;
Since:
5.0
See Also:
NotificationSink

validate

void validate()
              throws UserCalendarSpecifierInvalid,
                     UserCalendarPeriodInvalid,
                     UserCalendarInvalid,
                     TaskInvalid,
                     NotificationSinkInvalid
Validates various attributes of a TaskInfo. If invalid, exceptions are thrown.

Throws:
UserCalendarSpecifierInvalid - The specified UserCalendar calendar name for the specified UserCalendar is not valid.
UserCalendarPeriodInvalid - The specified UserCalendar period for the specified UserCalendar is not valid.
UserCalendarInvalid - The specified JNDI name for the UserCalendarHome could not be looked-up or is of the wrong type.
TaskInvalid - The TaskInfo is missing or has incorrect data.
NotificationSinkInvalid - The HomeHandle for the session bean cannot be retrieved or the home is null;
Since:
5.0

setName

void setName(java.lang.String name)
Set the name of the task. Tasks can be labeled and later queried by this name.

Parameters:
name - the label of this task
Since:
5.0

getName

java.lang.String getName()
Get the name of the task.

Specified by:
getName in interface TaskStatus
Returns:
the name of the task which was set with setName.
Since:
5.0
See Also:
setName(java.lang.String)

setAutoPurge

void setAutoPurge(boolean purge)
Specifies that upon completion, the task will be deleted from the persistent store.

Default is true.

Parameters:
purge - if true, automatically remove completed tasks.
Since:
5.0

getAutoPurge

boolean getAutoPurge()
Get the AutoPurge value for this task.

Returns:
the AutoPurge value.
Since:
5.0

setInitialState

void setInitialState(int initialState)
Set the state that this task should default to when initially created.

By default each scheduled instance is immediately scheduled (TaskStatus.SCHEDULED). The only valid parameters for this method are TaskStatus.SUSPENDED and TaskStatus.SCHEDULED

This value does not persist with the task, therefore there is no "get" method for this setting.

Parameters:
initialState - the state to set the newly-created task to.
Since:
5.0

setNotificationSink

void setNotificationSink(java.lang.String jndiName)
Specifies a callback which will be invoked for all events.

Parameters:
jndiName - Fully qualified JNDI name of a stateless session bean which uses NotificationSink remote interface.
Since:
6.0
See Also:
NotificationSink, TaskNotificationInfo

setNotificationSink

void setNotificationSink(java.lang.String jndiName,
                         int eventMask)
Specifies a callback which will be invoked based upon the requested filter. The filter is an ORred list of TaskNotificationInfo constants.

Parameters:
jndiName - Fully qualified JNDI name of a stateless session bean which uses NotificationSink remote interface.
eventMask - the events to monitor for. To monitor multiple events, you can OR the event types together. The default is to be notified on all events.
Since:
6.0
See Also:
NotificationSink, TaskNotificationInfo

getNotificationSinkJNDIName

java.lang.String getNotificationSinkJNDIName()
Gets the JNDI name of the NotificationSink associated with this TaskInfo.

Returns:
the Home of the NotificationSink bean.
Throws:
NotificationSinkInvalid - The HomeHandle for the session bean cannot be retrieved or the home is null;
Since:
6.0
See Also:
NotificationSink

setAuthenticationAlias

void setAuthenticationAlias(java.lang.String alias)
Set the Authentication Alias used for this task. The Alias is defined using the WSDefaultPrincipalMapping module and is created using the administrative console or scripting client.

Parameters:
alias - name of the authentication alias.
Since:
6.0

getAuthenticationAlias

java.lang.String getAuthenticationAlias()
Retrieves the Authentication Alias set for this task. If no alias was set, then this will return null.

Returns:
the authentication alias.
Since:
6.0

setQOS

void setQOS(int QOS)
Sets the quality of service for this task. See the QOS constants defined in this interface: QOS_ATLEASTONCE and QOS_ONLYONCE.

Parameters:
QOS - a quality of service constant defined in this interface.
Since:
6.0.2

getQOS

int getQOS()
Retreives the quality of service for this task set with the setQOS method.

Returns:
the quality of service set with setQOS(int)
Since:
6.0.2

setTaskExecutionOptions

void setTaskExecutionOptions(int executionOptions)
Set the task's execution options. The execution options are operational flags that affect how the task will run. Each option is an independent bit and are declared using the EXECUTION constants in this interface.

Therefore, to set multiple options, they must be OR'd together:
setTaskExecutionOptions(OPTION1 | OPTION2)

Parameters:
executionOptions - one of the EXECUTION contants. These values can be added together to provide multiple options.
Since:
6.0.2

getTaskExecutionOptions

int getTaskExecutionOptions()
Get the task's execution options. To determine if a particular execution option is set, you must use the bitwise operators. For example, to see if the EXECUTION_DELAYEDUPDATE option is set:
boolean isDelayUpdateSet = getTaskExecutionOptions() & EXECUTION_DELAYEDUPDATE != 0;

Returns:
the execution options that were set with setTaskExecutionOptions(int)
Since:
6.0.2

setExpectedDuration

void setExpectedDuration(int seconds)
Sets the expected duration of the task.

If set to 0 (the default), the task is considered a short running task. Short-running tasks will be managed by the application server and will use appropriate transaction timeouts and thread management.

Larger values may override applicable system timeout values and may run the task on a non-pooled thread instead of a pooled thread.

If set to Integer.MAX_VALUE, the task is expected to run for an undetermined amount of time. The runtime will attempt to disable applicable system timeout values.

Note: Running tasks for a long period of time in a single transaction may cause time-out and locking issues. For long running tasks such as batch jobs, it is best to also use a lower quality of service QOS_ATLEASTONCE with checkpoints or compensating techniques.

Parameters:
seconds - the number of seconds that the task is expected to run. If 0, the task is a short running task. If Integer.MAX_VALUE, the task will run an undetermined amount of time.
Since:
6.0.2

getExpectedDuration

int getExpectedDuration()
Retrieves the expected duration of this task.

Returns:
the duration set with the setExpectedDuration(int) method.
Since:
6.0.2

IBM WebSphere Application ServerTM
Release 7