Introduction to Java and Java EE Code in BPEL Processes Embedding Service Data Objects with bpelx:exec

Incorporating Java and Java EE Code in a BPEL Process 13-3 } catch NamingException ne { addAuditTrailEntryne; } catch ClassNotFoundException cnfe { addAuditTrailEntrycnfe; } catch CreateException ce { addAuditTrailEntryce; } catch RemoteException re { addAuditTrailEntryre; } ]] bpelx:exec

13.2.4 How to Embed Java Code Snippets in a BPEL Process in BPEL 2.0

The examples in this chapter focus primarily on how to embed Java code snippets with the bpelx:exec extension. For BPEL projects that support version 2.0 of the BPEL specification, the syntax is slightly different. The bpelx:exec extension and Java code are wrapped in an extensionActivity element. Example 13–2 provides details. Example 13–2 bpelx:exec Extension in BPEL 2.0 extensionActivity bpelx:exec language=java [CDATA[ java code ]] bpelx:exec extensionActivity When you drag a Java Embedding activity into a BPEL process in Oracle BPEL Designer, the extensionActivity element and bpelx:exec tag are automatically added. Example 13–3 shows the import syntax for BPEL 2.0: Example 13–3 Import Syntax in BPEL 2.0 import location=classpackage name importType=http:schemas.oracle.combpelextensionjava Example 13–4 shows a BPEL file with two Java embedding activities for a project that supports BPEL version 2.0. Example 13–4 Java Embedding Activities in a BPEL File for Version 2.0 process name=Test targetNamespace=http:samples.otn.combpel2.0ch10.9 . . . . . . import location=oracle.xml.parser.v2.XMLElement importType=http:schemas.oracle.combpelextensionjava . . . sequence . . . extensionActivity bpelx:exec language=java XMLElement elem = XMLElement getVariableDataoutput, payload; elem.setTextContentset by java exec; bpelx:exec extensionActivity 13-4 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite extensionActivity bpelx:exec language=java [CDATA[XMLElement elem = XMLElement getVariableDataoutput, payload; String t = elem.getTextContent; elem.setTextContentt + , set by java exec 2;]] bpelx:exec extensionActivity . . . sequence process For information on using this activity, see Section 13.4, Using Java Embedding in a BPEL Process in Oracle JDeveloper.

