oracle.as.scheduler
Interface RuntimeService

All Known Subinterfaces:

RuntimeServiceRemote

public interface RuntimeService

Runtime Service API. This API provides access to the runtime service for submitting and managing job requests and the job request history.

Nested Class Summary

static class

RuntimeService.QueryField Field names to be used when querying the Runtime Store.

Field Summary

static boolean	DEFAULT_EXECUTE_PAST The default setting for EXECUTE_PAST.
static int	DEFAULT_PRIORITY The default system priority associated with a request.
static int	DEFAULT_REPROCESS_DELAY The default period, in minutes, in which processing must be postponed by a callout handler.
static int	DEFAULT_REQUEST_EXPIRATION The default expiration, in minutes, for a request.
static int	DEFAULT_RETRIES The default number of times a failed request will be retried.

Method Summary

void	cancelRequest(RuntimeServiceHandle handle, long requestId) Cancels the processing of a request that is not in a terminal state.
java.util.Map	checkRequestPrivilege(RuntimeServiceHandle handle, long[] requestIds, RuntimeDataPermission.Action... privileges) Check whether the current user has privilegs on the input requests identified by a list of request ids.
void	close(RuntimeServiceHandle handle) Closes the runtime handle.
void	close(RuntimeServiceHandle handle, boolean abort) Closes the runtime handle.
void	deleteRequest(RuntimeServiceHandle handle, long requestId) Marks a submitted request as deleted.
FailedExecutionResult	getFailedExecutionResult(RuntimeServiceHandle handle, long requestId) Retrieves the result of the last failed execution attempt for the specified request which has been retried at least once.
java.util.Set<java.lang.String>	getLogicalApplicationNames(RuntimeServiceHandle handle) Get a list of all logical application names for ESS hosted applications currently deployed
RequestDetail	getRequestDetail(RuntimeServiceHandle handle, long requestId) Retrieves runtime details of the specified request.
RequestDetail	getRequestDetailBasic(RuntimeServiceHandle handle, long requestId) Retrieves basic runtime details of the specified request.
RequestDetail[]	getRequestDetails(RuntimeServiceHandle handle, long[] requestIds) Retrieves basic runtime details of the specified requests.
java.lang.Object	getRequestParameter(RuntimeServiceHandle handle, long requestId, java.lang.String name) Retrieves the value of a request parameter.
java.util.Enumeration<java.lang.Long>	getRequests(RuntimeServiceHandle handle, long requestId) Returns an enumeration of the request identifiers for those requests that have the specified request as their immediate parent and are associated with the current execution attempt of that parent request.
State	getRequestState(RuntimeServiceHandle handle, long requestId) Retrieves the current state of the specified request.
void	holdRequest(RuntimeServiceHandle handle, long requestId) Withholds further processing of a request that is in WAIT or READY state.
boolean	isHandleRollbackOnly(RuntimeServiceHandle handle) Determine if this handle has been marked such that the associated transaction can only be rolled back.
void	lockRequest(RuntimeServiceHandle handle, long requestId) Acquires a lock for the given request.
RuntimeServiceHandle	open() Allocates system resources for performing subsequent runtime operations.
void	publishEvent(RuntimeServiceHandle handle, java.lang.String targetApplication, ApplicationEvent event) Publishes an application event to the event queue.
void	purgeRequest(RuntimeServiceHandle handle, long requestId) Deprecated. As of 11.1.1.3.0(D8B4) Purge not supported via runtime API. Always throws NotAllowedException
java.util.Enumeration<java.lang.Long>	queryRequests(RuntimeServiceHandle handle, Filter filter, RuntimeService.QueryField orderBy, boolean ascending) Retrieves an enumeration of the request identifers for all requests whose attribute and system properties match those specified by the query parameters
void	releaseRequest(RuntimeServiceHandle handle, long requestId) Releases a request from the HOLD state.
void	replaceSchedule(RuntimeServiceHandle handle, long requestId, MetadataObjectId scheduleId) Replace the current schedule for a request that has already been submitted.
void	replaceSchedule(RuntimeServiceHandle handle, long requestId, MetadataObjectId scheduleId, Schedule schedule, java.util.Calendar start, java.util.Calendar end) Replace the current schedule for a request that has already been submitted with a schedule.
void	replaceSchedule(RuntimeServiceHandle handle, long requestId, Schedule schedule) Replace the current schedule for a request that has already been submitted.
void	setHandleRollbackOnly(RuntimeServiceHandle handle) Modify the transaction associated with this handle such that the only possible outcome of the transaction is to roll back the transaction.
void	setRequestParameter(RuntimeServiceHandle handle, long requestId, java.lang.String name, java.lang.Object value) Sets the value of a request parameter for a specified request.
long	submitRequest(RuntimeServiceHandle handle, RequestExecutionContext context, java.lang.String description, MetadataObjectId definition, RequestParameters parameters) Submits a sub-request.
long	submitRequest(RuntimeServiceHandle handle, java.lang.String description, JobType.ExecutionType type, Schedule schedule, Trigger trigger, java.util.Calendar start, java.util.Calendar end, RequestParameters parameters) Adhoc job request submission using specified Schedule and Trigger instances.
long	submitRequest(RuntimeServiceHandle handle, java.lang.String description, MetadataObjectId definition, java.util.Calendar start, RequestParameters parameters) Creates a new job request using metadata definition of the job to run once on a specific time.
long	submitRequest(RuntimeServiceHandle handle, java.lang.String description, MetadataObjectId definition, MetadataObjectId trigger, java.util.Calendar start, java.util.Calendar end, RequestParameters parameters) Creates a new job request using metadata definitions of the job and associated trigger
long	submitRequest(RuntimeServiceHandle handle, java.lang.String description, MetadataObjectId definition, MetadataObjectId schedule, MetadataObjectId trigger, java.util.Calendar start, java.util.Calendar end, RequestParameters parameters) Creates a new job request using metadata definitions of the job, schedule and associated trigger.
long	submitRequest(RuntimeServiceHandle handle, java.lang.String description, MetadataObjectId definition, Schedule schedule, Trigger trigger, java.util.Calendar start, java.util.Calendar end, RequestParameters parameters) Adhoc job request submission using job definition from metadata.
void	updateRequestParameter(RuntimeServiceHandle handle, long requestId, java.lang.String name, java.lang.Object value) Updates the value of a request parameter for a specified request.
void	updateRequestStartEnd(RuntimeServiceHandle handle, long requestId, java.util.Calendar start, java.util.Calendar end) Replace the start and end time for a request that has already been submitted.

