Package 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.

  • Field Details

    • 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:

    • DEFAULT_PRIORITY

      static final int DEFAULT_PRIORITY
      The default system priority associated with a request. The default value is 4.
      See Also:

    • 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:

    • 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:

    • 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:

    • DEFAULT_ASYNC_REQUEST_TIMEOUT

      static final long DEFAULT_ASYNC_REQUEST_TIMEOUT
      The default timeout in minutes for an asynchronous request. The default value is 0 which means the request will not timeout.
      See Also:

  • Method Details

    • open

      RuntimeServiceHandle open() throws RuntimeServiceException
      Allocates system resources for performing subsequent runtime operations.

      The handle returned by this method will associated with the allocated resources and can be used for multiple runtime operations. The close operation closes the handle 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 runtime service sub-system error.

    • open

      RuntimeServiceHandle open(Locale locale) throws RuntimeServiceException
      Allocates system resources for performing subsequent runtime operations.

      The handle returned by this method will associated with the allocated resources and can be used for multiple runtime operations. The close operation closes the handle 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.

      Parameters:
      locale - Client locale object used for accessing appropriate metadata resource bundles.
      Returns:
      a handle which can be used to perform subsequent runtime operations.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.

    • 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 runtime service sub-system error, 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 can commit (save) or rollback (discard) changes. It 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 runtime service sub-system error, or handle is null.

    • submitRequest

      long submitRequest(RuntimeServiceHandle handle, String description, MetadataObjectId definition, 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 search description for the request. This is primarily a search tag specific to this request. See RuntimeService.QueryField.NAME. This value cannot be defined in the job definition and is not required to be a human readable value.
      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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • submitRequest

      long submitRequest(RuntimeServiceHandle handle, String description, MetadataObjectId definition, MetadataObjectId schedule, MetadataObjectId trigger, Calendar start, Calendar end, RequestParameters parameters) throws MetadataNotFoundException, ValidationException, RuntimeServiceException
      Creates a new job request using metadata definitions of the job, and schedule.

      A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules 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 search description for the request. This is primarily a search tag specific to this request. See RuntimeService.QueryField.NAME. This value cannot be defined in the job definition and is not required to be a human readable value.
      definition - the metadata identifier of a job definition or job set to use from metadata.
      schedule - the metadata identifier of the job schedule to use from metadata.
      trigger - the value of this parameter must be null.
      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, 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 the Schedule, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • submitRequest

      long submitRequest(RuntimeServiceHandle handle, String description, JobType.ExecutionType type, Schedule schedule, oracle.as.scheduler.Trigger trigger, Calendar start, Calendar end, RequestParameters parameters) throws ValidationException, RuntimeServiceException
      Adhoc job request submission using specified Schedule.

      A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules, 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 search description for the request. This is primarily a search tag specific to this request. See RuntimeService.QueryField.NAME. This value is not required to be a human readable value.
      type - must be one of the base types values viz. JAVA_TYPE, SQL_TYPE and PROCESS_TYPE specified by JobType.ExecutionType enum.
      schedule - the instance of Schedule object, or null if none.
      trigger - the value of this parameter must be null.
      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 the Schedule 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, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • submitRequest

      long submitRequest(RuntimeServiceHandle handle, String description, MetadataObjectId definition, Schedule schedule, oracle.as.scheduler.Trigger trigger, Calendar start, 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 is defined adhoc, not in metadata.

      A submitted request might be singleton or it might yield one or more child requests viz. recurring schedules, 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 search description for the request. This is primarily a search tag specific to this request. See RuntimeService.QueryField.NAME. This value cannot be defined in the job definition and is not required to be a human readable value.
      definition - the metadata identifier of the job definition or job set stored in metadata.
      schedule - instance of schedule object.
      trigger - the value of this parameter must be null.
      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 the Schedule, 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 the Schedule, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • submitRequest

      long submitRequest(RuntimeServiceHandle handle, RequestExecutionContext context, 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 sub-request being submitted to the currently running request. After submitting the sub-request, the submitting (parent) request must pause before Enterprise Scheduler will execute the sub-request. For example, a Java job should throw an ExecutionPausedException. 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 search description for the request. This is primarily a search tag specific to this request. See RuntimeService.QueryField.NAME. This value cannot be defined in the job definition and is not required to be a human readable value.
      definition - the metadata identifier of the job definition 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • getRequestParameter

      Object getRequestParameter(RuntimeServiceHandle handle, long requestId, 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 runtime service sub-system error, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • updateRequestParameter

      void updateRequestParameter(RuntimeServiceHandle handle, long requestId, String name, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • setRequestParameter

      void setRequestParameter(RuntimeServiceHandle handle, long requestId, String name, 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 runtime service sub-system error, 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 runtime service sub-system error, 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 runtime service sub-system error, or handle is null.

    • getRequests

      Enumeration<Long> getRequests(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Gets 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 runtime service sub-system error, 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 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 runtime service sub-system error, or handle is null.

    • getRequestDetail

      RequestDetail getRequestDetail(RuntimeServiceHandle handle, long requestId, boolean includeTranslation) throws RequestNotFoundException, MetadataNotFoundException, RuntimeServiceException
      Retrieves runtime details of the specified request.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the request identifier of the request
      includeTranslation - true for getting info in localized form, or false for default values.
      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 runtime service sub-system error, 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, but some less commonly used information is omitted for performance reasons.

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

      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 runtime service sub-system error, 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, but some less commonly used information is omitted for performance reasons.

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

      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.
      RuntimeServiceException - if runtime service sub-system error, or handle is null.

    • getRequestDetails

      RequestDetail[] getRequestDetails(RuntimeServiceHandle handle, long[] requestIds, boolean includeTranslation) throws RequestNotFoundException, RuntimeServiceException
      Retrieves basic runtime details of the specified requests. The RequestDetails returned by this method includes most of the information as getRequestDetail, but some less commonly used information is omitted for performance reasons.

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

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestIds - the request identifier of the request
      includeTranslation - flag for retrieving information in localized form.
      Throws:
      RequestNotFoundException - if the request was not found.
      RuntimeServiceException - if runtime service sub-system error, or handle is null.

    • queryRequests

      Enumeration<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 runtime service sub-system error, or handle is null.

    • checkRequestPrivilege

      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 - runtime handle instance returned from a prior open call.
      requestIds - the request ids to be checked.
      privileges - the ESS request data security privileges to be checked. If multiple privileges are provided, a permission check for a request id passes only if the user has all the privileges on that request.
      Returns:
      a Map(Long,Boolean) of the results where the key is the request id and value is the check result. The result will be true if the permission check passed and false if permission is denied. Each request id will have one entry in the Map.
      Throws:
      ValidationException - if validation error occurs.
      RuntimeServiceException - if runtime service sub-system error.

    • checkDetailedPermissions

      Map<Long,Map<String,Boolean>> checkDetailedPermissions(RuntimeServiceHandle handle, long[] requestIds, RuntimeDataPermission.Action... privileges) throws RuntimeServiceException, ValidationException
      Check whether the current user has privilegs on the input requests identified by a list of request ids. This method returns a Map with key (Long) as the requestId and value as another Map with key as the RuntimePermission.Action and value as the Boolean result of its permission check.
      Parameters:
      handle - runtime handle instance returned from a prior open call.
      requestIds - the request ids to be checked.
      privileges - the ESS request data security privileges to be checked.
      Returns:
      the Map of result as specified above. Each request id will have one entry in the Map.
      Throws:
      ValidationException - if validation error occurs.
      RuntimeServiceException - if runtime service sub-system error.

    • 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 runtime service sub-system error, 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 runtime service sub-system error, 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 runtime service sub-system error, or handle is null.
      RollbackException - if handle has been marked for rollback only.

    • cancelRequests

      void cancelRequests(Filter filter, RuntimeService.QueryField orderBy, boolean ascending) throws RuntimeServiceException, ValidationException
      Cancels the processing of multiple request that are not in a terminal state. Maximum limit of requests to cancel is 100.
      Parameters:
      filter - specifies field/comparator/value combinations used as parameters for retrieving query results. Filter should always be specified, null value is not supported and it should only include requests that are in non-terminal states.
      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.
      Throws:
      RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null.
      ValidationException - if filter parameter validation fails.

    • 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, or a Schedule instance request.

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

      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 runtime service sub-system error, 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.

    • getLocale

      Locale getLocale(RuntimeServiceHandle handle)
      Get the locale associated with this session.
      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 runtime service sub-system error.

    • 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 runtime service sub-system error.
      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, Calendar start, 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.

      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 runtime service sub-system error.
      MetadataNotFoundException - if the schedule metadata specified for this operation was not found in the metadata repository.

    • updateRequestStartEnd

      void updateRequestStartEnd(RuntimeServiceHandle handle, long requestId, Calendar start, Calendar end) throws RequestNotFoundException, RuntimeServiceException, ValidationException
      Replace the start and end time for a request that has already been submitted.

      This method may be invoked for submitted requests whether or not they not have an associated schedule. If a schedule is associated with the request and it is to be changed, see replaceSchedule. If no schedule is associated with the request the end parameter 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:
      ValidationException - 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 runtime service sub-system error.

    • getDBSchedulerJobDetail

      DBSchedulerJobDetail getDBSchedulerJobDetail(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Returns the object containing DBScheduler External Job Status details
      Parameters:
      handle - runtime service handle
      requestId - the ESS request identifier
      Returns:
      The object containing DBScheduler External Job Status details
      Throws:
      RequestNotFoundException - if an error occurs
      RuntimeServiceException - if an error occurs

    • getLogicalApplicationNames

      Set<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<String> of hosted applications for the current isolation group
      Throws:
      RuntimeServiceException - if runtime service sub-system error.

    • getLogContentDetail

      ContentDetail getLogContentDetail(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Gets the log content detail for the request.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the request id.
      Returns:
      Details of the request log, or null if the log does not exist.
      Throws:
      RequestNotFoundException - if the request was not found.
      RuntimeServiceException - if runtime service sub-system error.

    • getOutputContentDetail

      ContentDetail getOutputContentDetail(RuntimeServiceHandle handle, long requestId, String contentName) throws RuntimeServiceException, RequestNotFoundException
      Gets details for the specified output content for the request.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the request id.
      contentName - name of output content.
      Returns:
      Details of the specified output content, or null if the content does not exist.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • getOutputContentDetail

      List<ContentDetail> getOutputContentDetail(RuntimeServiceHandle handle, long requestId) throws RuntimeServiceException, RequestNotFoundException
      Gets details for all output content for the request.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the request id.
      Returns:
      A List<ContentDetail> of details for all output content for the request. The list will be empty if there is no output content.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • openLogContent

      ContentHandle openLogContent(RuntimeServiceHandle handle, long requestId) throws NotFoundException, RuntimeServiceException
      Opens the request log to retrieve the log data.

      When done accessing the log content, the caller must release the ContentHandle by calling closeContent.

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - request id.
      Returns:
      Handle that can be used to retrieve log data.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.
      NotFoundException - if the log does not exist.

    • logContent

      void logContent(RequestExecutionContext context, Level level, String message) throws RequestNotFoundException, RuntimeServiceException
      Logs a message to the request log in the content store during job execution.

      The request log level is defined by the SystemProperty.REQUEST_LOG_LEVEL system property defaults to Level.INFO if not defined. The message will be logged if the given level is the same or higher than the current value of the request log level.

      Note that this can only be called from the job executable while the job is executing. To log in the pre- or post-processor or the request listener, use ContentFactory.

      Parameters:
      context - request execution context passed to the job executable.
      level - log level for the message.
      message - message to append to the request log.
      Throws:
      RequestNotFoundException - if the request does not exist.
      RuntimeServiceException - if runtime service sub-system error.
      See Also:

    • openOutputContent

      ContentHandle openOutputContent(RuntimeServiceHandle handle, RequestExecutionContext context, String contentName, ContentType contentType, EnumSet<ContentHandle.ContentOpenOptions> options) throws NotFoundException, RequestNotFoundException, RuntimeServiceException, ValidationException
      Opens the named request output during job execution.

      The output content may be opened for read or write, but not both. If opened for write, the content will be created if it does not already exist.

      The RuntimeServiceHandle passed by the caller will be cached and used by the write content methods to write to the output content. When done accessing the output content, the caller must release the ContentHandle by calling closeContent. The caller is responsible to commit or rollback the RuntimeServiceHandle after closing the ContentHandle.

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      context - request execution context passed to the job executable.
      contentName - name of the output content to open.
      contentType - type of the output content to open for write if the content must be created. For read, this parameter is ignored ContentType.Unknow can be passed.
      options - an EnumSet<ContentOpenOptions> of options specifying how to open the request output; may open for read or write, but not both.
      Returns:
      ContentHandle that can be used to either read or write data.
      Throws:
      NotFoundException - if the output does not exist, for a read.
      RequestNotFoundException - if the request does not exist.
      RuntimeServiceException - if runtime service sub-system error.
      ValidationException - if the options are invalid.

    • writelnContent

      void writelnContent(ContentHandle contentHandle, String message) throws IllegalArgumentException, NotFoundException, RuntimeServiceException, ValidationException
      Appends the string followed by a line feed character to the output content during job execution.

      The content must be open for write, and the runtime service handle that was passed to openOutputContent must be valid.

      Parameters:
      contentHandle - content handle from previous call to openOutputContent.
      message - string to write to the output content, followed by line feed character.
      Throws:
      IllegalArgumentException - if the content handle is invalid.
      NotFoundException - if the content does not exist.
      RuntimeServiceException - if error accessing runtime store.
      ValidationException - if it is invalid to write to the content, meaning the content type is binary or the content was created from an import.

    • writeContent

      void writeContent(ContentHandle contentHandle, String message) throws IllegalArgumentException, NotFoundException, RuntimeServiceException, ValidationException
      Appends the string to the output content during job execution.

      The content must be open for write, and the runtime service handle that was passed to openOutputContent must be valid.

      Parameters:
      contentHandle - content handle from previous call to openOutputContent.
      message - string to write to the output content.
      Throws:
      IllegalArgumentException - if content handle is invalid.
      NotFoundException - if content does not exist.
      RuntimeServiceException - if runtime service sub-system error.
      ValidationException - if it is invalid to write to the content, meaning the content type is binary or the content was created from an import.

    • writeContent

      void writeContent(ContentHandle contentHandle, char[] chars) throws IllegalArgumentException, NotFoundException, RuntimeServiceException, ValidationException
      Appends the characters to the output content during job execution.

      The content must be open for write, and the runtime service handle that was passed to openOutputContent must be valid.

      Parameters:
      contentHandle - content handle from previous call to openOutputContent.
      chars - characters to append.
      Throws:
      IllegalArgumentException - if content handle is invalid.
      NotFoundException - if content does not exist.
      RuntimeServiceException - if runtime service sub-system error.
      ValidationException - if it is invalid to write to the content, meaning the content type is binary or the content was created from an import.

    • writeContent

      void writeContent(ContentHandle contentHandle, byte[] bytes) throws IllegalArgumentException, NotFoundException, RuntimeServiceException, ValidationException
      Appends the bytes to the output content during job execution.

      The content must be open for write, and the runtime service handle that was passed to openOutputContent must be valid.

      Parameters:
      contentHandle - content handle from previous call to openOutputContent.
      bytes - bytes to append.
      Throws:
      IllegalArgumentException - if content handle is invalid.
      NotFoundException - if content does not exist.
      RuntimeServiceException - if runtime service sub-system error.
      ValidationException - if it is invalid to write to the content, meaning the content type is binary or the content was created from an import.

    • openOutputContent

      ContentHandle openOutputContent(RuntimeServiceHandle handle, long requestId, String contentName) throws NotFoundException, RuntimeServiceException
      Opens the specified request output to retrieve the output data.

      When done accessing the log content, the caller must release the ContentHandle by calling closeContent.

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the request id.
      contentName - name of the output content to open.
      Returns:
      Handle that can be used to retrieve output data.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.
      NotFoundException - if the output content does not exist.

    • getLogLines

      String[] getLogLines(RuntimeServiceHandle handle, ContentHandle contentHandle, int maxLines) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets at most maxLines lines from the request log, continuing from the last call to this method.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous call to openLogContent or openOutputContent.
      maxLines - maximum number of lines to get.
      Returns:
      array of lines from the log without line terminators; if no more lines, array will be empty.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • getTextContent

      char[] getTextContent(RuntimeServiceHandle handle, ContentHandle contentHandle, int maxChars) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets at most maxChars lines from the log or output text content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous call to openLogContent or openOutputContent.
      maxChars - maximum number of characters to get.
      Returns:
      array of uninterpreted characters from the log.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • getTextContent

      char[] getTextContent(RuntimeServiceHandle handle, ContentHandle contentHandle, int maxChars, boolean lockRow) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets at most maxChars lines from the log or output text content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous call to openLogContent or openOutputContent.
      maxChars - maximum number of characters to get.
      lockRow - the row will be locked if true.
      Returns:
      array of uninterpreted characters from the log.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • copyTextContentToFile

      boolean copyTextContentToFile(RuntimeServiceHandle handle, ContentHandle contentHandle, File file, boolean lockRow) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Copy log or output text content of the given request to file.
      Parameters:
      handle - runtime service handle
      contentHandle - content handle from previous open call.
      file - File to which content has to be copied.
      lockRow - the row will be locked if true.
      Returns:
      boolean true if copy is successful, else false.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found.

    • getBinaryContent

      byte[] getBinaryContent(RuntimeServiceHandle handle, ContentHandle contentHandle, int maxBytes) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets at most maxBytes bytes from the binary content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous open call.
      maxBytes - maximum number of bytes to get.
      Returns:
      array of bytes from the content.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • getBinaryContent

      byte[] getBinaryContent(RuntimeServiceHandle handle, ContentHandle contentHandle, int maxBytes, boolean lockRow) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets at most maxBytes bytes from the binary content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous open call.
      maxBytes - maximum number of bytes to get.
      lockRow - the row will be locked if true.
      Returns:
      array of bytes from the content.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • copyBinaryContentToFile

      boolean copyBinaryContentToFile(RuntimeServiceHandle rsh, ContentHandle handle, File file, boolean lockRow) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Copy binary content of the given request to file.
      Parameters:
      rsh - runtime service handle
      handle - content handle from previous open call.
      file - File to which content has to be copied.
      lockRow - the row will be locked if true.
      Returns:
      boolean true if copy is successful, else false.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if error accessing runtime store.
      RequestNotFoundException

    • closeContent

      void closeContent(RuntimeServiceHandle handle, ContentHandle contentHandle) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Closes the previously opened log or output content and releases the handle.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous call to openLogContent or openOutputContent.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • outputContentExists

      boolean outputContentExists(RequestExecutionContext context, String contentName) throws RuntimeServiceException, RequestNotFoundException
      Determines if the output content exists for the request.
      Parameters:
      context - request execution context passed to the job executable.
      contentName - name of output content.
      Returns:
      true if the content exists; false if the content does not exist.
      Throws:
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • deleteOutputContent

      void deleteOutputContent(RequestExecutionContext context, List<String> contentNames) throws RuntimeServiceException, RequestNotFoundException
      Deletes the list of request output content from the content store, if it exists. This can delete all output content for the request, including content that was created with the API or that was imported.
      Parameters:
      context - request execution context passed to the job executable.
      contentNames - a List<String> of names of output content.
      Throws:
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • isStandaloneEnv

      boolean isStandaloneEnv(RuntimeServiceHandle handle) throws RuntimeServiceException
      Indicates whether the environment is standalone or fusion.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      Returns:
      true if the environment is standalone; false if Fusion.
      Throws:
      RuntimeServiceException - if runtime service sub-system error.

    • getApplicationConfig

      ApplicationConfig getApplicationConfig(RuntimeServiceHandle handle) throws RuntimeServiceException
      Gets the configuration for this application as specified in ess-config.xml and customizations thereof, including default values.

      The configuration parameters specified have not been run through the substitution engine.

      The returned object does not differentiate between properties set directly for this application and ones which have default values as specified in the ESSAPP configuration.

      All authenticated users have permission to read the application configuration, but an anonymous user does not.

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      Returns:
      the configuration for this application
      Throws:
      RuntimeServiceAccessControlException - if a non-authenticated user invokes this operation.
      RuntimeServiceException - if runtime service sub-system error.

    • getExternalJobStatus

      ExternalJobStatus getExternalJobStatus(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Determines the general status of the external job for a request. The main purpose of this method is to return additional information about the request executable that may be currently running if such information is available.

      At present, support is provided for SQL requests that are currently in RUNNING or CANCELLING state. Nothing is returned for other request states or execution types.

      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      requestId - the id of the request
      Returns:
      the external job status. This will be null if no information is available for the specified request.
      Throws:
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.

    • forceCancelAsyncRequest

      void forceCancelAsyncRequest(long requestId) throws RequestNotFoundException, RuntimeServiceException, NotAllowedException
      Complete an asynchronous request with a CANCEL status. The request will be transitioned to CANCELLED state if the prerequisites are met. 1. The caller must make sure the remote job is no longer executing. 2. The request must be waiting for an asynchronous response and be in State.CANCELLING. 3. It must be at least N minutes since the request was put in State.CANCELLING or the last time the job checked in for this request.

      Updatable.onEvent is not invoked during this operation.

      Parameters:
      requestId - the request identifier of the request
      Throws:
      RequestNotFoundException - if the requestId is not found
      RuntimeServiceException - if a RuntimeService subsystem failure occurs.
      NotAllowedException

    • isForceCancelAllowed

      boolean isForceCancelAllowed(long requestId) throws RequestNotFoundException, RuntimeServiceException
      Check whether the prerequisites for forcing a request to State.CANCELLED using forceCancelAsyncRequest are met.

      The checks do NOT include verification that the job request is no longer executing. That check must be done manually.

      Parameters:
      requestId - the request identifier of the request
      Returns:
      true if the prerequisites have been met, false otherwise.
      Throws:
      RequestNotFoundException - if requestId is not found
      RuntimeServiceException - if a RuntimeService subsystem failure occurs.

    • getQuiesceState

      oracle.as.scheduler.runtime.ServerQuiesceState getQuiesceState(MetadataObjectId jobDefinition) throws MetadataServiceException, MetadataNotFoundException, RuntimeServiceException, ValidationException
      Get quiesce state of ESS Cluster associated with a specified job definition.

      This API maps the specified JobDefinition to its ProcessGroup and then determines the instance quiesce states for the ProcessGroup. If instances are in the same Quiesce state, it returns that Quiesce state, else throws appropriate exception.

      Parameters:
      jobDefinition - MetadataObjectId of JobDefinition
      Returns:
      ServerQuiesceState
      Throws:
      MetadataServiceException - if a MetadataService subsystem failure occurs
      MetadataNotFoundException - if jobDefinition metadata is not found
      RuntimeServiceException - if a RuntimeService subsystem failure occurs
      ValidationException - if jobDefinition does not specify a valid job definition

    • cancelRequestGraceful

      void cancelRequestGraceful(RuntimeServiceHandle handle, long requestId) throws IllegalStateException, RequestNotFoundException, RuntimeServiceException
      Cancels the processing of a request that is not in a terminal state. This is a soft or graceful cancel, which does not automatically kill PL/SQL or spawned jobs.

      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.

      A graceful cancel does not automatically kill PL/SQL or spawned jobs, but puts them in CANCELLING state. The jobs should poll for this state and exit accordingly.

      A graceful cancel is identical to a "hard" cancel for Java jobs. See cancelRequest(oracle.as.scheduler.RuntimeServiceHandle, long).

      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.

    • getRequestDiagnosis

      oracle.as.scheduler.Diagnosis getRequestDiagnosis(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Gets the diagnosis for a request which includes the request State and for requests in WAIT or READY state, additional diagnostic information.

      This may be an expensive operation for requests in READY state.

      Parameters:
      handle - runtime service handle
      requestId - request identifier
      Throws:
      RequestNotFoundException
      RuntimeServiceException - if a RuntimeService subsystem failure occurs

    • getRequestDetailstoExport

      RequestDetail[] getRequestDetailstoExport(RuntimeServiceHandle handle, Filter filter, RuntimeService.QueryField orderBy, boolean ascending, int maxCount, boolean counterInfo) throws ValidationException, RuntimeServiceException
      Retrieves runtime details 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);
      The RequestDetails returned by this method includes only the information which are required to export as CSV file.

      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.
      maxCount - count number of results to return. A value of 0 indicates all results should be returned.
      counterInfo - true if job monitoring and counter information needs to be included
      Throws:
      ValidationException - if filter parameter validation fails.
      RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

    • getReadyRequestsCount

      Integer getReadyRequestsCount() throws RuntimeServiceException
      Return the count of requests in Ready state in current isolation group at this moment
      Returns:
      count of requests in ready state
      Throws:
      RuntimeServiceException - wrapped exception

    • getRequestRank

      Integer getRequestRank(Long requestId) throws RequestNotFoundException, ValidationException, RuntimeServiceException
      Get the rank or position for a given request among the requests of same state. Supported states are WAIT and READY. The rank is computed as per the decending priority first and then the ascending time of requests moved into that pertinent state The returned rank is approximate and there's no guarantee that the job would get executed in the same order
      Parameters:
      requestId - long value of requestId
      Returns:
      integer rank among the requests of same state
      Throws:
      RequestNotFoundException - if request is not found
      ValidationException - if the state of the request is inappropriate
      RuntimeServiceException - wrapped exception

    • getJobStepRequestParameters

      Map<String,RequestParameters> getJobStepRequestParameters(RuntimeServiceHandle handle, long jobsetId) throws RequestNotFoundException, RuntimeServiceException
      Get the Map of scoped parameters for a jobset requestId. Map will have an entry for each stepId and value as its associated parameters. For non jobset requestId, it will return an empty map.
      Parameters:
      handle - the runtime handle instance returned from a prior open call.
      jobsetId - Request Id of a JobSet
      Returns:
      Map of key as string and value as RequestParameters Each scope(step) will have an entry in the Map.
      Throws:
      RequestNotFoundException - if request is not found
      RuntimeServiceException - if a RuntimeService subsystem failure occurs or handle is null

    • changeRequestPriority

      void changeRequestPriority(Long requestId, Integer priority) throws RequestNotFoundException, ValidationException, RuntimeServiceException
      Changes the priority for a submitted request that has not yet started to run. The new priority will be used for subsequent processing of the request.

      This can be used to change the priority for a request that is in WAIT, READY, HOLD state.

      The request priority will be changed even if it is read-only parameter for the request and normally not subject to be changed by the user.

      Parameters:
      requestId - the request identifier of the target request
      priority - the new request priority value. Value can range from zero (highest) to nine (lowest).
      Throws:
      ValidationException - if a validation error occurs. For example, if the priority is not valid; or the request that cannot be changed due to it being in an unsupported state for the operation.
      RequestNotFoundException - if the request was not found.
      RuntimeServiceException - if a RuntimeService subsystem failure occurs

    • isRequestPriorityChangeable

      boolean isRequestPriorityChangeable(Long requestId)
      Returns whether the priority of this request is changeable The request priority will be changeable when the logged user is belonging to ESSAdmin administrator role
      Parameters:
      requestId - the request identifier of the target request
      Returns:
      true if the prerequisites have been met, false if prerequisites were not met or during exception

    • getBlockedRequests

      List<Long> getBlockedRequests(RuntimeServiceHandle handle, long requestId) throws RequestNotFoundException, RuntimeServiceException
      Returns the request identifiers for all requests that are currently blocked by the specified request.
      Parameters:
      handle - the runtime service handle to use
      requestId - the target request id for this operation
      Returns:
      a list of all the requests currently blocked by requestId. This will be null if no requests are currently blocked by the target request.
      Throws:
      RequestNotFoundException - if target request was not found.
      RuntimeServiceException - if runtime service error

    • getJobIncompatibilities

      List<Incompatibility> getJobIncompatibilities(RuntimeServiceHandle handle, MetadataObjectId metaId, long requestId) throws MetadataNotFoundException, RuntimeServiceException
      Gets incompatibilities for a job/jobset definition from the the runtime metadata store.
      Parameters:
      handle - runtime handle
      metaId - the job/jobset metadata object id
      requestId - the absolute parent request for which the metadata was persisted
      Returns:
      list of incompatibilities for the job/jobset. This will be null if there are no incompatibilities.
      Throws:
      MetadataNotFoundException - If the job/jobset metadata was not found in the runtime store.
      RuntimeServiceException - If a runtime error occurred during processing.

    • getRequestsCountGroupByState

      Map<State,Integer> getRequestsCountGroupByState(String effectiveApplication, TimeUnit timeUnit, int timeUnitValue) throws RuntimeServiceException
      Gets number of requests in each state from the elapsed time.
      Parameters:
      effectiveApplication - - the effective application against this api is executed. Default value 'EssNativeHostingApp' if this is passed as null.
      timeUnit - - the time unit, supported values are TimeUnit.DAYS, TimeUnit.HOURS, TimeUnit.MINUTES. This method does not support TimeUnit.SECONDS, TimeUnit.MILLISECONDS, TimeUnit.MICROSECONDS, TimeUnit.NANOSECONDS
      timeUnitValue - - The associated TimeUnit value, i.e., the elapsed time after which to fetch the data. Default to 'Now - 15 minutes' if TimeUnit is not set or set to TimeUnit.SECONDS, TimeUnit.MILLISECONDS, TimeUnit.MICROSECONDS, TimeUnit.NANOSECONDS
      Returns:
      Map containing State as key and number of records in that state as Integer value
      Throws:
      RuntimeServiceException - If a runtime error occurred during processing

    • setExternalJobState

      void setExternalJobState(RuntimeServiceHandle handle, long requestID, ExternalJobState externalJobState) throws RequestNotFoundException, RuntimeServiceException, ValidationException
      Saves External state value for a JAVA BIP job type in request property.
      Parameters:
      handle - runtime handle
      requestID - request for which the data needs to be persisted.
      externalJobState - ExternalState enum value to be saved.
      Throws:
      RequestNotFoundException - If the request was not found in runtime store.
      RuntimeServiceException - If a runtime error occurred.
      ValidationException - If the request failed.

    • getTextContentLob

      Clob getTextContentLob(RuntimeServiceHandle handle, ContentHandle contentHandle) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets text content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous call to openLogContent or openOutputContent.
      Returns:
      Clob of uninterpreted characters from the log.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RuntimeServiceException - if runtime service sub-system error.
      RequestNotFoundException - if the request was not found

    • getBinaryContentLob

      Blob getBinaryContentLob(RuntimeServiceHandle handle, ContentHandle contentHandle) throws IllegalArgumentException, RuntimeServiceException, RequestNotFoundException
      Gets the binary content.
      Parameters:
      handle - runtime service handle.
      contentHandle - content handle from previous open call.
      Returns:
      Blob of bytes from the content.
      Throws:
      IllegalArgumentException - if handle is invalid.
      RequestNotFoundException - if the request was not found
      RuntimeServiceException - if runtime service sub-system error.