19 Administering Transactions

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. For information about JDBC transaction isolation levels, see "Using JDBC Transaction Isolation Levels" in Oracle GlassFish Server Application Development Guide.

  The GlassFish Server supports a variety of JDBC XA drivers. For a list of the JDBC drivers currently supported by the GlassFish Server, see the Oracle GlassFish Server Release Notes. For configurations of supported and other drivers, see Configuration Specifics for JDBC Drivers.

• Java Message Service (JMS) Providers - Use of transactions ensures that messages are reliably delivered. The GlassFish Server is integrated with GlassFish Server Message Queue, a fully capable JMS provider. For more information about transactions and the JMS API, see Administering the Java Message Service (JMS).

• 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 connectors, see Administering EIS Connectivity.

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 GlassFish Server, a JDBC resource is non-XA if it meets either of the following criteria:

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

• The Resource Type setting 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, because the transaction manager must use XA protocol to commit two or more resources.

• No transaction importing or exporting occurs.

Transactions that involve multiple resources or multiple participant processes are distributed or global transactions. A global transaction can involve one non-XA resource if last agent optimization is enabled. Otherwise, all resources 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.

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.

To Stop the Transaction Service

Use the freeze-transaction-service subcommand in remote mode to stop the transaction service. When the transaction service is stopped, all in-flight transactions are immediately suspended. You must stop the transaction service before rolling back any in-flight transactions.

Running this subcommand on a stopped transaction subsystem has no effect. The transaction service remains suspended until you restart it by using the unfreeze-transaction-service subcommand.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Stop the transaction service by using the freeze-transaction-service subcommand.

asadmin> freeze-transaction-service --target instance1
Command freeze-transaction-service executed successfully

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help freeze-transaction-service at the command line.

To Roll Back a Transaction

In some situations, you might want to roll back a particular transaction. Before you can roll back a transaction, you must first stop the transaction service so that transaction operations are suspended. Use the rollback-transaction subcommand in remote mode to roll back a specific transaction.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Enable monitoring using the set subcommand. For example:

   asadmin> set cluster1-config.monitoring-service.module-monitoring-levels.transaction-service=HIGH
   

3. Use the freeze-transaction-service subcommand to halt in-process transactions. See To Stop the Transaction Service.

4. Identify the ID of the transaction you want to roll back.

   To see a list of IDs of active transactions, use the get subcommand with the --monitor option to get the monitoring data for the activeids statistic. See Transaction Service Statistics. For example:

   asadmin> get --monitor instance1.server.transaction-service.activeids-current
   

5. Roll back the transaction by using the rollback-transaction subcommand.

   The transaction is not rolled back at the time of this command's execution, but only marked for rollback. The transaction is rolled back when it is completed.

asadmin> rollback-transaction --target instance1 0000000000000001_00
Command rollback-transaction executed successfully

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help rollback-transaction at the command line.

To Restart the Transaction Service

Use the unfreeze-transaction-service subcommand in remote mote to resume all the suspended in-flight transactions. Run this subcommand to restart the transaction service after it has been frozen.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Restart the suspended transaction service by using the unfreeze-transaction-service subcommand.

asadmin> unfreeze-transaction-service --target instance1
Command unfreeze-transaction-service executed successfully

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help unfreeze-transaction-service at the command line.

Determining Local Transaction Completion at Shutdown

When you shut down a GlassFish Server instance, all database connections are closed. When an Oracle JDBC driver-based database connection is closed in the middle of a non-XA transaction, all pending changes are committed. Other databases usually roll back pending changes when a connection is closed without being explicitly committed. To determine the exact behavior for your database, refer to the documentation from your JDBC driver vendor.

To explicitly specify whether GlassFish Server commits or rolls back non-XA transactions at server shutdown, set the com.sun.enterprise.in-progress-local-transaction.completion-mode JVM option to either commit or rollback using the create-jvm-options subcommand. For example:

asadmin> create-jvm-options -Dcom.sun.enterprise.in-progress-local-transaction.completion-mode=rollback

Automatic Transaction Recovery

GlassFish Server can perform automatic recovery in these ways:

• Pending transactions are completed upon server startup if automatic-recovery is set to true.

• Periodic automatic recovery is performed by a background thread if the pending-txn-cleanup-interval property is set to a positive value.

Changing these settings requires a server restart. For more information about how to change these settings, see Configuring the Transaction Service.

If commit fails during recovery, a message is written to the server log.

To Manually Recover Transactions

Use the recover-transactions subcommand in remote mode to manually recover transactions that were pending when a resource or a server instance failed.

For a standalone server, do not use manual transaction recovery to recover transactions after a server failure. For a standalone server, manual transaction recovery can recover transactions only when a resource fails, but the server is still running. If a standalone server fails, only the full startup recovery process can recover transactions that were pending when the server failed.

