com.sap.scheduler.api

Interface Scheduler

public interface Scheduler

This is the main interface to the NetWeaver Scheduler for Java. Applications can use this interface for all scheduler related tasks which includes scheduling jobs, viewing jobs, and browsing logfiles.

The methods of this class always return information which are related to the calling user. Administrative users will be able to access all information.

Nested Class Summary

static class

Scheduler.FireTimeEvent Instances of this class specify a particular expiration of a given scheduler task.

Method Summary

void	addEventListener(String[] eventsRegisteredFor, EventConsumer consumer) This method registers a EventConsumer for Jobs and /or tasks.
void	addFilters(SchedulerTaskID id, Filter[] f) Adds a filter to the list of filters currently associated to the given task.
void	cancelJob(JobID jobid) This method cancels a job.
void	cancelTask(SchedulerTaskID taskId) Cancels a scheduled task with id specified by the taskId parameter.
SchedulerTaskID[]	getAllSchedulerTaskIDs() Obtains all currently scheduled scheduler tasks which are in state active or hold.
Job[]	getChildJobs(JobID jobid) Get all child jobs for a given job id.
Scheduler.FireTimeEvent[]	getFireTimes(SchedulerTaskID id, SchedulerTime startTime, SchedulerTime endTime) This method returns the fire times of a SchedulerTask for a given time interval specified by the startTime, endTime and the id parameters.
Job	getJob(JobID jobid) This method returns a job for a given job id jobid.
JobDefinition	getJobDefinitionById(JobDefinitionID id) Get job definition by its job definition id.
JobDefinition	getJobDefinitionByName(String jobDefinitionName) Returns the job defintion for a given name.
JobDefinition[]	getJobDefinitions() Returns all job definitions known to the NetWeaver Scheduler.
LogIterator	getJobLog(JobID jobId, LogIterator it, int fetchSize) This method will return the log for the given job in chunks.
JobParameter[]	getJobParameters(JobID jobid) This method returns all parameters for a given job id jobid.
JobIterator	getJobs(JobFilter filter, JobIterator iter, int fetchSize) This method will return all jobs which match the provided filter criteria.
Job[]	getJobs(JobID[] jobid) This method returns the jobs for given job ids.
JobStatus	getJobStatus(JobID jobid) Returns the status of a job.
SchedulerTask	getTask(SchedulerTaskID id) Obtains the task with id specified by the id parameter.
boolean	hasChildJobs(JobID jobid) Returns true if this job has child jobs.
void	holdTask(SchedulerTaskID taskId) Holds a scheduled task with id specified by the taskId parameter.
void	releaseTask(SchedulerTaskID taskId) Releases a held task with id specified by the taskId parameter and set it back to state active.
void	removeEventListener(EventConsumer consumer) This methods removes a previous registered EventConsumer.
void	removeFilters(SchedulerTaskID id, Filter[] f) Removes the given filters from the list of filters associated with the given task.
void	removeJob(JobID jobid) This method removes all information about this job instance from the NetWeaver Scheduler (including logs).
void	removeJobs(JobID[] jobids) This method removes all information for the given job instances from the NetWeaver Scheduler (including logs).
void	schedule(SchedulerTask task) This method schedules the supplied task what means that the task will be persisted and performed.
void	setFilters(SchedulerTaskID id, Filter[] f) Sets filters for the specified task.

Method Detail

schedule

void schedule(SchedulerTask task)
              throws TaskValidationException,
                     SchedulerRuntimeException

This method schedules the supplied task what means that the task will be persisted and performed.

Parameters:

task - the task to be scheduled

Throws:

TaskValidationException - thrown if a task with this id is already scheduled or some of the fields are invalid

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getTask

SchedulerTask getTask(SchedulerTaskID id)
                      throws TaskDoesNotExistException,
                             SchedulerRuntimeException

Obtains the task with id specified by the id parameter. Only one task with this id can exist.

Parameters:

id - the id of the task

Returns:

the task with id that equals id parameter

Throws:

TaskDoesNotExistException - thrown if task with this id does not exist.

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

cancelTask

void cancelTask(SchedulerTaskID taskId)
                throws TaskDoesNotExistException,
                       SchedulerRuntimeException

Cancels a scheduled task with id specified by the taskId parameter.

Parameters:

taskId - the id of the task to be cancelled

Throws:

TaskDoesNotExistException - if a task with such id does not exist or the task can not be cancelled

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

holdTask

void holdTask(SchedulerTaskID taskId)
              throws TaskDoesNotExistException,
                     SchedulerRuntimeException

Holds a scheduled task with id specified by the taskId parameter. Holding a task means that it will be suspended from further execution until realeaseTask(taskId) will be called which sets the task back to active.

Parameters:

taskId - id of the task to be hold

Throws:

TaskDoesNotExistException - if a task with such id does not exist.

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

See Also:

releaseTask(SchedulerTaskID taskId)

releaseTask

void releaseTask(SchedulerTaskID taskId)
                 throws TaskDoesNotExistException,
                        SchedulerRuntimeException

