4 Post-Migration Tasks

4.2.1 Configuring Migrated Binding Components

Not all Oracle Java CAPS binding component properties have a one-to-one correspondence with Oracle SOA Suite adapter properties, so the migration tool migrates only the essential set of properties. Before deploying your migrated project, you should run the configuration wizard for each service and reference in the composite to verify or update the configuration.

To configure a service or reference

1. Open the project and its composite in Oracle JDeveloper as described in Section 4.1, "Opening a Migrated Project in Oracle JDeveloper."

2. Double-click the service or reference you want to configure, or right-click the component and select Edit.

   The configuration wizard for that component appears.

3. Follow the steps on the wizard to complete the configuration.

4.2.2 Adding Service Elements

WSDL supports multiple operations for a given port type. In Oracle Java CAPS, there can be one service definition for a port type, but Oracle SOA Suite requires that multiple service elements be defined for each operation. For references in the composite, there is no need for multiple reference elements for a port type with multiple operations. In Oracle SOA Suite project with binding types other than SOAP, the binding configuration in the JCA file defines multiple endpoint activation and endpoint interaction elements, one for each operation.

For Oracle Java CAPS WSDL documents that have port types with multiple operations, the migration tool populates multiple endpoint activation and endpoint interaction elements in the migrated WSDL and JCA files, but it does not define multiple service elements (one for each operation) in the generatedcomposite.xml file.

For such project, you need to manually edit the generated composite.xml file by creating multiple service elements, one for each operation. You also need to qualify the binding.jca attribute of the service element with an operation attribute.

<service name="FileInboundService_FileInWSDL_InboundPort" 
    ui:wsdlLocation="FileInWSDL.wsdl">
  <interface.wsdl interface="http://j2ee.netbeans.org/wsdl/FileInOut/
    FileInWSDL#wsdl.interface(FileInboundPortType)"/>
  <binding.jca 
    config="FileInboundService_FileInWSDL_InboundPort_file.jca"/>
</service>

<service name="FileInboundService_FileInWSDL_InboundPort" 
    ui:wsdlLocation="FileInWSDL.wsdl">
  <interface.wsdl interface="http://j2ee.netbeans.org/wsdl/FileInOut/
    FileInWSDL#wsdl.interface(FileInboundPortType)"/>
  <binding.jca 
    config="FileInboundService_FileInWSDL_InboundPort_file.jca" 
    operation="pollMain"/>
</service>
<service name="FileInboundService_FileInWSDL_InboundPort" 
    ui:wsdlLocation="FileInWSDL.wsdl">
   <interface.wsdl interface="http://j2ee.netbeans.org/wsdl/FileInOut/
    FileInWSDL#wsdl.interface(FileInboundPortType)"/>
  <binding.jca 
    config="FileInboundService_FileInWSDL_InboundPort_file.jca" 
    operation="pollBackupDir"/>
</service>

4.2.3 Configuring Quality of Service Properties

For Oracle Java CAPS JBI projects, you can configure certain Quality of Service properties. Not all of these properties transfer directly to Oracle SOA Suite features. Throttling and redelivery properties are not migrated by the Oracle Java CAPS Migration tool. Throttling allows you to set the maximum number of concurrent messages that are processed by a particular endpoint in order to maintain consistent performance. Redelivery settings handle message delivery when first-time delivery fails.

For throttling, you can limit the number of requests in memory for the BPEL process service engine. This affects in-only inbound requests. To set this limit, configure the MaximumNumberOfInvokeMessagesInCache property for the BPEL process service engine. For more information, see "Configuring BPEL Process Service Components and Engines" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

Rich redelivery can be configured using fault policies in the BPEL process service engine. For more information, see "Using the Fault Management Framework" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

4.2.4 Verifying the BPEL Structure

Since Oracle Java CAPS JBI supports some BPEL 2.0 that are not available in the Oracle SOA Suite, you need to verify the converted BPEL code for projects that use the following constructs. These are not supported in Oracle SOA Suite, but are included in the converted BPEL code.

• Compensation and termination handlers: When these exist in the original Java CAPS business process, partner links are included in the migrated BPEL as placeholders. After the migration, you need to recreate and configure the partner links.

