oracle.ias.scheduler
Interface Scheduler

All Known Subinterfaces:

SchedulerRemote

public interface Scheduler

Core interface of the OracleAS Job Scheduler. Provides methods for creating, managing, and querying jobs.

Field Summary

static long	DEFAULT_EXECUTION_THRESHOLD_MILLIS Internal use only.
static long	DEFAULT_INTERVAL_THRESHOLD_MINUTES The default interval threshold below which no timeout recovery is performed
static java.util.logging.Level	DEFAULT_JOB_EXECUTION_LOG_LEVEL The default log level for any job execution logger
static java.util.logging.Level	DEFAULT_JOB_LOG_LEVEL The default log level for any job logger
static long	DEFAULT_RETRY_PERIOD_MILLIS Internal use only.
static java.util.logging.Level	DEFAULT_ROOT_LOG_LEVEL The default log level for the scheduler root logger
static long	DEFAULT_ROUNDUP_THRESHOLD_MILLIS Internal use only.
static int	EXECUTION_ABORTED status value indicating job execution did not occur due to preemptory container crash or shutdown
static int	EXECUTION_BLACKOUT status value indicating job execution did not occur due to a blackout window that was in effect at the time of execution
static int	EXECUTION_CANCELLED status value indicating job execution has not completed as a result of the job being cancelled
static int	EXECUTION_FAILED status value indicating job execution has completed and was not successful
static int	EXECUTION_PAUSED status value indicating job execution did not occur as a result of the job being in the paused state
static int	EXECUTION_STARTED status value indicating job execution is incomplete
static int	EXECUTION_SUCCEEDED status value indicating job execution has completed and was successful
static int	EXECUTION_THRESHOLD_EXCEEDED status value indicating job execution did not occur due to execution time exceeding the configured threshold of the job
static int	REPLAY_TYPE job execution was delayed because the job was paused when the trigger initially expired
static int	RETRY_TYPE job execution is the result of retrying a previously failed execution
static int	STATE_ACTIVE Active job state.
static int	STATE_COMPLETED The job is no longer active.
static int	STATE_PAUSED Paused job state.
static int	STATE_UNDEF Internal use only.
static int	TRIGGER_TYPE job execution occurred as a result of the trigger firing

Method Summary

JobHandle	add(java.lang.String desc, java.lang.String className, Schedule schedule, java.util.Properties properties) Submits a job to the scheduler.
JobHandle	add(java.lang.String desc, java.lang.String className, Schedule schedule, Trigger trigger, java.util.Properties properties, java.util.logging.Level logLevel, long retryPeriod, long executionThreshold) Used to submit a job to the scheduler.
JobHandle	add(java.lang.String desc, java.lang.String className, Trigger trigger, java.util.Properties properties) Used to submit a job to the scheduler.
void	addBlackoutWindow(java.lang.String windowName, Schedule schedule, long duration) Add's a temporal window in which all job executions are supressed.
void	addListener(JobHandle job, java.lang.Class listener) Add event listener for job specified
void	cancel(JobHandle job) A submitted job may be optionally cancelled.
java.util.Collection	getBlackoutWindowNames() Retrieves a collection of blackout window names
Job	getJob(JobHandle job) Retrieve the metadata for the job specified.
java.util.Collection	getJobs() This methods return a collection view of all jobs submitted to the scheduler.
java.util.Collection	getJobs(int state) This methods return a collection view of the jobs submitted to the scheduler with the state specified.
java.util.Collection	getJobs(java.lang.String desc) This methods return a collection view of the jobs submitted to the scheduler with the description specified.
java.util.Collection	getJobs(java.lang.String desc, int state) This methods return a collection view of the jobs submitted to the scheduler with the description and state specified.
java.util.logging.Level	getLogLevel(JobHandle job) Returns the log level for the job specified.
int	getState(JobHandle job) Returns the state of the job specified.
void	notify(java.util.Collection jobs, Notification notification) This method is used to send an asynchronous notification to one or more triggers associated with the specified jobs.
void	notify(Notification notification) This method is used to send an asynchronous notification to all triggers.
void	pause(JobHandle job) Used to pause any subsequent executions of the specified job.
void	remove(JobHandle job) Once a job has been submitted to the scheduler it may be optionally removed.
void	removeBlackoutWindow(java.lang.String windowName) Removes a blackout window as specified by window name
void	removeListener(JobHandle job, java.lang.Class listener) Remote event listener for job specified
void	resume(JobHandle job, boolean replay) Used to resume the execution of a job that was previously paused.
void	setLogLevel(JobHandle job, java.util.logging.Level level) Set the log level for the job specified to the level indicated as defined in java.util.logging.Level.
void	updateBlackoutWindowDuration(java.lang.String windowName, long windowDuration) Updates duration of blackout window as specified by window name
void	updateBlackoutWindowSchedule(java.lang.String windowName, Schedule schedule) Updates schedule of blackout window as specified by window name

