1 Introduction to the Oracle Java CAPS Migration Tool

1.2.1.1 Repository Project Migration

When you migrate a Repository project that contains a business process, the BPEL 1.0 code is transformed to BPEL 2.0 in the Oracle SOA Suite project. Java Collaboration Definitions (JCDs) are converted to Spring components and the associated Spring context files are generated. The required and available JAR files from the Oracle Java CAPS project are copied to the Oracle SOA Suite project. JCDs that are exposed as web services are converted to a Spring context exposed as a service in the migrated project. Projects with business processes that call JCDs are converted to business processes that call Spring components.

The migration tool can migrate File, JMS, and web service adapters, but does not migrate the code for other types of adapters. When you migrate a project that uses specialized adapters (such as database adapters), the migration tool generates placeholder endpoints in the migration project, which are just basic WSDL interfaces. To complete the conversion of these projects, you need to add the corresponding Oracle SOA Suite adapter to the migrated project in Oracle JDeveloper and map it to the corresponding Spring component or business process. For more information, see Section 4.3.4, "Adding Adapters not Converted by the Migration Tool."

Most marshal and unmarshal operations in business processes are converted into Java Embedding activities in the business process in the migrated project, including XSD, DTD, User-Defined, and SWIFT OTD marshal and unmarshal operations. In addition, all JCDs that are converted into Spring components can marshal and unmarshal the generated JAXB objects using the helper methods from the OTDUtil class.

When you migrate a Repository project, the folder structure for the new Oracle SOA Suite project is created in a directory you specify. This folder includes all the required Oracle SOA Suite files, such as BPEL files, WSDL documents, the composite file, the project file, and so on. The migration tool also creates a temporary folder in the migration tool directory to store the original code from the migrated Oracle Java CAPS project. This allows you to compare the common files between the Oracle Java CAPS and Oracle SOA Suite projects, compare the JCD source code with the migrated code, compare the BPEL files, and so on.

1.2.1.2 JBI Project Migration

The mapping between project components for Oracle SOA Suite and Oracle Java CAPS JBI is more direct and requires fewer transformations. Instead of using OTDs, as in Oracle Java CAPS Repository projects, both JBI and Oracle SOA Suite projects convert native message formatting to XML and back again. When you migrate a JBI project, the migration tool extracts the information from the composite application's build ZIP file. It retrieves the endpoint and service connection information from the jbi.xml file, and then generates the BPEL file, associated WSDL and JCA files, the Oracle JDeveloper composite.xml file, and the project JPR file.

Not all Oracle Java CAPS JBI projects types can be converted using the migration tool. The projects that are most directly converted use business processes with the File, JMS, or HTTP binding components. Specialized service engines (such as Worklist Manager and Data Mashup) and binding components (such as Scheduler and HL7) are not migrated.

1.2.1.3 Oracle Java CAPS Repository Mapping to Oracle SOA Suite

Table 1-1 lists each Oracle Java CAPS Repository component along with the corresponding Oracle SOA Suite component to which it is migrated. As mentioned earlier, Oracle Java CAPS JBI projects have a more direct one-to-one mapping with Oracle SOA Suite projects.

1.2.1.4 Migration Tool Process Flow

1. The migration tool runs in one of two modes: command-line or wizard mode. The input is the Oracle Java CAPS archive file (either a ZIP or EAR file), the output directory, and the Oracle SOA Suite project name for the migrated project.

2. The migration tool extracts the contents of the input file into a temporary location and selects the required files to start the migration process.

3. The migration tool derives the project's endpoints, which determine the wires in the Oracle SOA Suite composite.

