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:
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.
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:
Check to see if the checking account has enough money to cover the transfer.
Debit the amount from the checking account.
Credit the amount to the savings account.
Record the transfer to the checking account log.
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.
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:
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.
Ensure that the server is running.
Remote subcommands require a running server.
Stop the transaction service by using the freeze-transaction-service(1) subcommand.
This example stops the transaction service.
asadmin> freeze-transaction-service Command freeze-transaction-service executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help freeze-transaction-service at the command line.
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.
Stop the transaction service before rolling back an in-flight transaction.
Ensure that the server is running.
Remote subcommands require a running server.
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.
Roll back the transaction by using the rollback-transaction(1) subcommand.
This example rolls back the transaction with transaction ID 0000000000000001_00.
asadmin> rollback-transaction 0000000000000001_00 Command rollback-transaction executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help rollback-transaction at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Restart the suspended transaction service by using the unfreeze-transaction-service(1) subcommand.
This example restarts the transaction service after it has been frozen.
asadmin> unfreeze-transaction-service Command unfreeze-transaction-service executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help unfreeze-transaction-service at the command line.
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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Manually recover transactions by using the recover-transactions(1) subcommand.
This example performs manual recovery of transactions on sampleserver.
asadmin recover-transactions sampleserver Transaction recovered. |
You can also view the full syntax and options of the subcommand by typing asadmin help recover-transactions at the command line.