| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.2) Part Number E10142-02 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.2) Part Number E10142-02 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use the runtime service that provides the APIs for submitting and managing job requests and for querying job request information from the job request history.
This chapter includes the following sections:
Oracle Enterprise Scheduler lets you define and run different job types including: Java classes, PL/SQL procedures, and process job types (forked processes). To run these job types you need to submit a job definition.
You can use the runtime service to perform different types of operations, including:
Submit: These operations let you supply a job definition to Oracle Enterprise Scheduler to create job requests
Manage: These operations allow you to change the state of job requests and to update job requests
Query: These operations let you find the status of job requests and report job request history
Like the metadata service, Oracle Enterprise Scheduler provides a runtime MBean proxy interface.
The runtime service open() method begins each Oracle Enterprise Scheduler runtime service user transaction. In an Oracle Enterprise Scheduler application client you obtain a RuntimeServiceHandle reference that is created by open() and you pass the reference to runtime service methods. The RuntimeServiceHandle reference provides a connection to the runtime service for the client application. In the client application you must explicitly close the runtime service by calling close(). This ends the transaction and causes 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.
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 13-1 shows a lookup for the Oracle Enterprise Scheduler runtime service using the RuntimeServiceLocalHome object.
Example 13-1 JNDI Lookup to Access Oracle Scheduler Runtime Service
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);
}
}
Note:
When you access the runtime service:JndiUtil.getRuntimeServiceEJB() assumes that the RuntimeService EJB has been mapped to the local JNDI location "ess/runtime". This happens automatically in the hosted application's message-driven bean (MDB).
The open() call provides a RuntimeServiceHandle reference. You use this reference with the methods that access the runtime service in your application program.
When you finish using the runtime service you must call close() to release the resources associated with the RuntimeServiceHandle.
When you submit a job definition you create a new job request. You can submit a job request using a job definition that is persisted to a metadata repository, or you can create a job request in an ad hoc manner where the job definition or the schedule is not stored in the metadata repository (for information about ad hoc requests, see Section 13.6, "Submitting Ad Hoc Job Requests").
You create a job request by calling submitRequest(). Depending on your needs, you can create a job request with one of the following formats:
Create a new job request using a job definition stored in the metadata repository, to run once at a specific time.
Create a new job request using a job definition and a schedule, each stored in the metadata repository.
Example 13-2 shows the submitRequest() method that creates a new job request with a job definition that resides in the metadata repository. You can also submit an ad hoc job request where the job definition and schedule are not stored in the metadata repository. For more information, see Section 13.6, "Submitting Ad Hoc Job Requests". You can also submit a sub-request. For more information, see Chapter 14, "Using Subrequests".
Example 13-2 Creating a Job Request with submitRequest()
long requestID = 0L;
MetadataObjectId jobDefnId;
RequestParameters p = new RequestParameters();
p.add(SystemProperty.CLASS_NAME, "demo.jobs.Job");
Calendar start = Calendar.getInstance();
start.add(Calendar.SECOND, startsIn);
requestID =
runtime.submitRequest(r,
"My Java job",
jobDefnId,
start,
p);
Note:
When you submit a job request using the runtime service:You obtain the runtime service handle as shown in Example 13-1.
The runtime service internally uses the metadata service to obtain job definition metadata with the supplied MetadataObjectId, jobDefnId.
When you create a job request Oracle Enterprise Scheduler resolves and stores the properties associated with the job request. Oracle Enterprise Scheduler requires that certain system properties are associated with a job request. If you do not set these required properties anywhere in the properties hierarchy when a job request is submitted, then Oracle Enterprise Scheduler provides default values.
Table 13-1 shows the runtime service field names and the corresponding system properties for the required job request properties.
Table 13-1 Runtime Service Default Value Fields and Corresponding System Properties
| Value | Runtime Service Default Value Field | Corresponding System Property | Description |
|---|---|---|---|
|
0 |
|
|
The default expiration time, in minutes, for a request. The default value is 0 which means the request will never expire. |
|
4 |
|
|
The default system priority associated with a request. |
|
5 |
|
|
The default period, in minutes, in which processing must be postponed by a callout handler that returns |
|
0 |
|
|
The default number of times a failed request will be retried. The default value is 0 which means a failed request is not retried. |
All Oracle Enterprise Scheduler Metadata associated with a job request is persisted in the runtime store at the time of request submission. Persisted metadata objects include job definition, job type, job set, schedule, incompatibility definitions, and exclusion definition. Metadata is stored in the context of a top level request, and each metadata object is uniquely identified by the absolute parent request id and its metadata id. Each unique metadata object is stored only once for a top-level request, even if the definition is used multiple times in the request. This ensures that every child request uses the same definition.
When a request is submitted, all known metadata for the request is persisted. For subrequests, the metadata is not know until the subrequest is submitted, so subrequest metadata is persisted when the subrequest is submitted, after first checking that the metadata object is not already persisted in the runtime store.
Metadata persisted in the runtime store is removed when the absolute parent request is deleted.
After you submit a job request, using the requestID you can do the following:
Get request information
Change the state of the request
Update request parameters
Purge a request
Using the runtime service, with a requestID, you can obtain information about a job request that is in the system. Table 13-2 shows the runtime service methods that allow you to obtain job request information.
Table 13-2 Runtime Service Get Request Methods
| Runtime Service Method | Description |
|---|---|
|
|
Retrieves complete runtime details for the specified request |
|
|
Retrieves basic runtime details of the specified request. The RequestDetail returned by this method includes most of the information as |
|
|
Retrieves the value of a request parameter. |
|
|
Retrieves an enumeration of immediate child request identifiers associated with the specified request |
|
|
Retrieves the current state of the specified request |
Example 13-3 shows code that determines if there is any immediate child request in the HOLD state.
Example 13-3 Determining Whether Any Immediate Child Job Requests Are on Hold
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 13-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.
Table 13-3 Runtime Service Job Request State Methods
| Runtime Service Method | Description |
|---|---|
|
|
Cancels the processing of a request that is not in a terminal state. |
|
|
Marks a request in a terminal state for deletion. |
|
|
Withholds further processing of a request that is in |
|
|
Releases a request from the |
Example 13-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.
Example 13-4 Runtime Service releaseRequest() Usage
rHandle = s_runtime.open();
try {
s_runtime.holdRequest(rHandle,reqid);
Enumeration e = s_runtime.getRequests(rHandle, reqid);
while (e.hasMoreElements()) {
long childid = ((Long)e.nextElement()).longValue();
State state = s_runtime.getRequestState(rHandle,childid);
if (state == State.HOLD) {
foundHold = true;
break;
}
}
.
.
.
s_runtime.releaseRequest(rHandle, reqid);
.
.
.
Note:
Note the following in Example 13-4:You obtain the runtime service handle, rHandle, as shown in Example 13-1.
The holdRequest() places the request in the HOLD state.
You may do some required processing while the request is in the HOLD state.
The releaseRequest() releases the request from the HOLD state.
Using the runtime service you can update job request system properties or request parameters. Table 13-4 shows the runtime service methods that allow you to lock and update up a job request.
Table 13-4 Runtime Service Update Methods
| Runtime Service Method | Description |
|---|---|
|
|
Acquires a lock for the given request. The lock is released when |
|
|
Updates the property value of the specified request subject to the property read-only constraints. |
Example 13-5 shows code that updates a job request parameter. This code would be wrapped in a try/finally block as shown in Example 13-1.
Example 13-5 Sample Runtime Service Parameter Update
... s_runtime.lockRequest(rhandle, reqid); s_runtime.updateRequestParameter(rhandle, reqId, paramName, "yy"); ...
Example 13-5 shows the following:
Obtain the runtime service handle, rhandle, as shown in Example 13-1.
Acquire a lock for either the request using lockRequest()
Perform the update operation with updateRequestParameter()
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.
Using the runtime service you can query job request information. This involves the following steps:
Query for request identifiers and limit results with a filter.
Get request details to provide additional information for each request ID that the query returns.
There is only one query method; the runtime service queryRequests() method returns an enumeration of request IDs that match the query. The queryRequests() method includes a filter argument that contains field, comparator, and value combinations that help select query results. For more information on filters, see Section 4.4.1, "How to Create a Filter".
When you create a filter for a query, you can use any of the field names shown in Table 13-5 when querying the runtime store.
Table 13-5 Query Filter Fields For Querying the Runtime (Defined in Enum RuntimeService.QueryField)
| Name | Description |
|---|---|
|
|
The absolute parent request ID of a request. |
|
|
The application name. |
|
|
Indicates if the job is asynchronous, synchronous or unknown. The value of the field is not set until the request is processed. The field data type is |
|
|
The name of the executable class that processed the request |
|
|
The date and time that Oracle Enterprise Scheduler finished processing the request. This field represents the time the process phase was set to COMPLETED. |
|
|
The job definition ID (Metadata Object ID). |
|
|
The amount of time, in milliseconds, that elapsed while the request was running. |
|
|
The enterprise ID. |
|
|
The request error type. |
|
|
The identifier for an external portion of an Enterprise Scheduler asynchronous Java job. |
|
|
The request ID of the instance parent request. |
|
|
The job type ID (Metadata Object ID). |
|
|
The request description. |
|
|
The parent request ID. |
|
|
The priority of the request. |
|
PROCESS_PHASE |
The process phase of the request. |
|
|
The date and time that the process ended. The |
|
|
The name of the instance that processed the request. |
|
|
The date and time that the process started. The |
|
|
The product name. |
|
|
The amount of time, in milliseconds, a request has been waiting to run since it became READY. |
|
|
The request category specified for the request. |
|
|
The requested end time. |
|
|
The requested start time. |
|
|
The request ID of a submitted request. |
|
REQUESTTYPE |
The type of request (that is, an element of |
|
|
Controls the starting and ending index of the returned results. This field allows users to express result constraints such as "return only results 10 through 20". |
|
|
The retried count associated with a job. This field represents the number of times the job was retried. |
|
|
The schedule ID (Metadata Object ID). |
|
|
The time when the request is scheduled to be executed. |
|
|
The job request state. |
|
|
The submission time of the request. |
|
|
The submitter of the request. |
|
|
The submitter GUID of the request. |
|
|
Indicates whether the job has timed out. |
|
|
The execution type of the request. |
|
|
The name of the user who submitted the request. |
|
|
The amount of time, in milliseconds, a request has been waiting to run. |
|
|
The name of the work assignment that was active when the request was processed. |
Table 13-6 shows the runtime service method for querying job requests and Example 13-6 shows the use of this method.
Table 13-6 Runtime Service Query Methods
| Runtime Query Method | Description |
|---|---|
|
|
Gets a summary of requests. |
Example 13-6 Using queryRequest() Method
Filter filter =
new Filter(RuntimeService.QueryField.DEFINITION.fieldName(),
Filter.Comparator.EQUALS,
m_myJavaSucJobDef.toString())
.and(RuntimeService.QueryField.STATE.fieldName(),
Filter.Comparator.EQUALS,
new Integer(12) );
//
Enumeration requests =
s_runtime.queryRequests(h,
filter,
RuntimeService.QueryField.REQUESTID,
false);
To use an ad hoc request you supply request parameters, a job definition, and optionally a schedule that you create and define without saving it to a metadata repository. An ad hoc request does not require you define the details of a job request in a metadata repository. Thus, ad hoc requests support an abbreviated job request submission process that can occur without using a connection to the metadata repository.
Note:
Ad hoc requests have the following limitation: job sets are not supported with ad hoc requests.To create an ad hoc request you use the ad hoc version of submitRequest(). For the job definition, instead of supplying a job definition MetadataObjectId, you can define the job definition object and use a system property that corresponds to the job type, as shown in Table 13-7.
Table 13-7 Ad Hoc Request Job Definition System Properties for Job Types
| System Property | Description |
|---|---|
|
|
Specifies the Java class to execute (for a Java job type). |
|
|
Specifies the PL/SQL stored procedure to execute (for an SQL job type). |
|
|
Specifies the command line used to invoke an external program for a process job request. |
With one signature of the ad hoc version of submitRequest() you do not need to supply MetadataObjectIds, you can provide the Schedule object as an argument as object instances directly to submitRequest(). Other ad hoc submitRequest() signatures allow you to submit a job request using a job definition from metadata and an instance for the Schedule object.
Example 13-7 shows sample code for an ad hoc request submission that uses a schedule.
Example 13-7 Creating Request Parameters and a Schedule for an Ad Hoc Request
RequestParameters p = new RequestParameters();
String propName = "testProp";
String propValue = "testValue";
p.add(propName, propValue);
p.add(SystemProperty.REQUEST_EXPIRATION, new Integer(10));
p.add(SystemProperty.LISTENER, "test.listener.TestListener");
p.add(SystemProperty.EXECUTE_PAST, "TRUE");
p.add("application", getApplication());
p.add(SystemProperty.CLASS_NAME, "test.job.HelloWorld");
Calendar start = Calendar.getInstance();
start.add(Calendar.SECOND, 5);
Calendar end = (Calendar) start.clone();
end.add(Calendar.SECOND, 5);
Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.SECONDLY,
2,
start,
end);
Schedule schedule = new Schedule("mySchedule",
"Run every 2 sec for 3 times.",
recur);
// adhoc submission, no metadata definitions passed
reqId = s_runtime.submitRequest(h,
"testAdhocJavaWithSchedule",
JobType.ExecutionType.JAVA_TYPE,
schedule,
null,
Calendar.getInstance(),
null,
p);
In this example, note the following ad hoc specific details for the request submission:
The CLASS name is set to define the Java class that runs when Oracle Enterprise Scheduler executes the job request: p.add(SystemProperty.CLASS_NAME, "test.job.HelloWorld");
The submitRequest() includes an argument that specifies the job type: JobType.ExecutionType.JAVA_TYPE.
Specify the Java class, the procedure name, or the command line program to execute when the ad hoc Request is processed by setting one of the system properties shown in Table 13-7.
Call the ad hoc version of submitRequest() specifying the type argument to correspond with the system property you set to define the request. The type you supply must be one of JAVA_TYPE, SQL_TYPE, or PROCESS_TYPE.
As with any job request, set the appropriate system properties to be associated with the job request.
The ad hoc submitRequest() returns the request identifier for the request. You can use this request identifier with runtime calls such as updateRequestParameter() or getRequestDetail() as you would with any other job request.
There is only one submitRequest signature that will create 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.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|