13.2.5 How to Use 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. 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. Example 13–5 provides an example: Example 13–5 Addition of XML facade bpelx:exec name= ... [CDATA ... Element element = ... ElementgetVariableDatainput,payload,loanApplication: Create an XMLFacade for the Loan Application Document LoanApplication xmlLoanApp= LoanApplicationFactory.createFacadeelement; ...

13.2.6 How to Use bpelx:exec Built-in Methods

Table 13–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 13–1 Built in Methods for bpelx:exec Method Name Description Object lookup String name JNDI access 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 setCompositeInstanceTitleString title Set the composite instance title Incorporating Java and Java EE Code in a BPEL Process 13-5

13.2.7 How to Use Java Code Wrapped in a Service Interface

Not all applications expose a service interface. You may have a scenario in which a business process must use custom Java code. For this scenario, you can: ■ Write custom Java code. ■ Create a service interface in which to embed the code. ■ Invoke the Java code as a web service over SOAP. For example, assume you create a BPEL process service component in a SOA composite application that invokes a service interface through a SOAP reference binding component. For this example, the service interface used is an Oracle Application Development Framework ADF Business Component. The high-level instructions for this scenario are as follows. To use Java code wrapped in a service interface: 1. Create an Oracle ADF Business Component service in Oracle JDeveloper. This action generates a WSDL file and XSD file for the service. 2. Create a SOA application that includes a BPEL process service component. Ensure that the BPEL process service component is exposed as a composite service. This void setIndex int i, String value String getIndex int i Six indexes can be used for a search 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 void addAuditTrailEntryString message, Object detail Add an entry to the audit trail void addAuditTrailEntryThrowable t Access file stored in the suitcase Object getVariableDataString name throws BPELFault Access and update variables stored in the scope Object getVariableDataString name, String partOrQuery throws BPELFault Access and update variables Object getVariableDataString name, String part, String query Access and update variables void setVariableDataString name, Object value Set variable data void setVariableDataString name, String part, Object value Set variable data void setVariableDataString name, String part, String query, Object value Set variable data Table 13–1 Cont. Built in Methods for bpelx:exec Method Name Description 13-6 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite automatically connects the BPEL process to an inbound SOAP service binding component. 3. Import the Oracle ADF Business Component service WSDL into the SOA composite application. 4. Create a web service binding to the Oracle ADF Business Component service interface. 5. Design a BPEL process in which you perform the following tasks: a. Create a partner link for the Oracle ADF Business Component service portType. b. Create an assign activity. For this example, this step copies data for example, a static XML fragment into a variable that is passed to the Oracle ADF Business Component service. c. Create an invoke activity and connect to the partner link you created in Step 5a. 6. Connect wire the partner link reference to the composite reference binding component. This reference uses a web service binding to enable the Oracle ADF Business Component service to be remotely deployed. 7. Deploy the SOA application. 8. Invoke the SOA application from the Test Web Service page in Oracle Enterprise Manager Fusion Middleware Control. For more information on creating Oracle ADF Business Components, see Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework. For more information on invoking a SOA composite application, see Oracle Fusion Middleware Administrators Guide for Oracle SOA Suite and Oracle BPM Suite.

13.3 Adding Custom Classes and JAR Files

You can add custom classes and JAR files to a SOA composite application. A SOA extension library for adding extension classes and JARs to a SOA composite application is available in the ORACLE_HOMEsoamodulesoracle.soa.ext_ 11.1.1 directory. For Oracle JDeveloper, custom classes and JARs are added to the application_name projectsca-inflib directory.

13.3.1 How to Add Custom Classes and JAR Files

If the classes are used in bpelx:exec, you must also add the JARs with the BpelcClasspath property in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control. To add JARs to BpelcClasspath: 1. From the SOA Infrastructure menu, select SOA Administration BPEL Properties .

2. At the bottom of the BPEL Service Engine Properties page, click More BPEL

Configuration Properties .

3. Click BpelcClasspath.

4. In the Value field, specify the class path.

5. Click Apply.

Incorporating Java and Java EE Code in a BPEL Process 13-7

6. Click Return.

In addition, ensure that the JARs are loaded by the SOA composite application. To add custom classes: 1. Copy the classes to the classes directory. 2. Restart Oracle WebLogic Server. To add custom JARs: 1. Copy the JAR files to this directory or its subdirectory. 2. Run ant. 3. Restart Oracle WebLogic Server.

13.4 Using Java Embedding in a BPEL Process in Oracle JDeveloper

In Oracle JDeveloper, you can add the bpelx:exec activity and copy the code snippet into a dialog.

13.4.1 How To Use Java Embedding in a BPEL Process in Oracle JDeveloper

To use Java embedding in a BPEL process in Oracle JDeveloper: 1. From the Component Palette, expand Oracle Extensions. 2. Drag the Java Embedding activity into the designer. 3. Double-click the Java Embedding activity to display the Java Embedding dialog. 4. In the Name field, enter a name. 5. In the Code Snippet field, enter or cut and paste the Java code. Figure 13–1 provides details. Note: For custom classes, you must include any JAR files required for embedded Java code in the BpelcClasspath property in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control. See Section 13.3.1, How to Add Custom Classes and JAR Files for instructions. The JAR files are then added to the class path of the BPEL loader. If multiple JAR files are included, they must be separated by a colon : on UNIX and a semicolon ; on Windows. 13-8 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite Figure 13–1 bpel:exec Code Example

13.4.2 What You May Need to Know About Using thread.sleep in a Java Embedding Activity

If you create and deploy a BPEL process that uses thread.sleep in a Java Embedding activity, the executing thread is blocked and the transaction associated with that thread is prevented from committing. This causes BPEL instances to appear only after the wait is over, which is the expected behavior. Instead, use a wait activity, which releases the resource upon entering the activity and enables the ongoing transaction to commit and the BPEL instance data to hydrate into the data store.

13.5 Embedding Service Data Objects with bpelx:exec

You can embed service data object SDO code in the .bpel file with the bpelx:exec tag. In the syntax provided in Example 13–6 , mytest.apps.SDOHelper is a Java class that modifies SDOs. Example 13–6 Embedding SDO Objects with the bpelx:exec tag bpelx:exec bpelx:exec name=ModifyInternalSDO version=1.5 language=java [CDATA[try{ Object o = getVariableDataVarSDO; Object out = getVariableDataExtSDO; Note: As an alternative to writing Java code in the Java Embedding activity, you can place your Java code in a JAR file, put it in the class path, and call your methods from within the Java Embedding activity. Incorporating Java and Java EE Code in a BPEL Process 13-9 System.out.printlnBPEL:Modify VarSDO... + o + ExtSDO: + out; mytest.apps.SDOHelper.printo; mytest.apps.SDOHelper.printout; mytest.apps.SDOHelper.modifySDOo; System.out.printlnBPEL:After Modify VarSDO... + o + ExtSDO: + out; mytest.apps.SDOHelper.printo; mytest.apps.SDOHelper.printout; }catchException e { e.printStackTrace; }]] bpelx:exec Example 13–7 provides an example of the Java classes modifySDOo and printo that are embedded in the BPEL file. Example 13–7 Java Classes public static void modifySDOObject o{ ifo instanceof commonj.sdo.DataObject { DataObjecto.getChangeSummary.beginLogging; SDOType type = SDOTypeDataObjecto.getType; HelperContext hCtx = type.getHelperContext; ListDataObject lines = ListDataObjectDataObjecto.getline; for DataObject line: lines { line.seteligibilityStatus, Y; } } else { System.out.printlnSDOHelper.modifySDO: + o + is not a DataObject; } } . . . . . . public static void printObject o { try{ ifo instanceof commonj.sdo.DataObject { DataObject sdo = commonj.sdo.DataObjecto; SDOType type = SDOType sdo.getType; HelperContext hCtx = type.getHelperContext; System.out.printlnhCtx.getXMLHelper.savesdo, type.getURI, type.getName; } else { System.out.printlnSDOHelper.print: Not a sdo + o; } }catchException e { e.printStackTrace; } }

13.6 Sharing a Custom Implementation of a Class with Oracle BPEL Process Manager

When you implement a custom Connection Manager class with the same name as a class used by Oracle BPEL Process Manager, you must ensure that the custom class does not override the class used by Oracle BPEL Process Manager. 13-10 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite For example, assume the following is occurring: ■ You are using embedded Java in a BPEL project. ■ The Connection Manager custom class is overriding the BPEL Connection Manager class. ■ A java.lang.NoClassDefFoundError is occurring at runtime.

13.6.1 How to Configure the BPEL Connection Manager Class to Take Precedence

To configure the BPEL Connection Manager class to take precedence: 1. Start Oracle JDeveloper.

2. Highlight the BPEL project.

3. From the Edit main menu, select Properties.

4. Select Libraries and Classpath.

5. Click Add JARDirectory.

6. Navigate to the location of the custom JAR file and click Select.

This adds the custom Connection Manager JAR file to the classpath.

7. Click OK.

8. Redeploy the BPEL project and retest.

14 Using Events and Timeouts in BPEL Processes 14-1 14 Using Events and Timeouts in BPEL Processes This chapter describes how to use events and timeouts. Because web services can take a long time to return a response, a BPEL process service component must be able to time out and continue with the rest of the flow after a period of time. This chapter includes the following sections: ■ Section 14.1, Introduction to Event and Timeout Concepts ■ Section 14.2, Creating a Pick Activity to Select Between Continuing a Process or Waiting ■ Section 14.3, Setting Timeouts for Request-Response Operations in Receive Activities ■ Section 14.4, Creating a Wait Activity to Set an Expiration Time ■ Section 14.5, Specifying Events to Wait for Message Arrival with an OnEvent Branch in BPEL 2.0 ■ Section 14.6, Setting Timeouts for Synchronous Processes

14.1 Introduction to Event and Timeout Concepts

This chapter provides an example of how to program a BPEL process service component to wait one minute for a response from a web service named Star Loan that provides loan offers. If Star Loan does not respond in one minute, then the BPEL process service component automatically selects an offer from another web service named United Loan. In the real world, the time limit is more like 48 hours. However, for this example, you do not want to wait that long to see if your BPEL process service component is working properly. Because asynchronous web services can take a long time to return a response, a BPEL process service component must be able to time out, or give up waiting, and continue with the rest of the flow after a certain amount of time. You can use a pick activity to configure a BPEL flow to either wait a specified amount of time or to continue performing its duties. To set an expiration period for the time, you can use the wait activity.