oracle.as.scheduler

Interface Executable

All Known Subinterfaces:

AsyncExecutable, RemoteCancellableExecutable, RemoteExecutable

public interface Executable

Contract for implementing the executable for a Java job. The client application must supply a class that implements this interface for a request executable of job type JAVA_TYPE.

A client application specifies the Java executable class by setting the the CLASS_NAME system property via either job metadata or at request submission. The executable class may also implement the Cancellable interface. The executable class implementation must provide an empty constructor.

When a request is ready to execute, Enterprise Scheduler will first invoke the pre-process callback if one was specified for the request. If the callback indicates that request execution should proceed, Enterprise Scheduler will then instantiate the Executable implementation class and call the execute method. Upon successful return from execute, the post-process callback will be invoked if one was specified for the request.

The execute method is called each time the request is executed. It is passed an execution context in the form of a RequestExecutionContext and the current request parameters. The execution context specifes the request identifer and additional details needed if the job implementation submits sub-requests. The manner in which execute returns to the caller, either by successful return or exception, determines how Enterprise Scheduler handles subsequent request processing.

A Java executable can submit sub-requests using RuntimeService.submitRequest. It must then throw ExecutionPausedException which causes the request to transition to PAUSED state. Once the sub-requests have completed, the parent request is run again as a resumed request. The execution context can be used to determine if the executable is being run as a resumed request.

The job executable is called zero, one, or more times for a given request based on various factors. The executable is never invoked for the submitted request (absolute parent) of a Schedule based submission since the submitted request does not actually execute. Instead, Enterprise Scheduler automatically creates a child request for each schedule instance, each having a different request id.

The executable may be invoked more that once for a given request during its overall lifecycle. One case is a request that submits sub-requests and pauses to allow sub-requests to run. The job executable for that parent request is invoked when the request is initially executed and again when it is resumed. Another case is if a system error is encountred while processing a request. Enterprise Scheduler may automatically retry the request execution depending on the value of the RETRIES system property.

Enterprise Scheduler creates a new instance of the executable class each time it is invoked for a given request. For example, a new instance is create when a paused request is resumed, or each retry of a request. As such, the job implementation should not rely on class static or instance member variables for maintaining state.

See Also:

RequestExecutionContext, State

Method Summary

Modifier and Type	Method and Description
void	execute(RequestExecutionContext context, RequestParameters parameters) Invoked every time the Java job request is executed.

Method Detail

execute

void execute(RequestExecutionContext context,
             RequestParameters parameters)
      throws ExecutionErrorException,
             ExecutionWarningException,
             ExecutionCancelledException,
             ExecutionPausedException

Invoked every time the Java job request is executed. This method must eventually return control to the caller.

Parameters:

context - the execution context for associated with this request

parameters - the request parameters associated with this request

Throws:

ExecutionErrorException - Should be thrown when the job implementation detects a failure condition that it needs to communicate to the scheduling subsystem.

• An exception that is an instance of ExecutionErrorException is treated as a system error. The request will transition to ERROR state unless it is subject to retries based on the value of the RETRIES system property. If the request will be retried it will transition to ERROR_AUTO_RETRY state and then WAIT state.
• An exception that is an instance of ExecutionBizErrorException is treated as a business error, which is not subject to retries. The request will transition to ERROR state.

ExecutionWarningException - Should be thrown when the job implementation detects a failure condition that it needs to communicate to the scheduling subsystem. The request will transition to WARNING state once the post-processing, if any, has been done.

ExecutionCancelledException - Should be thrown when the job implementation detects a condition for request cancellation that it needs to communicate to the scheduling subsystem. The request will transition to CANCELLED state.

ExecutionPausedException - Should be thrown when the job implementation submits a sub-request and is ready to pause to allow the sub-request to execute. The request will transition to PAUSED state.

See Also:

State