Field Detail

DEFAULT_REPROCESS_DELAY

static final int DEFAULT_REPROCESS_DELAY

The default period, in minutes, in which processing must be postponed by a callout handler. The default value is 5 minutes.

See Also:

Constant Field Values

DEFAULT_PRIORITY

static final int DEFAULT_PRIORITY

The default system priority associated with a request. The default value is 4.

See Also:

Constant Field Values

DEFAULT_REQUEST_EXPIRATION

static final int DEFAULT_REQUEST_EXPIRATION

The default expiration, in minutes, for a request. The default value is 0 which means the request will never expire.

See Also:

Constant Field Values

DEFAULT_RETRIES

static final int DEFAULT_RETRIES

The default number of times a failed request will be retried. The default value is 0 which means a failed request is not retried.

See Also:

Constant Field Values

DEFAULT_EXECUTE_PAST

static final boolean DEFAULT_EXECUTE_PAST

The default setting for EXECUTE_PAST. The default value is TRUE which means past recurrences that are within the range of requested start time to requested end time will be scheduled and executed.

See Also:

Constant Field Values

Method Detail

open

RuntimeServiceHandle open()
                          throws RuntimeServiceException

Allocates system resources for performing subsequent runtime operations. The handle returned by this method will associated with the allocaed resources and can be used for multiple runtime operations.

The close operation closes the handle returned by this method, and that handle instance cannot be used for subsequent operations.

If this method is called in a non-transactional context, then the close operation will attempt to save (commit) or discard (rollback) the runtime store changes associated with that handle.

If this method is called within a transactional context, then it is the responsibility of the transaction manager to commit or rollback the changes.

Returns:

a handle which can be used to perform subsequent runtime operations.

Throws:

RuntimeServiceException - if a RuntimeService subsystem failure

close

void close(RuntimeServiceHandle handle)
           throws RuntimeServiceException

Closes the runtime handle. Commits any changes made to runtime store using the handle and de-allocates system resources associated with the handle.

