This chapter includes the following sections:
This pattern is recommended for cases in which an asynchronous scheduled Java job executed by a hosting application must invoke an external asynchronous web service operation (such as a SOA composite or Oracle ADF Business Components service operation) using a Java API for XML Web Services (JAX-WS) client.
A Java job is scheduled to be executed by its Oracle Enterprise Scheduler hosting application. Oracle Enterprise Scheduler runs the job, invoking the asynchronous Java job. The job logic uses a JAX-WS client to invoke an external asynchronous web service operation.
The web service operation executes asynchronously in the background. On completion, the web service sends a response to the Oracle Enterprise Scheduler asynchronous callback web service using a callback message.
Involved components:
Oracle Enterprise Scheduler, which invokes the asynchronous Java job at the scheduled time.
A Fusion hosting application which executes the asynchronous Java job implementation specified by the scheduled job. The Java job implementation runs when Oracle Enterprise Scheduler executes the scheduled job.
An external, asynchronous SOAP-based web service (SOA composite or ADF Business Components service).
Other approaches involve using some form of JAX-WS client or proxy to invoke an external web service operation with custom logic for generating message IDs, correlating callback messages, and so on. Business events can also be used with SOA composites, but not with ADF Business Components or other non-SOA web services.
Following are alternative, unsupported approaches to the use case:
Invoke services asynchronously, without referencing the Oracle Enterprise Scheduler asynchronous callback web service. This approach is not supported, as using a callback handler external to Oracle Enterprise Scheduler involves using a non-standard job completion notification with Oracle Enterprise Scheduler.
Invoke a one-way service. This approach is not supported for Oracle ADF Business Components services.
Using business events to invoke the external web service operation. This approach does not use a direct web service invocation, and will not work for Oracle ADF Business Components web service without using some indirection. This approach is not supported.
WARNING:
These alternative approaches are not supported and should not be implemented.
You can download a sample asynchronous Java job implementation using a JRF JAX-WS client for invoking asynchronous web service operations here.
This pattern describes how to use web service addressing SOAP headers to ensure message ID generation that allows ESS request id correlation like callback message correlation.
The following code shows how to use a JAX-WS client and WS address SOAP headers to invoke an asynchronous web service operation. This code is part of the job logic of an Oracle Enterprise Scheduler asynchronous Java job.
The invoked asynchronous web service must respond with a callback SOAP message to the endpoint address specified in wsa:ReplyTo SOAP header.
The web service can specify the following URI in the wsa:Action header of the callback message, to indicate that the web service execution resulted in an error: http://xmlns.company.com/oracleas/schema/oracle-fault-11_0/Fault
Any other URI in the wsa:Action field of the callback message is regarded as success by the Oracle Enterprise Scheduler asynchronous callback web service).
Example 48-1 Invoking an asynchronous ADF Business Components service
...
// Set up a JAX-WS web service proxy or dispatch.
// The following sample uses a dispatch mode client.
// Similar code can be used for a JAX-WS proxy.
AddressingFeature wsAddressing = new AddressingFeature(true, true);
Dispatch<SOAPMessage> dispatch = dispatchService.createDispatch(
portQName, SOAPMessage.class,
Service.Mode.MESSAGE, wsAddressing);
// Construct SOAP message.
String reqSoapMsg = createSOAPMessageString(wsOp.getRequestMessage());
SOAPMessage dispatchRequest = createSOAPMessage(
jrfMessageFactory, reqSoapMsg);
// Get RequestContext and set up SOAP headers.
Map<String,Object> dispatchRequestContext = dispatch.getRequestContext();
// Initialize SOAPACTION HTTP header.
dispatchRequestContext.put(
BindingProvider.SOAPACTION_USE_PROPERTY, Boolean.TRUE);
dispatchRequestContext.put(
BindingProvider.SOAPACTION_URI_PROPERTY, operation);
// Generate message ID from RequestExecutionContext.
String messageId = reqExecContext.toIdString();
saveExternalId(requestId, messageId);
// Initialize the WS message SOAP header: Action, MessageId, To, ReplyTo.
AddressingHelper.setOutgoingAction(
dispatchRequestContext, operation);
AddressingHelper.setOutgoingMessageId(
dispatchRequestContext, messageId);
AddressingHelper.setOutgoingToAddress(
dispatchRequestContext, endpointURLString);
dispatchRequestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
endpointURLString);
// Configure the wsa:ReplyTo address as the Oracle Enterprise Scheduler Service asynchronous
// callback web service URL.
String callbackAddress = http://essHost:essPort/ess-async/essasynccallback;
AddressingHelper.setOutgoingReplyToAddress(
dispatchRequestContext, callbackAddress);
AddressingHelper.setOutgoingFaultToAddress(
dispatchRequestContext, callbackAddress);
// Configure the relatesTo string as the request EXTERNAL_ID system property value,
// only if this is a follow-on operation such as Cancel.
String relatesTo = getExternalId(reqParams);
AddressingHelper.setOutgoingRelatesToMessageId(
dispatchRequestContext, relatesTo);
// Invoke the proxy or dispatch operation.
dispatch.invokeOneWay(dispatchRequest);
...
// Save the messageId string as an EXTERNAL_ID system property on request using RuntimeService.
protected void saveExternalId(long requestId, String messageId)
throws ExecutionErrorException {
RuntimeService runtime;
RuntimeServiceHandle rsh;
try {
runtime = JndiUtil.getRuntimeServiceEJB();
rsh = runtime.open();
runtime.setRequestParameter (rsh, requestId,
SystemProperty.EXTERNAL_ID, messageId);
}
finally {
if (rsh != null)
runtime.close(rsh);
}
}
protected String getExternalId(RequestParameters params) {
return (String) params.getValue(SystemProperty.EXTERNAL_ID);
}
To secure this pattern, add the Oracle Web Services Manager policies to both the external web service endpoint (ADF Business Components service) and the callback client.
Add corresponding policies to the web service client and service policies subjects associated with the server running Oracle Enterprise Scheduler. The web service client policy is used to invoke the asynchronous web service operation, while the WS-service policy is used by the Oracle Enterprise Scheduler asynchronous callback web service to process callback responses.
For more information, see Securing Web Services Use Cases .
Build and deploy the Oracle Enterprise Scheduler hosting application which invokes the asynchronous Java job definition and job implementation, using Oracle JDeveloper. Ensure that the build and deployment are successful.
Use Oracle Enterprise Manager Fusion Applications Control to verify the job definitions associated with the hosting application. Submit the asynchronous Java job and verify the external asynchronous web service operation invocation.
The following suggestions help resolve issues that may arise when deploying or running this use case.
Deployment
Compile and deploy the application in JDeveloper, and watch the log at the bottom of the window. If the compilation or deployment fails, the failures and suggestions for resolving issues are displayed in the log.
If deployment succeeds, but the Oracle Enterprise Scheduler hosting application does not display in Fusion Applications Control, check the server's diagnostic log and console output for any exceptions, and resolve them.
Runtime
If faults occur when invoking the job, the Oracle Enterprise Scheduler server log and job log messages include information to help resolve any issues.
For diagnosing invoked SOA composites at runtime, you may use the Audit Flow view to diagnose the problem and correct your BPEL process, then redeploy the process.