For an installation of multiple server instances, you can use manual transaction recovery from a surviving server instance to recover transactions after a server failure. For manual transaction recovery to work properly, transaction logs must be stored on a shared file system that is accessible to all server instances. See Transaction Logging.

When you execute recover-transactions in non-delegated mode, you can recover transactions that didn't complete two-phase commit because of a resource crash. To use manual transaction recovery in this way, the following conditions must be met:

• The recover-transactions command should be executed after the resource is restarted.

• Connection validation should be enabled so the connection pool is refreshed when the resource is accessed after the recovery. For more information, see "Connection Validation Settings" in Oracle GlassFish Server Performance Tuning Guide.

If commit fails during recovery, a message is written to the server log.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Manually recover transactions by using the recover-transactions subcommand.

asadmin recover-transactions --target instance2 instance1
Transaction recovered.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help recover-transactions at the command line.

Distributed Transaction Recovery

To enable cluster-wide automatic recovery, you must first facilitate storing of transaction logs in a shared file system. See Transaction Logging.

Next, you must set the transaction service's delegated-recovery property to true (the default is false). For information about setting tx-log-dir and delegated-recovery, see Configuring the Transaction Service.

Recovery Workarounds and Limitations

The GlassFish Server provides workarounds for some known issues with transaction recovery implementations.

grant select on SYS.DBA_PENDING_TRANSACTIONS to user; 
grant execute on SYS.DBMS_SYSTEM to user; 
grant select on SYS.PENDING_TRANS$ to user; 
grant select on SYS.DBA_2PC_NEIGHBORS to user; 
grant execute on SYS.DBMS_XA to user;
grant select on SYS.DBA_2PC_PENDING to user;

To Store Transaction Logs in a Database

For multi-core machines, logging transactions to a database may be more efficient. Transaction logging is designed to work with any JDBC-compliant database. For databases with which transaction logging has been tested, see the Oracle GlassFish Server Release Notes.

1. Create a JDBC connection Pool. To use non-transactional connections to insert log records, you can either set the non-transactional-connections attribute to true in this step, or you can perform step 5 later.

2. Create a JDBC resource that uses the connection pool and note the JNDI name of the JDBC resource.

3. Automatic table creation for the transaction logs is done by default. However, if you would prefer to create the table manually, name it txn_log_table with the following schema:

   Column Name	JDBC Type
   LOCALTID	VARCHAR
   INSTANCENAME	VARCHAR
   SERVERNAME	VARCHAR(n)
   GTRID	VARBINARY

   
   

   The size of the SERVERNAME column should be at least the length of the GlassFish Server host name plus 10 characters.

   The size of the GTRID column should be at least 64 bytes.

4. Add the db-logging-resource property to the transaction service. For example:

   asadmin set server-config.transaction-service.property.db-logging-resource="jdbc/TxnDS"
   

   The property's value should be the JNDI name of the JDBC resource configured previously.

5. If you didn't set the non-transactional-connections attribute to true in step 1 and you want to use non-transactional connections to insert log records, use the following asadmin create-jvm-options command to reference an existing transactional resource but use non-transactional connections for the INSERT statements:

   asadmin create-jvm-options -Dcom.sun.jts.dblogging.use.nontx.connection.for.add=true
   

6. To disable file synchronization, use the following asadmin create-jvm-options command:

   asadmin create-jvm-options -Dcom.sun.appserv.transaction.nofdsync
   

7. Restart the server.

Next Steps

To define the SQL used by the transaction manager when it is storing its transaction logs in the database, use the following flags:

-Dcom.sun.jts.dblogging.insertquery=sql statement

-Dcom.sun.jts.dblogging.deletequery=sql statement

-Dcom.sun.jts.dblogging.selectquery=sql statement

-Dcom.sun.jts.dblogging.selectservernamequery=sql statement

The default statements are as follows:

-Dcom.sun.jts.dblogging.insertquery=insert into txn_log_table values ( ?, ?, ?, ? )

-Dcom.sun.jts.dblogging.deletequery=delete from txn_log_table where localtid = ? and servername = ?

-Dcom.sun.jts.dblogging.selectquery=select * from txn_log_table where servername = ?

-Dcom.sun.jts.dblogging.selectservernamequery=select distinct servername from txn_log_table where instancename = ?

To set one of these flags using the asadmin create-jvm-options command, you must quote the statement. For example:

create-jvm-options '-Dcom.sun.jts.dblogging.deletequery=delete from txn_log_table where gtrid = ?'

You can also set JVM options in the Administration Console. Select the JVM Settings component under the relevant configuration. These flags and their statements must also be quoted in the Administration Console. For example:

'-Dcom.sun.jts.dblogging.deletequery=delete from txn_log_table where gtrid = ?'

See Also

For information about JDBC connection pools and resources, see Administering Database Connectivity. For more information about the asadmin set and asadmin create-jvm-options commands, see the Oracle GlassFish Server Reference Manual. For databases with which transaction logging has been tested, see the Oracle GlassFish Server Release Notes.