Skip Headers

Oracle® Containers for J2EE Resource Adapter Administrator's Guide 10g Release 3 (10.1.3) B14436-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 6 Using RAs for Inbound Communication

This chapter describes concep ts and configuration for using a resource adapter to allow an EIS to initiate communication to a message endpoint in the application server; specifically, to a message-driven bean (MDB). The following topics are covered:

- Concepts: Using Resource Adapters for Inbound Communication

- Overview of Related Contracts for Inbound Communication

- Configuration and Deployment to Use an RA as a Listener for an MDB

- Understanding the Message Listening Lifecycle

- Special Conditions in Message Delivery

## Concepts: Using Resource Adapters for Inbound Communication

The following sections cover initial concepts in using resource adapters for inbound communication:

- Introduction to Using Resource Adapters for Inbound Communication

- Background and Use Case for Resource Adapters as Message Listeners for MDBs

### Introduct ion to Using Resource Adapters for Inbound Communication

This chapter considers a situation where an EIS must initiate communication with a J2EE application component to perform specific work. Such a scenario requires a resource adapter as the communication vehicle for the EIS, the optional use of a messaging system such as JMS (for example), and an MDB as the J2EE component that will receive the communication message. The MDB, in turn, may invoke an entity bean or session bean or use other resources to perform the work.

This type of scenario is possible through the J2CA inbound communication model, introduced in "Outbound Versus Inbound Communication Through Resource Adapters". To support inbound communication, the J2CA message inflow contract provides a mechanism for invoking MDBs from a resource adapter. This and other related contracts are briefly introduced in "Overview of Related Contracts for Inbound Communication".

This chapter describes configuration and other relevant actions relating to the following:

- Required configuration of the resource adapter

- Deploying and configuring the MDB and associating it with the resource adapter

- Message delivery lifecycle—activation of the MDB (the process where the MDB informs the resource adapter that it wants to receive a certain type of message), message delivery to the MDB, and deactivation of the MDB (the process where the MDB informs the resource adapter that it no longer wants to receive messages)

- Special conditions in message delivery—concurrent delivery, exceptions from MDBs, and failure during delivery within a transaction

### Backgrou nd and Use Case for Resource Adapters as Message Listeners for MDBs

In the EJB 2.0 specification, only J2EE containers (such as OC4J) could act as message listeners for MDBs, and MDBs were required to implement the `javax.jms.MessageListener` interface. In the EJB 2.1 specification, it is possible for a resource adapter to act as a message listener for MDBs, and an MDB can implement any message listener interface.

A resource adapter can support any type of listener, and any MDB can be associated with any resource adapter if they support the same type of listener. This relieves the J2EE container of potentially having to support an unlimited number of message listener types. In this way, the message listening capacity has become portable across containers.

In Oracle Application Server 10g Release 3 (10.1.3), to support JMS messaging implementations, Oracle supplies a generic JMS resource adapter that is the recommended vehicle for plugging JMS providers into OC4J. This generic adapter supports inbound communication (discussed in the next section, "Overview of Related Contracts for Inbound Communication"), but works only with MDBs implementing the `MessageListener` interface.

See "Introducing Oracle JMS Support and Generic JMS Resource Adapter" for additional information about the generic JMS adapter.

## Overview of Related Contracts for Inbound Communication

This section briefly discusses some of the J2CA contracts that are relevant to using resource adapters as message listeners for MDBs:

- Message inflow contract

- Transaction inflow contract

- Work management contract

The message inflow and transaction inflow contracts are not discussed in any detail in the current release of this manual, but OC4J simply implements the standard. The work management contract and key APIs are discussed in "Overview of the Work Management Contract", but not in great detail. Refer to version 1.5 of the J2EE Connector Architecture Specification for further information about these contracts.

### Introduction to the Message Inflow Contract

The J2CA message inflow contract outlines a contract between a J2EE container and a resource adapter to allow delivery of messages through the resource adapter to an MDB, where both execute in the J2EE container. The MDB must be configured to indicate what types of messages it wants to receive, and the resource adapter must be configured to indicate that it can support (seek, find, and relay) those types of messages.

Message delivery is typically asynchronous, but it is also possible for an MDB to send and receive messages synchronously, through APIs specific to a particular message system.

### Introduction to Imported Transactions and the Transaction Inflow Contract

