10 Incorporating Java and J2EE Code in BPEL Processes

You can embed sections of Java code into a BPEL process.

This chapter contains the following topics:

Use Case for Incorporating Java and J2EE Code BPEL Processes
Overview of Java and J2EE Code in BPEL Concepts
Using Java Embedding in JDeveloper BPEL Designer
Summary

10.1 Use Case for Incorporating Java and J2EE Code BPEL Processes

This use case demonstrates how you can invoke a session bean from within a BPEL process. In this sample, you design the BPEL process so that it picks up a Social Security number from the payload, and then use a Java embedding activity to invoke the session bean (called CreditRating) by using the Social Security number (called ssn) as a parameter. The CreditRating session bean then returns the credit rating for the given Social Security number.

See Also:

The following examples:

C:\orabpel\samples\tutorials\111.CallingSessionBeans (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\samples\tutorials\111.CallingSessionBeans\SessionBeanSample.bpel (for JDeveloper BPEL Designer)

10.2 Overview of Java and J2EE Code in BPEL Concepts

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:

Using Java Code with WSIF Binding
Using Java Code Wrapped as a SOAP Service
Directly Embedding Java Code in a BPEL Process

10.2.1 Using Java Code with WSIF Binding

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:

It has less tool support than SOAP services (described next).
It has less interoperability, because each application server needs a specific binding.

Currently, you must write the binding manually.

See Also:

C:\orabpel\samples\tutorials\702.Bindings for Eclipse BPEL Designer or Oracle_Home\integration\orabpel\samples\tutorials\702.Bindings for JDeveloper BPEL Designer for examples of WSIF bindings for EJB, HTTP, and Java. Bindings must be written to match the application server.
C:\orabpel\samples\demos\BankTransferDemo\BankTransferFlow (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\samples\demos\BankTransferDemo\BankTransferFlow (for JDeveloper BPEL Designer)

10.2.2 Using Java Code Wrapped as a SOAP Service

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).

10.2.3 Directly Embedding Java Code in a BPEL Process

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.

10.2.3.1 Using the bpelx:exec Tag to Embed Java Code Snippets into a BPEL Process

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, the 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>

See Also:

C:\orabpel\samples\tutorials\111.CallingSessionBeans (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\samples\tutorials\111.CallingSessionBeans (for JDeveloper BPEL Designer)

10.2.3.2 Using an XML Facade to Simplify DOM Manipulation

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). 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:

c:\orabpel\bin (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\bin (for JDeveloper BPEL Designer

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:

c:\orabpel\samples\tutorials\702.Bindings\JavaBinding (for Eclipse BPEL Designer)
Oracle_Home\integration\orabpel\samples\tutorials\702.Bindings\JavaBinding (for JDeveloper BPEL Designer)

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"

10.2.3.3 bpelx:exec Built-in Methods

Table 10-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 10-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)`

10.3 Using Java Embedding in JDeveloper BPEL Designer

In JDeveloper BPEL Designer, 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 dialog box.
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:

Description of the illustration java4.gif

See Also:

"Java Embedding Activity" for additional details about this activity, including adding JAR files to classpaths.

10.4 Summary

This 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.