| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.3) Part Number E15524-03 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.3) Part Number E15524-03 |
|
|
View PDF |
This chapter describes what a SOA composite application needs to do to invoke an asynchronous service such as an Oracle ADF service or another SOA composite application.
When to implement: A SOA composite application needs to invoke an asynchronous service such as an Oracle ADF service or another SOA composite application.
Design Pattern Summary: A SOA composite is designed with a Mediator or BPEL component that invokes an asynchronous service endpoint, after which goes into a state of rest until the asynchronous endpoint calls back with the response payload.
Involved components:
One SOA composite (Consumer role).
One or more (Producer role) SOA Composites or Oracle ADF Services.
Oracle Fusion web applications often include services with long-running computation that are exposed through service interfaces. When invoking services through a synchronous service interface, the service may not execute as desired due to time outs or lack of resources as a result of blocked, waiting threads. To solve this problem, service are exposed through asynchronous interfaces that wait for a response when invoking long-running services.
The recommended approach to asynchronous invocation is to create an asynchronous SOA composite with a BPEL process that invokes the asynchronous service.
Note:
Per Oracle Fusion Applications standards, a composite that exposes a synchronous interface must not invoke an asynchronous service.
Figure 41-1 illustrates the process flow of BPEL process invoking an asynchronous service.
The client BPEL process invokes an asynchronous service through the WSDL partner link. The service runs as required, and returns a response to the waiting client BPEL process.
Following are alternative, unsupported approaches to the use case.
Invoke services synchronously. This approach is not supported due to time out issues.
Invoke services asynchronously, without registering a callback handler service. This approach is not supported, as a callback handler is required when asynchronously invoking a service.
Invoke a one-way service. This approach is not supported for Oracle ADF services.
Invoke a service asynchronously, registering another service as the callback handler. This approach is not supported. Use business events instead.
Caution:
These approaches are not supported and should not be implemented.
An interface table is populated by third-party entities using legacy interfaces, such as FTP and files. Once the interface table is populated, a periodic Oracle Enterprise Scheduler job runs, checking for new interface table rows. If the job finds new table rows, it raises a business event that initiates a BPEL process. The BPEL process orchestrates any required services such as those used to import and notify users, obtain necessary approvals, and so on.
In this scenario, one or more services or tasks require several minutes or even hours to complete, as is typical among asynchronous service interfaces. The BPEL process invokes the service and enters a dormant state in which the process progress and variable data are stored in the database, which frees memory and thread resources for other BPEL processes. When the long-running service completes, the asynchronous callback revives the process. The BPEL process continues from where it left off.
You can find the sample code for this use case here:
To initiate an asynchronous service from a BPEL process, do the following:
Create a SOA composite with a BPEL process.
Create the service reference to the asynchronous web service you want to invoke.
Populate the BPEL process with scope, invoke, receive, assign and fault-handling activities.
Before defining the service reference, create your composite and BPEL process with the requisite input and output payload types. Figure 41-2 shows an example of a minimalist composite with a new BPEL process.
Defining the service reference to the asynchronous web service endpoint involves the following tasks:
Define the new web service reference.
Wire the BPEL process to the new service reference.
Invoke the asynchronous web service from the BPEL flow.
Deploying and testing the composite.
Define the service that the composite is to invoke.
To define the new web service reference, do the following:
In the composite, define the asynchronous service reference by dragging a Web Service component to the right-hand swim lane of the composite.
The Create Web Service dialog opens.
In the Create Web Service dialog, enter the following information:
Name: Enter the name of the web service reference for this composite.
Type: Select Reference. A Reference is a service that this composite will be invoking.
WSDL URL: Select the full URL to the WSDL of the asynchronous web service to be invoked. Use the service explorer to navigate to and select the WSDL.
Port Type: Select the execute port type of the end point service. This value is often automatically defaulted by the UI. This is the port type invoked by the composite.
Callback Port Type: Select the callback port type of the end point service. This value is often defaulted automatically by the UI. This is the port type used to call back the composite.
Figure 41-3 shows an example of a completed Create Web Service dialog.
In order to invoke a web service, a BPEL process must include a local partner link definition. You can define a partner link in one of two ways.
Define a partner link in the BPEL process editor.
Drag the interface pin from the BPEL process to the service reference.
Defining a partner link involves additional work as compared to the alternative approach of dragging the interface pins. However, when creating a partner link for a web service that has not yet been defined as a service reference in the composite, Oracle JDeveloper automatically creates the composite service reference and wires the BPEL process to that service.
Dragging the interface pin from a component to a service is a quick and easy way to automatically create partner links and other service component integrations, such as wiring a Mediator to a Business Rule component. Wiring components by clicking and dragging automatically generates the metadata files and entries used to support the interaction between the components.
To define a partner link in the BPEL process editor:
In the Composite Editor, double-click the BPEL process component.
In the right-hand swim lane of the BPEL process, right-click the area under Partner Links.
The Create Partner Link dialog displays, as shown in Figure 41-4.
In the Create Partner Link dialog, enter the following information:
Name: Enter the name of the partner link. This defaults to the service name.
WSDL URL: Enter the full URL for the WSDL file of the asynchronous web service to be invoked.
Partner Link Type: Enter the service partner link type. This value is automatically filled in using the service name, as derived from the WSDL referenced in the WSDL URL field.
Partner Role: From the dropdown list, select the ServiceNameProvider role. This is the role of the producer service for which you entered the WSDL.
My Role: From the dropdown list, select the ServiceNameRequester role. This is the role of the BPEL process as the consumer of the asynchronous service.
Alternatively, click and drag the pin from the BPEL component to the service reference.
Hover the mouse over the BPEL component and the input and output icons.
Drag the input and output icons to the matching icons on the service reference component, as shown in Figure 41-5.
By default, an asynchronous BPEL flow contains two activities: the receive activity that starts the process and the invoke activity that initiates the callback response.
Asynchronous services do not throw faults, such that they must always return a valid payload whenever possible. In the event of a business failure at the endpoint service, services should return a payload that contains a failed status.
Invoking the asynchronous web service from the BPEL flow involves the following steps:
Add required resilience and logging.
Add a scope activity to include the asynchronous service invocation and variable assignment activities.
Add fault handlers to trap any system failures that may occur during any activities within a scope, so as to permit logging, incident creation and error management as required by the use case. Asynchronous services do not throw WSDL-defined faults, necessitating a fault handler.
Add logging. All BPEL processes within Oracle Fusion web applications are required to implement translatable, tokenized, message-level logging for fault-handling scenarios.
Invoke the service.
Add invoke, receive and assign activities.
Invoke: This activity defines the partner link and invoke operation, and defines the BPEL variable containing the payload to be submitted.
Receive: This activity defines the partner link and operation to be invoked, and defines the variable to store the response payload when the asynchronous callback is made.
Assign (1): The first assign activity copies BPEL process input data, XML fragments and XPath expression results to the payload that is sent to the asynchronous service.
Assign (2): The second assign activity copies the contents of the asynchronous response payload to the BPEL output variable, which is then sent back to the calling process.
To invoke the asynchronous web service from the BPEL flow:
To adhere to Oracle Fusion Applications fault handling and logging standards, add the following activities:
Scope: By default, the main BPEL flow is the top-level scope of the process. However, should any of the activities generate a fault within that scope, compensation or recovery options are limited. Leverage nested scopes in order to contain errors and implement resilient functionality.
Fault Handlers: Each nested and top-level scope should have qualified and catch-all fault handlers to catch business- or system-level faults and respond accordingly to the use case.
Logging: Add assign activities as needed. Alternatively, add copy operations to pre-existing assign activities in order to implement logging.
Add a scope activity.
In the Composite Editor, double-click the BPEL component to open the BPEL process editor.
Drag a new scope activity onto the process and name according to the activities it will contain, for example, InvokeAsyncServiceName.
To the scope activity, add the service invocation and variable assignment activities.
Add a catch-all fault handler to trap any errors that may occur during assign, invoke, receive or dehydration activities that may occur within the scope. Use either of the following:
Reply Normally: Returns a payload with an error status and completes in all cases.
Wait State: Sends the asynchronous response, which then sends a user notification or updates an Oracle ADF record, and enters a correlated wait state. The wait state allows another entity to invoke the in-flight process that provides additional instructions.
Implement translatable, tokenized, message-level logging for fault-handling scenarios. Optionally, implement bread crumb logging and incident creation, where applicable to the use case.
Define an invoke activity for the asynchronous web service. In the scope previously defined, drag an Invoke activity to the flow.
Double-click the activity. In the Invoke Activity dialog, enter the following information.
Name: The name of the invoke activity, such as Invoke<ServiceName>.
Interaction Type: Select Partner Link.
Partner Link: Select a partner link from the list of partner links that were previously defined in the BPEL process metadata. To select a partner link, browse through the expanded list of partner links for the asynchronous service defined earlier.
Operation: Select an operation from the list of all the available synchronous and asynchronous operations defined on the web service of the partner link. Be sure to select the relevant asynchronous operation.
Note:
For Oracle ADF Services, the operation names end with Async.
Input: Click the Add button to create a scope-local variable to contain the payload intended for the asynchronous service invocation.
Figure 41-6 shows a completed Invoke Activity dialog.
Define a receive activity to handle the asynchronous callback from the endpoint service, and store the response payload in a variable for use by the process. Drag a receive activity immediately following the invoke activity.
In the Receive Activity dialog, enter the following information.
Name: Enter a name for the invoke activity, such as Invoke<ServiceName>.
Interaction Type: Select Partner Link.
Partner Link: Select a partner link from the list of partner links that were previously defined in the BPEL process metadata. To select a partner link, click the Browse button and browse through the expanded list of partner links for the asynchronous service defined earlier.
Operation: Select an operation from the list of all the available synchronous and asynchronous operations defined on the partner link's web service. Be sure to select the appropriate asynchronous callback operation.
Variable: Click the Add button to define a scope-local variable to contain the payload received from the asynchronous service invocation.
Figure 41-7 shows a completed Receive Activity dialog.
Drag an assign activity onto the flow (within the scope) just above the invoke activity you created earlier. Drag a second assign activity onto the flow just below the receive activity you created earlier.
Name each assign activity.
Double-click the activity, click the General tab and enter a meaningful name such as AssignInputforAsync<ServiceName> or CopyOutputfrom<ServiceName>.
Select the Copy Operation tab and click the Add button to open the Create Copy Operation dialog.
In the Create Copy Operation dialog, select Copy Operation.
Depending on the type of data you want to assign to the invoke input variable, configure the following.
Variable: Select the contents of an element from the source variable, such as the default BPEL inputVariable, as shown in Figure 41-8.
XPath Expression: Enter an XPath expression as required, such as concat($variable1, '-', $variable2), as shown in Figure 41-9.
XML Fragment: A fully namespace-qualified XML document that matches the XML schema structure of the target variable or variable element, as shown in Figure 41-10.
Note:
If you receive an "Invalid XML" error message, ensure that all elements are namespace qualified within the context of the fragment as BPEL process namespaces are not scoped into fragments.
Partner Link: The contents and properties of a Partner Link (useful for dynamic partner links).
Save your files.
Deploy the SOA composite application to the SOA infrastructure. For more information, see "Deploying SOA Composite Applications" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Test the application. For more information, see the chapter "Automating Testing of SOA Composite Applications" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Defining the web service reference generates a local, abstract WSDL (.wsdl) file named after the service for which it was created. This WSDL file contains partner link information used by BPEL, as well as a reference to the asynchronous web service WSDL URL for looking up message type and schema information. Typically, the WSDL file name is the same as the service name, with the suffix .wsdl appended at the end.
At runtime, the following occurs within the BPEL process:
The invoke activity initiates the remote service.
The BPEL process is dehydrated (session and variable data is serialized) to the database.
The process thread is freed such that other potential processes may use it while waiting for the asynchronous service to complete and respond.
To secure this pattern, add the Oracle Web Services Manager policies to both the service endpoint and service reference components in the composite.
For more information, see Chapter 51, "Securing Web Services Use Cases."
To properly test this pattern, deploy this SOA composite to the SOA domain and initiate the composite through the service test client page.
To verify the deployment:
Open a web browser and navigate to the following URL format.
http://host:port/em
Note:
Use the HTTPS protocol instead of HTTP if your server is configured to use SSL.
You will see a list of all successfully deployed composites in this SOA environment.
Click the service endpoint link beneath the name of the deployed composite. This renders the service test client page, which then can be used to enter payload data and invoke the composite.
Enter the payload fields as needed and click Initiate.
Navigate to Oracle Enterprise Manager Fusion Middleware Control Console using the following URL format.
http://host:port/em
Login to Oracle Enterprise Manager Fusion Middleware Control Console and take the following actions.
On the left side of Oracle Enterprise Manager Fusion Middleware Control Console, expand the SOA tree node.
Expand the soa-infra node for the correct SOA server and select the name of the deployed composite.
Click the instance ID link for the most recent instance of this composite. The Flow Trace window displays.
In the Flow Trace window, find the entry for your BPEL process component. Click the BPEL process component to open the Audit Flow view.
The Audit Flow view displays the activities that were executed in the BPEL process, along with payload details that you can view by clicking the activity.
Following are tips that may help resolve common issues that arise when deploying or running this use case.
If failures occur during compilation or deployment, observe the Oracle JDeveloper console and compiler output to resolve any issues.
If deployment is successful but the composite does not display in the soa-infra composites list, check the server's diagnostic log and console output for any exceptions and resolve them.
If faults occur when invoking the composite, the logging activities and fault-handling branches should provide meaningful content in the applications diagnostic log (defined in logging.xml) or be present in the callback payload.
Use the Audit Flow view to diagnose the problem and correct your BPEL process, then redeploy. For more information about using the Audit Flow view, see the deployment steps in Section 41.6, "Verifying the Deployment."
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