There are many circumstances where a message provider creates a transaction for message delivery and sends messages to the resource adapter within that transaction. In this situation, the resource adapter imports the transaction and attempts to relay the messages to the MDB within the same transaction. The specific actions of the resource adapter for this exchange are according to the J2CA transaction inflow contract.

This contract, between a J2EE container and a resource adapter, allows the resource adapter to propagate the transaction to the J2EE container so that work can be performed there as part of the imported transaction. The contract also allows a resource adapter to accept transaction completion and recovery calls initiated by an EIS, so that ACID properties of the transaction are maintained. (See "Transaction Characteristics and Scopes" regarding ACID properties.)

Note that when messages are delivered within the context of an imported transaction, the application server must take that into account when handling transaction demarcation.

### Relation ship Between Imported Transactions and the Work Management Contract

When a transaction, started by an external transaction manager, is imported by a resource adapter, the resource adapter uses the J2CA work management contract to introduce to the J2EE container an execution context object that includes identification information for the transaction. The J2EE container must then set up a transaction context internally that is visible to other components executing in the same thread of control.

The purpose of the work management contract, between the J2EE container and the resource adapter, is to provide a mechanism for a resource adapter to perform work by submitting work units to the J2EE container for execution. The contract allows the resource adapter to schedule work, such as message delivery to an MDB, to be performed by container-managed threads.

## Configu ration and Deployment to Use an RA as a Listener for an MDB

Using a resource adapter as a message listener on behalf of an MDB requires the following:

- A J2EE-compliant application server that supports version 1.5 of the J2EE Connector Architecture Specification, as is the case with OC4J

- A resource adapter that is deployed on the application server, is capable of message delivery in general, and supports the message types the MDB wants to receive in particular

- Deployment of the MDB to the application server

Notes: The resource adapter is typically provided by a third party in order to plug in a particular kind of message system to the application server. It is often standalone, and that situation is implied by some of the discussion in this chapter, but it can alternatively be deployed in the EAR file with the application that uses it. More than one application, or more than one MDB within an application, can use the same resource adapter as a message listener. An MDB can be undeployed and redeployed any number of times during the lifecycle of a resource adapter; however, a resource adapter cannot be undeployed until all MDBs activated against it have been undeployed.

The rest of this section discusses the following topics:

- Understanding the Resource Adapter Configuration

- Understanding the MDB Configuration for Deployment

- Understanding Configuration for Use of Transactions in Message Delivery

- Configuring the MDB

- Error Conditions for Deployment and Configuration

### Understanding the Resource Adapter Configuration

To support an MDB for message listening, OC4J must have a deployed resource adapter that supports the message system and message listener type that the MDB will use. The resource adapter is often a standalone adapter previously deployed, but can also be deployed with the same application as the MDB (in the same EAR file).

Resource adapter configuration to support MDBs is included in the standard `ra.xml` file, which lists the message listener types that the resource adapter supports. Each listener type is specified as a fully qualified Java type that indicates the message listener interface that is implemented.

Because MDB support requires an inbound resource adapter, the resource adapter is configured in an `<inbound-resourceadapter>` element. This involves a `<messageadapter>` subelement, one or more `<messagelistener>` subelements of `<messageadapter>` (one for each type of message listener supported by the resource adapter), and the following subelements of `<messagelistener>`:

- The `<messagelistener-type>` subelement indicates the type of message listener to be used and must match a message listener type implemented by the MDB, as specified in a `<messaging-type>` element of the `ejb-jar.xml` file where the MDB is configured.

- The `<activationspec>` subelement specifies information that OC4J must have in order to activate the MDB at runtime, as follows:

  - For each message listener type, the resource adapter provides a JavaBean class that implements the SPI `ActivationSpec` interface, and the name of this class is indicated in the `<activationspec-class>` subelement of `<activationspec>`. An instance of this class contains activation information for a message endpoint (an MDB) and is passed to the resource adapter during endpoint activation.

  - Any bean properties of this class that must be set for activation are indicated under the `<required-config-property>` subelement of `<activationspec>`, with a `<config-property-name>` element for each. Each `<config-property-name>` specification corresponds to a matching `<activation-config-property>` name/value pair in the `ejb-jar.xml` file.

