Chapter 10 Using the Transaction Service

The Java EE platform provides several abstractions that simplify development of dependable transaction processing for applications. This chapter discusses Java EE transactions and transaction support in the Sun GlassFish Enterprise Server.

This chapter contains the following sections:

• Transaction Scope

• Configuring the Transaction Service

• The Transaction Manager, the Transaction Synchronization Registry, and UserTransaction

For more information about the Java^TM Transaction API (JTA) and Java Transaction Service (JTS), see the following sites: http://java.sun.com/products/jta/ and http://java.sun.com/products/jts/.

You might also want to read “Chapter 35: Transactions” in the Java EE 5 Tutorial.

For information about JDBC transaction isolation levels, see Using JDBC Transaction Isolation Levels.

For GlassFish v3 Prelude, global (XA) transactions are not supported unless the optional JTS add-on component, including the dependent Object Management Group (OMG) subcomponent, is downloaded from the Update Tool. Without this add-on component, only local transactions are supported. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

Transaction recovery is not implemented for GlassFish v3 Prelude, even if the JTS and OMG add-on components are installed. Therefore, all transaction service attributes and properties pertaining to transaction recovery or transaction logs are not implemented.

Transaction Scope

A local transaction involves only one non-XA resource and requires that all participating application components execute within one process. Local transaction optimization is specific to the resource manager and is transparent to the Java EE application.

In the Enterprise Server, a JDBC resource is non-XA if it meets any of the following criteria:

• In the JDBC connection pool configuration, the DataSource class does not implement the javax.sql.XADataSource interface.

• The Global Transaction Support box is not checked, or the Resource Type setting does not exist or is not set to javax.sql.XADataSource.

A transaction remains local if the following conditions remain true:

• One and only one non-XA resource is used. If any additional non-XA resource is used, the transaction is aborted.

• No transaction importing or exporting occurs.

Transactions that involve multiple resources are global transactions. A global transaction can involve one non-XA resource if last agent optimization is enabled. Otherwise, all resourced must be XA. The use-last-agent-optimization property is set to true by default. For details about how to set this property, see Configuring the Transaction Service.

For GlassFish v3 Prelude, transaction propagation between multiple participant processes, applications, or JVM machines is not supported.

If only one XA resource is used in a transaction, one-phase commit occurs, otherwise the transaction is coordinated with a two-phase commit protocol.

A two-phase commit protocol between the transaction manager and all the resources enlisted for a transaction ensures that either all the resource managers commit the transaction or they all abort. When the application requests the commitment of a transaction, the transaction manager issues a PREPARE_TO_COMMIT request to all the resource managers involved. Each of these resources can in turn send a reply indicating whether it is ready for commit (PREPARED) or not (NO). Only when all the resource managers are ready for a commit does the transaction manager issue a commit request (COMMIT) to all the resource managers. Otherwise, the transaction manager issues a rollback request (ABORT) and the transaction is rolled back.

Configuring the Transaction Service

You can configure the transaction service in the Enterprise Server in the following ways:

• To configure the transaction service, use the asadmin set command to set the following attributes and properties.

  server-config.transaction-service.automatic-recovery = false
  server-config.transaction-service.heuristic-decision = rollback
  server-config.transaction-service.keypoint-interval = 2048
  server-config.transaction-service.retry-timeout-in-seconds = 600
  server-config.transaction-service.timeout-in-seconds = 0
  server-config.transaction-service.tx-log-dir = domain-dir/logs
  server-config.transaction-service.property.use-last-agent-optimization = true

  You can use the asadmin get command to list all the transaction service attributes and properties. For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

Changing keypoint-interval, retry-timeout-in-seconds, or timeout-in-seconds does not require a server restart. Changing other attributes or properties requires a server restart.

Transaction recovery is not implemented for GlassFish v3 Prelude, even if the JTS and OMG add-on components are installed. Therefore, all transaction service attributes and properties pertaining to transaction recovery or transaction logs are not implemented.

The Transaction Manager, the Transaction Synchronization Registry, and UserTransaction

To access a UserTransaction instance, you can either look it up using the java:comp/UserTransaction JNDI name or inject it using the @Resource annotation.

If you need to access the javax.transaction.TransactionManager implementation, you can look up the Enterprise Server implementation of this interface using the JNDI name java:appserver/TransactionManager. If possible, you should use the javax.transaction.TransactionSynchronizationRegistry interface instead, for portability. You can look up the implementation of this interface by using the JNDI name java:comp/TransactionSynchronizationRegistry. For details, see the Javadoc page for Interface TransactionSynchronizationRegistry and Java Specification Request (JSR) 907.