This method only commits changes, and only if the open operation that returned the handle was done in a non-transactional context. If it was a transactional context, then it is the responsibility of the transaction manager to commit or rollback the changes.

Once a close operation is performed on a handle instance, that handle cannot be used any subsequent operations.

Parameters:

handle - the resources associated with the RuntimeServiceHandle instance to be de-allocated.

Throws:

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

close

void close(RuntimeServiceHandle handle,
           boolean abort)
           throws RuntimeServiceException

Closes the runtime handle. This will commit or rollback changes made to the runtime store using the handle and de-allocates system resources associated with the handle.

This method only commits (saves) changes, and can only do so if the open operation that returned the handle was done in a non-transactional context. If it was a transactional context, then it is the responsibility of the transaction manager to commit or rollback the changes.

Once a close operation is performed on a handle instance, that handle cannot be used any subsequent operations.

Parameters:

handle - the resources associated with the RuntimeServiceHandle instance to be de-allocated.

abort - true to discard any runtime store changes associated with this handle, or false to retain changes. This parameter has no effect if the open was done in a transactional context.

Throws:

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   java.lang.String description,
                   MetadataObjectId definition,
                   java.util.Calendar start,
                   RequestParameters parameters)
                   throws MetadataNotFoundException,
                          ValidationException,
                          RuntimeServiceException

Creates a new job request using metadata definition of the job to run once on a specific time.

A submitted request might be singleton or it might yield one or more child requests for a job set. In the later case, the single identifier returned by this method is the parent of all ensuing child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

description - an optional description for the request.

definition - the metadata identifier of a Job definition or JobSet definition for the request being submitted.

start - the requested start time for the request. The request will not run prior to this time. If null, the current time will be used. If the request is meant to begin immediately, null should be specified.

parameters - parameters specified as part of the request.

Returns:

the request identifier of the submitted request. This will be the parent request of ensuing child requests, if applicable.

Throws:

MetadataNotFoundException - if any metadata specified for this operation was not found in the metadata repository.

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   java.lang.String description,
                   MetadataObjectId definition,
                   MetadataObjectId trigger,
                   java.util.Calendar start,
                   java.util.Calendar end,
                   RequestParameters parameters)
                   throws MetadataNotFoundException,
                          ValidationException,
                          RuntimeServiceException

Creates a new job request using metadata definitions of the job and associated trigger

A submitted request might be singleton or it might yield one or more child requests if it is a job set. In the later case, the single identifier returned by this method is the parent of all ensuing child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

description - an optional description for the request.

definition - the metadata identifier of a job definition or job set for the request.

trigger - the metadata identifier of job trigger to use, or null if none.

start - the requested start time for the request. The request will not run prior to this time. If null, the current time will be used. If the request is meant to begin immediately, null should be specified.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect.

parameters - request parameters specified as part of the request.

Returns:

the request identifier of the submitted request. This will be the parent request of ensuing child requests, if applicable.

Throws:

MetadataNotFoundException - if any metadata specified for this operation was not found in the metadata repository.

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   java.lang.String description,
                   MetadataObjectId definition,
                   MetadataObjectId schedule,
                   MetadataObjectId trigger,
                   java.util.Calendar start,
                   java.util.Calendar end,
                   RequestParameters parameters)
                   throws MetadataNotFoundException,
                          ValidationException,
                          RuntimeServiceException

Creates a new job request using metadata definitions of the job, schedule and associated trigger.

A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules, trigger-based submission and job sets. In the later cases, the single identifier returned is the parent of all ensuing child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

description - an optional description for the request

definition - the name of a job definition or job set to use from metadata.

schedule - the name of the job schedule to use from metadata.

trigger - the name of job trigger to use from metadata.

start - the requested start time for the request. The request will not run prior to this time. The value may also, in some cases, be used to fill in missing recurrence fields for a recurring schedule. If null, the current time will be used. If the request is meant to begin immediately, null should be specified. The start time applies to both Schedule and Trigger, if present.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect. The end time applies to both the Schedule and Trigger, if present.

parameters - request parameters specified as part of the request.

Returns:

the request identifier of the submitted request. This will be the parent request of ensuing child requests, if applicable.

Throws:

MetadataNotFoundException - if any metadata specified for this operation was not found in the metadata repository.

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   java.lang.String description,
                   JobType.ExecutionType type,
                   Schedule schedule,
                   Trigger trigger,
                   java.util.Calendar start,
                   java.util.Calendar end,
                   RequestParameters parameters)
                   throws ValidationException,
                          RuntimeServiceException

Adhoc job request submission using specified Schedule and Trigger instances.

A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules, trigger-based submission and job sets. In the later cases, the single identifier returned is the parent of all ensuing child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

description - an optional description for the request.

type - must be one of the base types values viz. JAVA_TYPE, SQL_TYPE and PROCESS_TYPE specified by JobType enum.

schedule - the instance of Schedule object, or null if none.

trigger - the instance of Trigger object, or null if none.

start - the requested start time for the request. The request will not run prior to this time. The value may also, in some cases, be used to fill in missing recurrence fields for a recurring schedule. If null, the current time will be used. If the request is meant to begin immediately, null should be specified. The start time applies to both Schedule and Trigger if present.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect. The end time applies to both the Schedule and Trigger definitions, if specified.

parameters - request parameters specified as part of the request.

Returns:

the request identifier of the submitted request. This will be the parent request of ensuing child requests, if applicable.

Throws:

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   java.lang.String description,
                   MetadataObjectId definition,
                   Schedule schedule,
                   Trigger trigger,
                   java.util.Calendar start,
                   java.util.Calendar end,
                   RequestParameters parameters)
                   throws MetadataNotFoundException,
                          ValidationException,
                          RuntimeServiceException

Adhoc job request submission using job definition from metadata. The job definition predefined in metadata, while the Schedule and Trigger are defined adhoc, not in metadata.

A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules, trigger-based submission and job sets. In the later cases, the single identifier returned is the parent of all ensuing child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

description - an optional description for the request.

definition - the Metadata Object Id, identifying the job definition as stored in metadata.

schedule - instance of schedule object.

trigger - the instance of Trigger object.

start - the requested start time for the request. The request will not run prior to this time. The value may also, in some cases, be used to fill in missing recurrence fields for a recurring schedule. If null, the current time will be used. If the request is meant to begin immediately, null should be specified. The start time applies to both the Schedule and Trigger, if present.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect. The end time applies to both the Schedule and Trigger, if present.

parameters - request parameters specified as part of the request.

Returns:

the request identifier of the submitted request. This will be the parent request of ensuing child requests, if applicable.

Throws:

MetadataNotFoundException - if any metadata specified for this operation was not found in the metadata repository.

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

submitRequest

long submitRequest(RuntimeServiceHandle handle,
                   RequestExecutionContext context,
                   java.lang.String description,
                   MetadataObjectId definition,
                   RequestParameters parameters)
                   throws MetadataNotFoundException,
                          ValidationException,
                          RuntimeServiceException

Submits a sub-request. A request is considered as a sub-request when a running job submits a new request, passing its own execution context.

Passing the execution context ties the request being submitted to the currently running request. After submitting the sub request, the submitting (parent) request should throw an ExecutionPausedException that will pause the request and trigger the execution of sub-request. Upon completion of the sub-request, the parent request will be resumed.

Parameters:

handle - the runtime handle instance returned from a prior open call.

context - the execution context of the running request that is submitting the sub-request.

description - an optional description for the request.

definition - the Metadata Object Id, identifying the job definition, as stored in metadata, for the sub-request.

parameters - request parameters specified a part of the request.

Returns:

the request identifier of the submitted sub-request.

Throws:

MetadataNotFoundException - if any metadata specified for this operation was not found in the metadata repository.

ValidationException - if the request validation failed.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

getRequestParameter

java.lang.Object getRequestParameter(RuntimeServiceHandle handle,
                                     long requestId,
                                     java.lang.String name)
                                     throws RequestNotFoundException,
                                            ValidationException,
                                            RuntimeServiceException

Retrieves the value of a request parameter. This method can be used to retrieve a system property or an application parameter.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request.

name - the name of the System property or user request parameter to retrieve.

Returns:

the parameter value.

Throws:

RequestNotFoundException - if the request was not found

ValidationException - if the name parameter does not exist, or name does not represent a valid system property.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

lockRequest

