| Oracle® Application Server Adapter Concepts Guide 10g Release 3 (10.1.3.1.0) Part Number B31005-01 |
|
|
View PDF |
| Oracle® Application Server Adapter Concepts Guide 10g Release 3 (10.1.3.1.0) Part Number B31005-01 |
|
|
View PDF |
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:
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.
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.
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_ HOME/integration/orabpel/system/appserver/oc4j/j2ee/home/admin.jar ormi://localhost oc4jadmin welcome1 -deployConnector -file myAdapter.rar -name myAdapter
For the standalone OC4J installation, use the following command to remove the JCA 1.5 resource adapter:
java -jar $ORACLE_ HOME/integration/orabpel/system/appserver/oc4j/j2ee/home/admin.jar 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:
Note:
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_ SOA
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:
$ORACLE_HOME/integration/orabpel/system/appserver/oc4j/j2ee/home/application-deployments/d
efault/DbAdapter/oc4j-ra.xml.
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/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.
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.
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.
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
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.
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 payload record element of the XMLRecord.
Use the encrypt command in the orabpel\bin directory (encrypt.sh 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.
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.
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.
All other exceptions 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 need to provide an Exception Filter (Java class) which can translate third party exceptions to eitherPCRetriableResourceException (RemoteFault) or PCResourceException (BindingFault). The exception filter must be declare in the jca:binding element, as follows:
<jca:binding ExceptionFilter="oracle.tip.adapter.sample.SampleExceptionFilter"/>
The filter (Java class) must implement the interface, oracle.tip.adapter.api.exception.ExceptionFilter.
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.
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
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.
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-n ame> </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-messag e-partname> </property>
Note:
[:<password>] in the preceding 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|mess age</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.
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.
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.
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:
commit the removal of the message from the inbound adapter endpoint (for example, table and queue.)
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.
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.
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.
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.
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.
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.