The following example is for a resource adapter that supports a Java Message Service (JMS) message system, using the `javax.jms.MessageListener` listener type. The resource adapter activation spec implementation is the JavaBean `oracle.j2ee.ra.jms.generic.JMSActivationSpec`, which has three properties that must be set for activation: `ConnectionFactoryJndiName`, `DestinationName`, and `DestinationType`.

    <connector ... >
       ...
       <resourceadapter>
          ...
          <inbound-resourceadapter>
             <messageadapter>
                <messagelistener>
                   <messagelistener-type>
                      javax.jms.MessageListener
                   </messagelistener-type>
                   <activationspec>
                      <activationspec-class>
                         oracle.j2ee.ra.jms.generic.JMSActivationSpec
                      </activationspec-class>
                      <required-config-property>
                         <config-property-name>
                            ConnectionFactoryJndiName
                         </config-property-name>
                         <config-property-name>
                            DestinationName
                         </config-property-name>
                         <config-property-name>
                            DestinationType
                         </config-property-name>
                      </required-config-property>
                   </activationspec>
                </messagelistener>
                ...
             </messageadapter>
          </inbound-resourceadapter>
          ...
       </resourceadapter>
       ...
    </connector>

Notes: A resource adapter can support multiple message listener types, so there can be multiple `<messagelistener>` elements for each `<inbound-resourceadapter>` element in the `ra.xml` file. However, each `<messagelistener>` element must specify a unique message listener type. In the Application Server Control, the supported message listener types for a resource adapter are indicated in the Resource Adapter Home page. For each `<messagelistener>` element, there is only one `<activationspec>` element. A resource adapter can support multiple activations for any given message listener type.

### Understanding the MDB Configuration for Deployment

The MDB developer or deployer configures the MDB in the `ejb-jar.xml` file, through a `<message-driven>` element and the following subelements:

- The `<messaging-type>` subelement specifies the message listener interface that the MDB implements, and must match the message listener type specified in a `<messagelistener-type>` element in the `ra.xml` file of the resource adapter being used.

- The `<activation-config>` subelement and its `<activation-config-property>` subelements are for configuration properties specific to the message system that will be used—specifically, for customized property settings for the activation configuration JavaBean supplied by the resource adapter. The configuration is expressed in terms of name/value pairs specified in subelements of `<activation-config-property>`. The property names here correspond to property names from `<config-property-name>` elements in the `ra.xml` file and specify default values for at least the properties that are specified in `ra.xml` as being required. (What properties are recognized for a particular message system is beyond the scope of the J2CA specification or EJB specification.)

For complete information about configuring an MDB, refer to the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide or to version 2.1 of the Enterprise JavaBeans Specification.

The example that follows is for use of queues with a JMS message system. To understand the property names and values in this example, you must have some knowledge of JMS.

    <ejb-jar>
       ...
       <enterprise-beans>
          ...
          <message-driven>
             <ejb-name>simpleMdb</ejb-name>
             <ejb-class>oracle.j2ee.ra.jms.mqjratest.simpleMdb</ejb-class>
             <messaging-type>javax.jms.MessageListener</messaging-type>
             <transaction-type>Container</transaction-type>
             <activation-config>
                <activation-config-property>
                  <activation-config-property-name>
                      DestinationType
                  </activation-config-property-name>
                  <activation-config-property-value>
                      javax.jms.Queue
                  </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                  <activation-config-property-name>
                      DestinationName
                  </activation-config-property-name>
                  <activation-config-property-value>
                      java:comp/resource/MQSeries/MQQ
                  </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                  <activation-config-property-name>
                      MessageSelector
                  </activation-config-property-name>
                  <activation-config-property-value>
                      RECIPIENT='MDB'
                  </activation-config-property-value>
                </activation-config-property>
                <activation-config-property>
                  <activation-config-property-name>
                      ConnectionFactoryJndiName
                  </activation-config-property-name>
                  <activation-config-property-value>
                      java:comp/resource/MQSeries/MQXAQCF
                  </activation-config-property-value>
                </activation-config-property>
              </activation-config>
              ...
              <resource-ref>
                 <description>connfactory for reply</description>
                 <res-ref-name>jms/XAQCF</res-ref-name>
                 <res-type>javax.jms.XAQueueConnectionFactory</res-type>
                 <res-auth>Container</res-auth>
                 <res-sharing-scope>Shareable</res-sharing-scope>
              </resource-ref>
              ...
              <resource-env-ref>
                 <description>Queue to send reply to</description>
                 <resource-env-ref-name>jms/QUEUE1</resource-env-ref-name>
                 <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
              </resource-env-ref>
              ...
          </message-driven>
          ...
       </enterprise-beans>
       ...
       <assembly-descriptor>
          <container-transaction>
             <method>
                <ejb-name>simpleMdb</ejb-name>
                <method-name>onMessage</method-name>
                <method-params>
                   <method-param>javax.jms.Message</method-param>
                </method-params>
             </method>
             <trans-attribute>Required</trans-attribute>
          </container-transaction>
          ...
       </assembly-descriptor>
       ...
    </ejb-jar>