• Standard faults: These include forcedTermination, repeatedCompensation, and invalidReply.

• Partners: A partner groups several partnerLink elements, but they were removed from BPEL 2.0 because the partner concept did not have any executable properties.

4.3.1 Enabling File or JMS Message Types as Opaque

The Oracle Java CAPS Migration Tool converts all the File and JMS inbound and outbound adapters to use Oracle SOA Suite File and JMS adapters. Converted JMS and File adapters are configured to use the XML schema types ewaytype:FileTextMessage and ewaytype:Message in their corresponding WSDL documents. The WSDL documents are imported by the migrated adapter connections in the composite, so changes to these files affect all the connections of that adapter.

The defined ewaytype is an element type, which means that the input message should be wrapped inside an XML tag, as illustrated in Example 4-2. Oracle SOA Suite always requires an XML element as the input message for File and JMS endpoints that are not defined as opaque. In the converted WSDL documents, the message part is defined as a string element by default.

<?xml version="1.0" encoding="UTF-8" ?>
<FileTextMessage xmlns=" http://xml.netbeans.org/schema/eWayTypes " >
    <<Actual messagse input>>
</FileTextMessage>

You can modify the WSDL document to convert the input message part from an ewaytype element type to an opaque element type in Oracle SOA Suite. If the message part is converted to opaque, Oracle SOA Suite adapters process the message as a Base64-encoded string. The input and output messages can be a simple string, similar to Oracle Java CAPS adapters, if the opaque message type is used.

To enable the message type as opaque

1. Open the converted project in Oracle JDeveloper, and then open the WSDL document you want to modify.

2. In the WSDL document, scroll to the message element.

   Below is an excerpt of the types and message elements. You can see the commented section describing how to define the element as opaque.

   <types>
     <schema targetNamespace="http://xml.netbeans.org/schema/eWayTypes"
          xmlns="http://www.w3.org/2001/XMLSchema">
       <element name="Message" type="string"/>
     </schema>
     <schema targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/opaque/"
          xmlns="http://www.w3.org/2001/XMLSchema">
       <element name="Message" type="base64Binary"/>
     </schema>
   </types>
   
   <message name="Message">
     <part name="Message" element="ewaytype:Message"/>
   <!-- This is an opaque message type, comment out Message part defined above
   
    and uncomment following Message part to use opaque message type
    <part name="Message" element="opaque:Message"/>
   -->
   </message>
   

3. To change the message type to opaque, comment out the line immediately above the instructional comments, and uncomment <part name="Message" element="opaque:Message"/>.

4. Do the following for the opaque message type before using the input string message or before writing or sending the output message:

   1. Decode Base64-encoded input using the oracle.soa.common.util.Base64Decoder.decode() method to get the string message.

   2. Convert the output message to Base64 string using the oracle.soa.common.util.Base64Encoder.encode() method.

5. For the opaque message type, do one of the following:

   • If you use the OTDUtil.otdOperation method to marshal or unmarshal opaque messages, set the last parameter to true as shown below:

     OTDUtil.otdOperation(otdClass,"marshalToString",inputelem,"text",true);
     

   • If you do not use the OTDUtil.otdOperation method, you need to add logic to call the encode or decode methods to convert the message before using it in the business process or Spring output.

   Note:

   With the last parameter of OTDUtil.otdOperation set to true, the following occurs, depending on the OTD operation used:

   • The output is converted to Base64 after a marshalToString operation.

   • The input is decoded using Base64Decoder before an unmarshalFromString operation.

   Oracle SOA Suite adapters might not work as expected if the message is not encoded to Base64 before invoking the outbound adapter.

4.3.2 Configuring a Project with the Same XSD and FCX OTDs for Inbound and Outbound

When you migrate a project that includes a JCD with the same XSD and FCX OTDs for inbound and outbound, you need to retrieve the value from the JAX-WS holder as shown below. The JAX-WS proxy generated for this type of implementation creates a JAX-WS holder encapsulating the JAXB object.

