6 Adapter Life-Cycle Management

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: $Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\admin.jar ormi://localhost admin welcome -deployConnectorname -file rar filename Adaptername

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

$Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\admin.jar ormi://localhost admin welcome -undeployConnectorname Adaptername

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

The following is a sample oc4j.xml file:

Description of the illustration oc4j_xml.gif

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 OC4Jra.xml file of the resource adapter. In addition, you must manually locate and edit oc4-ra.xml for the required adapter. The oc4j.xml file contains run-time connection parameters for an adapter.

For example, to deploy OracleAS Adapter for Database logically, edit the oc4j.xml file at the following location: $Oracle_Home\integration\bpelpm\orabpel\system\appserver\OC4J\j2ee\home\application-deployments\default\DbAdapter\oc4j-ra.xml.

Viewing Adapter Logs

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

• Technology adapters and OracleAS Adapter for Oracle Applications: These adapters implement the LogManager interface of Adapter Framework, which redirects the adapter logs to the BPEL domain logs. For both outbound and inbound interactions, the log files are redirected to BPEL domain logs.

  The BPEL domain logs can be present at the following location:

  $Oracle_Home\integration\bpelpm\orabpel\domains\default\logs\domain.log.

  
  

  Note: You can also view adapter logs from BPEL Console.

  
  

• Packaged-application: These adapters do not implement the LogManager interface because it is not part of the J2CA 1.5 standard. Therefore, the log outputs of these adapters are redirected to the opmn/logs directory. For Outbound Interactions, the logs are directed to opmn logs. On the other hand, for Inbound Interactions, logs are redirected to the BPEL domain logs.

• Legacy adapters: In addition to the J2CA resource adapter, legacy adapters consists of Oracle Connect, which consists of native adapters for communicating with the mainframe application and data stores. Oracle Connect logs can be viewed using Oracle Studio, which is the mainframe adapter design-time tool and Oracle Connect management tool. Oracle Connect generates various types of logs, such as the daemon log, workspace log, and server process log. The following figure shows the daemon log monitor, which displays activity between clients and the daemon, including clients logging in and out from the daemon.

  
  Description of the illustration oracle_connect_logs.gif
  
  

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:

• Technology adapters and OracleAS Adapter for Oracle Applications: Using BPEL Console, set the trace level for technology adapters and OracleAS Adapter for Oracle Applications. After opening the BPEL Console, click Manage BPEL Domain, and then select the Logging tab. For outbound interaction, set the default.collaxa.cube.ws property. For inbound interaction, set the default.collaxa.cube.activation property.

• Packaged-application adapters: For outbound interactions, set the Loglevel property for packaged-application adapters in the oc4j-ra.xml file.

• Legacy adapters: The trace level for Oracle Connect, the mainframe server, can be set by using Oracle Studio.

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:

• Integrity of WSDL (JCA) Bindings

• Validation of JNDI location if it is deployed through JDev, or managedConnectionFactory/ConnectionSpec (if provided in jca:service)

• Existence of InteractionSpec or ActivationSpec specified in jca:operation

• Validation of all property names and values bound to the InteractionSpec or ActivationSpec in jca:operation

• Validation of any XML Record converter specified in jca:binding or pc:inbound_binding

• Finally, if the InteractionSpec or ActivationSpec implements the DeploymentValidation interface, its validate() method will be invoked

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:

• getHeaderRecordElement: Retrieves the Header RecordElement.

• getPayloadRecordElement: Retrieves the Payload RecordElement.

• setHeaderRecordElement: Sets the header record element of the XMLRecord.

• setPayloadRecordElement: Sets the header record element of the XMLRecord.

Encrypting Passwords in oc4j-ra.xml

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

Managing Errors

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

• WSIFException: The JCA artifacts for both the inbound and outbound interactions are captured in the WSDL that defines the Adapter Service. At run-time, the JCA WSIF Provider component of the AF parses the WSDL for JCA artifacts and creates InteractionSpec for outbound interaction. If the InteractionSpec class cannot be located in the class path, or if the instantiation fails, then the AF throws WSIFException.

