4 Oracle BPEL Process Manager Deployment and Integration

To deploy and integrate OracleAS CDC Adapters for Adabas with Oracle BPEL Process Manager, you need to configure the BPEL Process Manager.

This section includes the following topics:

Overview of Oracle BPEL Process Manager Integration
Configuring the Adabas CDC Adapter In the Application Server
Configuring the Oracle BPEL Process Manager

Overview of Oracle BPEL Process Manager Integration

Oracle BPEL Process Manager provides a comprehensive solution for creating, deploying, and managing BPEL business processes. Oracle BPEL Process Manager is based on the Service Oriented Architecture (SOA) to provide enterprises with flexibility, interoperability, reusability, extensibility, and rapid implementation of Web services and business processes. It reduces the overall costs of management, modification, extension, and redeployment of existing business processes. Each business activity is a self-contained, self-describing, and modular application whose interface is defined by the WSDL, and the business process is modeled as a Web Service.

A Web Service is first published and then composed or orchestrated into business flows. Publishing a service is implemented by taking a function within an existing application or system and making it available in a standard way, while orchestration is implemented by composing multiple services into an end-to-end business process. The CDC solutions that are defined as part of the configuration of the OracleAS CDC Adapter for Adabas are integrated into the orchestration as PartnerLinks. Every PartnerLink is linked to a WSDL that describes the CDC table.

Configuring the Adabas CDC Adapter In the Application Server

You can use the OC4J or WebLogic application servers to deploy the Oracle Connect Legacy adapter. This section describes how to deploy the Legacy adapter, set up the necessary connections, and build the CDC Stream Positions table.

This section includes the following topics:

CDC Stream Positions Table Definition
Configuring the Adabas CDC Adapter Connection Factory

CDC Stream Positions Table Definition

Each CDC inbound process is defined for one source table only. You create one CDC Stream Positions table for each CDC adapter. The CDC Stream Positions table contains one row for each process (for each table) to control its stream position and XA transaction. The following SQL statement is used to define the table:

create table CDC_STREAM_POSITIONS(TABLE_NAME varchar(127) not null, STREAM_POSITION varchar(127), PREPARED_STREAM_POSITION varchar(127), ROLLBACK_STREAM_POSITION varchar(127), NEW_STREAM_POSITION varchar(127), XID_FORMAT int, XID_BRANCH varchar(128), XID_GLOBAL varchar(128));create unique index CDC_STREAM_POSITIONS_INDEX on CDC_STREAM_POSITIONS (TABLE_NAME);

You can change the name of the table, but not the columns.

The following table describes the CDC Stream Positions table columns.

Table 4-1 CDC Stream Positions Table

Columns	Description
`TABLE_NAME`	The name of the CDC table for the inbound process. You should not change the data in this column.
`STREAM_POSITION`	The last committed stream position of the CDC process for the current table. You should not change the data in this column.
`PREPARED_STREAM_POSITION`	The last prepared stream position of the CDC process for the current table. You should not change the data in this column.
`ROLLBACK_STREAM_POSITION`	In case of a Rollback Loop, this column contains the stream position of the event that occured at the time of the rollback.
`NEW_STREAM_POSITION`	You can enter a valid stream position value in this column to manually change the current stream position. Before you update this column, deactivate the corresponding CDC process. Note: Make sure that the XID_FORMAT column has a null value. If the `XID_FORMAT` column is not null, do not enter a value for this column.
`XID_FORMAT` `XID_BRANCH` `XID_GLOBAL`	The last prepared XID fields. If the `XID_FORMAT` column is null, the stream position is committed. In this case the `XID_BRANCH` and `XID_GLOBAL` columns will contain the last committed XID fields.

You should configure the native data source that contains the CDC Stream Positions tables in your application server. The following example shows an example of a data source definition in OC4J (in the data-sources.xml file):

<native-data-source  name="CdcContextOracleDS"  jndi-name="jdbc/CdcContextOracleDS"  description="Native CDC Context DataSource"  data-source-class="oracle.jdbc.pool.OracleDataSource"  user="system"  password="manager"  url="jdbc:oracle:thin:@//server1-xp:2551/ora10202"></native-data-source>

Configuring the Adabas CDC Adapter Connection Factory

Deploy the Oracle Connect Legacy Adapter RAR into the OC4J or WebLogic server with the name jca-legacy-adapter.

Create the appropriate connection factories in the OC4J or WebLogic application server.

This table provides a description of the connection factory properties.

Table 4-2 Connection Properties for CDC Inbound Process

