|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
 Previous |
 Next |
|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-02 |
|
|
Previous |
Next |
This chapter shows how a JAVA or a JSP application can call a BPEL process to perform functions or use services.
This chapter contains the following topics:
In this chapter's use case, you learn how to invoke synchronous and asynchronous BPEL processes through either the simple object access protocol (SOAP) or Java. The BPEL process accepts a social security number and sends a credit rating in return. The user Web interface is provided by a JSP file, which takes the input and passes it to a BPEL process to get back a credit rating.
|
See Also: The following sample files:
|
This chapter shows how a JAVA or a JSP application can call a BPEL process to perform functions or use services. A BPEL process is itself a Web service, defining and supporting a client interface through WSDL and SOAP. However, you can make BPEL processes deployed on Oracle BPEL Process Manager available to clients through a Java API.
You can invoke a BPEL process as a Web service through a WSDL or SOAP interface, or as a Java component through its client Java interface. The application puts the request in the form of a payload that then goes to the BPEL process. The BPEL process receives the payload and responds with a payload containing the information that the application requested.
illustrates how an application interacts with a BPEL process through a client partner link, using one of a number of possible protocols.
Figure 12-1 Application Interaction with a BPEL Process
You can invoke a BPEL process by using a generic Java API. Oracle provides classes that enable your BPEL process to use a generic Java API to connect to Oracle BPEL Process Manager and to pass XML messages through a generic Java API. You can use these classes to perform either two-way or one-way invoke operations.
This section covers the following topics:
Oracle provides a com.oracle.bpel.client.Locator class that supports a flexible client interface without being affected by server clustering and other production details. Use this class to do the following:
Connect to Oracle BPEL Process Manager, authenticating if required
Obtain handles to services provided by Oracle BPEL Server
For example, the Locator class can connect to the default domain on a local Oracle BPEL Process Manager and fetch a list of BPEL processes deployed on that server. In this case, the Locator class returns a handle to a com.oracle.bpel.client.dispatch.IDeliveryService instance.
The following instance can invoke or initiate BPEL processes on Oracle BPEL Server:
import com.oracle.bpel.client.Locator;
import com.oracle.bpel.client.dispatch.IDeliveryService;
// Connect to domain ÒdefaultÓ using password ÒbpelÓ
// null IP address means local server
Locator locator = new Locator("default", "bpel", null);
IDeliveryService deliveryService = (IDeliveryService)locator.lookupService
(IDeliveryService.SERVICE_NAME );
Because all Web services, including BPEL processes, accept and return XML messages, any Java API using Web services needs a way to pass XML data through Java. You can use the Oracle BPEL Process Manager client class com.oracle.bpel.client.NormalizedMessage to activate an XML message dynamically.
For example, to activate an input message for the CreditRatingService from static string XML data, you can use the following code:
import com.oracle.bpel.client.NormalizedMessage;
String xml =
"<ssn xmlns=\"http://services.otn.com\">123456789</ssn>";
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload", xml );
In practice, you activate NormalizedMessages more dynamically. For full documentation of the NormalizedMessage class, see the Oracle BPEL Process Manager Javadocs in:
C:\orabpel\docs\apidocs (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\docs\apidocs (for JDeveloper BPEL Designer)
Once a delivery service has been instantiated, it can initiate a BPEL process with a NormalizedMessage XML message. You can use one of the IDeliveryService.request() methods to invoke a two-way Web service operation, which has an input message and returns a result synchronously.
The IDeliveryService.request() method is overloaded. To find out more about its available versions, refer to the Oracle BPEL Process Manager Javadoc. In this version, the request() method has the following signature:
public NormalizedMessage request(java.lang.String processId,
java.lang.String operationName,
NormalizedMessage message)
throws java.rmi.RemoteException
The following code example (provided with the Oracle BPEL Process Manager samples) demonstrates how to use this API to invoke the CreditRatingService BPEL process.
<%@page import="java.util.Map" %>
<%@page import="com.oracle.bpel.client.Locator" %>
<%@page import="com.oracle.bpel.client.NormalizedMessage" %>
<%@page import="com.oracle.bpel.client.dispatch.IDeliveryService" %>
<html>
<head>
<title>Invoke CreditRatingService</title>
</head>
<body>
<%
String ssn = request.getParameter("ssn");
if(ssn == null)
ssn = "123-12-1234";
String xml = "<ssn xmlns=\"http://services.otn.com\">"
+ ssn + "</ssn>";
Locator locator = new Locator("default","bpel",null);
IDeliveryService deliveryService =
(IDeliveryService)locator.lookupService
(IDeliveryService.SERVICE_NAME );
// construct the normalized message and send to oracle bpel process
manager
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload", xml );
NormalizedMessage res =
deliveryService.request("CreditRatingService", "process", nm);
Map payload = res.getPayload();
out.println( "BPELProcess CreditRatingService executed!<br>" );
out.println( "Credit Rating is " + payload.get("payload") );
%>
|
See Also: The following samples:
|
A one-way invoke operation has only an input message and does not return a result. The procedure for invoking a one-way BPEL operation through the Java API is very similar to how you invoke two-way operations. The difference is that you use the IDeliveryService.post() method instead of IDeliveryService.request(). This method is overloaded; its methods invoke a one-way operation on a BPEL process and thus return void because a response is not expected (at least not a synchronous response).
From the Javadoc for com.oracle.bpel.client.dispatch.IDeliveryService:
public void post(java.lang.String processId,
java.lang.String operationName,
NormalizedMessage message)
throws java.rmi.RemoteException
In the following example, the post() method is very similar to the request() method shown in the two-way example discussed earlier, except that it returns void.
<%@page import="com.oracle.bpel.client.Locator" %>
<%@page import="com.oracle.bpel.client.NormalizedMessage" %>
<%@page import="com.oracle.bpel.client.dispatch.IDeliveryService" %>
...
Locator locator = new Locator("default", "bpel", null);
...
NormalizedMessage nm = new NormalizedMessage( );
nm.addPart("payload" , xml );
deliveryService.post("HelloWorld", "initiate", nm);
out.println( "BPELProcess HelloWorld initiated!" );
%>
|
See Also: The following samples:
|
If you use the Java API to initiate an asynchronous BPEL process, you must often consider how to receive the result of the process, because a typical Java client cannot be called back the same way as a Web service. You can handle this problem by using the following strategies:
Have your code inform users of the progress of the process. For example, the LoanFlowPlus BPEL demonstration application (located in C:\orabpel\samples\demos\LoanDemoPlus for Eclipse BPEL Designer or Oracle_Home\integration\orabpel\samples\demos\LoanDemoPlus for JDeveloper BPEL Designer) informs users of the progress through a user task, such as manually approving the final loan offer. You also can have the process send some sort of notification, such as an e-mail message or a JMS message, when it completes.
For asynchronous BPEL processes, have the Java client poll the result. In this case, the client needs a handle to fetch status information for a particular instance. The post() method does not automatically return such a handle, but it does allow the client to specify a conversation ID. This ID can be any unique identifier that the client can later use to identify a specific instance and retrieve status information for it. See the Oracle BPEL Javadocs for the com.oracle.bpel.client.NormalizedMessage class to find the specific field name for the conversation ID and other properties, which you can set at the time a BPEL process is instantiated through the Java API. You can also use the com.oracle.bpel.client.Locator.lookupInstance(String key) method to locate a specific instance based on a conversation ID.
You also can use the NormalizedMessage properties to specify the address of a Web service for the callback. This initiates an asynchronous BPEL process from Java, but receives a SOAP/XML callback to a Web service listener.
It is also possible using the supported NormalizedMessage properties to specify the address of a Web service for the callback and therefore initiate an asynchronous BPEL process from Java, but receive a SOAP/XML callback to a Web service listener.Contact Oracle Support Services for more information on how to retrieve status or results from an asynchronous BPEL process in your specific environment.
|
See Also: The following samples for examples of how to send e-mail or JMS messages from BPEL processes:If you are using Eclipse BPEL Designer:
If you are using JDeveloper BPEL Designer:
|
The code examples described in previous sections are executed within the same application server container in which the Oracle BPEL Process Manager is running. You can run these APIs from a remote client, however, and use them through a remote method invocation (RMI) from a remote application server. The RMI client code you use depends on the application server in which the client is running. Work with Oracle Support Services regarding how to use the Oracle BPEL Process Manager Java API over RMI for your specific client configuration and environment.
After you deploy a BPEL process to Oracle BPEL Server, it is automatically published as a Web service. This means that the process can be accessed through its XML/SOAP/WSDL interface without any additional developer effort. Supporting a standard Web services interface means that BPEL processes can be invoked from any client technology that supports Web services. This includes Microsoft .NET, Sun's JAX-RPC implementation, Apache Axis, Oracle JDeveloper, and many other Web services tool kits. In addition, it means that BPEL and Oracle BPEL Process Manager can publish Web services. Those services, both synchronous and asynchronous, can be invoked from applications and services implemented with nearly any technology and language.
You access a BPEL process through its Web service interface in the standard way you access any Web service: by writing a client that uses the BPEL process WSDL interface definition and SOAP as a protocol.
Once deployed, a BPEL process is exposed through both a WSDL or SOAP interface and a business delegate Java interface. The Java business delegate interface allows Java and JSP applications to initiate new instances of a BPEL process.The Java business delegate can be used locally or remotely using RMI. The Java business delegate is JTA-aware, allowing the initiation of a process to be part of a broader transaction.
