Version 2

    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.




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





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



    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.




    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 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







    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




    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




    which controls the ManagedConnectionFactory for the resource adapter.




    We will make the following changes:


    Add support for the new fields in jboss-ds_5_1.dtd / jboss-ds_6_0.dtd
    will represent recover-security-domain.
     * 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
     * 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.




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