Java EE XA Recovery Example

This example will demonstrate XA recovery in WildFly with a ActiveMQ XA resource and a "buggy" XA resource.

The example application will invoke an EJB which will send a JMS message in a transaction. The server will crash while the transaction has not been committed (it is in the prepared state).
On server restart, the transaction will be recovered and the JMS message will finally be sent.
The example application will then receive the message.

The example leverages the JBoss Arquillian framework to run a WildFly instance and deploy the MDB.

XA Recovery configuration

In previous versions of JBoss Application Server (the precursor to WildFly) the XA recovery configuration was manual. However, in WildFly the XA recovery configuration is completely automated.

Example step-by-step

download WildFly 8.0.0.Final from here and install.

set the JBOSS_HOME property to point to the WildFly install directory

type mvn verify from the example directory to run

The example code is composed of 3 main classes:

XARecoveryExampleStepOne and XARecoveryExampleStepTwo

the client application to invoke the EJB and receive the message

XARecoveryExampleBean

a Stateless EJB3 which performs all the XA logic

Example Application

Let's take a look at XARecoveryExampleStepOne first.

1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the jndi.properties

             
                 Properties env = new Properties();
                 env.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
                 initialContext = new InitialContext(env);
             
         

2. We look up the EJB

             XARecoveryExampleService service = (XARecoveryExampleService) initialContext.lookup("ejb:/test//XARecoveryExampleBean!org.apache.activemq.javaee.example.server.XARecoveryExampleService");
         

3. We invoke the EJB's send method. This method will send a JMS text message (with the text passed in parameter) and crash the server when committing the transaction

             String message = "This is a text message sent at " + new Date();
             System.out.println("invoking the EJB service with text: " + message);
             try
             {
                service.send(message);
             }
             catch (Exception e)
             {
                System.out.println("#########################");
                System.out.println("The server crashed: " + e.getMessage());
                System.out.println("#########################");
             }
         

At that time, the server is crashed and is automatically restarted by the test runner (i.e. XARecoveryRunnerTest).

Let's take a look at XARecoveryExampleStepTwo now.

1. We will try to receive a message. Once the server is restarted, the message will be recovered and the consumer will receive it.

            boolean received = false;
            while (!received)
            {
               try
               {
                  Thread.sleep(15000);
                  receiveMessage();
                  received = true;
               }
               catch (Exception e)
               {
                  System.out.println(".");
               }
            }
         

The receiveMessage() method contains code to receive a text message from the JMS Queue and display it.

2. And finally, always remember to close your resources after use, in a finally block.

             finally
             {
                if (initialContext != null)
                {
                  initialContext.close();
                }
             }
          

Let's now take a look at the EJB example

In order to crash the server while a transaction is prepared, we will use a failing XAResource which will crash the server (calling Runtime.halt()) in its commit phase.

We will manage ourselves the transaction and its resources enlistment/delistment to be sure that the failing XAResource will crash the server after the JMS XA resources is prepared but before it is committed.

1. First, we create a new initial context

             ic = new InitialContext();
        

2. We look up the Transaction Manager

             TransactionManager tm = (TransactionManager)ic.lookup("java:/TransactionManager");
        

3. We look up the JMS XA Connection Factory (which is bound to java:/JmsXA)

             XAConnectionFactory cf = (XAConnectionFactory)ic.lookup("java:/JmsXA");
        

4. We look up the JMS Queue

             Queue queue = (Queue)ic.lookup("queue/testQueue");
        

5. We create a JMS XA connection, a XA session and a message producer for the queue

             xaConnection = xacf.createXAConnection();
             XASession session = xaConnection.createXASession();
             MessageProducer messageProducer = session.createProducer(queue);
        

6. We create a FailingXAResource. For this example purpose, this XAResource implementation will call Runtime.halt() from its commit() method

             XAResource failingXAResource = new FailingXAResource();
         

7. We begin the transaction and retrieve it from the transaction manager

             tm.begin();
             Transaction tx = tm.getTransaction();
         

8. We enlist the failing XAResource

             tx.enlistResource(failingXAResource);
         

9. We enlist the JMS XA Resource

             tx.enlistResource(session.getXAResource());
         

10. We create a text message with the text passed in parameter of the EJB method and send it

             TextMessage message = session.createTextMessage(text);
             messageProducer.send(message);
             System.out.format("Sent message: %s (%s)\n", message.getText(), message.getJMSMessageID());
         

11. We delist the failing XAResource

             tx.delistResource(failingXAResource);
         

12. We delist the JMS XA Resource

             tx.delistResource(session.getXAResource());
         

13. We commit the transaction

             System.out.println("committing the tx");
             tx.commit();
         

When the transaction is committed, it will prepare both XAResources and then commit them.


The failing resources will crash the server leaving the JMS XA Resource prepared but not committed

When WildFly is restarted, it will automatically trigger a recovery phase. During that phase, ActiveMQ resources will be scanned and the prepared transaction will be recovered and committed. It is then possible to consume this message