12.7. Use JTA Transactions

1. Get an instance of UserTransaction.

   You can get the instance using JNDI, injection, or an EJB's context, if the EJB uses bean-managed transactions, by means of a @TransactionManagement(TransactionManagementType.BEAN) annotation.

   • JNDI

     new InitialContext().lookup("java:comp/UserTransaction")

   • Injection

     @Resource UserTransaction userTransaction;

   • Context

     • In a stateless/stateful bean:

       @Resource SessionContext ctx;
       ctx.getUserTransaction();

     • In a message-driven bean:

       @Resource MessageDrivenContext ctx;
       ctx.getUserTransaction()

2. Call UserTransaction.begin() after you connect to your datasource.

   ...
   try {
       System.out.println("\nCreating connection to database: "+url);
       stmt = conn.createStatement();  // non-tx statement
       try {
           System.out.println("Starting top-level transaction.");
           userTransaction.begin();
           stmtx = conn.createStatement(); // will be a tx-statement
           ...
       }
   }
   

1. Call the commit() method on the UserTransaction.

   When you call the commit() method on the UserTransaction, the Transaction Manager attempts to commit the transaction.

   @Inject
   private UserTransaction userTransaction;
   
   public void updateTable(String key, String value)
       EntityManager entityManager = entityManagerFactory.createEntityManager();
       try {
           userTransaction.begin():
           <!-- Perform some data manipulation using entityManager -->
           ...
           // Commit the transaction
           userTransaction.commit();
       } catch (Exception ex) {
           <!-- Log message or notify Web page -->
           ...
           try {
               userTransaction.rollback();
           } catch (SystemException se) {
               throw new RuntimeException(se);
           }
           throw new RuntimeException(e);
       } finally {
           entityManager.close();
       }
   }
   

2. If you use Container Managed Transactions (CMT), you do not need to manually commit.

   If you configure your bean to use Container Managed Transactions, the container will manage the transaction lifecycle for you based on annotations you configure in the code.

   @PersistenceContext
   private EntityManager em;
   
   @TransactionAttribute(TransactionAttributeType.REQUIRED)
   public void updateTable(String key, String value)
     <!-- Perform some data manipulation using entityManager -->
     ...
   }
   

1. Call the rollback() method on the UserTransaction.

   When you call the rollback() method on the UserTransaction, the Transaction Manager attempts to roll back the transaction and return the data to its previous state.

    
   @Inject
   private UserTransaction userTransaction;
   
   public void updateTable(String key, String value)
       EntityManager entityManager = entityManagerFactory.createEntityManager();
       try {
           userTransaction.begin():
           <!-- Perform some data manipulation using entityManager -->
             ...
             // Commit the transaction
           userTransaction.commit();
       } catch (Exception ex) {
           <!-- Log message or notify Web page -->
           ...
           try {
               userTransaction.rollback();
           } catch (SystemException se) {
               throw new RuntimeException(se);
           }
           throw new RuntimeException(e);
       } finally {
           entityManager.close();
       }
   }
   

2. If you use Container Managed Transactions (CMT), you do not need to manually roll back the transaction.

   If you configure your bean to use Container Managed Transactions, the container will manage the transaction lifecycle for you based on annotations you configure in the code.

   Note

   Rollback for CMT occurs if RuntimeException is thrown. You can also explicitly call the setRollbackOnly method to gain the rollback. Or, use the @ApplicationException(rollback=true) for application exception to rollback.

Procedure 12.5. Handle a heuristic outcome in a transaction

1. Determine the cause

   The over-arching cause of a heuristic outcome in a transaction is that a resource manager promised it could commit or roll-back, and then failed to fulfill the promise. This could be due to a problem with a third-party component, the integration layer between the third-party component and JBoss EAP 6, or JBoss EAP 6 itself.
   By far, the most common two causes of heuristic errors are transient failures in the environment and coding errors in the code dealing with resource managers.

2. Fix transient failures in the environment

   Typically, if there is a transient failure in your environment, you will know about it before you find out about the heuristic error. This could be a network outage, hardware failure, database failure, power outage, or a host of other things.
   If you experienced the heuristic outcome in a test environment, during stress testing, it provides information about weaknesses in your environment.

   Warning

   JBoss EAP 6 will automatically recover transactions that were in a non-heuristic state at the time of the failure, but it does not attempt to recover heuristic transactions.

3. Contact resource manager vendors

   If you have no obvious failure in your environment, or the heuristic outcome is easily reproducible, it is probably a coding error. Contact third-party vendors to find out if a solution is available. If you suspect the problem is in the transaction manager of JBoss EAP 6 itself, contact Red Hat Global Support Services.

4. In a test environment, delete the logs and restart JBoss EAP 6.

   In a test environment, or if you do not care about the integrity of the data, deleting the transaction logs and restarting JBoss EAP 6 gets rid of the heuristic outcome. The transaction logs are located in EAP_HOME/standalone/data/tx-object-store/ for a standalone server, or EAP_HOME/domain/servers/SERVER_NAME/data/tx-object-store in a managed domain, by default. In the case of a managed domain, SERVER_NAME refers to the name of the individual server participating in a server group.

   Note

   The location of the transaction log also depends on the object store in use and the values set for the oject-store-relative-to and object-store-path parameters. For file system logs (such as a standard shadow and HornetQ logs) the default direction location is used, but when using a JDBC object store, the transaction logs are stored in a database.

5. Resolve the outcome by hand

   The process of resolving the transaction outcome by hand is very dependent on the exact circumstance of the failure. Typically, you need to take the following steps, applying them to your situation:
   1. Identify which resource managers were involved.
   2. Examine the state in the transaction manager and the resource managers.
   3. Manually force log cleanup and data reconciliation in one or more of the involved components.
   The details of how to perform these steps are out of the scope of this documentation.