4. The migration tool invokes a series of parsers:

   • The BPEL parser retrieves partner link definitions and, for Repository projects, transforms the BPEL 1.0 code to BPEL 2.0.

   • The WSDL parser maps the partner link defined in the WSDL document to the converted BPEL. It also converts the message types so they are compatible with WS-I Basic Profile.

   • The JCD parser parses the JCD Java code to derive the inbound and outbound. It adds the JAX-WS proxy method and all the accessor methods for the Logger, CollaborationContext, and TypeConverter.

   • The Connectivity parser parses the endpoints and builds the wire information in the Oracle SOA Suite composite.

   • The Descriptor parser reads the Oracle Java CAPS endpoints properties file for File and JMS adapters, and creates the required JCA files for the Oracle SOA Suite project. The parser reads through the project's ra.xml and ejb.xml files to derive the endpoint properties and create the metadata needed to generate the JCA files.

5. The migration tool generates the following project components:

   • Java Embedding activity in migrated business process for each of the marshal/unmarshal processes for messageable OTDs.

   • JAX-WS interface for JCDs invoked by a business process and JCDs exposed as web services.

   • XSD files for the messageable OTDs in the project.

   • Spring contexts and component types for each JCD.

   • Oracle SOA Suite composite.xml file.

   • JCA files.

   • Oracle SOA Suite project file (.jpr), which is required to open the migrated project in Oracle JDeveloper.

6. The migration tool extracts the required Oracle Java CAPS libraries from the source file and copies them to the /SCA-INF/lib directory of the migrated project.

1.2.2.1 Support for Java Collaboration Definition Migration

The migration tool converts Oracle Java CAPS projects that contain Java Collaboration Definitions (JCDs) implemented in the ways described in Section 1.2.2, "Support for Repository Project Migration." When a JCD is migrated, the migration tool reads and parses the JCD source code from the EAR file. Based on the type of JCD implementation, the JCD parser modifies the original source code.

For standalone JCDs that use either the File Adapter or JMS adapter for the inbound or outbound connection, the parser identifies the inbound connection type and modifies the JCD to implement the corresponding Oracle SOA Suite adapter interface. The parser creates a method for the interface using pseudocode, in which a call to the original JCD method is made.

For JCDs that are called from a business process and for standalone JCDs that use File or JMS adapters for the inbound connection but not the outbound connection, the parser modifies the JCD to implement a JAX-WS interface, which is generated by the Oracle SOA Suite JAX-WS tool. The original JCD input and output OTD types are converted to JAXB. The generated JAXB objects are represented by several Java classes.

All Spring Beans created during the migration from JCDs can marshal and unmarshal the generated JAXB objects using the helper methods from the OTDUtil class.

For additional information and sample code for converted JCDs, see Appendix A, "Examples of Java Collaboration Definition Conversions."

1.2.2.2 Support for Adapters and OTDs

The Oracle Java CAPS Migration tool supports the migration of the following Object Type Definitions (OTDs): User-defined, XSD, DTD, SWIFT, and HL7. The migration tool converts all OTDs used in a Oracle Java CAPS project into XSD files, and provides utility methods to convert the XML data (JAXB/DOM defined by the XSD) to OTD and the OTD data back to XML data. The migration tool's OTD parser reads OTD metadata from the OTD JAR files in the input EAR file. It then creates an XSD file that represents the OTD and places the XSD file in the migrated Oracle SOA Suite project's xsd folder.

The migration tool names the XSD file based on the name of the OTD from which it was generated. The generated WSDL documents are modified to use these XSDs to define the message type so any business processes using the OTDs can resolve OTD message types.

The generated XSD files use the OTD field names for the element names unless the element name would be invalid. BPEL XPath expressions that use OTD types are transformed to match the generated XSD file. You can use the provided OTDUtil methods to convert data between OTD and XML data. The migration tool includes the OTDUtil class, and packages it in the migrated Oracle SOA Suite project. The OTDUtil class provides utility methods to perform native OTD operations by invoking the OTD operations on the OTD implementation and convert data back to XML defined by generated XSD. For more information, see the migration.caps.runtime.OTDUtil javadocs, which are packaged in the caps.migration.runtime.util.jar file packaged with the migration tool (in migration_tool_home/oracle.migrationtool.jcaps.libraries/lib). This JAR file is also included with the migrated Oracle SOA Suite project.

