Skip Headers
Oracle® Application Server Adapter Concepts Guide
10g Release 3 (

Part Number B31005-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

6 Adapter Life-Cycle Management

Oracle Application Server adapters are based on J2EE Connector Architecture (J2CA) 1.5 standards and deployed in the Oracle Containers for J2EE (OC4J). The life cycle of Oracle Application Server adapters depends on Business Process Execution Language for Web Services (BPEL) Process Manager. These adapters integrate with BPEL Process Manager through the Adapter Framework component.

This chapter contains the following sections:

Installing Oracle Application Server Adapters

Technology adapters and OracleAS Adapter for Oracle Applications are available as part of the Oracle BPEL Process Manager install. In addition, these adapters support both standalone OC4J and middle tier deployments. Packaged-application adapters and Legacy adapters are available as part of the OracleAS Adapters CD. These adapters support middle tier deployment only.

Starting and Stopping an Adapter

Oracle Application Server adapters are deployed as J2CA 1.5 resource adapters. Therefore, to start or stop an adapter, every resource adapter must implement the start (BootstrapContext) and stop methods as part of the SPI interface. Oracle Application Server adapters are started when a BPEL process using them starts a J2CA Outbound Interaction. Adapters can also be started when the BPEL process is itself loaded for inbound interactions or when adapters publish events to the BPEL process.

After an adapter is started, the only way to stop the adapter is to shut down OC4J. In this release, Adapter Framework acts as a part of the J2CA 1.5 container.

Physically Deploying an Adapter

Oracle Application Server adapters are deployed as J2CA 1.5 resource adapters in an OC4J container. Adapters are packaged as Resource Adapter Archive (RAR) files using the Java Archive (JAR) format. The physical deployment of adapters involves using the RAR file and registering adapters as connectors with the underlying OC4J or the middle tier platform. The RAR file contains the ra.xml file, which is the deployment descriptor XML file containing deployment-specific information about the resource adapter. In addition, the RAR file contains declarative information about the contract between OC4J and resource adapter.

In addition to the ra.xml file in the.rar file, adapters package the oc4j-ra.xml template file. The oc4j-ra.xml file is used to define resource adapter ConnectorFactory objects (logical deployment). The oc4j-ra.xml file is the OC4J-specific deployment descriptor for a resource adapter. It contains deployment configurations for deploying resource adapters to OC4J, which includes the back-end application connection information as specified in the deployment descriptor of the resource adapter, Java Naming and Directory Interface (JNDI) name to be used, connection pooling parameters, resource principal mapping mechanism, and configurations.

Example 6-1 Standalone OC4J install

This example illustrates the physical deployment of technology and OracleAS Adapter for Oracle Applications as a part of the BPEL Process Manager standalone OC4J installation. For the standalone OC4J installation, use the following command to deploy the JCA 1.5 resource adapter:

java -jar $ORACLE_
ormi://localhost oc4jadmin welcome1 -deployConnector -file myAdapter.rar -name

For the standalone OC4J installation, use the following command to remove the JCA 1.5 resource adapter:

java -jar $ORACLE_
ormi://localhost oc4jadmin welcome1 -undeployConnector -name myAdapter

The Connectors folder also contains MANIFEST.MF, oc4j-ra.xml, and ra.xml files.

The following is a sample oc4j-ra.xml file:

Description of oc4j_xml.gif follows
Description of the illustration oc4j_xml.gif


For the middle tier installation, run the dcmctl utility to deploy the J2CA 1.5 resource adapter. Use the following command:
cd $ORACLE_HOME/dcm/bin
./dcmctl deployApplication -f myAdapter.rar -a myAdapter -co OC4J_

Logically Deploying an Adapter

The logical deployment of adapters refers to the creation of ConnectionFactory objects in oc4j-ra.xml deployment descriptor file. To add the connection information and assign to a JNDI name, edit the corresponding oc4j-ra.xml file of the resource adapter. In addition, you must manually locate and edit oc4j-ra.xml for the required adapter. The oc4j-ra.xml file contains run-time connection parameters for an adapter.

For example, to deploy OracleAS Adapter for Database logically, edit the oc4j-ra.xml file at the following location:


Viewing Adapter Logs

You can view the logs for Oracle Application Server adapters as follows:

Using Adapter Headers

Adapters expose the underlying back-end operation specific properties as Header elements and allow the manipulation of these elements within a business process. For example, the Header element for OracleAS Adapter for Advanced Queuing exposes Header properties, such as Correlation ID and Message ID, for correlating two Advanced Queuing messages within a business process.

Setting the Trace Level of an Adapter

Set the trace level for Oracle Application Server adapters as follows:

Adapter Deployment Validation Within JDeveloper

During the deployment step (JDev or obant) the WSDL's containing J2CA bindings will be scrutinized by a J2CA WSDL Validation Service. The WSDL Validation Service will only select the WSDLs containing J2CA bindings.

The following validation steps occur:

Turning on the XML Validation

XML validation can be turned on for the BPEL server domain through BPEL Console or at the PartnerLink level. The inbound and outbound XML validation is turned on in the BPEL Process Manager.

Describing XML Data Structure

The Record implementation for Oracle Application Server adapters is XMLRecord. All adapter interactions are started with an XMLRecord. Each JCA record must be an implementation of oracle.tip.adapter.api.record.XMLRecord. Each instance of XMLRecord contains one or two instances of RecordElements: one mandatory Payload RecordElement and one optional Header RecordElement. RecordElements contain data. In addition, each RecordElement contains one BLOB of data, which can either be an UTF-8-encoded XML string or a binary opaque byte stream.

XMLRecord consists of the following methods:

Encrypting Passwords in oc4j-ra.xml

Use the encrypt command in the orabpel\bin directory ( or encrypt.bat) to encrypt passwords in the oc4j-ra.xml file.

Each JCA resource adapter implementation is then responsible for using the proper Adapter Framework decryption facility to decrypt the password. If the adapter does not do this, then it does not make sense to encrypt any of its oc4j-ra.xml entries.

Managing Errors

The Adapter and the underlying Adapter Framework (AF) library throw the following type of exceptions:

Handling Connection Errors

Technology and OracleAS Adapter for Oracle Applications adapters can handle connection errors for the following interactions:

Handling Adapter Data Errors

You can handle errors that might occur during the following interactions:

Describing Message Ordering

Message ordering can be achieved by making a BPEL process synchronous, as it implies that the resource adapter thread publishing a message to the BPEL engine will be used for executing the entire BPEL instance.

For asynchronous BPEL processes, a pool of BPEL engine worker threads will process received messages. Thus, it will prevent a message ordering guarantee, as the duration of one BPEL instance will almost always be different from that of others.

Generally, a JCA resource adapter wizard only creates a one way (asynchronous) WSDLs, that is, WSDLs where the operation has only an input message. It is necessary to manually modify the wizard generated WSDLs, that is, changing it so that it becomes a request-response (synchronous) type WSDL with input and output messages.

Consider the following example to create a XML schema type for a response (output) message that is generally not generated:

  <schema xmlns=""
    <import namespace=""
            schemaLocation="adapterTypes.xsd" />
      <element name="empty">

After creating an XML schema type, the next step is to define the WSDL message (in the adapter WSDL file) as shown in the following example:

<message name="ignoreMessage">
  <part name="empty" element="tns:empty"/>

The next step is to add an output message to the inbound WSDL operation as shown in the following example:

<portType name="Receive_ptt">
  <operation name="Receive">
    <input message="tns:payloadMessage"/>
    <output message="tns:ignoreMessage"/>

Next, you need to add an output element in the binding section as shown in the following example:

<binding name="Receive_binding" type="tns:Receive_ptt">
  <pc:inbound_binding />
  <operation name="Receive">
    <jca:operation .../>

The WSDL is OK.

Next, in the BPEL Process you should add a reply activity at the end of the business process logic as shown in the following example:

  <variable name="ignore" messageType="ns1:ignoreMessage"/>
<sequence name="main">
  <receive partnerLink="ReceivePL" portType="ns1:Receive_ptt" 
           <!-- processing -->
  <invoke partnerLink="DB_Insert" portType="ns1:DB_Insert_ptt"
          operation="InsertCust" inputVariable="NewCust"/>
<reply partnerLink="ReceivePL" portType="ns1:Receive_ptt"
         operation="Receive" variable="ignore"/>
         <!-- optionally more processing -->

If the resource adapter in the preceding example supports multi-threading inbound, it must be configured/tuned to only use one thread, because multiple threads will break the message ordering guarantee due to their stochastic durations.

Describing Message Rejection Handlers

You can configure the Message Rejection handler to do the following:

You should specify the Message Rejection handler in the bpel.xml file under the associated PartnerLink activity. In addition, you should define Message Rejection handlers as part of the Activation agent properties. The following are four types of Message Rejection handlers:

Describing How Adapters Ensure no Message Loss

This section describes how Adapters ensure no message loss, and how you can recover recover messages stuck in the BPEL dehydration store.

The BPEL engine is constructed to always ensure delivery. Dehydration points are established before each receive, pick, wait and after each reply and invoke. By default dehydration after an invoke is deferred but you have control of that through tuning process parameters (see the idempotent setting option in the BPEL Tuning Guide).

The JCA Resource Adapters extend the reach of the BPEL engine and in a specific way contribute to making sure that the delivery guarantee is upheld.

Transactional adapters allow the EIS to participate in one-phase or two-phase commits (local transactions or global/distributed transactions). These commits are controlled either by the adapter (inbound) or by the BPEL engine (outbound). Non-transactional adapters implement their own schemes to ensure delivery, without the use of transactional semantics.

Local transaction and Global (XA) transactions

In BPEL PM 10.1.3 transactional adapters support global (two-phase commit) transactions, through the JCA 1.5 XA contracts. This include adapters for Oracle Applications, Database, Advanced Queuing, JMS and MQSeries. Non transactional adapters include the File and FTP adapters.

Inbound Transactions

For an asynchronous BPEL process, a transactional adapter will initiate a global JTA transaction before sending an inbound message to BPEL. The inbound message is queued into the dehydration store through the Delivery Service in the BPEL engine. When control returns to the adapter, it will commit the JTA transaction thus executing the following set of actions as an atomic unit of work:

  1. commit the removal of the message from the inbound adapter endpoint (for example, table and queue.)

  2. commit the insertion of this message to the dehydration store.

If anything fails during this, both the actiond 1 and 2 will be rolled back guaranteed.

After successful message delivery by the adapter to the dehydration store, the inbound message remains in the store until the next BPEL process dehydration point occurs, for example, until the first invoke. At that point the message from the receive activity is removed from the Delivery Service. Any activities between these checkpoints are treated as being part of a JTA (global) transaction. If the BPEL server fails between the two dehydration points, the entire transaction is rolled back so that state is assured. Your last message would be replayed by the next available BPEL server. All this happens under the covers.

For a synchronous process, the global transaction initiated by the adapter will span message delivery and BPEL process execution up until the first reply activity, which is typically placed at the end of a process flow.

Outbound Transactions

For transactional adapters outbound JCA interactions (the invoke activities) are scoped with the global BPEL JTA (ejb) transaction. This means that all BPEL activities, including JCA adapter invocations will be part of a global transaction, and as such either all activities are committed or rolled back, if an error occurs.

For example, a BPEL process can insert data into several tables (on different databases) through different invoke activities (invoking the Database adapter). When the BPEL instance is about to finish, the JTA transaction is committed. Only at that point will the database insert operations be committed. If any errors occur during the BPEL instance execution, all activities (and thus database operations) will be rolled back to the last dehydration point.

BPEL Clustering Support Within Adapters

The Adapter Framework supports active fail-over of inbound Adapter Services. You can achieve this by adding a property to a particular JCA activation agent (in bpel.xml) as shown in the following example:

  <activationAgent className="..." partnerLink="MyInboundAdapterPL">
    <property name="clusterGroupId">myBpelCluster</property>

If the BPEL PM servers (JVMs) in the cluster are located across TCP/IP subnet boundaries, then it is necessary to add the attribute clusterAcrossSubnet=true.

In a cluster group, the multiple activations of the same (for example, File) adapter Activation Agent (for a specific partnerlink) will be detected implicitly and automatically by all the instances of the adapter framework active in that cluster. Only one activation will be allowed to actually start the reading or publishing messages. The adapter framework instances chooses one among them, randomly as to who should assume the Primary Activation responsibility. The other activations (instances) in the cluster will initiate to a hot stand-by state, without actually invoking EndpointActivation on the JCA resource adapter.

If a primary activation at some point becomes unresponsive, is deactivated manually or if it crashes/exits, then any one of the remaining adapter framework members of the cluster group will immediately detect this, and reassign the primary activation responsibility to one of activation agents standing by. This feature uses JGroups underneath for the implementation, hence the clusterGroupId property.

Deploying Adapter Services

Adapter services can be deployed in two ways, using JDeveloper and BPEL Console. In addition, deploying a BPEL process deploys an adapter service. You can remove an adapter service from the BPEL Console.

Batching and Debatching Support

The batching and debatching functionality is supported only by OracleAS Adapter for Files and OracleAS Adapter for FTP, and OracleAS Adapter for Databases. OracleAS Adapter for File and OracleAS Adapter for FTP consist of a Reader to debatch a single huge file into several batches. You need to specify the batch size during the design-time configuration. In addition, the adapter includes a Writer to batch a set of messages into a single file.

OracleAS Adapter for Databases consists of a Publish component to poll a set of tables to detect events. This component can raise events to the BPEL process one record at a time or multiple records at a time.

Migrating Repositories

All the adapter service WSDLs generated by the Adapter Configuration wizard have a reference to the JNDI name. The reference is defined in the oc4j-ra.xml file which is the adapter's deployment descriptor, through the location attribute on the jca:address element. This is the key when you want to migrate from a development environment to a test environment to a production environment. You should update the oc4j-ra.xml file to have the same JNDI name in all three environments: development, testing, and production. You should specify values for deployment time properties, such as retry interval and retry count, and then redeploy to testing environment or production environment. The oc4j-ra.xml will identify the end point as a development EIS or testing EIS or production EIS. For example, consider that when running through the Database Adapter Service wizard, you specify eis/DB/custStore as the JNDI name for createCustomer service. After modeling the BPEL process by using this adapter service, you should deploy it to the development, test or production environments without making any changes. But before you do this, ensure that you have a corresponding JNDI entry for eis/DB/custStore in each of your various environments pointing to the right EIS instance.