Field Detail

DEFAULT_JOB_EXECUTION_LOG_LEVEL

public static final java.util.logging.Level DEFAULT_JOB_EXECUTION_LOG_LEVEL

The default log level for any job execution logger

DEFAULT_JOB_LOG_LEVEL

public static final java.util.logging.Level DEFAULT_JOB_LOG_LEVEL

The default log level for any job logger

DEFAULT_ROOT_LOG_LEVEL

public static final java.util.logging.Level DEFAULT_ROOT_LOG_LEVEL

The default log level for the scheduler root logger

DEFAULT_INTERVAL_THRESHOLD_MINUTES

public static final long DEFAULT_INTERVAL_THRESHOLD_MINUTES

The default interval threshold below which no timeout recovery is performed

See Also:

Constant Field Values

STATE_ACTIVE

public static final int STATE_ACTIVE

Active job state. The job is active and may be executed at any time.

See Also:

Constant Field Values

STATE_PAUSED

public static final int STATE_PAUSED

Paused job state. The job was paused and will not execute until the job has been resumed.

See Also:

Constant Field Values

STATE_COMPLETED

public static final int STATE_COMPLETED

The job is no longer active. The schedule associated with the job has no further expirations.

See Also:

Constant Field Values

EXECUTION_STARTED

public static final int EXECUTION_STARTED

status value indicating job execution is incomplete

See Also:

Constant Field Values

EXECUTION_SUCCEEDED

public static final int EXECUTION_SUCCEEDED

status value indicating job execution has completed and was successful

See Also:

Constant Field Values

EXECUTION_FAILED

public static final int EXECUTION_FAILED

status value indicating job execution has completed and was not successful

See Also:

Constant Field Values

EXECUTION_CANCELLED

public static final int EXECUTION_CANCELLED

status value indicating job execution has not completed as a result of the job being cancelled

See Also:

Constant Field Values

EXECUTION_BLACKOUT

public static final int EXECUTION_BLACKOUT

status value indicating job execution did not occur due to a blackout window that was in effect at the time of execution

See Also:

Constant Field Values

EXECUTION_THRESHOLD_EXCEEDED

public static final int EXECUTION_THRESHOLD_EXCEEDED

status value indicating job execution did not occur due to execution time exceeding the configured threshold of the job

See Also:

Constant Field Values

EXECUTION_ABORTED

public static final int EXECUTION_ABORTED

status value indicating job execution did not occur due to preemptory container crash or shutdown

See Also:

Constant Field Values

EXECUTION_PAUSED

public static final int EXECUTION_PAUSED

status value indicating job execution did not occur as a result of the job being in the paused state

See Also:

Constant Field Values

TRIGGER_TYPE

public static final int TRIGGER_TYPE

job execution occurred as a result of the trigger firing

See Also:

Constant Field Values

REPLAY_TYPE

public static final int REPLAY_TYPE

job execution was delayed because the job was paused when the trigger initially expired

See Also:

Constant Field Values

RETRY_TYPE

public static final int RETRY_TYPE

job execution is the result of retrying a previously failed execution

See Also:

Constant Field Values

