Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to J2EE Services and APIs

> ## Chapter 3
> Using the Transaction Service

> The J2EE™ platform provides several abstractions that simplify development of dependable transaction processing for applications. This chapter discusses J2EE transactions and transaction support in the Sun Java™ System Application Server.

> This chapter contains the following sections:

> - Introducing Transactions
> - Configuring the Transaction Service
> - Looking Up a Transaction
> - Transaction Logging
> - Sample Applications

> ##

> Introducing Transactions

> The purpose of a transaction is to ensure that data is updated in an all-or-nothing fashion. For example, a message is either delivered or not delivered. A transaction has these four characteristics.

> - Atomicity - A transaction can end in two ways: with a commit or a rollback. When a transaction is committed, modifications made to the data within the transaction boundaries are saved and made permanent. When a transaction is rolled back, all modifications made to the data are undone.
> - Consistency - If a transaction fails, data integrity is preserved.
> - Isolation - Phases in a transaction cannot be observed by other applications and threads until the transaction is committed or rolled back.
> - Durability - Committed changes can survive system failures.

> In addition, J2EE transaction semantics do not support nested transactions. You must commit or roll back a transaction before you can begin another one.

> For more information about the Java™ Transaction API (JTA) and Java™ Transaction Service (JTS), see the Sun Java System Application Server Administrator’s Guide and the following sites:

> http://java.sun.com/products/jta/

> http://java.sun.com/products/jts/

> You may also want to read the chapter on transactions in the J2EE tutorial:

> http://java.sun.com/j2ee/tutorial/1_3-fcs/index.html

> This section covers the following topics:

> - Transaction Resource Managers
> - Transaction Scope
> - Transaction Management
> - Transaction Recovery

> ### Transaction Resource Managers

> There are three types of transaction resource managers:

> - Databases - Use of transactions prevents databases from being left in inconsistent states due to incomplete updates. Sun Java System Application Server supports a variety of JDBC™ XA drivers, listed in “Configurations for Specific JDBC Drivers” on page 28. For information about JDBC transaction isolation levels, see “Using JDBC Transaction Isolation Levels” on page 44.
> - Java™ Message Service (JMS) Providers - Use of transactions ensures that messages are reliably delivered. Sun Java System Application Server is integrated with Sun Java System Message Queue, a fully capable JMS provider. For more information about transactions and the JMS API, see “Using Transactions for Message Acknowledgement” on page 90.
> - J2EE™ Connector Architecture (CA) components - Use of transactions prevents legacy EIS systems from being left in inconsistent states due to incomplete updates. For more information about J2EE CA connectors, see the Sun Java System Application Server J2EE CA Service Provider Implementation Administrator’s Guide.

> For details about how transaction resource managers, the transaction service, and applications interact, see the Sun Java System Application Server Administrator’s Guide.

> ### 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 J2EE application.

> In Sun Java System Application 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 res-type attribute in server.xml 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 or XA resource is used, the transaction is aborted.
> - No transaction importing or exporting occurs.

> If the transaction timeout is greater than zero:

> - If the resource involved is non-XA, this resource is wrapped in a Sun Java System XA wrapper, and the global transaction infrastructure is used.
> - If the resource involved is XA, it is like any other global transaction.

> Transactions that involve multiple resources (which must all be XA), or multiple participant processes, are distributed or global transactions.

> 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 may 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.

> ### Transaction Management

> Sun Java System Application Server supports both types of transaction management:

> - Container-Managed Transactions
> - Component-Managed Transactions

> These sections provide brief summaries. For more information, see the Sun Java System Application Server Administrator’s Guide and the Sun Java System Application Server Developer’s Guide to Enterprise JavaBeans Technology.

> #### Container-Managed Transactions

> In an enterprise bean with container-managed (or declarative) transactions, the EJB™ container sets the boundaries of the transactions. You can use container-managed transactions with any type of enterprise bean: session, entity, or message-driven. Container-managed transactions simplify development because the enterprise bean code does not explicitly mark the transaction’s boundaries. The code does not include statements that begin and end the transaction.

