com.sap.scheduler.runtime

Interface JobContext

public interface JobContext

The job context of a running job which allows the job to access the scheduler runtime environment. Every job has a job context. The JobContext is passed as an argument to the onJob method and is specific to the job that is passed to. You are always authorized to call methods of this interface.

Note: Most of the methods of the interface throw a SchedulerRuntimeException which indicates a problem with the application server infrastructure. This exception should not be caught by the implementation of a job since it is caught by the scheduler runtime environment.

Method Summary

JobID	executeJob(JobDefinitionID jobDefId) Submit a job for immediate execution.
JobID	executeJob(JobDefinitionID jobDefId, JobParameter[] parameters) Submit a job for immediate execution.
JobID	executeJob(String jobDefinitionName) Submit a job for immediate execution.
JobID	executeJob(String jobDefinitionName, JobParameter[] parameters) Submit a job for immediate execution.
com.sap.tc.logging.Category	getCategory() Get the category for this job which can be used to log messages in the context of the job.
Job	getChildJobById(JobID jobId) Get an existing job instance by its job id.
Job	getJob() Get the Job object associated with this job.
JobDefinition	getJobDefinition(String jobDefinitionName) Get the JobDefinition object which represents the job metadata for the given name
JobParameter	getJobParameter(String name) Get a job parameter.
JobParameterDefinition	getJobParameterDefinition(String jobDefinitionName, String parameterName) Returns the named job definition parameter for the given job defintion which was provided when the job was deployed.
JobParameterDefinition[]	getJobParameterDefinitions(String jobDefinitionName) Returns the job definitions parameters for the given job defintion which were provided when the job was deployed.
Object	getJobParameterGeneric(String name) Get a job parameter.
com.sap.tc.logging.Location	getLocation() Get the location that is required in order to be able to log to the Job's category.
Logger	getLogger() Get a JDK-compliant Logger object.
boolean	isCancelled() Returns true if the job has received a request for cancellation.
void	jobFailed() This method should be called in order to indicate that this job should be set to the status ERROR after it has been completed.
void	setJobParameter(JobParameter param) Update the runtime with the given JobParameter.
void	setJobParameterGeneric(String name, Object value) Set a job parameter.
void	setReturnCode(short returnCode) Set the job return code.
void	waitForChildJobs() Wait for all child jobs to finish.
void	waitForChildJobs(JobID[] jobs) Wait for the specified child jobs to wait for.
boolean	waitForChildJobs(JobID[] jobs, long timeout) Wait for the specified child jobs to complete.
boolean	waitForChildJobs(long timeout) Wait for all child jobs to finish.

Method Detail

getJob

Job getJob()
           throws SchedulerRuntimeException

Get the Job object associated with this job.

Returns:

the job object

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the value

getChildJobById

Job getChildJobById(JobID jobId)
                    throws SchedulerRuntimeException

Get an existing job instance by its job id. It is only possible to retrieve child jobs.

Parameters:

jobId - the id of the job to get.

Returns:

the job, or null if the job cannot be found or is not a child job

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the values

getJobDefinition

JobDefinition getJobDefinition(String jobDefinitionName)
                               throws SchedulerRuntimeException

Get the JobDefinition object which represents the job metadata for the given name

Parameters:

jobDefinitionName - name of the job definition

Returns:

a JobDefinition object or null in case there is no such job definition.

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the values

getJobParameterDefinitions

JobParameterDefinition[] getJobParameterDefinitions(String jobDefinitionName)
                                                    throws SchedulerRuntimeException

Returns the job definitions parameters for the given job defintion which were provided when the job was deployed.

Parameters:

jobDefinitionName - job definition name for which to retrieve the parameter definitions

Returns:

array of job definition parameters (may be empty). If there is no such job definition a null pointer will be returned.

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the values

getJobParameterDefinition

JobParameterDefinition getJobParameterDefinition(String jobDefinitionName,
                                                 String parameterName)
                                                 throws SchedulerRuntimeException

Returns the named job definition parameter for the given job defintion which was provided when the job was deployed.

Parameters:

jobDefinitionName - the name of the job definition

Returns:

JobDefinitionParameter or null if there is no such parameter for the specified job or if there is no such job

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the value

getLogger

Logger getLogger()

Get a JDK-compliant Logger object. Log records written to this logger are persisted in the context of this particular job.

Returns:

a logger to write log messages to.

getCategory

com.sap.tc.logging.Category getCategory()

Get the category for this job which can be used to log messages in the context of the job. The log messages written to this category will be persisted in the database and are available with the job information.

Returns:

the Category object

getLocation

com.sap.tc.logging.Location getLocation()

Get the location that is required in order to be able to log to the Job's category. Records written to this category are discarded. Use only in conjunction with the category object.

Returns:

the Location object

getJobParameter

JobParameter getJobParameter(String name)
                             throws IllegalArgumentException

Get a job parameter. If the job parameter has not been set and there is a default value it will contain the default value, otherwise null will be returned.

Parameters:

name - the name of the parameter

Returns:

JobParameter object or null if there is no such parameter

Throws:

IllegalArgumentException - if the parameter is not an IN or INOUT parameter or if there is no such parameter

setJobParameter

void setJobParameter(JobParameter param)
                     throws IllegalArgumentException,
                            SchedulerRuntimeException