DEFAULT_ROUNDUP_THRESHOLD_MILLIS

public static final long DEFAULT_ROUNDUP_THRESHOLD_MILLIS

Internal use only.

See Also:

Constant Field Values

DEFAULT_EXECUTION_THRESHOLD_MILLIS

public static final long DEFAULT_EXECUTION_THRESHOLD_MILLIS

Internal use only.

See Also:

Constant Field Values

DEFAULT_RETRY_PERIOD_MILLIS

public static final long DEFAULT_RETRY_PERIOD_MILLIS

Internal use only.

See Also:

Constant Field Values

STATE_UNDEF

public static final int STATE_UNDEF

Internal use only.

See Also:

Constant Field Values

Method Detail

add

public JobHandle add(java.lang.String desc,
                     java.lang.String className,
                     Schedule schedule,
                     java.util.Properties properties)
              throws InvalidArgumentException,
                     BlackoutException,
                     java.rmi.RemoteException

Submits a job to the scheduler. Once a job is successfully submitted the class specified is executed by the scheduler according to the schedule specified. If the schedule specified is not repeating the job becomes inactive immediately after the timer expiration notification is sent to the associated trigger.

Parameters:

desc - used to specify a name or description for the job submission. The name specified is not required to be unique. The name specified can be used, for example, to locate this job after submission and likewise accompanies associated log entries. This parameter may be null.

className - specifies the associated class name for this job. The name provided MUST specify an implementation of the Executable interface. The class specified MUST be deployed with the application. All submitted jobs must include a class name.

schedule - specifies when and how often a timer expiration notification is sent to the associated trigger.

properties - specifes one or more arguments when the job is invoked. This parameter is optional and may be null. All keys or values specified must implement java.util.Serializable.

Returns:

On success a JobHandle object is returned. The resultant object functions as a handle to the submitted job. This handle may be used to administrate the job. This object may be stored by the application for later use.

Throws:

BlackoutException - If initial expiration of job is occurs in a blackout window.

InvalidArgumentException - for any of the following conditions:

• Any key or value specified in the properties is not serializable.
• schedule parameter is null.
• class name specified is undefined.

Please consult exception message to determine exact cause

java.rmi.RemoteException

add

public JobHandle add(java.lang.String desc,
                     java.lang.String className,
                     Trigger trigger,
                     java.util.Properties properties)
              throws InvalidArgumentException,
                     BlackoutException,
                     java.rmi.RemoteException

Used to submit a job to the scheduler. Once a job is successfully submitted the class specified is executed by the scheduler according to the trigger specified.

Parameters:

desc - used to specify a name or description for the job submission. The name specified is not required to be unique. The name specified can be used, for example, to locate this job after submission and likewise accompanies associated log entries. This parameter may be null.

className - specifies the associated class name for this job. The name provided MUST specify an implementation of the Executable interface. The class specified MUST be deployed with the application. All submitted jobs must include a class name.

trigger - specifies which notification(s) result in the execution of this job.

properties - specifes one or more arguments when the job is invoked. This parameter is optional and may be null. All keys or values specified must implement java.util.Serializable.

Returns:

On success a JobHandle object is returned. The resultant object functions as a handle to the submitted job. This handle may be used to administrate the job. This object may be stored by the application for later use.

Throws:

BlackoutException - if initial expiration is masked by blackout windows.

InvalidArgumentException - for any of the following conditions:

• trigger condition is illegal.
• Any key or value specified in the properties is not serializable.
• class name specified is undefined.
• trigger parameter is null.

Please consult exception message to determine exact cause.

java.rmi.RemoteException

add

public JobHandle add(java.lang.String desc,
                     java.lang.String className,
                     Schedule schedule,
                     Trigger trigger,
                     java.util.Properties properties,
                     java.util.logging.Level logLevel,
                     long retryPeriod,
                     long executionThreshold)
              throws InvalidArgumentException,
                     BlackoutException,
                     java.rmi.RemoteException