void lockRequest(RuntimeServiceHandle handle,
                 long requestId)
                 throws RequestNotFoundException,
                        RuntimeServiceException

Acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

The method can be used to ensure data consistency when updating request parameters or system properties.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request.

Throws:

RequestNotFoundException - if the request was not found

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

updateRequestParameter

void updateRequestParameter(RuntimeServiceHandle handle,
                            long requestId,
                            java.lang.String name,
                            java.lang.Object value)
                            throws RequestNotFoundException,
                                   ValidationException,
                                   RuntimeServiceException

Updates the value of a request parameter for a specified request. The parameter can be a system property or an application property.

This operation fails if the request parameter does not already exist.

This operation is subject to any read-only constraint on the parameter being updated and an error occurs if the parameter is read-only.

This operation applies to only the target request. It does not cascade to any other requests that may be associated with the request.

This operation acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request.

name - the name of the parameter to modify.

value - the new value of the parameter.

Throws:

RequestNotFoundException - if the request was not found

ValidationException - if parameter validation fails.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null.

RollbackException - if handle has been marked for rollback only.

setRequestParameter

void setRequestParameter(RuntimeServiceHandle handle,
                         long requestId,
                         java.lang.String name,
                         java.lang.Object value)
                         throws RequestNotFoundException,
                                ValidationException,
                                RuntimeServiceException

Sets the value of a request parameter for a specified request. The parameter can be a system property or an application property.

The parameter will be added if it does not already exist, otherwise the value of the parameter will be updated.

This operation is subject to any read-only constraint on the parameter being set and an error occurs if the parameter already exists and is read-only.

This operation applies to only the target request. It does not cascade to any other requests that may be associated with the request.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request.

name - the name of the parameter to set.

value - the new value of the parameter.

Throws:

RequestNotFoundException - if the request was not found

ValidationException - if parameter validation fails.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null.

RollbackException - if handle has been marked for rollback only.

getRequestState

State getRequestState(RuntimeServiceHandle handle,
                      long requestId)
                      throws RequestNotFoundException,
                             RuntimeServiceException

Retrieves the current state of the specified request.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request.

Returns:

the current State of the request

Throws:

RequestNotFoundException - if the request was not found

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

getFailedExecutionResult

FailedExecutionResult getFailedExecutionResult(RuntimeServiceHandle handle,
                                               long requestId)
                                               throws RequestNotFoundException,
                                                      RuntimeServiceException

Retrieves the result of the last failed execution attempt for the specified request which has been retried at least once.

Parameters:

handle - runtime handle instance returned from a prior open call.

requestId - request identifier of the request.

Returns:

FailedExecutionResult of the last failed execution attempt for the request.

Throws:

RequestNotFoundException - if no failed execution history was found for the request, meaning the request has not been retried

RuntimeServiceException - if a RuntimeService subsystem failure occured or handle is null

getRequests

java.util.Enumeration<java.lang.Long> getRequests(RuntimeServiceHandle handle,
                                                  long requestId)
                                                  throws RequestNotFoundException,
                                                         RuntimeServiceException

Returns an enumeration of the request identifiers for those requests that have the specified request as their immediate parent and are associated with the current execution attempt of that parent request.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the target request.

Returns:

an Enumeration (Long) of request identifiers which have requestId as the immediate parent.

Throws:

RequestNotFoundException - if the request was not found.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

getRequestDetail

RequestDetail getRequestDetail(RuntimeServiceHandle handle,
                               long requestId)
                               throws RequestNotFoundException,
                                      MetadataNotFoundException,
                                      RuntimeServiceException

Retrieves runtime details of the specified request.

Parameters:

handle - the runtime handle instance returned from a prior (@code open} call.

requestId - the request identifier of the request

Throws:

RequestNotFoundException - if the request was not found.

MetadataNotFoundException - if any metadata referenced for this operation was not found in the metadata repository.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

getRequestDetailBasic

RequestDetail getRequestDetailBasic(RuntimeServiceHandle handle,
                                    long requestId)
                                    throws RequestNotFoundException,
                                           RuntimeServiceException

Retrieves basic runtime details of the specified request. The RequestDetail returned by this method includes most of the information as getRequestDetail(oracle.as.scheduler.RuntimeServiceHandle, long), but certain less commonly used information is omitted to improve performance.