> Typically, the container begins a transaction immediately before an enterprise bean method starts. It commits the transaction just before the method exits. Each method can be associated with a single transaction. Nested or multiple transactions are not allowed within a method.

> #### Component-Managed Transactions

> There may be times when component-managed (or programmatic) transaction management using the JDBC API or javax.transaction.UserTransaction is appropriate for an application. In these cases, you can program the transaction management in the application yourself.

> In a component-managed transaction, the code in the session or message-driven bean explicitly marks the boundaries of the transaction. An entity bean cannot have component-managed transactions; it must use container-managed transactions instead. Although beans with container-managed transactions require less coding, they have one limitation: When a method is executing, it can be associated with either a single transaction or no transaction at all. If this limitation will make coding your bean difficult, you should consider using component-managed transactions.

> To initiate and perform programmatic transactions, components reference the Sun Java System Application Server’s default transaction coordinator as described in Looking Up a Transaction. EJB components can also reference the transaction using the EJBContext.getUserTransaction() method.

> ### Transaction Recovery

> Transaction recovery is an important aspect of distributed transactions. If a resource becomes unreachable, or if there are unrecoverable errors, the status of the distributed transaction can be in question. Automatic and manual recovery of stranded or incomplete transactions is an important feature in Sun Java System Application Server. To enable automatic transaction recovery, see Configuring the Transaction Service.

> ##

> Configuring the Transaction Service

> You can configure the transaction service in Sun Java System Application Server in the following ways:

> - Using the Administration Interface
> - Using the Command Line Interface

> The “Using The Administration Interface” section describes each connection pool setting. The “Using The Command Line Interface” section merely lists syntax and default values.

> This section covers basic configuration. For details about monitoring and other administration topics, see the Sun Java System Application Server Administrator’s Guide.

> ### Using the Administration Interface

> To configure the transaction service using the Administration interface, perform the following tasks:

> 1. Open the Transaction Service component under your server instance.
> 2. Edit the following information if desired. All of these settings are optional.
> - Monitoring Enabled - Check this box to enable monitoring of the transaction service. By default, monitoring is disabled.
> - Log Level - Controls the type of messages logged by the transaction service to the server log. You can select a specific level, or you can select the default level set in the Log Service. For details, see the description of the Log Service in the Sun Java System Application Server Administrator’s Guide.
> - Recover on Restart - Check this box if you want the server instance to attempt transaction recovery during startup. By default, recovery is not attempted.
> - Transaction Timeout - Specifies the amount of time after which the transaction is aborted. If set to 0 (the default), the transaction never times out. This is the application level timeout. To set the XAResource timeout, use the xaresource-txn-timeout property, described in Step 3.
> - Transaction Log Location - Sets the location of the transaction log directory. The directory in which the transaction logs are kept must be writable by whatever user account the server runs as. The default location is instance_dir/logs.
> - Heuristic Decision - During recovery, if the outcome of a transaction cannot be determined from the logs, this property determines the outcome. The default is rollback. The other choice is commit.
> - Keypoint Interval - Specifies the number of transactions between keypoint operations in the log. Keypoint operations reduce the size of the transaction log file by compressing it. A larger value for this attribute (for example, 4096) results in a larger transaction log file, but fewer keypoint operations and potentially better performance. A smaller value (for example, 100) results in smaller log files, but slightly reduced performance due to the greater frequency of keypoint operations.
> 3. To add properties to the transaction service, perform the following tasks:
> 1. Click the Properties button.
> 2. Specify names and values for any properties you want to use. If you need another name-value row, use the Add button to add it. The following table lists the transaction service properties for Sun Java System Application Server.

> Table 3-1 Transaction Service Properties