Property	Description
`eisName`	Required. Sets the name of the adapter to use. The adapter is defined in the Oracle Connect server using Oracle Studio.
`serverName`	Required. Enter the name of the server with the TCP/IP address or host name where the Oracle Connect daemon is running. See Also: Advanced Tuning of the Daemon for details about the daemon.
`workspace`	Required. Specifies the name of an Oracle Connect server workspace to use. See Also: Workspaces for details about workspaces.
`portNumber`	Optional. Specifies the TCP/IP port where the Oracle Connect daemon is running on the server. The default port is `2551`.
`userName`	Optional. Specifies a user who can access the Oracle Connect server. The user is defined in the Oracle Connect daemon configuration. See also: daemon Security and workspace Security for details about users allowed to access an Oracle Connect server
`password`	Optional. Specifies a valid password for the user.
`persistentConnection`	By defalult this is set to `true`. You should not change this value.
`keepAlive`	By defalult this is set to `true`. You should not change this value.
`firewallProtocol`	Optional. Specifies the firewall protocol used: either `none` or `fixedNat` (the Nat protocol using a fixed address for the daemon). The default is set to `none`.
`connectTimeout`	Optional. Specifies the connection timeout in seconds. The default is 0, indicating that there is no connection timeout.
`encryptionProtocol`	Optional. Specifies the name of encryption protocol to use. The default is set to `RC4`. If the value of the property is not defined, the RC4 protocol is used.
`encryptionKeyName`	Optional. Specifies the name of the symmetric encryption key to use.
`encryptionKeyValue`	Optional. Specifies the value of the symmetric encryption key to use.
`useNamespace`	By defalult this is set to `true`. You should not change this value.
`exposeEventStreamMetadata`	By defalult this is set to `true`. You should not change this value.
`retryInterval`	Optional. The amount of time the resource adapter waits if no events are found in the server before issuing the next request. The default value is `15` seconds.
j`dbcDataSource`	Required. The JNDI name of the JDBC native data source that contains cdcStreamPositionsTable.
`cdcStreamPositionsTable`	The SQL table that is used to control the CDC inbound process. See CDC Stream Positions Table Definition for more information.

Configuring the Oracle BPEL Process Manager

This section includes the following topics:

Setting up the Connection to the Oracle Connect Server Metadata
Using JDeveloper to Integrate a CDC Inbound Process to the Inbound Application

Setting up the Connection to the Oracle Connect Server Metadata

Perform the following steps to set up the connection to the Oracle Connect server to provide an automatic BPEL application built by JDeveloper:

Open the Oracle BPEL Admin window.
On the Server tab, on the Configuration tab, specify the following:
- LegacyServer: The IP address of the server where Oracle Connect is installed.
- LegacyPort: The port number of the server where Oracle Connect is installed.
Repeat the previous step for each Oracle Connect server to be used by Oracle BPEL Process Manager. Use a comma as a separator between the different servers and ports.
Click Apply.
Restart the Oracle SOA Suite.

Using JDeveloper to Integrate a CDC Inbound Process to the Inbound Application

The following sections describe how to integrate the CDC inbound process to the inbound application.

Configuring a CDC Adapter Partner Link
Configuring WSDL

Configuring a CDC Adapter Partner Link

Carry out the following steps in Oracle JDeveloper to configure a CDC Adapter Partner Link.