Specifically, the information returned by the following RequestDetail methods is not meaningful: getSchedule, getTrigger, getTriggerState, getTriggerEvaluationStatus

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request identifier of the request

Throws:

RequestNotFoundException - if the request was not found.

MetadataNotFoundException - if any metadata referenced for this operation was not found in the metadata repository.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

getRequestDetails

RequestDetail[] getRequestDetails(RuntimeServiceHandle handle,
                                  long[] requestIds)
                                  throws RequestNotFoundException,
                                         RuntimeServiceException

Retrieves basic runtime details of the specified requests. The RequestDetails returned by this method includes most of the information as getRequestDetail(oracle.as.scheduler.RuntimeServiceHandle, long), but certain less commonly used information is omitted to improve performance.

Specifically, the information returned by the following RequestDetail methods is not meaningful: getSchedule, getTrigger, getTriggerState, getTriggerEvaluationStatus

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestIds - the request identifier of the request

Throws:

RequestNotFoundException - if the request was not found.

MetadataNotFoundException - if any metadata referenced for this operation was not found in the metadata repository.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

queryRequests

java.util.Enumeration<java.lang.Long> queryRequests(RuntimeServiceHandle handle,
                                                    Filter filter,
                                                    RuntimeService.QueryField orderBy,
                                                    boolean ascending)
                                                    throws ValidationException,
                                                           RuntimeServiceException

Retrieves an enumeration of the request identifers for all requests whose attribute and system properties match those specified by the query parameters

If no filter is specifed, a default filter equivalent to the following is used:

        new Filter(RuntimeService.QueryField.REQUESTID.fieldName(),
                   Filter.Comparator.NOT_EQUALS, null);
 

Parameters:

handle - the runtime handle instance returned from a prior open call.

filter - specifies field/comparator/value combinations used as parameters for retrieving query results. If null, a default filter is used (see above).

orderBy - the field to sort the results by.

ascending - true if the ordering based on the given field should be ascending, or false for descending.

Returns:

an Enumeration (Long) of request identifiers of the requests that satisfy the query parameters.

Throws:

ValidationException - if filter parameter validation fails.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

checkRequestPrivilege

java.util.Map checkRequestPrivilege(RuntimeServiceHandle handle,
                                    long[] requestIds,
                                    RuntimeDataPermission.Action... privileges)
                                    throws ValidationException,
                                           RuntimeServiceException

Check whether the current user has privilegs on the input requests identified by a list of request ids.

Parameters:

handle - runtimeServiceHandle

requestIds - the request ids to be checked.

privileges - the ESS request data security privileges to be checked. If multiple privileges are provided, one request id check requestis passed only if the user has all the privileges on that request.

Returns:

the Map of passed (true) or denied (false) results. Each input request ids will have one entry in the Map.

Throws:

ValidationException

RuntimeServiceException

holdRequest

void holdRequest(RuntimeServiceHandle handle,
                 long requestId)
                 throws RequestNotFoundException,
                        IllegalStateException,
                        NotAllowedException,
                        RuntimeServiceException

Withholds further processing of a request that is in WAIT or READY state. For parent requests, this operation will cascade to all eligible child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the identifier of the request to hold.

Throws:

RequestNotFoundException - if the request was not found.

IllegalStateException - if request is not in a compatible state.

NotAllowedException - if this operation is not allowed on the specified request.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

releaseRequest

void releaseRequest(RuntimeServiceHandle handle,
                    long requestId)
                    throws RequestNotFoundException,
                           IllegalStateException,
                           NotAllowedException,
                           RuntimeServiceException

Releases a request from the HOLD state. For parent requests, this operation will cascade to all eligible child requests.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the identifier of the request to release.

Throws:

RequestNotFoundException - if the request was not found.

IllegalStateException - if request is not in a compatible state.

NotAllowedException - if this operation is not allowed on the specified request.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

cancelRequest

void cancelRequest(RuntimeServiceHandle handle,
                   long requestId)
                   throws IllegalStateException,
                          RequestNotFoundException,
                          RuntimeServiceException

Cancels the processing of a request that is not in a terminal state.

For a singleton and child request in WAIT, READY, BLOCKED or HOLD state, this operation will cause them to go to CANCELLED state.