Releases a held task with id specified by the taskId parameter and set it back to state active. This method takes only effect if the task was set to hold before.

Parameters:

taskId - id of the task to be released

Throws:

TaskDoesNotExistException - if a task with taskId and set to HOLD does not exist.

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

See Also:

holdTask(SchedulerTaskID taskId)

setFilters

void setFilters(SchedulerTaskID id,
                Filter[] f)
                throws TaskDoesNotExistException,
                       SchedulerRuntimeException

Sets filters for the specified task. This method replaces all filters currently associated to this task with the filters supplied by f parameter. This method could also be useful to remove all filters associated with the given task by calling setFilters(id, new Filter[0]).

Parameters:

id - id of the task

f - array of filters

Throws:

TaskDoesNotExistException - - if task with id specified by id parameter does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

addFilters

void addFilters(SchedulerTaskID id,
                Filter[] f)
                throws TaskDoesNotExistException,
                       SchedulerRuntimeException

Adds a filter to the list of filters currently associated to the given task.

Parameters:

id - id of the task

f - array of filters to be associated with the given task

Throws:

TaskDoesNotExistException - thrown if the given task does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

removeFilters

void removeFilters(SchedulerTaskID id,
                   Filter[] f)
                   throws TaskDoesNotExistException,
                          SchedulerRuntimeException

Removes the given filters from the list of filters associated with the given task. This method does not throw an exception if any of the filters supplied by the array f are not found among the list of filters associated with the given task. It simply removes all the filters that are found both in f and the list of currently associated filters.

Parameters:

id - task whose filters will be removed

f - filters which will be removed from the list of filters associated to task id

Throws:

TaskDoesNotExistException - thrown if the task specified by id does not exist.

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getAllSchedulerTaskIDs

SchedulerTaskID[] getAllSchedulerTaskIDs()
                                         throws SchedulerRuntimeException

Obtains all currently scheduled scheduler tasks which are in state active or hold.

Returns:

an array of all currently scheduled tasks. This method never returns null. If there are no currently scheduled tasks it returns an empty array.

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getFireTimes

Scheduler.FireTimeEvent[] getFireTimes(SchedulerTaskID id,
                                       SchedulerTime startTime,
                                       SchedulerTime endTime)
                                       throws TaskDoesNotExistException,
                                              TooManyFireEventsException,
                                              SchedulerRuntimeException

This method returns the fire times of a SchedulerTask for a given time interval specified by the startTime, endTime and the id parameters.

Parameters:

id - the task id

startTime - the start time of the interval

endTime - the end time of the interval

Returns:

a possible empty array of FireTimeEvents

Throws:

TooManyFireEventsException - if there are too many executions of this task in the given interval

TaskDoesNotExistException - thrown if the task specified by id does not exist.

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobDefinitions

JobDefinition[] getJobDefinitions()
                                  throws SchedulerRuntimeException

Returns all job definitions known to the NetWeaver Scheduler.

Note: Also undeployed job definitions are also returned

Returns:

an array of JobDefinitions known to the scheduler (may by empty)

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobDefinitionByName

JobDefinition getJobDefinitionByName(String jobDefinitionName)
                                     throws SchedulerRuntimeException

Returns the job defintion for a given name. The format for a job definitions name is <providerName>/<applicationName>:<jobName>

Note: This method will only return current job definitions. It will not return job definitions from undepoyed applications.

Parameters:

jobDefinitionName - the name of job definition

Returns:

the job definition or null if there is no such job definition

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobDefinitionById

JobDefinition getJobDefinitionById(JobDefinitionID id)
                                   throws SchedulerRuntimeException

Get job definition by its job definition id.

Note: This method will return also job definitions from undeployed applications.

Parameters:

id - the job definition id

Returns:

job definition or null if there is no such job definition

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

cancelJob

void cancelJob(JobID jobid)
               throws JobIllegalStateException,
                      SchedulerRuntimeException

This method cancels a job. If it has not been started it will immediately go into the CANCELLED state. If it has been started, it will cooperatively try to abort the job. This method will just return with no indication whether the job was successfully cancelled or not.

This method will only allow jobs to be cancelled which run under the same user id as the caller.

Parameters:

jobid - job id for the running job

Throws:

JobIllegalStateException - thrown if the job is not status RUNNING

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

See Also:

JobContext.isCancelled()

getChildJobs

Job[] getChildJobs(JobID jobid)
                   throws NoSuchJobException,
                          SchedulerRuntimeException

Get all child jobs for a given job id.

Parameters:

jobid - the id for the job

Returns:

possible empty array of child jobs

Throws:

NoSuchJobException - thrown if a job with the given job id does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

hasChildJobs

boolean hasChildJobs(JobID jobid)
                     throws NoSuchJobException,
                            SchedulerRuntimeException

Returns true if this job has child jobs. the caller

Parameters:

jobid - job id to use

Returns:

true if the job has child jobs, false otherwise

Throws:

NoSuchJobException - thrown if a job with the given job id does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

removeJob