public void test(Holder<org.netbeans.xml.schema.synchronous.TypeA> input,
Holder<org.netbeans.xml.schema.synchronous.TypeA> output) throws Throwable {
//output.setTypeA(input.getTypeA()); ? Replace this line
output.value = input.value; ? Retrieve the value from the input Holder to output.

4.3.3 Configuring FCX OTDs

The migration tool automates the migration of Repository projects with FCX OTDs in a business process or in a JCD. The supported models include the following:

• A business process with FCX OTDs performing marshal and unmarshal activities.

• A business process calling a JCD with an FCX OTD as both inbound and outbound.

• A standalone JCD exposed as a web service with FCX OTDs as request and reply types.

In the above cases, the migration tool converts the FCX OTDs, which are based on XMLBeans, by replacing them with JAXB objects. The mappings in the Oracle Java CAPS project's FCX OTD are preserved in the JAXB objects.

For Oracle Java CAPS projects that include a JCD with FCX OTDs used as other OTDs, the migration tool does not convert the OTDs to JAXB objects. Use the -xsd2jaxb option to convert the FCX OTD used as other OTD to JAXB.

To update an FCX OTD used as other OTDs

1. Run the migration tool on the project's EAR file as described in Section 3.2, "Migrating Oracle Java CAPS Projects."

   If you navigate to the converted Java code, you will see the FCX OTD used as other OTDs remains as an OTD and was not converted to JAXB.

2. Run the migration tool using the -xsd2jaxb option to convert the FCX OTDs to JAXB objects.

   This is described in Section 3.4, "Converting XSD to JAXB Format."

3. Replace the FCX OTD in the converted JCD code with the generated JAXB object in the converted Java code.

4.3.4 Adding Adapters not Converted by the Migration Tool

While the migration tool automatically generates code for JMS, File, and Web Service OTDs, certain adapters are not handled by the migration tool and need to be added manually to the project. The migration tool creates placeholders for these endpoints in business process projects, and the placeholders need to be replaced by the corresponding Oracle SOA Suite adapter.

To add unconverted adapters in Spring

1. In Oracle JDeveloper, open the migrated Oracle SOA Suite project and then open its associated composite.xml file.

2. In the Component Palette, locate the Oracle SOA Suite equivalent adapter to the unmigrated adapter, and drag it to either the services or references swim lane.

3. Follow the steps in the configuration wizard to configure the adapter.

4. Connect the new adapter to the Spring component that was generated for the appropriate JCD (that is, the JCD that was connected to the unmigrated adapter in the original Oracle Java CAPS project).

5. In the Application Navigator, expand Application Sources and locate the Java class for the Spring component you just connected.

   You can find the package and class name for the Spring Bean Java class in the bean element of the Spring XML file. An example is shown below.

   <bean name="Consume_Message_ptt" class="CAPSJCDProj_JMSInFileJMSOut.Collaboration_JMSIn">
   

6. Open the Java class file and add a global field of a type of the adapter interface class that was generated when you connected the new adapter above. Create the accessor methods for the field.

7. Validate and then save and close the Java file.

8. In the composite.xml, right-click the Spring component and select Edit.

   The Spring XML file opens in the Oracle JDeveloper editor.

9. In the Spring XML file, locate the adapter reference that was generated when you connected the adapter and Spring component. Add the global field you created above to the bean element of the Spring class and refer to the adapter reference from the property.

   Note:

   The global adapter field created above is automatically instantiated at runtime. You can use it as if it is already instantiated.

<property name="database" ref="XE" />

4.4.1 Modifying the Spring Bean Java Class

Regardless of whether your project includes any of the special cases included in this section, it is important to review the migrated Java class that contains the original JCD logic. This class contains comments and notes that give you more information about changes you might need to make for your specific JCD implementation.

To modify the Spring Bean Java class

1. In Oracle JDeveloper, open the Spring component XML file.

2. Locate the bean element containing the name of the Bean class and note the package and class names. The element looks similar to the following:

   <bean name="Consume_Message_ptt" class="CAPSJCDProj_JMSInFileJMSOut.Collaboration_JMSIn"
   

3. In the left navigation panel of Oracle JDeveloper, expand Application Sources, and then expand the package specified by bean element.

4. Open the Java class file with the name specified by the bean element.

5. Review the code and look for comments generated by the migration tool. These are preceded by the text ***Migration Tool*** so they are easy to locate in the file.

6. When you are done making changes, save and close the file.

4.4.2 Converting a Byte Array Input to String

By default, Oracle SOA Suite receives input messages as a Byte message for inbound JMS and File Adapters. In the Oracle Java CAPS project, the input can be a String message. In this case, you need to convert the byte array to a string in the generated code.

To convert a byte input array to string

1. Locate and open the Spring Bean class as described in Section 4.4.1, "Modifying the Spring Bean Java Class."

2. In the Spring Bean Java class file, check whether the input is text. For example:

   public void receive(com.stc.connectors.jms.Message input,
   
    com.stc.connector.appconn.file.FileApplication FileClient_1,
   
    com.stc.connectors.jms.JMS JMS_1)  throws Throwable {
   
           String in = input.getTextMessage();
   
           ...
   

3. If the original JCD receives a TextMessage as input for a File Adapter, convert the byte[] to String, as shown below:

   String in =  new String(input.getBytesMessage());
   

4. If the original JCD receives a TextMessage as input for a JMS Adapter, set the TextMessage in the code for the consumeMessage method, as shown below:

   public void consumeMessage(byte opaque[]) {
   
      com.stc.connectors.jms.Message input = new 
   
           com.stc.connectors.jms.impl.MessageImpl();
   
      //input.setBytesMessage(opaque);
   
      input.setTextMessage(new String(input.getBytesMessage()));      
   

5. Save and close the file.

4.4.3 Configuring the Spring Bean Class for File or JMS Outbound Adapters

For converted outbound File and JMS Adapters, locate any code in the generated Spring Bean class that uses the Oracle Java CAPS File or JMS outbound references and replace it with Oracle SOA Suite calls using the Spring Bean reference.

To configure the Spring Bean class for File or JMS outbound Adapters

1. Locate and open the Spring Bean class as described in Section 4.4.1, "Modifying the Spring Bean Java Class."

2. Open the Spring XML file and locate the Bean properties. For example:

   <bean name="Consume_Message_ptt" class="CAPSJCDProj_JMSInFileJMSOut.Collaboration_JMSIn">
   
       <property name="JMSOUT_Collaboration_JMSIn_JMS_1" 
   
                 ref="JMSOUT_Collaboration_JMSIn_JMS_1"/>
   
       <property name="FILEOUT_Collaboration_JMSIn_FileClient_1" 
   
                 ref="FILEOUT_Collaboration_JMSIn_FileClient_1"/>
   
       <property name="collabContext" ref="collabCtxBean"/>
   
       ....
   

   Note:

   The above code has been wrapped for readability.

3. Make a note of the property names for the outbound adapters.

4. In the Spring Bean Java class file, locate any variables that represent the Java CAPS outbound File and JMS Adapters that are used as parameters to a method. For example:

   public void receive(com.stc.connectors.jms.Message input,
   
    com.stc.connector.appconn.file.FileApplication FileClient_1,
   
    com.stc.connectors.jms.JMS JMS_1)  throws Throwable {
   
           String in = new String(input.getBytesMessage());
   
           System.out.println("@@ Input message " + in);
   
           System.out.println("@@ Sending text message to File " + in);
   
           FileClient_1.setText(in); 
   
           FileClient_1.write(); 
   
           System.out.println("@@ Sending text message to JMS " + in);
   
           JMS_1.sendText(in);
   
       }
   

5. Replace the Java CAPS adapter references with the Oracle SOA Suite adapter Spring Bean properties from the Spring XML file. For example:

   String in = new String(input.getBytesMessage());
   
     System.out.println("@@ Input message " + in);
   
     System.out.println("@@ Sending text message to File " + in);
   
     this.FILEOUT_Collaboration_JMSIn_FileClient_1.write(in.getBytes());
   
     System.out.println("@@ Sending text message to JMS " + in);
   
     this.JMSOUT_Collaboration_JMSIn_JMS_1.produceMessage(in.getBytes());
   

6. Save and close the file.

4.4.4 Accessing JMS Header Properties

Oracle Java CAPS supports the JMS message, which encapsulates the JMS header along with the payload. In Oracle SOA Suite, the JMS header and the payload are not associated in one object, but you can define code to access the header properties.

To access JMS header properties from a Spring Component

1. In Oracle JDeveloper, open the Spring context that you need to modify.

2. Add the following property to the Spring Context in the appropriate bean element:

   <property name="headerHelper" ref="headerHelperBean"/>
   

3. In an editor, open the class file for the Spring Bean to which you added the property, and do the following:

   1. Add an import statement for the IHeaderHelperBean helper class:

      import oracle.soa.platform.component.spring.beans.IHeaderHelperBean;
      

   2. Declare a variable with the name headerHelper (the name used in the Spring context file).

      private IHeaderHelperBean headerHelper;
      

   3. Define the getter and setter methods for the headerHelper variable in the Bean class.

      Use the get and set properties from the header helper Bean. For all the custom properties use the prefix jca.jms.JMSProperty.<PROPERTY_NAME>:

      headerHelper.setHeaderProperty("jca.jms.JMSDestinationName", "queue_TMHException");
      

4.4.5 Configuring Sub-Collaborations Called from Java Collaboration Definitions

When an Oracle Java CAPS project contains a main Java Collaboration Definition (JCD) that calls another JCD (known as a sub-collaboration), the model is not fully migrated. The code for both JCDs is converted to the generated Oracle SOA Suite project, so you can manually update the project to complete the migration.

Only the main JCD is converted into a Spring Bean class. The sub-collaboration requires some manual conversions and wiring to the main JCD.

To migrate a sub-collaboration

1. Create a Java interface and add the method definition (that is, the main operation) of the sub-collaboration.

2. Update the sub-collaboration to implement the new interface.

3. Modify the sub-collaboration's Spring component XML file by adding the service and Bean nodes. Refer to the interface for the service node type, and refer to the sub-collaboration's Bean class for the Bean node class.

4. Modify the Spring component XML file for the main JCD by adding a reference node with the type as the Java interface you created earlier.

5. Add a Bean property and set the ref attribute to the reference node of the sub-collaboration.

6. Create a class variable named the same as the Bean property name you added to the main JCD's Spring component XML file.

7. In the main JCD's Bean class, define getter and setter methods for the Bean property defined above.

   In the Oracle SOA Suite project's composite.xml file, the Spring components for both the main JCD and the sub-collaboration have new endpoints exposed after you make the above changes.

8. Wire the main JCD's Spring component to the sub-collaboration's Spring component by linking the two endpoints.

9. Modify the main JCD's Spring component XML file to replace the reference to the JCD invoking the sub-collaboration with the Spring Bean reference for the sub-collaboration.

10. Save the project.

4.5.1 Migrating User Activities in Business Processes

The migration tool cannot migrate business processes with user activities (Worklist Manager). The original business process contains BPEL constructs specific to Oracle Java CAPS, which need to be manually replaced with Oracle SOA Suite human workflow services. For more information about using Oracle SOA Suite human workflow services, see "Getting Started with Human Workflow" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

4.5.2 Migrating Correlation Initialization in Marshal and Unmarshal Activities

When correlation is initialized in the marshal and unmarshal (Invoke) activities in a business process, the initialization is ignored in the migrated business process because the marshal and unmarshal activities are replaced with embedded Java activities.

To address this, move the correlation initialization logic outside the marshal and unmarshal activities before migrating a project with this condition. Replace the correlation property alias definition in the WSDL document with an element attribute instead of a messagetype attribute by doing the following:

• Change the messageType attribute to its corresponding element attribute

• Remove the part attribute in the propertyAlias definition

Below is an example of the code before and after the required changes.

<message name="ReserveVehicleIn">
<part name="itinerary" element="ota:TravelItinerary"/>
</message>

<bpws:propertyAlias
propertyName="tres:ItineraryRefId"
messageType="vres:ReserveVehicleIn"
part="itinerary">
<bpws:query>/ota:TravelItinerary/ota:ItineraryRef/ota:UniqueID</bpws:query>
</bpws:propertyAlias>

Change the propertyAlias definition as shown below:

<bpws:propertyAlias
propertyName="tres:ItineraryRefId"
element="ota:TravelItinerary">
<bpws:query>/ota:TravelItinerary/ota:ItineraryRef/ota:UniqueID</bpws:query>
</bpws:propertyAlias>