Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
You can embed sections of Java code into a BPEL process.
This chapter contains the following topics:
This chapter explains how you can embed sections of Java code into a BPEL process. This is particularly useful when there is already Java code that can perform the desired function, and you want to use the existing code rather than start over with BPEL.
You can incorporate Java code using any of the following methods:
If the Java application has a BPEL-compatible interface, you either use Web Services Inspection Language (WSIF) binding or wrap the Java code as a SOAP service to use it in a BPEL process.
WSIF binding is the most common way of using Java code in a BPEL process. This method enables a BPEL process to invoke an Enterprise Java Bean through native J2EE protocol (local or remote method invocation (RMI)). With WSIF binding, a section of the WSDL file defines the protocol for communicating between Java and XML. This approach maintains Java's transactionality and does not sacrifice performance. It is also quicker for you to add WSIF binding to an existing Java application rather than starting over in Oracle BPEL Process Manager. However, WSIF binding has the following drawbacks:
Less tool support than SOAP services
Less interoperability, because each application server needs a specific binding
Currently, you must write the binding manually.
Oracle BPEL Process Manager's Java binding implementation is based on the Apache WSIF package's Java binding. Java binding enables a BPEL process to invoke user-defined Java classes.
All data used internally in a BPEL process is of a W3C DOM element. Therefore, data marshalling must be performed between a BPEL process and the user-defined Java classes. Oracle BPEL Process Manager's Java binding implementation currently supports Java classes that use the following data types:
XML simple type
XML complex type using Oracle BPEL Process Manager facade data type
DOM element
Most XML simple types can be mapped to Java types, and vice versa. The data mapping can be defined in the WSDL file using the format
extension. For example, a Java method is defined as follows:
public float getQuote (String symbol) throws Exception;
The format:typeMap
definitions are defined as follows:
<binding name="JavaBinding" type="tns:StockquotePT"> <java:binding/> <format:typeMapping encoding="Java" style="Java"> <format:typeMap typeName="xsd:string" formatType="java.lang.String" /> <format:typeMap typeName="xsd:float" formatType="java.lang.float" /> </format:typeMapping> <operation name="getQuote"> <java:operation methodName="getQuote"/> <input/> <output/> </operation> </binding>
See Also:
SOA_Oracle_Home
\samples\demos\IBMSamples\simple
for a sample of using XML simple typesAn XML facade is an Oracle BPEL Process Manager technology that provides a Java bean-like interface on top of an XML DOM element. Given the XML schemas, facade classes can be generated using the Oracle BPEL Process Manager schemac
tool. In the following example, the classes use XML facade classes in the method:
public CommentsType addComment(CommentsType payload, CommentType comment) throws JavaBindingException;
The WSDL Java binding is defined as follows:
<binding name="JavaBinding" type="tns:HelperService"> <java:binding/> <format:typeMapping encoding="Java" style="Java"> <format:typeMap typeName="tns:commentType" formatType="com.otn.services.CommentType" /> <format:typeMap typeName="tns:commentsType" formatType="com.otn.services.CommentsType" /> </format:typeMapping> <operation name="addComment"> <java:operation methodName="addComment"/> <input/> <output/> <fault name="CommentException"/> </operation> <operation name="testFault"> <java:operation methodName="testFault"/> <input/> <output/> <fault name="CommentException"/> </operation> </binding>
The Java types CommentType
and CommentsType
are XML facade classes.
See Also:
"schemac" for details about the schemac
tool and XML facades
Oracle BPEL Process Manager internally uses an XML DOM element. If a Java binding class uses XML DOM elements, data marshalling is not needed. For example, in the following example, the addComment()
method is defined:
public Element addComment(Element payload, Element comment) throws JavaBindingException;
The Java binding of the WSDL file is defined as follows:
<binding name="JavaBinding2" type="tns:HelperService2"> <java:binding/> <format:typeMapping encoding="Java" style="Java"> format:typeMap typeName="tns:commentType" formatType="org.w3c.dom.Element"/> <format:typeMap typeName="tns:commentsType" formatType="org.w3c.dom.Element"/> </format:typeMapping> <operation name="addComment"> <java:operation methodName="addComment"/> <input/> <output/> <fault name="CommentException"/> </operation> <operation name="testFault"> <java:operation methodName="testFault"/> <input/> <output/> <fault name="CommentException"/> </operation> </binding>
With the Java class using a DOM element type, Java binding can support any XML data type.
As a Web service, a Java binding can throw a fault. The fault can be defined in the WSDL file as a Web service.
<message name="CommentFaultMessage"> <part name="payload" type="tns:commentType"/> </message> <portType name="HelperService2"> <operation name="testFault"> <input message="tns:TestFaultRequestMessage"/> <output message="tns:TestFaultResponseMessage"/> <fault name="CommentException" message="tns:CommentFaultMessage" /> </operation> </portType> <binding name="JavaBinding2" type="tns:HelperService2"> ... <operation name="testFault"> <java:operation methodName="testFault"/> <input/> <output/> <fault name="CommentException"/> </operation> </binding>
To throw a Web service fault, the Java class must declare to throw a predefined fault type com.collaxa.cube.ws.wsif.providers.java.JavaBindingException
or its subclass.
In the following example, the Java file has a function that throws this exception:
public CommentType testFault(CommentType payload) throws JavaBindingException { System.out.println("testFault : " + payload); if (payload != null) { JavaBindingException ex = new JavaBindingException(); ex.setFaultName("CommentException"); ex.setPart("payload", payload); System.out.println(" throwing exception " + ex); throw ex; } else { return payload; } }
In a different Java file, there is a similar function:
public Element testFault(Element payload) throws JavaBindingException { System.out.println("testFault2: " + payload); if (payload != null) { JavaBindingException ex = new JavaBindingException(); ex.setFaultName("CommentException"); ex.setPart("payload", payload); System.out.println(" throwing exception " + ex); throw ex; } else { return payload; } }
If such an exception is thrown from the Java binding class, the BPEL WSIF layer converts it into a Web service exception that can be caught by the BPEL source as follows:
<variables> ...... <variable name="fault" messageType="services:CommentFaultMessage"/> </variables> ...... <faultHandlers> <catch faultName="services:CommentException" faultVariable="fault"> <assign> <copy> <from expression="string('CommentException')"/> <to variable="output" part="payload" query="/types:comments/types:item[1]/types:message"/> </copy> </assign> </catch> <catchAll> <empty/> </catchAll> </faultHandlers>
See Also:
Chapter 8, "Fault Handling" for additional details about faults
SOA_Oracle_Home
\bpel\samples\tutorials\702.Bindings
for examples of WSIF bindings for EJB, HTTP, and Java. Bindings must be written to match the application server.
SOA_Oracle_Home
\bpel\samples\demos\BankTransferDemo\BankTransferFlow
As an alternative to WSIF binding, you can wrap the Java code as a SOAP service. As with WSIF binding, this method requires that the Java application have a BPEL-compatible interface. A Java application wrapped as a SOAP service appears as any other Web service, which can be used by many different kinds of applications. There are also tools available for writing SOAP wrappers.
However, a Java application wrapped as a SOAP service has the following drawbacks:
It loses performance, because interactions are constantly being mapped back and forth between the Java code and the SOAP wrapper.
It loses interoperability, that is, the ability to perform several operations in an all-or-none mode (such as debiting one bank account while crediting another, where either both transactions must be completed, or neither of them).
Another way to use Java in a BPEL process is to embed the code directly into the BPEL process using the Java BPEL exec extension bpelx:exec
. The benefits of this approach are speed and transactionality. However, you can incorporate only fairly small segments of code. If you want to incorporate larger segments of code, or if the project requires the Java code to have the same look and feel throughout all the BPEL processes being created, consider using WSIF binding or wrapping it as a SOAP service.
The BPEL tag bpelx:exec
enables you to embed a snippet of Java code within a BPEL process. The server executes any snippet of Java code contained within a bpelx:exec
activity, within its Java Transaction API (JTA) transaction context.The BPEL tag bpelx:exec
converts Java exceptions into BPEL faults and then adds them into the BPEL process.The Java snippet can propagate its JTA transaction to session and entity beans that it calls.
For example, a SessionBeanSample.bpel
file uses the following bpelx:exec
tag to embed the invokeSessionBean
Java bean:
<bpelx:exec name="invokeSessionBean" language="java" version="1.4"> <![CDATA[ try { Object homeObj = lookup("ejb/session/CreditRating"); Class cls = Class.forName( "com.otn.samples.sessionbean.CreditRatingServiceHome"); CreditRatingServiceHome ratingHome = (CreditRatingServiceHome) PortableRemoteObject.narrow(homeObj,cls); if (ratingHome == null) { addAuditTrailEntry("Failed to lookup 'ejb.session.CreditRating'" + ". Please make sure that the bean has been" + " successfully deployed"); return; } CreditRatingService ratingService = ratingHome.create(); // Retrieve ssn from scope Element ssn = (Element)getVariableData("input","payload","/ssn"); int rating = ratingService.getRating( ssn.getNodeValue() ); addAuditTrailEntry("Rating is: " + rating); setVariableData("output", "payload", "/tns:rating", new Integer(rating)); } catch (NamingException ne) { addAuditTrailEntry(ne); } catch (ClassNotFoundException cnfe) { addAuditTrailEntry(cnfe); } catch (CreateException ce) { addAuditTrailEntry(ce); } catch (RemoteException re) { addAuditTrailEntry(re); } ]]> </bpelx:exec>
You can use an XML facade to simplify DOM manipulation. Oracle BPEL Process Manager provides a lightweight Java Architecture for XML Binding (JAXB)-like Java object model on top of XML (called a facade). An XML facade provides a Java bean-like front end for an XML document or element that has a schema. Facade classes can provide easy manipulation of the XML document and element in Java programs.
You add the XML facade by using a createFacade
method within the bpelx:exec
statement in the .bpel
file. For example:
<bpelx:exec name= ... <![CDATA ... Element element = ... (Element)getVariableData("input","payload","/loanApplication/"): //Create an XMLFacade for the Loan Application Document LoanApplication xmlLoanApp= LoanApplicationFactory.createFacade(element); ...
To generate the facade classes, use the schemac
tool, which is provided with Oracle BPEL Process Manager. You can find the schemac
tool in the following locations:
SOA_Oracle_Home
\bpel\bin
To use schemac
, run a command similar to the following to generate the facades from WSDL or XSD files:
C:\BPEL_project_dir\> schemac *.wsdl /*.xsd
After you run schemac
, it creates a src
folder for a HelperService.java
service and a com
folder for the generated Java classes. Oracle provides a sample in the following directories that showcases the use of facade classes in Java bindings:
SOA_Oracle_Home
\bpel\samples\tutorials\702.Bindings\JavaBinding
When it generates the facade, schemac
uses the following files:
Using build.xml
, schemac
generates the source of the facade classes.
The schemac tool creates a Java binding provider class HelperService.java
, which in the 702.Bindings
example is located under 702.Bindings\JavaBinding\src\com\otn\services
. It has one method, which uses the facade classes CommentsType
and CommentType
:
public CommentsType addComment(CommentsType payload, CommentType comment)
To map the XML types to the corresponding facade classes, a Java binding service is defined in the HelperService.wsdl
file. See the format:typeMapping
section of Java binding:
<format:typeMapping encoding="Java" style="Java"> <format:typeMap typeName="tns:commentType" formatType="com.otn.services.CommentType" /> <format:typeMap typeName="tns:commentsType" formatType="com.otn.services.CommentsType" /> </format:typeMapping>
See Also:
"schemac"Table 9-1 lists a set of bpelx:exec
built-in methods that you can use to read and update scope variables, instance metadata, and audit trails.
Table 9-1 Built in Methods for bpelx:exec
Method Name | Description |
---|---|
Object lookup( String name ) |
JNDI access |
Locator getLocator( ) |
BPEL Process Manager Locator |
long getInstanceId( ) |
Unique ID associated with each instance |
String setTitle( String title ) / String getTitle() |
Title of this instance |
String setStatus( String status ) / String getStatus() |
Status of this instance |
void setIndex( int i, String value ) / String getIndex( int i ) |
Six indexes can be used for search |
void setPriority( int priority ) / int getPriority() |
Priority |
void setCreator( String creator ) / String getCreator() |
Who initiated this instance |
void setCustomKey( String customKey ) / String getCustomKey() |
Second primary key |
void setMetadata( String metadata ) / String getMetadata () |
Metadata for generating lists |
String getPreference( String key ) |
Access preference defined in bpel.xml |
void addAuditTrailEntry(String message, Object detail) |
Add an entry to the audit trail |
void addAuditTrailEntry(Throwable t) |
Access file stored in the suitcase |
Object getVariableData(String name) throws BPELFault |
Access and update variables stored in the scope |
Object getVariableData(String name, String partOrQuery) throws BPELFault |
|
Object getVariableData(String name, String part, String query) |
|
void setVariableData(String name, Object value) |
|
void setVariableData(String name, String part, Object value) |
|
void setVariableData(String name, String part, String query, Object value) |
In Oracle JDeveloper, you can add the bpelx:exec
activity, and copy the code snippet into a dialog box, as follows:
Drag and drop the Java Embedding activity (with the coffee cup icon) from the Component Palette.
Double-click the Java Embedding activity to display the Java Embedding window.
Name the Java Embedding activity.
In the Code Snippet field, enter (or cut and paste) the Java code.
For example, the bpel:exec
code example described under "Using the bpelx:exec Tag to Embed Java Code Snippets into a BPEL Process" appears as follows:
See Also:
"Java Embedding Activity" for additional details about this activity, including adding JAR files to classpathsThis chapter demonstrates how you can embed sections of Java code into a BPEL process using one of the following techniques:
If the Java application has a BPEL-compatible interface, you can use WSIF binding or wrap the Java code in a SOAP service.
You can directly embed the Java code by including an inline code snippet using bpelx:exec
. This snippet is executed within the transaction context of Oracle BPEL Server. This method allows you to propagate that transaction to your own session and entity beans. You can use a set of built-in methods to enable the bpelx:exec
snippet to read and update variables, change instance meta data, and throw faults. To simplify DOM manipulation, use an XML facade.