Used to submit a job to the scheduler. Once a job is successfully submitted the class specified is executed by the scheduler according to the schedule and/or the trigger specified. If the schedule specified is not repeating the job becomes inactive immediately after the timer expiration notification is sent to the associated trigger.

Parameters:

desc - used to specify a name or description for the job submission. The name specified is not required to be unique. The name specified can be used, for example, to locate this job after submission and likewise accompanies associated log entries. This parameter may be null.

className - specifies the associated class name for this job. The name provided MUST specify an implementation of the Executable interface. The class specified MUST be deployed with the application. All submitted jobs must include a class name.

schedule - specifies when and how often a timer expiration notification is sent to the associated trigger.

trigger - specifies which notification(s) result in the execution of this job.

properties - specifes one or more arguments when the job is invoked. This parameter is optional and may be null. All keys or values specified must implement java.util.Serializable.

logLevel - specifies the log level for this job. Any of the levels specified in java.util.logging.Level may be used a a valid value.

retryPeriod - The period of time in millis in which a job is retried after an execution failure

executionThreshold - The period of time in millis following expected execution time, within which if a job does not execute, causes the execution to be discarded

Returns:

On success a JobHandle object is returned. The resultant object functions as a handle to the submitted job. This handle may be used to administrate the job. This object may be stored by the application for later use.

Throws:

BlackoutException - if initial expiration is masked by blackout windows

InvalidArgumentException - for any of the following conditions:

• execution threshold is not allowed.
• trigger condition is illegal.
• any key or value specified in the properties is not serializable.
• the specified log level is not one of the constant levels[Level.ALL,Level.CONFIG,Level.FINE, Level.FINER,Level.FINEST, Level.INFO, Level.OFF, Level.SEVERE or Level.WARNING ]defined in java.util.logging.Level
• both the schedule and trigger parameters are null.
• class name specified is undefined.

Please consult exception message to determine exact cause.

java.rmi.RemoteException

getJob

public Job getJob(JobHandle job)
           throws JobNotFoundException,
                  java.rmi.RemoteException

Retrieve the metadata for the job specified.

Parameters:

job - job for which metadata is requested.

Returns:

On success returns a Job object.

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

java.rmi.RemoteException

remove

public void remove(JobHandle job)
            throws JobNotFoundException,
                   java.rmi.RemoteException

Once a job has been submitted to the scheduler it may be optionally removed. On success the job is permanently removed. Successful invocation of this method does not result in terminating any outstanding execution(s) of this job.

Parameters:

job - job to remove

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

java.rmi.RemoteException

cancel

public void cancel(JobHandle job)
            throws JobNotFoundException,
                   IllegalOperationException,
                   java.rmi.RemoteException

A submitted job may be optionally cancelled. This operation is only possible if the job class implements the Cancellable interface. The result of invoking this method is that the cancel method is invoked on all currently executing job instances. Successful invocation of this method does not result in terminating any outstanding execution(s) of this job.

Parameters:

job - job to cancel

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

IllegalOperationException - for any of the following conditions:

• job class does not implement the Cancellable interface.
• job class is not found.

Please consult exception message to determine exact cause.

java.rmi.RemoteException

pause

public void pause(JobHandle job)
           throws JobNotFoundException,
                  IllegalOperationException,
                  java.rmi.RemoteException

Used to pause any subsequent executions of the specified job. When a job has been paused and the associated trigger fires the execution of the job is postponed indefinitely until the job is resumed. Successful invocation of this method does not result in pausing any outstanding execution(s) of this job.

Parameters:

job - job to pause

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

IllegalOperationException - If the job is not in the state STATE_ACTIVE.

java.rmi.RemoteException

resume

public void resume(JobHandle job,
                   boolean replay)
            throws JobNotFoundException,
                   IllegalOperationException,
                   java.rmi.RemoteException

Used to resume the execution of a job that was previously paused. If the associated trigger fired one or more times while the job was in the paused state the scheduler executes the job once if the replay parameter is set to a value of true otherwise execution is skipped.

Parameters:

job - job to pause

replay - if true the job execution is replayed once if the associated trigger fired, otherwise execution is skipped.

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

