XA Recovery in the JCA layer

This page describes the design of how the JCA layer registers XA datasource for XA Resource Recovery with the JBoss TS project.

Goals

The goal of the feature is to register XA datasource with the JBoss TS project through the

org.jboss.tm.XAResourceRecovery

interface.

This is done by register the component that implements the above with the

org.jboss.tm.XAResourceRecoveryRegistry

component through its addXAResourceRecovery() / removeXAResourceRecovery() methods.

The XAResourceRecovery interface contains the method

/**
 * Provides XAResource(s) to the transaction system for recovery purposes.
 *
 * @return An array of XAResource objects for use in transaction recovery
 * In most cases the implementation will need to return only a single XAResource in the array.
 * For more sophisticated cases, such as where multiple different connection types are supported,
 * it may be necessary to return more than one.
 *
 * The Resource should be instantiated in such a way as to carry the necessary permissions to
 * allow transaction recovery. For some deployments it may therefore be necessary or desirable to
 * provide resource(s) based on e.g. database connection parameters such as username other than those
 * used for the regular application connections to the same resource manager. 
 */
public XAResource[] getXAResources()

which must return a single XAResource that represents the datasource.

Requirements

The JCA specification states that XA recovery is done through

ManagedConnection mc = mcf.createManagedConnection(subject, null)

where "mcf" is the ManagedConnectionFactory and "subject" represents the javax.security.auth.Subject instance.

This ties into the above with

XAResource xaResource = mc.getXAResource()

In order to provide additional information to JBoss TS we can use an instance
of the

org.jboss.tm.XAResourceWrapper

interface.

Design

First some considerations:

• The current JCA container is based on the JBoss JMX architecture, so we must use a mix of JBoss Microcontainer and JBoss JMX in order to implement this feature.
• We must create a new -ds.xml which can contain the needed security information for recovery.
• We should keep changes as local as possible such that the patch overhead is minimal.

MC vs. JMX

We will bridge the JBoss Microcontainer components with the JBoss JMX components using
the

org.jboss.system.metadata

package in our builders.

New -ds.xml file

We will create a jboss-ds_5_1.dtd (EAP 5.1) / jboss-ds_6_0.dtd (AS 6) which has the additional fields of

• recover-user-name
• recover-password
• recover-security-domain
• no-recover

The first two will represent a user and password pair which has the credentials to perform the recovery operation. The third likewise, but using a security domain instead. The last field is to exclude a datasource from recovery.

The fields should have a fall back value of their non-recover counterparts - e.g. user-name, password and security-domain.

Minimal changes

We should limit the main changes to

org.jboss.resource.connectionmanager.ManagedConnectionFactoryDeployment

which controls the ManagedConnectionFactory for the resource adapter.

Implementation

We will make the following changes:

org/jboss/resource/metadata/mcf/XADataSourceDeploymentMetaData

Add support for the new fields in jboss-ds_5_1.dtd / jboss-ds_6_0.dtd

org/jboss/resource/metadata/mcf/RecoverSecurityDomainMetaData

will represent recover-security-domain.

org/jboss/resource/deployers/builder/ManagedConnectionFactoryBuilder

 * Make the "SubjectFactory" MC bean a required dependency
 * Make the "jboss:service=TransactionManager" JMX bean a required dependency (EAP)
 * Make the "RecoveryManager" MC bean a required dependency (AS)

* Pass the JMX ObjectName for the connection manager to the generated 
   ManagedConnectionFactoryDeployment in the constructor

org/jboss/resource/connectionmanager/ManagedConnectionFactoryDeployment

 * startService()

   * If XA datasource and XAResourceRecovery is defined

     * Extract the recover user name, password and security domain from the configuration
     * Fall back to standard values
     * Register with XAResourceRecovery

 * stopService()

   * If we are registered for recovery

     * Unregister with XAResourceRecovery

 * getXAResources()

   * Get the subject
   * Get the ManagedConnection
   * Get the XAResource
   * If possible create a XAResourceWrapperImpl based on the values from the connection manager
   * Return

 * getSubject()

   * If no security domain is defined 

     * Create a SimplePrincipal
     * Create a PasswordCredential
     * Assign ManagedConnectionFactory to PasswordCredential
     * Add above to Subject
     * Return

   * If security domain is defined

     * Use Unauthenticated subject to access security domain
     * Get Subject from security domain
     * Return

The implementation can be tested using the XA recovery test cases in the JBoss Application Server test suite.

Availability

• JBoss Enterprise Application Platform 5.1 or higher
• JBoss Application Server 6.0.0.M4 or higher