> Property | Default | Description
> --- | --- | ---
> disable-distributed-transaction-logging | false | If true, disables transaction logging, which may improve performance. If false, the transaction service writes transactional activity into transaction logs so that transactions can be recovered. If Recover on Restart is checked, this property is ignored. Use only if performance is more important than transaction recovery.
> xaresource-txn-timeout | specific to the XAResource used | Changes the XAResource timeout. In some cases, the XAResource default timeout causes transactions to be aborted, so it is desirable to change it. To set the application level timeout, use the Transaction Timeout setting, described in Step 2.

> 3. Click the Save button.
> 4. Go to the server instance page.
> 5. Click the General tab.
> 6. Click the Apply Changes button.

> ### Using the Command Line Interface

> To configure the transaction service using the command line interface, use the asadmin set command. The syntax is as follows, with defaults shown for optional parameters that have them:

> asadmin set --user admin_user [--password admin_password] [--passwordfile password_file] [--host localhost] [--port 4848] [--secure | -s] attribute_name=value [attribute_name=value] *

> For more information about the general asadmin parameters (--user, --password, --passwordfile, --host, --port, and --secure), see the Sun Java System Application Server Administrator’s Guide.

> The attribute_name is a hierarchical name that looks like this:

> instance.transaction-service.ts_attribute_name

> The instance is the application server instance name. The ts_attribute_name is the transaction service attribute that needs to be configured. For example:

> server1.transaction-service.transactionTimeout

> To view the list of transaction service attribute names that can be configured using the asadmin set command, use the asadmin get command with a wildcard. The asadmin get command has the same syntax as the asadmin set command. For example:

> asadmin get --user joeuser --password secret "server1.transaction-service.*"

> A list of attribute names for configuring the transaction service of the server1 application server instance is displayed. The transaction service attributes are as follows:

> server1.transaction-service.logLevel
> server1.transaction-service.automaticTransactionRecovery
> server1.transaction-service.heuristicDecision
> server1.transaction-service.transactionTimeout
> server1.transaction-service.keypointInterval
> server1.transaction-service.monitoringEnabled
> server1.transaction-service.transactionLogFile

> Here is an example of running the asadmin set command:

> asadmin set --user joeuser --password secret server1.transaction-service.transactionTimeout=0

> The attribute_name for a transaction service property is a hierarchical name that looks like this:

> instance.transaction-service.property.ts_property_name

> The instance is the application server instance name. The ts_property_name is the transaction service property that needs to be configured. Here is an example of running the asadmin set command to set a transaction service property:

> asadmin set --user joeuser --password secret server1.transaction-service.property.xaresource-txn-timeout=30

> ##

> Looking Up a Transaction

> Application components obtain reference to the container’s default transaction coordinator by doing a Java Naming and Directory Interface™ (JNDI) lookup of java:comp/UserTransaction. The returned object implements the javax.transaction.UserTransaction interface and can be used in the application to begin, commit, rollback, and query the status of programmatic transactions. For more information about the JNDI API, see the JDBC 2.0 Standard Extension API and Chapter 4, “Using the Java Naming and Directory Interface.” The transaction lookup in the application code looks like this:

> InitialContext ic = new InitialContext();
> String txName = "java:comp/UserTransaction";
> UserTransaction tx = (javax.transaction.UserTransaction)ic.lookup(txName);
> tx.begin();
> // transacted commands, such as JDBC calls
> tx.commit();

> ##

> Transaction Logging

> The transaction service writes transactional activity into transaction logs so that transactions can be recovered. You can control transaction logging in these ways:

> - Set the location of the transaction log files using the Transaction Log Location setting in the Administration interface or the transactionLogFile attribute in the command line interface.
> - Turn off transaction logging by setting the disable-distributed-transaction-logging property to true. Do this only if performance is more important than transaction recovery.

> For details, see Configuring the Transaction Service.

> You can set the level of detail for transaction-related messages in the server log file using the Log Level setting in the Administration interface or the LogLevel attribute in the command line interface.

> ##

> Sample Applications

> Sample applications that use transactions are in the following directory:

> install_dir/samples/transactions

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.