Drag a Partner Link into one of the Services lanes of the visual editor.
In the Create Partner Link dialog box, click the Service Explorer button (the second button under WSDL Settngs.
In the Service Explorer, expand Adapter Services.
Expand the connection server on which you deployed the Adabas resource adapter (this is the server where you created your CDC solution).
Under Adapters, expand Legacy to view a list of the Oracle Connect servers that you defined by using the Oracle BPEL Admin window.
Expand the Oracle Connect server with the metadata you want to check, to view a list of workspaces.

Expand the CDC staging area workspace that you created when . This workpace will have the name with the suffix _sa.
Expand the CDCQueue adapter to view a list of captured tables.
Select the table you are working with and click OK.
Define the Partner Role and My Role then click OK.

Configuring WSDL

When you build an inbound Partner Link, Oracle BPEL Process Manager automatically creates the WSDL that corresponds to the captured table, including the properties of the AttuCDCActivationSpec class. These properties are the only relevant properies for a CDC inbound process. These properties, except for the TableName, can also be provided using the Connection Factory. For information on how to configure the Connection Factory, see Configuring the Adabas CDC Adapter Connection Factory.

The WSDL specifies the name of the adapter's connection factory as the value of the adapterInstanceJndi attribute of the <jca:address> element in the <service> section. If a connection factory exists on the applicatio server, its properties are taken. Otherwise, the properties specified by the ActivationSpec are used. If a value is specified by both the connection factory and the ActivationSpec, the ActivationSpec property overrides the value in the connection factory. If you want to use the value specified in the connection factory, you have to delete the property from the WSDL.

The following is an example of a CDC inbound WSDL:

<?xml version = '1.0' encoding = 'UTF-8'?>
<definitions name="nation" targetNamespace="http://xmlns.oracle.com/pcbpel/dlg1_
CDCQueue/nation" xmlns="http://schemas.xmlsoap.org/wsdl/" 
xmlns:legacyReq="noNamespace://dlg1_CDCQueue" 
xmlns:tns="http://xmlns.oracle.com/pcbpel/dlg1_CDCQueue/nation" 
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" 
xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/" 
xmlns:pc="http://xmlns.oracle.com/pcbpel/" xmlns:legacyRes="noNamespace://DEMO#">
    <types>
        <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns="noNamespace://dlg1_CDCQueue" targetNamespace="noNamespace://dlg1_CDCQueue" 
elementFormDefault="qualified" attributeFormDefault="unqualified">
  
          <xsd:element name="nationStream" type="nationStreamDescription"/>
            <xsd:complexType name="nationStreamDescription">
                <xsd:sequence>
                    <xsd:element name="nation" type="nationOut" minOccurs="1" 
maxOccurs="unbounded"/>
                </xsd:sequence>
            </xsd:complexType>
            <xsd:element name="nationOut" type="nationOut"/>
            <xsd:complexType name="nationOut">
                <xsd:sequence>
                    <xsd:element minOccurs="0" maxOccurs="1" name="header" 
type="nation__header"/>
                    <xsd:element minOccurs="0" maxOccurs="1" name="data" 
type="nation__data"/>
                </xsd:sequence>
            </xsd:complexType>
            <xsd:element name="nation__data" type="nation__data"/>
            <xsd:complexType name="nation__data">
                <xsd:attribute name="n_nationkey" type="xsd:int" use="required"/>
                <xsd:attribute name="n_name" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="25"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="n_regionkey" type="xsd:int" use="required"/>
                <xsd:attribute name="n_comment" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="152"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
            </xsd:complexType>
            <xsd:element name="nation__header" type="nation__header"/>
            <xsd:complexType name="nation__header">
                <xsd:attribute name="timestamp" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="26"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="tableName" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="64"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="operation" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="12"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="transactionID" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="24"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="context" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="32"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="agent_context" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="64"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="terminalID" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="4"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
                <xsd:attribute name="taskID" use="required">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value="8"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:attribute>
            </xsd:complexType>
        </xsd:schema>
    </types>
    <message name="event">
        <part name="event_nation" element="legacyReq:nationStream"/>
    </message>
    <portType name="nationPortType">
        <operation name="nation">
            <input name="Event_nation" message="tns:event"/>
        </operation>
    </portType>
    <binding name="nationJCABinding" type="tns:nationPortType">
        <pc:inbound_binding/>
        <operation name="nation">
            <jca:operation 
ActivationSpec="com.oracle.adapter.oracle.AttuCDCActivationSpec" 
TableName="nation" JdbcDataSource="jdbc/CdcContextOracleDS" 
CdcStreamPositionsTable="" EisName="dlg1_CDCQueue" ServerName="server1-xp" 
PortNumber="2551" UserName="" Password="" Workspace="dlg1_sa" RetryInterval="15" 
ConnectTimeout="0"/>
            <input/>
        </operation>
    </binding>
    <service name="nationService">
        <port name="nationPort" binding="tns:nationJCABinding">
            <jca:address 
ResourceAdapterClassName="com.oracle.adapter.AttuResourceAdapter" 
adapterInstanceJndi="eis/legacy/dlg1_CDCQueue"/>
        </port>
    </service>
    <plt:partnerLinkType name="nationPartnerLinkType">
        <plt:role name="nationRole">
            <plt:portType name="tns:nationPortType"/>
        </plt:role>
    </plt:partnerLinkType>
</definitions>

Note:

IIn this example, the element <nation> is defined as an array. The maximum number of elements in this array is defined by the maxRecords property in the corresponding CDC Queue adapter.

Troubleshooting Rollback Loops

When a problem occurs in the CDC resource adapter work thread, the thread will wait for a defined period of time (retryInterval) then it will retry the last operation. If you want to stop the adapter, you must deactivate the endpoint. The behavior of the resource adapter is different according to the type of rollback loop. In all cases, the resource adapter writes the corresponding error messages to the resource adapter log file and sends the message to the message listener onAlert method.

If the connection to Oracle Connect is lost, the resource adapter always waits for a defined period of time (retryInterval) until the connection is reestablished.
In all other cases, the resource adapter retrys the last operation immediately and if the problem returns, the resource adapter waits for acsending periods of time, beginning with the retryInterval and doubling the wait time for each successive attempt, but not for more than one minute.

If the OracleAS resource manager invokes a rollback before a 2PC prepare operation, the CDC resource adapter take steps to carry out a special operation that assists you in troublshooting the problem. In this case, the resource adapter separately sends each event from the last event array to the BPEL endpoint, which saves the stream position of the last problematic event in the ROLLBACK_STREAM_POSITION column.

If you notice that a rollback loop occurs in the CDC resource adapter work thread, check the value of the ROLLBACK_STREAM_POSITION is not null. If the value is not null, check whether there was a data problem. You can select the problematic event from the staging area, using the current stream position value. In this way you can analyze the data to determine what the problem is. In addition, you can skip the problematic event. In this case you stop the endpoint and update the NEW_STREAM_POSITION column with the value of the ROLLBACK_STREAM_POSITION.