For a singleton and child request in RUNNING or COMPLETED state, cancellation is best effort and the state will go to a transitory CANCELLING state which will persist until the request has been cancelled and transitions to CANCELLED or some other terminal state.

For parent requests, this operation cascades to all its children.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the identifier of the request to cancel.

Throws:

RequestNotFoundException - if the request was not found.

IllegalStateException - if request is already in a terminal state.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null.

RollbackException - if handle has been marked for rollback only.

deleteRequest

void deleteRequest(RuntimeServiceHandle handle,
                   long requestId)
                   throws RequestNotFoundException,
                          IllegalStateException,
                          NotAllowedException,
                          RuntimeServiceException

Marks a submitted request as deleted. For parent requests, this operation will cascade to all children.

The target request must be a submitted request that has finished and is in a terminal state. An error occurs if the target request is not in a terminal state, or if it is a child request of some kind, for example, a JobSet step, a sub-request, a Schedule instance request, or Trigger instance request.

This does not physically remove request data, although the request will no longer be accessible (visible) for most operations. purgeRequest can be used to physically remove the request.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the identifier of the request to delete.

Throws:

RequestNotFoundException - if the request was not found.

IllegalStateException - if the operation cannot be performed due to the current state of the request.

NotAllowedException - the this operation is not supported for the request.

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

purgeRequest

@Deprecated
void purgeRequest(RuntimeServiceHandle handle,
                             long requestId)
                  throws RequestNotFoundException,
                         IllegalStateException,
                         NotAllowedException,
                         RuntimeServiceException

Deprecated. As of 11.1.1.3.0(D8B4) Purge not supported via runtime API. Always throws NotAllowedException

Throws:

RequestNotFoundException

IllegalStateException

NotAllowedException

RuntimeServiceException

publishEvent

void publishEvent(RuntimeServiceHandle handle,
                  java.lang.String targetApplication,
                  ApplicationEvent event)
                  throws ValidationException,
                         RuntimeServiceException

Publishes an application event to the event queue. The event will be applied to all request triggers interested in that event.

Parameters:

handle - the runtime handle instance returned from a prior open call.

targetApplication - the name of the target application to which this event is to be delivered.

event - the event to be published

Throws:

ValidationException - the event or target application name is null or invalid

RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

RollbackException - if handle has been marked for rollback only.

isHandleRollbackOnly

boolean isHandleRollbackOnly(RuntimeServiceHandle handle)

Determine if this handle has been marked such that the associated transaction can only be rolled back.

Parameters:

handle - the runtime handle being checked.

Returns:

true if this handle as been marked as rollback only, or false otherwise.

setHandleRollbackOnly

void setHandleRollbackOnly(RuntimeServiceHandle handle)

Modify the transaction associated with this handle such that the only possible outcome of the transaction is to roll back the transaction.

Parameters:

handle - the runtime handle.

replaceSchedule

void replaceSchedule(RuntimeServiceHandle handle,
                     long requestId,
                     Schedule schedule)
                     throws RequestNotFoundException,
                            ValidationException,
                            RuntimeServiceException

Replace the current schedule for a request that has already been submitted.

The new schedule is an adhoc schedule. The old schedule could have been a metadata schedule or an adhoc schedule. This operation cannot be invoked on a singleton request with only a start time and no other schedule specified.

This can be used to replace the schedule for a request that is in WAIT or HOLD state.

All previously scheduled instances of this request that have not started running will be canceled. The new schedule will be effective immediately for scheduling new instances.

This operation acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request whose schedule is to be replaced. This request must be a submitted request, not a generated request.

schedule - the new schedule to use for this request

Throws:

ValidationException - if the schedule is not valid or if requestId is not for a submitted request or represents a request in an unsupported state for the operation.

RequestNotFoundException - if requestId was not found.

RuntimeServiceException - if a RuntimeService subsystem failure occurs

replaceSchedule

void replaceSchedule(RuntimeServiceHandle handle,
                     long requestId,
                     MetadataObjectId scheduleId)
                     throws RequestNotFoundException,
                            MetadataNotFoundException,
                            ValidationException,
                            RuntimeServiceException

Replace the current schedule for a request that has already been submitted.

The new schedule will be a schedule obtained from the metadata of the application that submitted the request. The old schedule could have been a metadata schedule or an adhoc schedule. This operation cannot be invoked on a singleton request with only a start time and no other schedule specified.

