Chapter 21 Administering Transactions

This chapter discusses how to manage the transaction service for the Oracle GlassFish Server environment by using the asadmin command-line utility. Instructions for manually recovering transactions are also included.

The following topics are addressed here:

• About Transactions

• Managing the Transaction Service

• Recovering Transactions

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help. For additional information on configuring the transaction service, transaction logging, and distributed transaction recovery, see Chapter 15, Using the Transaction Service, in Oracle GlassFish Server 3.0.1 Application Development Guide.

About Transactions

A transaction is a series of discreet actions in an application that must all complete successfully. By enclosing one or more actions in an indivisible unit of work, a transaction ensures data integrity and consistency. If all actions do not complete, the changes are rolled back.

For example, to transfer funds from a checking account to a savings account, the following steps typically occur:

1. Check to see if the checking account has enough money to cover the transfer.

2. Debit the amount from the checking account.

3. Credit the amount to the savings account.

4. Record the transfer to the checking account log.

5. Record the transfer to the savings account log.

These steps together are considered a single transaction.

If all the steps complete successfully, the transaction is committed. If any step fails, all changes from the preceding steps are rolled back, and the checking account and savings account are returned to the states they were in before the transaction started. This type of event is called a rollback. A normal transaction ends in either a committed state or a rolled back state.

The following elements contribute to reliable transaction processing by implementing various APIs and functionalities:

• Transaction Manager. Provides the services and management functions required to support transaction demarcation, transactional resource management, synchronization, and transaction context propagation.

• GlassFish Server. Provides the infrastructure required to support the application runtime environment that includes transaction state management.

• Resource Manager. Through a resource adapter, the resource manager provides the application access to resources. The resource manager participates in distributed transactions by implementing a transaction resource interface used by the transaction manager to communicate transaction association, transaction completion, and recovery work. An example of such a resource manager is a relational database server.

• Resource Adapter. A system-level software library is used by GlassFish Server or a client to connect to a resource manager. A resource adapter is typically specific to a resource manager. The resource adapter is available as a library and is used within the address space of the client using it. An example of such a resource adapter is a Java Database Connectivity (JDBC) driver. For information on supported JDBC drivers, see Configuration Specifics for JDBC Drivers.

• Transactional User Application. In the GlassFish Server environment, the transactional user application uses Java Naming and Directory Interface (JNDI) to look up transactional data sources and, optionally, the user transaction). The application might use declarative transaction attribute settings for enterprise beans, or explicit programmatic transaction demarcation.

Managing the Transaction Service

You can roll back a single transaction by using the asadmin subcommands described in this section. To do so, the transaction service must be stopped (and later restarted), allowing you to see the active transactions and correctly identify the one that needs to be rolled back.

For instructions on configuring the transaction service and setting up automatic recovery, see Chapter 15, Using the Transaction Service, in Oracle GlassFish Server 3.0.1 Application Development Guide.

The following topics are addressed here:

• To Stop the Transaction Service

• To Roll Back a Transaction

• To Restart the Transaction Service

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(1) subcommand.

Example 21–1 Stopping the Transaction Service

This example stops the transaction service.

asadmin> freeze-transaction-service
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.

Before You Begin

Stop the transaction service before rolling back an in-flight transaction.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

   To see a list of IDs of active transactions, use the get subcommand to get the monitoring data for the activeids statistic. See Transaction Service Statistics.

3. Roll back the transaction by using the rollback-transaction(1) subcommand.

Example 21–2 Rolling Back a Transaction

This example rolls back the transaction with transaction ID 0000000000000001_00.

asadmin> rollback-transaction 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(1) subcommand.

Example 21–3 Restarting the Transaction Service

This example restarts the transaction service after it has been frozen.

asadmin> unfreeze-transaction-service
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.

Recovering Transactions

There are some situations where the commit or rollback operations might be interrupted, typically because the server crashed or a resource manager crashed. Crash situations can leave some transactions stranded between steps. GlassFish Server is designed to recover from these failures and complete the transactions upon server startup. If the failed transaction spans multiple servers, the server that started the transaction can contact the other servers to get the outcome of the transaction. If the other servers are unreachable, the transaction uses heuristic decision information to determine the outcome. The transactions are resolved upon server startup.

To Manually Recover Transactions

Use the recover-transactions subcommand in remote mode to manually recover transactions that were pending when a resource on the server 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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Manually recover transactions by using the recover-transactions(1) subcommand.

Example 21–4 Manually Recovering Transactions

This example performs manual recovery of transactions on sampleserver.

asadmin recover-transactions sampleserver
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.