void removeJob(JobID jobid)
               throws JobIllegalStateException,
                      NoSuchJobException,
                      SchedulerRuntimeException

This method removes all information about this job instance from the NetWeaver Scheduler (including logs). This method only works on jobs which are in state COMPLETED, ERROR or UNKNOWN, CANCELLED.

Parameters:

jobid - the job id to use

Throws:

JobIllegalStateException - thrown if the to be removed is not in one state mentioned above.

NoSuchJobException - thrown if a job with the given job id does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

removeJobs

void removeJobs(JobID[] jobids)
                throws SchedulerRuntimeException

This method removes all information for the given job instances from the NetWeaver Scheduler (including logs). This is a convenience method. Logical errors (e.g. one or more jobs in an illegal state) will be ignored.

Parameters:

jobids - the job ids to use

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJob

Job getJob(JobID jobid)
           throws SchedulerRuntimeException

This method returns a job for a given job id jobid.

Parameters:

jobid - the job id of the job

Returns:

the job or null if there is no such job

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobParameters

JobParameter[] getJobParameters(JobID jobid)
                                throws NoSuchJobException,
                                       SchedulerRuntimeException

This method returns all parameters for a given job id jobid.

Parameters:

jobid - the given job is

Returns:

job parameters for specified job

Throws:

NoSuchJobException - if there is no job with the given id

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobs

Job[] getJobs(JobID[] jobid)
              throws SchedulerRuntimeException

This method returns the jobs for given job ids.

Parameters:

jobid - the job ids of the jobs

Returns:

an array of jobs. The size of the returned array is the same as the size of the passed one. If a job does not exist the field in the array will be null.

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobLog

LogIterator getJobLog(JobID jobId,
                      LogIterator it,
                      int fetchSize)
                      throws NoSuchJobException,
                             SchedulerRuntimeException

This method will return the log for the given job in chunks. If the result set is bigger than the provided fetchSize parameter the remaining entries can be retrieved using the returned iterator. The following code snipped shows how to retrieve the result from the call.

 LogIterator iter = scheduler.getJobLog(jobId, null, 1000);
 String log = iter.nextChunk();
 // do something with the returned log String
 while(iter.hasMoreChunks()) {
     iter = scheduler.getJobLog(jobId, iter, 1000);
     log = iter.nextChunk();
     // do something with the returned log
 }
 

Returns:

the whole log file as string

Throws:

NoSuchJobException - if the job with the id jobId does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobStatus

JobStatus getJobStatus(JobID jobid)
                       throws NoSuchJobException,
                              SchedulerRuntimeException

Returns the status of a job.

Parameters:

jobid - the given job id

Returns:

status for job with the provided job id

Throws:

NoSuchJobException - if the job with the id jobId does not exist

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

getJobs

JobIterator getJobs(JobFilter filter,
                    JobIterator iter,
                    int fetchSize)
                    throws SchedulerRuntimeException

This method will return all jobs which match the provided filter criteria. If the result set is bigger than the provided fetchSize parameter the remaining entries can be retrieved using the returned iterator. The following code snipped shows how to retrieve the result from the call.

 JobIterator iter = scheduler.getJobs(myFilter, null, 1000);
 Job[] jobs = iter.nextChunk();
 // do something with the returned job ojbects
 while(iter.hasMoreChunks()) {
     iter = scheduler.getJobs(myFilter, iter, 1000);
     Job[] jobs = iter.nextChunk();
     // do something with the returned job objects
     //
 }
 

Parameters:

filter - the pre-initialized filter object

iter - an iterator which has been returned by a previous invocation or null if this is the first call

fetchSize - the number of records to fetch

Returns:

the JobIterator object which contains the next chunk of data

Throws:

SchedulerRuntimeException - RuntimeException thrown if there is a problem with the underlying infrastructure.

addEventListener

void addEventListener(String[] eventsRegisteredFor,
                      EventConsumer consumer)

This method registers a EventConsumer for Jobs and /or tasks. Users of this method need to implement the methods of the EventConsumer interface and register for the events to listen for. The available events are listed in class Event. Examples afor events are EVENT_JOB_STARTING, EVENT_JOB_FINISHED, EVENT_TASK_CREATED, EVENT_TASK_FINISHED, and so on.

If you want to register for all available events you might use the String[] from RUNTIME_EVENT_TYPES.

If one and the same EventConsumer is registered a second time an IllegalArgumentException will be thrown.

Note: All events for which the user registers here for are delivered to every server node within the cluster. The user has to take care if events should be processed only at one server node.

Parameters:

eventsRegisteredFor - the String[] with the events to register for

consumer - the implementation of an EventConsumer

See Also:

Event, EventConsumer, removeEventListener(EventConsumer)

removeEventListener

void removeEventListener(EventConsumer consumer)

This methods removes a previous registered EventConsumer. If this method is called several times or the EventConsumer has not been registered before the call would be ignored.

Parameters:

consumer - the EventConsumer to remove

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGFACADE	[sap.com] tc/je/scheduler/api