Oracle JCA Adapters High Availability Error Handling Oracle Database Adapters High Availability

5-64 Oracle Fusion Middleware High Availability Guide 2. Associate the fault policy with a service endpoint of the composite in the fault-bindings.xml file. 3. Copy the fault-policies.xml file and the fault-bindings.xml file to Oracle SOA Composite project directory. 4. Deploy the Oracle SOA Composite project. Retry frequency and retry interval are both configurable. Service engines can mark an invocation as retriable. In a clustered environment, if rollback occurs, it may be picked up by another instance. If another node picks up the message, it generates a unique ID. The number of retries are configured within the composite, under the binding.jca element. For more information, see the Oracle Fusion Middleware User’s Guide for Technology Adapters. System-Defined Rejected Message Handlers The following system-defined error handlers can be configured in fault policies: ■ Web Service Handler - A predefined WSDL interface must be implemented by the target service ■ Custom Java Handler - A predefined Java interface must be implemented by the target class. ■ JMS Queue - The rejected message is enqueued to a queue as a JMS message with the appropriate context and payload. ■ File - The rejected message is stored in the file system with the proper context and payload. Payload Persistence For resubmitting rejected messages, payload persistence is imperative. Payloads are stored in the database and be viewed through Oracle Enterprise Manager Fusion Middleware Control. Error handlers invoked during automatic error handling also receive the payload during their invocation. Error payload persistence in the database is enabled by default.

5.10.2 Oracle JCA Adapters High Availability Architecture and Failover Considerations

This section describes Oracle JCA Adapters high availability considerations for configuring Oracle JCA Adapters to run on an Oracle SOA cluster.

5.10.2.1 Oracle JCA Adapters High Availability Error Handling

This section describes Oracle JCA High Availability error handling. Connection Errors Oracle JCA Adapters and Oracle Adapters for Oracle Applications handle connection errors for the following interactions: ■ Outbound Interaction : Oracle JCA Adapters and Oracle Adapter for Oracle Applications raise the oracle.tip.adapter.api.exception.PCRetriableResourceException exception for transient connection errors, which are recoverable connection errors. For example, a database listener may not have started, resulting in connection errors. You can define the maximum number of attempts to reconnect made using the fault-policy.xml file. The parameters for attempts to reconnect can be specified using this file. After the configured number of retries is reached, the fabricInvocationException exception is thrown. Configuring High Availability for Oracle Fusion Middleware SOA Suite 5-65 Fault handling and retry properties are defined as part of the binding level configuration. When the binding level retry has expired, the fault is handled based on policies specified within the fault-policy.xml. For more information on binding properties, see the Oracle Fusion Middleware User’s Guide for Technology Adapters. ■ Inbound Interaction : Oracle JCA Adapters, Oracle Adapter for Oracle Applications, 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 Oracle SOA Service Infrastructure. The inbound interaction connection errors are written to a log, and can be viewed through Oracle WebLogic Server Administration Console.

5.10.2.2 Oracle File and FTP Adapters High Availability

The Oracle File and FTP Adapters can be configured for high availability using an active-active topology. A cluster-based high availability configuration is supported for both inbound and outbound operations. File and FTP Adapters do not support XA and hence can only guarantee at-least-once delivery of messages. Thus, it is possible to have duplicate messages after recovery from a server crash. Prerequisites for High Availability The following list describes prerequisites for Oracle File and FTP Adapters high availability: ■ In a clustered configuration, inbound adapters across managed servers must point to the same physical directory, a directory on a shared drive. ■ Connection-factories must specify the same shared folder as the control directory, and their names must match. For example, if the deployment descriptor for one connection-factory has sharedcontrol_dir as the value for controlDir, the other deployment descriptor must also have the same value. The Oracle File and FTP Adapters must ensure that only one node processes a particular file in a distributed topology. You can use the database table as a coordinator to ensure that Oracle File and FTP Adapters are highly available for inbound operations. See the Oracle Fusion Middleware User’s Guide for Technology Adapters for details on configuring a database table as a coordinator. The Oracle File and FTP Adapters must ensure that if multiple references write to the same directory, then these do not overwrite each other. The following locking capabilities can be used to make Oracle File and FTP Adapters highly available for outbound operations: ■ Database mutex ■ User-defined mutex See the Oracle Fusion Middleware User’s Guide for Technology Adapters for details on configuring a database mutex. Oracle File and FTP Adapters High Availability Configuration A cluster-based high availability configuration is supported for both inbound and outbound operations. However, consider the following: ■ Inbound Operations - Oracle File and FTP Adapters must ensure that only one node processes a particular file in a distributed topology. ■ Outbound Operations - Oracle File and FTP Adapters must ensure that if multiple references write to the same directory, these do not overwrite each other. 5-66 Oracle Fusion Middleware High Availability Guide Database-based mutexes are used as coordinators to ensure these behaviors in a clustered topology. Configuring a Database Mutex Configure a database table as a coordinator by modifying Oracle File and FTP Adapter deployment descriptor for the connection-instance corresponding to eisHAFileAdapter from Oracle WebLogic Server Administration Console:

1. Click FileAdapter under Summary of Deployments on Oracle WebLogic Server

Administration Console.

2. Click the Outbound Connection Pools tab, and expand

javax.resource.cci.ConnectionFactory to see the configured connection factories.

3. Click eisHAFileAdapter. The Outbound Connection Properties for the

connection factory corresponding to high availability is displayed. 4. Update the connection factory properties. Update the Adapter configuration to use the connection factory as shown in the following example: adapter-config name=FlatStructureOut adapter=File Adapter xmlns=http:platform.integration.oracleblocksadapterfwmetadata connection-factory location=eisHAFileAdapter adapterRef= endpoint-interaction portType=Write_ptt operation=Write interaction-spec className=oracle.tip.adapter.file.outbound.FileInteractionSpec property.. property.. interaction-spec endpoint-interaction adapter-config The new parameters in connection factory for Oracle File and FTP Adapters are as follows: ■ controlDir - Set this parameter to the directory structure where you want the control files to be stored. Set it to a shared location if multiple Oracle WebLogic Server instances are running in a cluster. ■ inboundDataSource - Set this parameter to jdbcSOADataSource. This is the data source where the schemas corresponding to high availability are pre-created. The pre-created schemas are located under MW_ HOMEAS11gR1SOArcuintegrationsoainfrasqladaptercreatesc hema_adapter_oracle.sql. To create the schemas elsewhere, use this script. Set the inboundDataSource property accordingly if you choose a different schema. ■ outboundDataSource - Set this parameter to jdbcSOADataSource. This is the data source where the schemas corresponding to high availability are pre-created. The pre-created schemas can be found under MW_ HOMEAS11gR1SOArcuintegrationsoainfrasqladaptercreatesc hema_adapter_oracle.sql. To create the schemas elsewhere, use this script. Set the outboundDataSource property if you do create the schemas elsewhere. Note: The location attribute is set to eisHAFileAdapter for the connection factory. Configuring High Availability for Oracle Fusion Middleware SOA Suite 5-67 ■ outboundLockTypeForWrite - Set this parameter to oracle if you are using Oracle database. By default Oracle File and FTP Adapters use an in-memory mutex to lock outbound write operations. Choose one of the following values for synchronizing write operations: – memory - Oracle File and FTP Adapters use an in-memory mutex to synchronize access to the file system. – oracle - The adapter uses Oracle database sequence. – db - The adapter uses a pre-created database table FILEADAPTER_MUTEX as the locking mechanism. Use this option only if you are using a schema other than the Oracle database schema. – user-defined - The adapter uses a user-defined mutex. In order to configure the user-defined mutex, implement the mutex interface: oracle.tip.adapter.file.Mutex and then configure a new binding-property with the name oracle.tip.adapter.file.mutex and value as the fully qualified class name for the mutex for the outbound reference.

5.10.2.3 Oracle Database Adapters High Availability

The Oracle Database Adapter supports high availability in an active-active setup. In an active-active setup, distributed polling techniques can be used for inbound Database Adapters to ensure that the same data is not retrieved more than once. For more information on best practices for distributed polling, see the Oracle JCA Adapter for Database chapter in Oracle Fusion Middleware Users Guide for Technology Adapters. Similar to other adapters, an Oracle Database Adapter can also be configured for singleton behavior within an active-passive setup. This allows a high performance multi-threaded inbound Oracle Database Adapter instance running in an active-passive setup, to follow a fan out pattern and invoke multiple composite instances across a cluster. The Oracle Database Adapter also supports the high availability feature when there is a database failure or restart. The DB adapter picks up again without any message loss. For information about how an inbound rejected message is handled by using fault policy, see the Oracle Fusion Middleware User’s Guide for Technology Adapters. Surviving Database Restart The Oracle Database Adapter can survive a database down scenario and pick up again without any message loss. For avoiding data loss, the data source needs to be XA enabled and configured for Oracle RAC multi data source. For information on configuring a datasource for high availability, see Appendix B, Recommended Multi Data Sources. Note: For large payloads, increase transaction timeout for the SOA DataSource by adding the following: xa-set-transaction-timeouttruexa-set-transaction -timeout xa-transaction-timeout1000xa-transaction-timeout Increase global transaction timeouts if a database is used as the coordinator. 5-68 Oracle Fusion Middleware High Availability Guide

5.10.2.4 Oracle JMS Adapters High Availability