IllegalOperationException - If the job is not in the state STATE_PAUSED.

java.rmi.RemoteException

getState

public int getState(JobHandle job)
             throws JobNotFoundException,
                    java.rmi.RemoteException

Returns the state of the job specified.

Parameters:

job - job for which the state is requested.

Returns:

STATE_ACTIVE if the job is active, STATE_PAUSED if the job has been paused, or STATE_COMPLETED if the job is no longer active.

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

java.rmi.RemoteException

setLogLevel

public void setLogLevel(JobHandle job,
                        java.util.logging.Level level)
                 throws JobNotFoundException,
                        InvalidArgumentException,
                        java.rmi.RemoteException

Set the log level for the job specified to the level indicated as defined in java.util.logging.Level. If the logging level is set to a value of Level.WARNING, log entries are written under the following conditions:

• Execution of the job resulted in a JobExecutionException.
• Execution of the job resulted in a RuntimeException.

If the logging level is set to a value of Level.FINE the following additional information is written to the log:

• Date and time at which the job started execution.
• Date and time at which the job ended execution.

If the log level is set to a value of Level.FINER the following additional information is written to the log:

• Date and time at which the associated trigger evaluated a notification, and the result of the evaluation.

If the log level is set to a value of Level.FINEST the following additional information is written to the log:

• Total elapsed execution time of the job.

The default log level is Level.FINER. All log entries are written to the hosting applications log file. Each log entry contains the following:

• job description (if non-null)
• job implementation class name
• date and time
• if execution of the job resulted in an exception the accompanying stack trace and associated message

Parameters:

job - job to set the log level.

level - any level as defined in java.util.logging.Level

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

InvalidArgumentException - If the log level specified is not one of the allowed values.

java.rmi.RemoteException

getLogLevel

public java.util.logging.Level getLogLevel(JobHandle job)
                                    throws JobNotFoundException,
                                           java.rmi.RemoteException

Returns the log level for the job specified.

Parameters:

job - job for which the log level is requested.

Returns:

associated log level. The log levels are defined in the class java.util.logging.Level The following is the mapping of what information gets logged for a job at each log level If the logging level is set to a value of Level.WARNING, log entries are written under the following conditions:

• Execution of the job resulted in a JobExecutionException.
• Execution of the job resulted in a RuntimeException.

If the logging level is set to a value of Level.FINE the following additional information is written to the log:

• Date and time at which the job started execution.
• Date and time at which the job ended execution.

If the log level is set to a value of Level.FINER the following additional information is written to the log:

• Date and time at which the associated trigger evaluated a notification, and the result of the evaluation.

If the log level is set to a value of Level.FINEST the following additional information is written to the log:

• Total elapsed execution time of the job.

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

java.rmi.RemoteException

getJobs

public java.util.Collection getJobs()
                             throws java.rmi.RemoteException

This methods return a collection view of all jobs submitted to the scheduler.

Returns:

Collection of all jobs that match the specified criteria.

Throws:

java.rmi.RemoteException

getJobs

public java.util.Collection getJobs(java.lang.String desc)
                             throws java.rmi.RemoteException

This methods return a collection view of the jobs submitted to the scheduler with the description specified.

Parameters:

desc - Retrieve all jobs with the description specified.

Returns:

Collection of all jobs that match the specified criteria.

Throws:

java.rmi.RemoteException

getJobs

public java.util.Collection getJobs(int state)
                             throws InvalidArgumentException,
                                    java.rmi.RemoteException

This methods return a collection view of the jobs submitted to the scheduler with the state specified.

Parameters:

state - Retrieve all job with the value specified.

Returns:

Collection of all jobs that match the specified criteria.

Throws:

InvalidArgumentException - if the state specified is invalid.

java.rmi.RemoteException

getJobs

public java.util.Collection getJobs(java.lang.String desc,
                                    int state)
                             throws InvalidArgumentException,
                                    java.rmi.RemoteException

This methods return a collection view of the jobs submitted to the scheduler with the description and state specified.