//1: Get OTD marshal/unmarshal operation input by passing inputvariable and part name 
org.w3c.dom.Element inputelem = (org.w3c.dom.Element)getVariableData
    ("customerunmarshalFromStringInput","text");
String otdClass = "ud1.customer689211042.Customer"; 
    //Name of OTD class generated by Java CAPS

//2: Invoke OTDUtil.otdOperation by passing OTDClassType, operationname, and input element
Object output = migration.caps.runtime.OTDUtil.otdOperation(otdClass,

    "unmarshalFromString",inputelem,"customer");

//3 : Set OTD marshal/unmarshal operation output by passing outputvariable, part name, and data element
setVariableData("customerunmarshalFromStringOutput","customer",output,false);

//1: Get OTD marshal/unmarshal operation input by passing inputvariable and part name
org.w3c.dom.Element inputelem =
  (org.w3c.dom.Element)getVariableData("customermarshalToStringInput","customer");
String otdClass = "ud1.customer689211042.Customer"; 
    //Name of OTD class generated by Java CAPS

//2:Invoke OTDUtil.otdOperation by passing OTDClassType, operationname, and input element
Object output = migration.caps.runtime.OTDUtil.otdOperation(otdClass,
    "marshalToString",inputelem,"text");

//3:Set OTD marshal/unmarshal operation output by passing outputvariable, part name, and data element
setVariableData("customermarshalToStringOutput","text",output,false);

1.2.2.3 Support for Oracle Java CAPS Framework Classes

During the migration, code is generated to handle Oracle Java CAPS framework classes in Oracle SOA Suite. This includes the logger, collaboration context, and type converter classes. Alerter classes are not handled by the migration tool. The migrated code includes access methods for these classes, and the references to these classes are instantiated by Spring context injection. The classes are located in jcaps_interfaces.jar in the Application Sources folder of the migration project.

1.2.5.1 WS-I Version 1 Compliance

Oracle SOA Suite is compliant with the Web Services Interoperability Organization's (WS-I) Basic Profile, version 1.0. This means that the WSDL document can only have one part, which must have a type of element. It cannot be complextype or simpletype. Make sure any JBI projects to be migrated are WS-I compliant; otherwise the migrated project might fail during build, deployment, or runtime. The migration utility does not check for WS-I compliance.

1.2.5.2 Same Target Namespace for Different Message Definitions

Oracle Java CAPS JBI projects allow WSDL documents to use the same target namespace but override the message definitions. In other words, the element name is the same but the structure is different. In Oracle SOA Suite, only the first WSDL document is loaded and the overridden definitions are lost. If the JBI project you are migrating contains multiple WSDL documents with the same target namespace, modify the target namespace so it has a unique name, or make sure that the WSDL documents using the same target namespace do not define message type definitions with same name.

1.2.5.3 System Properties

In Oracle Java CAPS, additional Quality of Service (QoS) properties can be configured on the service connections, such as redelivery and throttling. Oracle SOA Suite does not have corresponding properties. The migration tool ignores these configurations during the migration. You can configure the project after the migration using available Oracle SOA Suite properties. For more information, see Section 4.2.3, "Configuring Quality of Service Properties."

1.2.5.4 BPEL 2.0 Constructs

Some of the BPEL 2.0 constructs that Oracle Java CAPS JBI supports are not available in the Oracle SOA Suite. During migration, the BPEL 2.0 code is converted without any modifications to the BPEL constructs. Some constructs that worked in Oracle Java CAPS will not work in Oracle SOA Suite, including the following:

• Compensation and termination handlers

• The standard faults: forcedTermination, repeatedCompensation, and invalidReply

• The partner concept (a partner groups several partnerLink elements, but it did not have any executable properties so it was removed from BPEL 2.0)

For compensation and termination handlers, the partner links are migrated as placeholders that you need to recreate. The switch element was also removed from BPEL 2.0, but the migration tool replaces the switch element with the if element in the Oracle SOA Suite project.

For post-migration steps to address unsupported constructs, see Section 4.2.4, "Verifying the BPEL Structure."