This can be used to replace the schedule for a request that is in WAIT or HOLD state.

All previously scheduled instances of this request that have not started running will be canceled. The new schedule will be effective immediately for scheduling new instances.

This operation acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request whose schedule is to be replaced. This request must be a submitted request, not a generated request.

scheduleId - a MetadataObjectId representing the new schedule to use for this request

Throws:

ValidationException - if the schedule is not valid or if requestId is not for a submitted request or represents a request in an unsupported state for the operation.

RequestNotFoundException - if requestId was not found.

RuntimeServiceException - if a RuntimeService subsystem failure occurs

MetadataNotFoundException - if the schedule metadata specified for this operation was not found in the metadata repository.

replaceSchedule

void replaceSchedule(RuntimeServiceHandle handle,
                     long requestId,
                     MetadataObjectId scheduleId,
                     Schedule schedule,
                     java.util.Calendar start,
                     java.util.Calendar end)
                     throws RequestNotFoundException,
                            MetadataNotFoundException,
                            ValidationException,
                            RuntimeServiceException

Replace the current schedule for a request that has already been submitted with a schedule.

The new schedule will be a schedule obtained from the metadata of the application that submitted the request or an adhoc schedule. The old schedule could have been a metadata schedule or an adhoc schedule. This operation cannot be invoked on a singleton request that only had a start time and no other schedule.

Either scheduleId or schedule must be specified. See updateRequestStartEnd(oracle.as.scheduler.RuntimeServiceHandle, long, java.util.Calendar, java.util.Calendar).

This can be used to replace the schedule for a request that is in WAIT or HOLD state.

All previously scheduled instances of this request that have not started running will be canceled. The new schedule will be effective immediately for scheduling new instances.

This operation acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request whose schedule is to be replaced. This request must be a submitted request, not a generated request.

scheduleId - a MetadataObjectId representing the new schedule to use for this request

schedule - the new schedule to use for this request

start - the new requested start time for the request. The request will not run prior to this time. If null, the current time will be used. If the request is meant to begin immediately, null should be specified.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect.

Throws:

ValidationException - if both scheduleId and schedule are null, the schedule is not valid or if requestId is not for a submitted request or represents a request in an unsupported state for the operation.

RequestNotFoundException - if requestId was not found.

RuntimeServiceException - if a RuntimeService subsystem failure occurs

MetadataNotFoundException - if the schedule metadata specified for this operation was not found in the metadata repository.

updateRequestStartEnd

void updateRequestStartEnd(RuntimeServiceHandle handle,
                           long requestId,
                           java.util.Calendar start,
                           java.util.Calendar end)
                           throws RequestNotFoundException,
                                  RuntimeServiceException,
                                  ValidationException

Replace the start and end time for a request that has already been submitted.

This method should may be invoked for submitted requests whether or not they not have an associated schedule or trigger. If a schedule or trigger is associated with the request and it is to be changed, please see replaceSchedule(oracle.as.scheduler.RuntimeServiceHandle, long, oracle.as.scheduler.Schedule). If no schedule or trigger is associated with the request note that end has very little meaning. It is only used in validation to ensure that it does not come before start.

This operation acquires a lock for the given request. The lock is released when close operation is subsequently invoked or the encompassing transaction is committed.

If an application tries to invoke this operation while the lock is being held by another thread, this method will block until the lock is released.

Parameters:

handle - the runtime handle instance returned from a prior open call.

requestId - the request whose schedule is to be replaced. This request must be a submitted request, not a generated request.

start - the new requested start time for the request. The request will not run prior to this time. If null, the current time will be used. If the request is meant to begin immediately, null should be specified.

end - the time past which this request or its child requests will not be dispatched for execution. If null, no end time is in effect.

Throws:

RequestNotFoundException

RuntimeServiceException

ValidationException

getLogicalApplicationNames

java.util.Set<java.lang.String> getLogicalApplicationNames(RuntimeServiceHandle handle)
                                                           throws RuntimeServiceException

Get a list of all logical application names for ESS hosted applications currently deployed

Parameters:

handle - the runtime handle instance returned from a prior open call.

Returns:

the set of hosted applications for the current isolation group

Throws:

RuntimeServiceException - if a RuntimeService subsystem failure occurs