• ActivationException: The BPEL Process throws ActivationException on failure of activation of the Adapter endpoint associated with JCA inbound interaction.

• PCRetriableResourceException: The Adapter throws PCRetriableResourceException for transient connection errors, which are recoverable errors in case of outbound interaction. The PCRetriableResourceException exception can be retried by defining a retry policy in bpel.xml.

• ResourceException: The ResourceException exception is thrown in all cases.

Handling Connection Errors

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

• Outbound Interaction: technology adapters and OracleAS Adapter for Oracle Applications raise oracle.tip.adapter.api.exception.PCRetriableResourceException for transient connection errors, which are recoverable connection errors. For example, a database listener may not have started and this might be giving connection errors.

  You can define the maximum number of reconnection attempts that can be made in the bpel.xml file. In this file, under the PartnerLinkBinding parameter, specify the parameters for reconnection attempts as shown in the following example:

  <BPELSuitcase>
  <BPELProcess ...>
    <partnerLinkBindings>
       <partnerLinkBinding name="myOutboundPartnerLink">
       <property name="wsdlLocation">Outbound.wsdl</property>
       <property name="retryInterval">10</property>
       <property name="retryMaxCount">30</property>
    </partnerLinkBinding>
  
  

  In this example, the reconnection parameter settings specify the BPEL run time to make an attempt to reconnect every 10 seconds and allow the maximum number of 30 attempts to reconnect. After the maximum number of attempts, the RemoteFault exception is raised for the BPEL process. However, if you do not specify the maximum number of attempts, then reconnection cycle will continue indefinitely. It will stop reconnecting only if the BPEL Process Manager is stopped or the connection is established.

  All other exceptions are cannot be recovered and result in throwing the BindingFault exception to the BPEL process.

  
  

  Note: Packaged-application adapters, except OracleAS Adapter for Oracle Applications, and Legacy adapters return connection exception errors. For these adapters, you cannot specify reconnection parameters. Therefore, the adapter interactions are not functional after the first connection failure.

  
  

• Inbound interaction: Technology adapters, Oracle AS adapters, and legacy adapters support a poll model for connecting to the back-end application for receiving events. In case of unrecoverable connection failures, the adapters recycle old connections, and send out alerts or notifications to the BPEL process. In addition, the adapter shuts down the inbound endpoint and the associated BPEL process instance. The inbound interaction connection errors are written to a log, and can be viewed through the BPEL console.

Handling Adapter Data Errors

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

• Outbound interaction: The J2CA Adapter throws a ResourceAdapter exception for the Outbound Interaction case. The correction of data and replaying of the message has to be handled within the BPEL Process.

• Inbound interaction: Each J2CA adapter can have one or more Message Rejection handlers associated, as well as a fail over BPEL process in the case of a termination condition. In bpel.xml, you can configure how these messages should be handled as follows:

  • Write the error to a specific directory

  • Write the error to an Advanced Queue (AQ) queue

  • Send the error to an error handler BPEL process

  • Call a WSIF service

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:

<types>  <schema xmlns="http://www.w3.org/2001/XMLSchema"          targetNamespace="http://acme.com/adapterService/">    <import namespace="http://TargetNamespace.com/adapterService/type"            schemaLocation="adapterTypes.xsd" />...      <element name="empty">        <complexType/>      </element>

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"/></message>

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"/>  </operation></portType>

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 .../>    <input/>    <output/>  </operation></binding>

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:

<variables>  <variable name="ignore" messageType="ns1:ignoreMessage"/>  .  .  .<sequence name="main">  <receive partnerLink="ReceivePL" portType="ns1:Receive_ptt"            operation="Receive"            variable="Receive_1_Read_InputVariable"            createInstance="yes"/>           .           .           .           <!-- 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 --></sequence>

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:

• Process translation errors

• Take corrective action

• Issue an alert or a notification message to the BPEL process

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:

• File system based Message Rejection handler: The file system based Message Rejection handler writes the bad messages to the configured directory by using the following file name pattern:

  INVALID_MSG_ + <process-name> + <operation-name> + <current-time>
  
  

  The syntax for specifying a file system based Rejection handler is as follows:

  <property name="rejectedMessageHandlers">    file://<directory-path></property>
  
  

  An example for specifying file based Rejection handler is as follows:

  <property name="rejectedMessageHandlers">    file://C:/orabpel/domains/default/rejectedMessages</property>
  
  