Notes: This sample also shows additional elements that are relevant for a messaging system example. The `<resource-ref>` and `<resource-ref-env>` elements are for standard resource reference and resource reference environment settings. The `<trans-attribute>` element, under `<assembly-descriptor>`, specifies whether transactions are required. (This is discussed in the next section, "Understanding Configuration for Use of Transactions in Message Delivery".) See "Configuring the MDB" for considerations in associating a resource adapter with an MDB during deployment.

### Understa nding Configuration for Use of Transactions in Message Delivery

In addition to what is discussed in the preceding section, configuration in the `ejb-jar.xml` file specifies whether an MDB uses transactions, and therefore whether message delivery will be transacted. Message delivery is transacted under the following circumstances:

- The `<transaction-type>` subelement of `<message-driven>` in `ejb-jar.xml` has a value of `Container`, and the `<trans-attribute>` subelement of `<container-transaction>` (under the `<assembly-descriptor>` element) has a value of `Required`. This is shown in the example in the preceding section, "Understanding the MDB Configuration for Deployment".

  In this circumstance, if there is an imported transaction, then message delivery and related work are performed within that transaction. If there is no imported transaction, OC4J creates a transaction, and message delivery and related work are performed within that transaction.

- The `<transaction-type>` subelement of `<message-driven>` in `ejb-jar.xml` has a value of `Bean`.

  In this circumstance, the MDB manages the transaction. If a transaction is imported, OC4J will suspend it before the message delivery method call to the MDB, in order to avoid conflict.

Message delivery is not transacted if the `<transaction-type>` subelement of `<message-driven>` in `ejb-jar.xml` has a value of `Container`, but the `<trans-attribute>` element has a value of `NotSupported`. If there is an imported transaction in this circumstance, OC4J will suspend the transaction before the message delivery method call to the MDB.

Details of how transactions are started and completed are described in "Message Delivery Semantics".

### Configuring the MDB

After deployment, you can use Application Server Control to change the values of any activation configuration JavaBean properties for an MDB. The new settings take effect when the MDB application is restarted.

In the Application Server Control Console, do the following as appropriate:

1. In the Applications tab of the OC4J Home page, choose the desired application.

2. In the resulting Application Home page, choose the desired EJB module.

3. In the EJBs tab of the resulting EJB Module page, under Message Driven Beans, choose the appropriate MDB.

4. In the resulting Message Driven Bean page, under Message Properties, view the following:

   - Whether the MDB is currently associated with a resource adapter as a listener (`True` or `False`)

   - The name of the resource adapter (if one is used as a listener)

   - A list of activation configuration properties

   The list of activation configuration properties (relevant only when a resource adapter is used as a listener) shows the assembled values, according to settings in the `ejb-jar.xml` file during deployment, and any modified deployed values.

5. In the Message Driven Bean page, use the "Configure Message Listener Properties" feature to access the Configure Message Listener Properties page and specify new values for any of the activation configuration properties, as desired.

6. Apply any changes.

Any new activation configuration property values are shown in the Message Driven Bean page and reflected in the `orion-ejb-jar.xml` file, as shown in Table 6-1. For more information, see the context-sensitive topics "Message Driven Bean Page" and "Configure Message Listener Properties Page" in the Application Server Control online help.

Table 6-1 MDB Activation Configuration Properties