Parameters:

desc - Retrieve all jobs with the description specified.

state - Retrieve all job with the value specified.

Returns:

Collection of all jobs that match the specified criteria.

Throws:

InvalidArgumentException - if the state specified is invalid.

java.rmi.RemoteException

notify

public void notify(Notification notification)
            throws java.rmi.RemoteException

This method is used to send an asynchronous notification to all triggers.

Throws:

java.rmi.RemoteException

notify

public void notify(java.util.Collection jobs,
                   Notification notification)
            throws JobNotFoundException,
                   java.rmi.RemoteException

This method is used to send an asynchronous notification to one or more triggers associated with the specified jobs.

Parameters:

jobs - a collection of one or more JobHandle objects.

Throws:

JobNotFoundException - If one or more of the jobs specified is undefined.

java.lang.ClassCastException - If one or more of the objects specified is not a JobHandle object.

java.rmi.RemoteException

addBlackoutWindow

public void addBlackoutWindow(java.lang.String windowName,
                              Schedule schedule,
                              long duration)
                       throws InvalidArgumentException,
                              BlackoutException,
                              java.rmi.RemoteException

Add's a temporal window in which all job executions are supressed. The window may repeat as determined by the schedule parameter.

Parameters:

windowName - name of the the new window.

schedule - the schedule of the start time of the window. Note that the schedule may repeating as in the case of a IntervalSchedule.

duration - duration in minutes of the specified window.

Throws:

BlackoutException - if window of the same name already exists.

InvalidArgumentException - if schedule and duration are incompatible or if the window will never take effect.

java.rmi.RemoteException

removeBlackoutWindow

public void removeBlackoutWindow(java.lang.String windowName)
                          throws WindowNotFoundException,
                                 java.rmi.RemoteException

Removes a blackout window as specified by window name

Parameters:

windowName - name of the window to be removed.

Throws:

WindowNotFoundException - if a window of specified name does not exist

java.rmi.RemoteException

updateBlackoutWindowSchedule

public void updateBlackoutWindowSchedule(java.lang.String windowName,
                                         Schedule schedule)
                                  throws WindowNotFoundException,
                                         InvalidArgumentException,
                                         java.rmi.RemoteException

Updates schedule of blackout window as specified by window name

Parameters:

windowName - name of the window to be removed.

Throws:

WindowNotFoundException - if a window of specified name does not exist

InvalidArgumentException - if schedule and duration are incompatible or if the window will never take effect.

java.rmi.RemoteException

updateBlackoutWindowDuration

public void updateBlackoutWindowDuration(java.lang.String windowName,
                                         long windowDuration)
                                  throws WindowNotFoundException,
                                         InvalidArgumentException,
                                         java.rmi.RemoteException

Updates duration of blackout window as specified by window name

Parameters:

windowName - name of the window to be removed.

Throws:

WindowNotFoundException - if a window of specified name does not exist

InvalidArgumentException - if schedule and duration are incompatible or if the window will never take effect.

java.rmi.RemoteException

getBlackoutWindowNames

public java.util.Collection getBlackoutWindowNames()
                                            throws java.rmi.RemoteException

Retrieves a collection of blackout window names

Throws:

java.rmi.RemoteException

addListener

public void addListener(JobHandle job,
                        java.lang.Class listener)
                 throws JobNotFoundException,
                        InvalidArgumentException,
                        java.rmi.RemoteException

Add event listener for job specified

Parameters:

job - job to which listenr is added.

listener - the listener class

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

InvalidArgumentException - If fails to create a listener instance.

java.rmi.RemoteException

removeListener

public void removeListener(JobHandle job,
                           java.lang.Class listener)
                    throws JobNotFoundException,
                           ListenerNotFoundException,
                           java.rmi.RemoteException

Remote event listener for job specified

Parameters:

job - job to which listenr is added.

listener - the listener class

Throws:

JobNotFoundException - If the job associated with the handle specified is undefined.

ListenerNotFoundException - If listener instance specified by class is not found

java.rmi.RemoteException