• RAW Oracle Advanced Queue based Message Rejection handler: The RAW Oracle Advanced Queue based Message Rejection handler allows the user to designate a Oracle RDBMS RAW AQ queue as the rejection storage.

  An example for specifying RAW Oracle Advanced Queue based Message Rejection handler is as follows:

  <property name="rejectedMessageHandlers">queue://jdbc:oracle:thin:@<db-host>:<tns-port>:<sid>|<user>/<password>|<queue-name></property>
  
  

  Ensure that you type : and | in the exactly the same location in the code as shown in this example.

• BPEL Process Message Rejection Handler: The BPEL Process Message Rejection handler sends the bad message to the designated error handling BPEL process.

  The syntax for specifying a BPEL Process Message Rejection Handler is as follows:

  <property name="rejectedMessageHandlers">bpel://<bpel-domain[:<password>]>|<process-name>|<operation-name>|<input-message-partname></property>
  
  

  
  

  Note: [:<password>] in the preceeding syntax can be encrypted by using the encrypt.bat/encrypt.sh utility.

  
  

  You can thus define a process with a receive operation of your choice by choosing (WSDL and BPEL source wise) - the only constraint is on the WSDL Message Type of the message that will be sent to this rejection handler. It must be declared to have the type RejectedMessage. You can do this by importing the xmllib resident WSDL RejectionMessage.wsdl, which defines such a message as shown in the following example:

  <message name="RejectionMessage">     <part name="message" element="err:RejectedMessage"/></message>
  
  

  You can import an xmllib WSDL from another WSDL by using the URL shown in the following example:

  <import namespace="http://xmlns.oracle.com/pcbpel/rejectionHandler"location="http://localhost:9700/orabpel/xmllib/jca/RejectionMessage.wsdl"/>
  
  

  The BPEL process would only contain the import as shown in this example. The port type would reference the following:

  <definitions ...xmlns:rej="http://xmlns.oracle.com/pcbpel/rejectionHandler"   <portType name="MyRejectionHandlerPortType">      <operation name="myHandleRejectionOperation">      <input message="rej:RejectionMessage"/>      </operation>   </portType>
  
  

• WSIF Based Rejection Handler: In WSIF based Message Rejection handler, you can configure any type of WSIF WSDL, such as JCA, EJB, JMS, HTTP, and Java. You can configure any kind of service that can be reached through WSIF as the bad message handler.

  The syntax for specifying a WSIF based Message Rejection handler is as follows:

  <property name="rejectedMessageHandlers">    wsif://<wsif-wsdl-location>|<operation-name>|<input-message-part-name></property>
  
  

  You can specify a WSIF based Message Rejectionhandler as shown in the following example:

  <property name="rejectedMessageHandlers">wsif://file:/C:/orabpel/samples/test/ErrorTest/FileAdapterWrite.wsdl|write|message</property>
  
  

  The WSIF based Message Rejection handler has the same constraint on message type as that of BPEL Process Rejection Handler. Refer to the BPEL Process Rejection Handler section.

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.

oracle.tip.adapter.api.exception.PCRetriableResourceException

<property name="retryInterval">60</property>
<property name="retryMaxCount">10</property>

Load Balancing and 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:

<activationAgents>  <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.

Validating Adapter Deployment

You can validate the deployment of only technology adapters and OracleAS Adapter for Oracle Applications. During the deployment step in JDeveloper, the following validation steps occur:

1. Verifying the integrity of WSDL (JCA) bindings.

2. Validating the JNDI location.

3. Verifying the existence of InteractionSpec or ActivationSpec parameters specified in jca:operation.

4. Validating all property names and values bound to InteractionSpec or ActivationSpec parameters in jca:operation.

5. Validating any XML Record converter specified in jca:binding or pc:inbound binding.

All exceptions that are raised during validation steps are reported back to JDeveloper.

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.