Application Server Control Property | Corresponding XML Entity | Description
--- | --- | ---
Resource Adapter Name | `resource-adapter` attribute of `<message-driven-deployment>` element | The resource adapter to use as a message listener for this MDB (read only). It must support the same message listener type.
Appropriate Name and Deployed Value entries in the list of activation configuration properties | A `<config-property>` element with `<config-property-name>` and `<config-property-value>` subelements | Under the appropriate `<message-driven-deployment>` element, there is a `<config-property>` element for each activation configuration property you updated, with a `<config-property-name>` subelement that indicates the name of the property, and a `<config-property-value>` subelement reflecting your new setting.

### Error Conditions for Deployment and Configuration

During resource adapter and MDB deployment and configuration, OC4J verifies settings as follows and throws exceptions as necessary:

- If a resource adapter supports multiple message listener types, OC4J checks that each `<messagelistener-type>` setting in `ra.xml` is unique.

- For each association between an MDB and a resource adapter, OC4J checks that the resource adapter supports the message listener type that the MDB implements.

- For message listener activation, OC4J checks that the activation configuration JavaBean (as specified in the `<activationspec-class>` element) implements the `javax.resource.spi.ActivationSpec` interface, is a JavaBean, and is serializable. OC4J also checks that all configuration properties listed as required in `ra.xml` (under `<required-config-property>` elements) are actually supported by the activation configuration JavaBean .

## Understanding the Message Listening Lifecycle

This section discusses the key phases and functionality of the lifecycle for message-listening, covering the following topics:

- MDB Activation

- Message Delivery

- MDB Deactivation

### MDB Activation

To enable message delivery from a resource adapter to an MDB (message endpoint), the MDB must be activated whenever it is deployed or started. When an MDB application is deployed, OC4J handles the activation process, as well as automatic reactivation after a system shutdown or failure.

Essentially, activation consists of telling the resource adapter what set of messages the MDB should receive. Message delivery can begin once this information is provided. How the set of messages is defined depends on the type of message listener, such as definitions based on destination type and message selectors for JMS.

Specifically, the following occurs during activation:

- OC4J instantiates the appropriate activation configuration JavaBean, and associates the appropriate resource adapter with it. Property values for the JavaBean are taken from configuration in `ejb-jar.xml`, or according to any subsequent changes made through Application Server Control.

- OC4J calls an activation method on the appropriate resource adapter (specifically, on an instance of a class that implements the SPI `ResourceAdapter` interface) to activate the MDB.

- In the method call to activate the MDB, OC4J passes in the following:

  - The activation configuration JavaBean instance

  - A factory object to use in delivering messages to the MDB

The resource adapter, through the property values of the activation configuration JavaBean, knows what type of messages are expected, where to get them, and how to filter them.

The factory object is an instance of a class that implements the `javax.resource.spi.endpoint.MessageEndpointFactory` interface and is provided by OC4J. See the next section, "Message Delivery", for how the message endpoint factory object is used.

Note: OC4J, in conjunction with the resource adapter, uses a method of the activation configuration JavaBean to check the validity of the bean property settings. If any invalid settings were specified, either in the `ejb-jar.xml` file during deployment or through the Application Server Control Console during subsequent configuration, a failure will result. Refer to the OC4J log files and set an appropriate new value for the parameter in question.

### Message Delivery

This section discusses the following aspects of message delivery functionality:

- Message Endpoint Proxy Objects

- Message Delivery Semantics

#### Message Endpoint Proxy Objects

During message delivery, the resource adapter calls a method on the message endpoint factory it received during MDB activation, to retrieve proxy objects that are used to deliver messages. These proxy objects are instances of a class provided by OC4J that implements the following:

- The `javax.resource.spi.endpoint.MessageEndpoint` interface

- The message listener interface that the MDB implements

Because proxy objects implement the same listener interface as the MDB, the resource adapter can use custom methods of the listener interface to deliver messages.

As discussed in "Understanding Configuration for Use of Transactions in Message Delivery", message delivery can be either transacted (that is, messages are delivered within transactions) or non-transacted. If delivery is transacted, and the resource adapter passed an `XAResource` object when it retrieved the message endpoint proxy object, then the resource adapter will receive transaction notifications through the `XAResource` instance.

Use of the proxy objects between the resource adapter and the actual message endpoint (MDB) is necessary in case OC4J has to intercept message delivery for any reason, such as to inject a transaction or perform checks.

