|
Oracle® Containers for J2EE Resource Adapter Administrator's Guide
10g Release 3 (10.1.3) B14436-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Resource Adapter Administrator's Guide
10g Release 3 (10.1.3) B14436-01 |
|
|
Previous |
Next |
This chapter describes concepts 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:
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
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
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.
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.
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.
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.
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.
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 rest of this section discusses the following topics:
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:
|
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:
|
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".
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:
In the Applications tab of the OC4J Home page, choose the desired application.
In the resulting Application Home page, choose the desired EJB module.
In the EJBs tab of the resulting EJB Module page, under Message Driven Beans, choose the appropriate MDB.
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.
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.
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 |
|
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 |
Under the appropriate |
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 .
This section discusses the key phases and functionality of the lifecycle for message-listening, covering the following topics:
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 theejb-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.
|
This section discusses the following aspects of message delivery functionality:
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:
|
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:
|
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.
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.
"Message Delivery" covered basic functionality. This section describes special conditions, particularly error conditions, during 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. Thenmin-instances and max-instances attributes in the ejb-jar.xml configuration file control the size of the pool.
|
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.
This section describes recovery from failure during transacted message delivery, both for transactions managed by OC4J and for imported transactions.
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.
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.
