JMS XA Heuristic Example

This example shows you how to make an XA heuristic decision through the ActiveMQ Artemis Management Interface.

A heuristic decision is a unilateral decision to commit or rollback an XA transaction branch after it has been prepared.

In this example we simulate a transaction manager to control the transactions. First we create an XASession and enlist it in a transaction through its XAResource. We then send a text message, 'hello' and end/prepare the transaction on the XAResource, but neither commit nor roll back the transaction. Another transaction is created and associated with the same XAResource, and a second message, 'world' is sent on behalf of the second transaction. Again we leave the second transaction in prepare state. Then we get the MBeanServerConnection object to manipulate the prepared transactions. To illustrate, we roll back the first transaction but commit the second. This will result in that only the message 'world' is received.

This example uses JMX to manipulate transactions in a ActiveMQ Artemis Server. For details on JMX facilities with ActiveMQ Artemis, please look at the JMX Example.

Example step-by-step

To run the example, simply type mvn verify -Pexample from this directory

  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 client-jndi.properties file in the directory ../common/config
    2.            InitialContext initialContext = getContext(0);
  2. We look-up the JMS queue object from JNDI
    3.            Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
  3. We perform a lookup on the XA Connection Factory
    4.            XAConnectionFactory cf = (XAConnectionFactory) initialContext.lookup("/XAConnectionFactory");
  4. We create a JMS XAConnection
    5.            connection = cf.createXAConnection();
  5. We Start the connection
    6.            connection.start();
  6. We create a JMS XASession
    7.           XASession xaSession = connection.createXASession();
  7. We create a normal session
    8.           Session normalSession = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
  8. We create a normal Message Consumer
    9.            
           MessageConsumer normalConsumer = normalSession.createConsumer(queue);
           normalConsumer.setMessageListener(new SimpleMessageListener());
  9. We get the JMS Session
    10.           Session session = xaSession.getSession();
  10. We create a message producer
    11.           MessageProducer producer = session.createProducer(queue);
  11. We create two Text Messages
    12.           
          TextMessage helloMessage = session.createTextMessage("hello");
          TextMessage worldMessage = session.createTextMessage("world");
  12. We create a transaction
    13.           Xid xid1 = new XidImpl("xa-example1".getBytes(), 1, UUIDGenerator.getInstance().generateStringUUID().getBytes());
  13. We get the JMS XAResource
    14.           XAResource xaRes = xaSession.getXAResource();
  14. We begin the Transaction work
    15.           xaRes.start(xid1, XAResource.TMNOFLAGS);
  15. We do work, sending hello message.
    16.           
          normalProducer.send(helloMessage);
  16. We stop the work for xid1
    17.           xaRes.end(xid1, XAResource.TMSUCCESS);
  17. We prepare xid1
    18.           xaRes.prepare(xid1);
  18. We check the none should be received.
    19.           checkNoMessageReceived();
  19. We create another transaction 
    20.           Xid xid2 = new XidImpl("xa-example2".getBytes(), 1, UUIDGenerator.getInstance().generateStringUUID().getBytes());
  20. We begin the transaction work
    21.           xaRes.start(xid2, XAResource.TMNOFLAGS);
  21. We send the second message
    22.            producer.send(worldMessage);
  22. We stop the work for xid2
    23.           xaRes.end(xid2, XAResource.TMSUCCESS);
  23. We prepare xid2
    24.           xaRes.prepare(xid2);
  24. Again, no messages should be received!
    25.           checkNoMessageReceived();
  25. We create JMX Connector to connect to the server's MBeanServer.
    26.           
          JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());
  26. We retrieve the MBeanServerConnection
    27.           MBeanServerConnection mbsc = connector.getMBeanServerConnection();
  27. We list the prepared transactions
    28.           
          ObjectName serverObject = ObjectNameBuilder.DEFAULT.getMessagingServerObjectName();
          String[] infos = (String[])mbsc.invoke(serverObject, "listPreparedTransactions", null, null);
         
          System.out.println("Prepared transactions: ");
          for (String i : infos)
          {
             System.out.println(i);
          }
  28. We roll back the first transaction
    29.           mbsc.invoke(serverObject, "rollbackPreparedTransaction", new String[] {XidImpl.toBase64String(xid1)}, new String[]{"java.lang.String"});
  29. We commit the second one
    30.           mbsc.invoke(serverObject, "commitPreparedTransaction", new String[] {XidImpl.toBase64String(xid2)}, new String[]{"java.lang.String"});
  30. We check the result, only the 'world' message received
    31.           checkMessageReceived("world");
  31. We check the prepared transaction again, should have none.
    32.           
          infos = (String[])mbsc.invoke(serverObject, "listPreparedTransactions", null, null);
          System.out.println("No. of prepared transactions now: " + infos.length);
  32. We close the JMX connector.
    33.           connector.close();
  33. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
    34.            finally
           {
              if (initialContext != null)
              {
                initialContext.close();
              }
              if (connection != null)
              {
                 connection.close();
              }
           }