Notes: The message endpoint factory may choose to pool message endpoint proxy objects. The resource adapter calls a release method on a message endpoint proxy object when the object is no longer needed, restoring the proxy object into the pool if pooling is used. The message endpoint factory provides a utility method, `isDeliveryTransacted()`, for the resource adapter to use in determining if message deliveries will be transacted or not. This information helps the resource adapter to make runtime decisions or perform optimizations.

#### Message Delivery Semantics

When a resource adapter calls a method for message delivery (the method being specific to the message listener being used), the following must occur:

- The message must be delivered to the actual MDB instance, with any response being returned to the resource adapter.

- Exceptions during message delivery must be handled by OC4J and propagated to the resource adapter, as discussed in "Exceptions from MDB Listener Methods".

- Transaction semantics must be enforced according to the J2EE Connector Architecture Specification, as described in the text that follows.

The following scenarios are considered. (See "Understanding Configuration for Use of Transactions in Message Delivery" for related information about transaction settings.)

- Container-managed transaction (CMT) demarcation with a setting of `Required` in the MDB configuration, without imported transactions

- Container-managed transaction demarcation with a setting of `NotSupported` in the MDB configuration, without imported transactions

- Container-managed transaction demarcation with a setting of `Required`, with imported transactions

- Container-managed transaction demarcation with a setting of `NotSupported`, with imported transactions

- Bean-managed transaction (BMT) demarcation, without imported transactions

- Bean-managed transaction demarcation, with imported transactions

Furthermore, a resource adapter has the option of exerting control over transaction demarcation by using the `beforeDelivery()` and `afterDelivery()` methods (specified in the `MessageEndpoint` interface) of the message endpoint proxy objects. It can call `beforeDelivery()` before calling the message delivery method on the MDB, and call `afterDelivery()` afterward. We will refer to this as the "before/after" delivery option, and consider it for each of the preceding scenarios.

Independent of this, the resource adapter may choose to pass in an `XAResource` object, to be used for transaction notifications, whenever it retrieves a message endpoint proxy object.

Notes: For message delivery that is not transacted, the resource adapter considers a successful return of the message delivery method call to be confirmation of delivery. Any exception from the message endpoint proxy object is interpreted to indicate delivery failure. For message delivery that is transacted, a commit of the transaction is interpreted as confirmation of delivery. A rollback is interpreted to indicate delivery failure.

CMT with Required Setting, without Imported Transactions If the resource adapter does not use the before/after delivery option:

- OC4J starts a new transaction before each message delivery method call.

- If the resource adapter provided an `XAResource` object, all transaction notifications are sent to that object.

- OC4J completes the transaction after each message delivery method call.

If the resource adapter uses the before/after delivery option:

- OC4J starts the transaction when `beforeDelivery()` is called.

- If the resource adapter provided an `XAResource` object, all transaction notifications are sent to that object.

- OC4J completes the transaction when `afterDelivery()` is called.

CMT with NotSupported Setting, without Imported Transactions Regardless of whether the resource adapter uses the before/after delivery option:

- OC4J makes no attempt to start a transaction before the message delivery method call or when `beforeDelivery()` is called (as applicable).

- If the resource adapter provided an `XAResource` object, it is ignored.

- OC4J makes no attempt to complete any transaction after the message delivery method call or when `afterDelivery()` is called (as applicable).

CMT with Required Setting, with Imported Transactions Regardless of whether the resource adapter uses the before/after delivery option:

- OC4J does nothing regarding transactions before each message delivery method call or when `beforeDelivery()` is called (as applicable), because an imported transaction already exists.

- If the resource adapter provided an `XAResource` object, all transaction notifications (from the beginning of message delivery or the `beforeDelivery()` call, as applicable) are sent to that object.

- All work done by the MDB is included in the imported transaction.

- OC4J makes no attempt to complete the imported transaction after each message delivery method call or when `afterDelivery()` is called (as applicable), because completion is triggered by the external transaction manager through the resource adapter. OC4J may, however, mark the transaction for rollback based on exceptions that occurred during the call.

CMT with NotSupported Setting, with Imported Transactions If the resource adapter does not use the before/after delivery option:

- OC4J suspends the imported transaction before each message delivery method call.

- If the resource adapter provided an `XAResource` object, it is ignored.

- OC4J resumes the imported transaction after each message delivery method call.

If the resource adapter uses the before/after delivery option:

- OC4J suspends the imported transaction when `beforeDelivery()` is called.

- If the resource adapter provided an `XAResource` object, it is ignored.

- OC4J resumes the imported transaction when `afterDelivery()` is called.

BMT, without Imported Transactions Regardless of whether the resource adapter uses the before/after delivery option:

- OC4J makes no attempt to start, complete, suspend, or resume any transaction.

- If the resource adapter provided an `XAResource` object, it is ignored.

BMT, with Imported Transactions If the resource adapter does not use the before/after delivery option:

- OC4J suspends the imported transaction before each message delivery method call.

- If the resource adapter provided an `XAResource` object, it is ignored.

- OC4J resumes the transaction after each message delivery method call.

If the resource adapter uses the before/after delivery option:

- OC4J suspends the imported transaction when `beforeDelivery()` is called.

- If the resource adapter provided an `XAResource` object, it is ignored.

- OC4J resumes the imported transaction when `afterDelivery()` is called.

### MDB Deactivation

Endpoint deactivation is required whenever a resource adapter should stop delivering messages to an MDB, such as when the MDB application that is associated with the resource adapter is undeployed or stopped. Deactivation is handled by OC4J.

Specifically, OC4J calls a deactivation method on the appropriate resource adapter (an instance of a class that implements the SPI `ResourceAdapter` interface) to deactivate the MDB. In the deactivation method call, OC4J passes in the same activation configuration JavaBean instance and message endpoint factory instance that were used in activating the MDB.

## Special Conditions in Message Delivery

"Message Delivery" covered basic functionality. This section describes special conditions, particularly error conditions, during message delivery:

- Concurrent Message Delivery

- Exceptions from MDB Listener Methods

- Failure During Transacted Message Delivery

### Concurrent Message Delivery

During message delivery, after a resource adapter has retrieved one or more message endpoint proxy objects, the resource adapter has the option of using a single proxy object to serially deliver messages, or multiple proxy objects to deliver messages using different threads. This latter mode is known as concurrent delivery.

Note that the message delivery method call and the `beforeDelivery()` and `afterDelivery()` calls (if applicable) are all considered to be part of a single unit of message delivery and all must be called from a single thread.

OC4J supports concurrent delivery as long as a separate proxy object is used in each thread; however, it may attempt to limit the number of message endpoint proxy objects in simultaneous use by throwing `UnavailableException` errors during endpoint proxy creation.

OC4J does not support any attempt to concurrently deliver messages using the same endpoint proxy object in different threads. If work is started using a particular proxy object in one thread, the work cannot be handed off to another thread. An attempt to use the same proxy object in different threads results in an exception.

Note: For concurrent message delivery, OC4J maintains a pool of MDBs. Then `min-instances` and `max-instances` attributes in the `ejb-jar.xml` configuration file control the size of the pool.

### Exceptions from MDB Listener Methods

This section describes OC4J action in handling exceptions from the message listener method of an MDB, considering the following scenarios:

- Container-managed transaction demarcation with the MDB method running in a transaction context (the case for an MDB `Required` setting)

- Container-managed transaction demarcation with the MDB method running in an unspecified transaction context (the case for an MDB `NotSupported` setting)

- Bean-managed transaction demarcation

CMT with MDB Required Setting For an application exception (`AppException`), OC4J generally attempts to commit the transaction and throw the exception to the resource adapter. However, if the MDB has specified that the only possible outcome of the transaction is a rollback (through the `setRollbackOnly()` method of a `UserTransaction` object on OC4J), then the transaction is rolled back before the exception is thrown to the resource adapter.

For a system exception, OC4J does the following:

- Logs the error.

- Rolls back the transaction.

- Discards the MDB instance (meaning no further methods will be invoked on that instance).

- Throws the exception to the resource adapter after wrapping it in an EJB exception (`EJBException`).

CMT with MDB NotSupported Setting For an application exception, OC4J throws the exception to the resource adapter.

For a system exception, OC4J does the following:

- Logs the error.

- Discards the MDB instance.

- Throws the exception to the resource adapter after wrapping it in an EJB exception.

BMT For an application exception, OC4J throws the exception to the resource adapter.

For a system exception, OC4J does the following:

- Logs the error.

- Marks the transaction for rollback if it was started but not yet completed.

- Discards the MDB instance.