Update the runtime with the given JobParameter. The parameter is immediately updated in the database.

Parameters:

param - JobParameter to update

Throws:

IllegalArgumentException - if this is an IN parameter or it does not match the job parameter definition of the job definition.

SchedulerRuntimeException - if there was a technical problem setting the value

setJobParameterGeneric

void setJobParameterGeneric(String name,
                            Object value)
                            throws IllegalArgumentException,
                                   ClassCastException,
                                   SchedulerRuntimeException

Set a job parameter. Only for out and inout parameters

Parameters:

name - of the parameter

Throws:

ClassCastException - if the value is of an incorrect type

IllegalArgumentException - if this is an IN parameter or it does not match the job parameter definition of the job definition.

SchedulerRuntimeException - if there was a technical problem setting the value

getJobParameterGeneric

Object getJobParameterGeneric(String name)
                              throws IllegalArgumentException

Get a job parameter.

Parameters:

name - the name of the parameter

Returns:

the parameter object or null if there is no such parameter. The return value must be casted to the specified type.

Throws:

IllegalArgumentException - if the parameter is not an IN or INOUT parameter

setReturnCode

void setReturnCode(short returnCode)
                   throws SchedulerRuntimeException

Set the job return code.

Parameters:

returnCode - the value for the return code.

Throws:

SchedulerRuntimeException - if there was a technical problem setting the return value

isCancelled

boolean isCancelled()
                    throws SchedulerRuntimeException

Returns true if the job has received a request for cancellation.

Returns:

true if a requet for cancellation has been received, false otherwise.

Throws:

SchedulerRuntimeException - if there was a technical problem retrieving the value

jobFailed

void jobFailed()

This method should be called in order to indicate that this job should be set to the status ERROR after it has been completed.

executeJob

JobID executeJob(JobDefinitionID jobDefId)
                 throws ParameterValidationException,
                        NoSuchJobDefinitionException,
                        SchedulerRuntimeException

Submit a job for immediate execution. The new job is considered a child job of this job.

Parameters:

jobDefId - the job definition for the job to submit

Returns:

the JobID object representing id of the submitted job.

Throws:

ParameterValidationException - if the provided parameters do not match the required parameters for the job

NoSuchJobDefinitionException - if there is no such job definition or the job definition is not deployed anymore

SchedulerRuntimeException - if there was a technical problem submitting the job.

executeJob

JobID executeJob(String jobDefinitionName)
                 throws ParameterValidationException,
                        NoSuchJobDefinitionException,
                        SchedulerRuntimeException

Submit a job for immediate execution. The new job is considered a child job of this job.

Parameters:

jobDefinitionName - the job definition name for the job to submit

Returns:

the JobID object representing the if of the submitted job.

Throws:

ParameterValidationException - if the provided parameters do not match the required parameters for the job

NoSuchJobDefinitionException - if there is no such job definition or the job definition is not deployed anymore

SchedulerRuntimeException - if there was a technical problem submitting the job.

executeJob

JobID executeJob(JobDefinitionID jobDefId,
                 JobParameter[] parameters)
                 throws ParameterValidationException,
                        NoSuchJobDefinitionException,
                        SchedulerRuntimeException

Submit a job for immediate execution. A parameter set may optionally be specified. Schedule parameters may be specified by appropriate names in the parameter map.

Parameters:

jobDefId - the job definition for the job to submit

parameters - an optional list of parameter/value pairs.

Returns:

the JobID object representing the id of the submitted job.

Throws:

ParameterValidationException - if the provided parameters do not match the required parameters for the job

NoSuchJobDefinitionException - if there is no such job definition or the job definition is not deployed anymore

SchedulerRuntimeException - if there was a technical problem submitting the job.

executeJob

JobID executeJob(String jobDefinitionName,
                 JobParameter[] parameters)
                 throws ParameterValidationException,
                        NoSuchJobDefinitionException,
                        SchedulerRuntimeException

Submit a job for immediate execution. A parameter set may optionally be specified. Schedule parameters may be specified by appropriate names in the parameter map.

Parameters:

jobDefinitionName - the job definition name for the job to submit

parameters - an optional list of parameter/value pairs.

Returns:

the JobID object representing the id of the submitted job.

Throws:

ParameterValidationException - if the provided parameters do not match the required parameters for the job

NoSuchJobDefinitionException - if there is no such job definition or the job definition is not deployed anymore

SchedulerRuntimeException - if there was a technical problem submitting the job.

waitForChildJobs

void waitForChildJobs()

Wait for all child jobs to finish.

waitForChildJobs

boolean waitForChildJobs(long timeout)

Wait for all child jobs to finish.

Parameters:

timeout - timeout for waiting, zero means no timeout

Returns:

true if all child jobs have been completed in the given timeout period, false otherwise

waitForChildJobs

void waitForChildJobs(JobID[] jobs)

Wait for the specified child jobs to wait for.

Parameters:

jobs - an array of child job ids

waitForChildJobs

boolean waitForChildJobs(JobID[] jobs,
                         long timeout)

Wait for the specified child jobs to complete.

Parameters:

jobs - an array of child jobs to wait for

timeout - timeout for waiting, zero means no timeout

Returns:

true if all child jobs have been completed in the given timeout period, false otherwise

Access Rights

This class can be accessed from:

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