Oracle Enterprise Scheduler exposes the runtime service to your application program as a Stateless Session Enterprise Java Bean (EJB). You can use JNDI to locate the Oracle Enterprise Scheduler runtime service Stateless Session EJB.

Example 19-1 shows a lookup for the Oracle Enterprise Scheduler runtime service using the RuntimeServiceLocalHome object.

import oracle.as.scheduler.core.JndiUtil;
// Demonstration of how to lookup runtime service from a
// Java EE application component
    
    RuntimeService runtime = JndiUtil.getRuntimeServiceEJB();
    RuntimeServiceHandle rHandle = null;
    .
    .
    .
    try
    {
         ...
         rHandle = runtime.open();
         ...
    }
    finally
    {
        if (rHandle != null)
        {
            runtime.close(rHandle);
        }
    }

When you create a job request Oracle Enterprise Scheduler resolves and stores the properties associated with the job request. Certain system properties can be associated with a job request. If you do not set these properties anywhere in the properties hierarchy when a job request is submitted, then Oracle Enterprise Scheduler provides default values.

Table 19-1 shows the default runtime service field names and the corresponding system properties.

Oracle Enterprise Scheduler associates a DMS ECID and FlowId value with every request. Oracle Enterprise Scheduler usually obtains the ECID and FlowId from the current DMS execution context, if present, at request submission and uses that ECID and FlowId value during subsequent processing of the request. For example, Oracle Enterprise Scheduler sets up a DMS execution context that associates the ECID and FlowId with the request when it initiates the job executable.

If a DMS FlowId property is not present in the DMS execution context at request submission, then a new FlowId is associated with the request. For example, if the request is not submitted by SOA, there might not be a FlowId present on the DMS execution context and Oracle Enterprise Scheduler associates a new FlowId with the request.

If no DMS execution context is present at request submission, then a new ECID and new FlowId are associated with the request. For example, if a request is submitted using the Oracle Enterprise Scheduler PL/SQL interface, there might be no DMS context information available from the database session when the PL/SQL submit procedure is called. A new ECID and new FlowId are associated with the request after it is successfully validated by the Oracle Enterprise Scheduler mid-tier.

Using the runtime service, with a requestID, you can obtain information about a job request that is in the system. Table 19-2 shows the runtime service methods that allow you to obtain job request information.

Example 19-3 shows code that determines if there is any immediate child request in the HOLD state.

        h = s_runtime.open();
        try {
 
            s_runtime.holdRequest(h,reqid);
 
            Enumeration  e = s_runtime.getRequests(h, reqid);
 
            boolean foundHold = false;
            while (e.hasMoreElements()) {
 
                long childid = ((Long)e.nextElement()).longValue();
                State state = s_runtime.getRequestState(h,childid);
                if (state == State.HOLD) {
                    foundHold = true;
                    break;
                }
            }

Using the runtime service, with a requestID, you can change the state of a job request. Table 19-3 shows the runtime service job request state change methods. The job request management methods allow you to change the state of a request, depending on the state of the job request. For example, you cannot cancel a request with cancelRequest() if the request is in the COMPLETED state.

Example 19-4 shows a submitRequest() with methods that control the state of the job request. The holdRequest() holds the processing of the job request. The corresponding releaseRequest() releases the request. This example does not show the conditions that require the hold for the request.

rHandle = runtime.open();
try 
{
            runtime.holdRequest(rHandle,reqid);
.
.
.
            runtime.releaseRequest(rHandle, reqid);
.
.
.
}
finally
{
        if (rHandle != null)
        {
            runtime.close(rHandle);
        }
 }

Using the runtime service you can update job request system properties or request parameters. Table 19-4 shows the runtime service methods that allow you to lock and update up a job request.

Example 19-5 shows code that updates a job request parameter. This code would be wrapped in a try/finally block as shown in Example 19-1.

Example 19-5 shows the following:

• Obtain the runtime service handle, rhandle, as shown in Example 19-1.

• Acquire a lock for either the request using lockRequest()

• Perform the update operation with setRequestParameter()

• Use close() to cause the transaction to be committed or rolled back (undone). The close() not only controls the transactional behavior within the runtime service, but it also allows Oracle Enterprise Scheduler to release the resources associated with the RuntimeServiceHandle.

...
  s_runtime.lockRequest(rhandle, reqid);
  s_runtime.setRequestParameter(rhandle, reqId, paramName, "yy");
...

The ad hoc submitRequest() returns the request identifier for the request. You can use this request identifier with runtime calls such as setRequestParameter() or getRequestDetail() as you would with any other job request.

There is only one submitRequest signature that creates a request with an ad hoc job definition. The job definition ID, obtained from RequestDetail.getJobDefn(), is null in this case. Without an ad hoc job definition, a request cannot be considered ad hoc.

If you want to define a schedule to use with an ad hoc request and you want to specify exclusion dates, you need to exclude the dates using the addExclusionDate() method for the schedule. For ad hoc requests, you cannot use a schedule that specifies exclusion dates using addExclusion() method for the schedule.

Currently, if the schedule is ad hoc, a check of ExclusionDefinition is skipped. Thus, if you use a schedule and use addExclusion() and submit an ad hoc job request, then Oracle Enterprise Scheduler does not use the ExclusionsDefinition IDs with the job request.

With a pre-process handler, your code can do things to create an environment for your job to execute. This could include creating connections to resources that your job requires, for example.

The pre-processor is instantiated and invoked at the start of request execution when the request transitions to RUNNING state. This is done each time the request is executed, including when a failed request is retried or a paused request is resumed after its sub-requests have completed.

You create a pre-process handler by implementing the oracle.as.scheduler.PreProcessHandler interface. With your pre-process handler class in hand, you specify that it should be used by setting the SYS_preProcess system property to the fully-qualified name of your handler class. You can define the property on job metadata or include it in the request submission parameters.

With a post-process handler, your code can do things that should take place after your job has executed. This could include releasing connections to resources that your job required, for example, or generating a report based on request-specific data or status.

The post-processor is instantiated and invoked after job execution, when the request transitions to COMPLETED state. The post-processor is invoked only once for a request, in contrast to the pre-processor.

You create a post-process handler by implementing the oracle.as.scheduler.PostProcessHandler interface. With your post-process handler class in hand, you specify that it should be used by setting the SYS_postProcess system property to the fully-qualified name of your handler class. You can define the property on job metadata or include it in the request submission parameters.