- Throws the exception to the resource adapter after wrapping it in an EJB exception.

### Failure During Transacted Message Delivery

This section describes recovery from failure during transacted message delivery, both for transactions managed by OC4J and for imported transactions.

#### Message Redelivery for Transactions Managed by OC4J

In case of OC4J system failure during transacted message delivery, where the transaction was started by OC4J, there is functionality to notify message providers about the outcomes of all deliveries that were in progress during the failure and are in doubt (prepared but not committed). Recovery is initiated by OC4J. It is left to the message providers to decide if they should attempt redelivery.

Once OC4J is running again, it executes the following recovery steps:

- Restarts the resource adapter instances that were running.

- Obtains an array of `XAResource` objects from each resource adapter, with each object representing a resource manager. In obtaining this array, OC4J passes an array of activation configuration JavaBean instances to each resource adapter, where each activation configuration JavaBean corresponds to an MDB application that was running at the time of system failure.

- Processes the array of `XAResource` objects to create a subset where each object represents a unique resource manager. (Because multiple resource adapters may use the same resource manager, the initial array of `XAResource` objects may have multiple objects corresponding to the same resource manager.)

- Calls methods on each `XAResource` object to query each resource manager for the list of transactions that had been prepared but not yet committed, then completes each such transaction with a commit or rollback call, as appropriate.

#### Message Redelivery for Imported Transactions

The J2CA specification considers the scenarios that follow for recovery processing from failure during an imported transaction. Recovery is initiated by the EISs through their resource adapters. Note that for imported transactions, OC4J can recover a transaction; however, because it is not the transaction coordinator, it cannot complete the transaction without instruction from the transaction initiator.

An EIS, through its resource adapter, uses the OC4J implementation of the SPI `XATerminator` interface for transaction completion and recovery. This interface includes the methods `prepare()`, `commit()`, `rollback()`, and `recover()`.

For the following discussion, an "active" transaction is one that was not yet prepared, and an "in doubt" transaction is one that was successfully prepared but not yet committed.

If OC4J failure is discovered by the EIS while the transaction is active: The transactional work is presumed aborted. The EIS makes no attempt to wait for OC4J or to attempt recovery processing.

If OC4J failure is discovered by the EIS while the transaction is in doubt: The EIS attempts to complete the transaction. To accomplish this, it attempts to reestablish network connectivity with OC4J until it succeeds. When OC4J recovers, it determines the state of the transaction and completes it as appropriate.

The following specific steps, in accordance with the J2CA specification, are executed in this scenario:

- When OC4J recovers, it restarts the resource adapter that imported the transaction.

- The resource adapter obtains an `XATerminator` object from OC4J.

- The resource adapter re-establishes communication with the EIS.

- The EIS, acting as the transaction coordinator, instructs the resource adapter regarding whether the transaction should be committed or rolled back, and provides the transaction ID through a `javax.transaction.xa.Xid` instance.

- The resource adapter notifies OC4J of the decision to commit or roll back the transaction by calling the `commit()` or `rollback()` method of the `XATerminator` object, passing in the transaction ID.

- OC4J commits or rolls back, as appropriate, all work done on behalf of the transaction.

If EIS failure is discovered by the resource adapter while the transaction is active: The resource adapter aborts it.

If EIS failure is discovered by the resource adapter while the transaction is in doubt: The resource adapter waits for the EIS to recover. When the EIS recovers, it re-establishes network connectivity with the resource adapter and completes the transaction.

The following specific steps, in accordance with the J2CA specification, are executed in this scenario:

- When the EIS recovers, OC4J re-establishes communication.

- The EIS instructs the resource adapter to obtain a list of in-doubt transactions that were imported from the EIS into OC4J.

- The resource adapter obtains a list of transaction IDs (`Xid` instances) of in-doubt transactions. It accomplishes this by calling the `recover()` method of an `XATerminator` object previously obtained.

- The resource adapter forwards the list of transaction IDs to the EIS.

- The EIS, acting as the transaction coordinator, decides for each transaction whether the transaction should be committed or rolled back, and informs the resource adapter of this decision.

- For each transaction, the resource adapter calls the `XATerminator` `commit()` or `rollback()` method, as appropriate, passing the transaction ID.

- OC4J commits or rolls back, as appropriate, all work performed on behalf of the transaction.