Steps for Performing XA Transactions

The following basic steps are required for a client to perform an XA transaction using the Solace JMS implementation.

1. Obtain an XA Connection Factory and use it to create an XA Connection to the event broker.

   The XA Connection Factory used must have its xa messaging property enabled to allow JMS connections created by the XA Connection Factory to support XA sessions. Its direct‑transport transport property should also be disabled to only allow Guaranteed (that is, messages with a Persistent or Non‑Persistent delivery mode) messages to be published or received.

   For information on how to programmatically create or look up Connection Factories, and how to establish a connection, refer to Establishing Connections.

   • A SolXAConnectionFactory, a Solace-proprietary implementation of the standard JNDI ConnectionFactory is properly configured for performing XA transactions on an event broker.
   • To establish a JMS connection that permits transacted sessions and XA transactions, the connection must also use a client username account provisioned on the event broker that is assigned a client profile that has the allow‑transacted‑sessions property enabled (by default, this property is not enabled). For information on how administrators may configure client usernames and the client profiles that are assigned to them, refer to Configuring Client Authentication.
2. Create an XA Session (refer to Creating XA Sessions).
3. Within the XA Session, a client can do one or both of the following:
• acquire a message producer that can be used to publish messages to a destination topic or queue
• acquire a message consumer or topic subscriber that can be used to receive messages
4. Obtain an XA Resource for the XA Session.

   The XAResource enables a client to control the state of transactions associated with the XA Session (refer to Performing XA Transaction Operations).

   Typically, a Transaction Manager within an Application Server uses the methods provided by the XAResource to control the transaction operations.

5. Obtain unique Xids to identify each transaction branch created in the XA Session and the global transaction they are associated with.

   The combination of the format identifier, global transaction identifier, and branch qualifier must be globally unique for each Xid within the Message VPN the XA Session is connected to. Typically, a Transaction Manager provides the Xids.

6. Start a transaction branch within the XA Session (refer to ). Only one transaction can be active associated at a time in an XA Session.

   After XAResource.start(...) is called, any messages published by a producer in an XA Session are transacted messages.

7. Do one or both of the following:
   • Using the acquired publisher, publish messages that you want to include in the transaction branch. Refer to Publishing Messages in XA Transactions.
   • Using the acquired message consumer or topic subscriber, consume messages that you want to include in the transaction branch. Refer to Consuming Messages in XA Transactions.

   Messages that are published and received in a transaction branch are staged on the event broker. Up to 256 messages can be included in a transaction branch.

8. Call XAResource.end(...) to end the transaction branch. This ends the work performed on behalf of the transaction branch. The event broker, as the Resource Manager, disassociates the XA Session from the transaction branch, which allows the transaction to complete.

   XAResource.end(...) can also be used to suspend a transaction branch.

9. Call XAResource.prepare(...) to prepare the transaction for a commit or rollback.
10. If the transaction is successfully prepared, do one of the following:
• Repeat steps 6 through 10 for each additional transaction to be performed in the XA Session.
• When finished, follow the instructions in Closing XA Sessions to close the XA Session.

It is also possible for event broker administrators to manually perform the following heuristic operations: to delete an XA Session or to commit, rollback, or delete an XA transaction branch. For more information, refer to Performing Heuristic Actions on Transactions.