PK
U:wEoa, mimetypeapplication/epub+zipPK U:wE iTunesMetadata.plisti
This chapter describes troubleshooting tools and tasks for use in determining why transactions fail and deciding what actions to take to correct the problem.
This section discusses the following topics:
WebLogic Server includes the ability to monitor currently running transactions and ensure that adequate information is captured in the case of heuristic completion. It also provides the ability to monitor performance of database queries, transactional requests, and bean methods.
WebLogic Server provides the following aids to transaction troubleshooting:
WebLogic JTA supports all standard JTA exceptions. For more information about standard JTA exceptions, see the API Javadoc for the following packages, available at http://docs.oracle.com/javase/1.5.0/docs/api/
:
javax.transaction
javax.transaction.xa
In addition to the standard JTA exceptions, WebLogic Server provides the class weblogic.transaction.RollbackException
. This class extends javax.transaction.RollbackException
and preserves the original reason for a rollback. Before rolling a transaction back, or before setting it to rollbackonly
, an application can supply a reason for the rollback. All rollbacks triggered inside the transaction service set the reason (for example, timeouts, XA errors, unchecked exceptions in beforeCompletion
, or inability to contact the transaction manager). Once set, the reason cannot be overwritten.
The Transaction Service assigns a transaction identifier (Xid
) to each transaction. This ID can isolate information about a specific transaction in a log file. You can retrieve the transaction identifier using the getXID
method in the weblogic.transaction.Transaction
interface. For detailed information on methods for getting the transaction identifier, see weblogic.transaction.Transaction
in the Oracle WebLogic Server API Reference.
WebLogic JTA provides extensions to javax.transaction.Transaction
that support transaction naming and user-defined properties. These extensions are included in the weblogic.transaction.Transaction
interface.
The transaction name indicates a type of transaction (for example, funds transfer or ticket purchase) and should not be confused with the transaction ID, which identifies a unique transaction on a server. The transaction name makes it easier to identify a transaction type in the context of an exception or a log file.
User-defined properties are key/value pairs, where the key is a string identifying the property and the value is the current value assigned to the property. Transaction property values must be objects that implement the Serializable
interface. You manage properties in your application using the set and get methods defined in the weblogic.transaction.Transaction
interface. Once set, properties stay with a transaction during its entire lifetime and are passed between machines as the transaction travels through the system. Properties are saved in the transaction log, and are restored during crash recovery processing. If a transaction property is set more than once, the latest value is retained.
For detailed information on methods for setting and getting the transaction name and transaction properties, see weblogic.transaction.Transaction
in the Oracle WebLogic Server API Reference.
The Java Transaction API provides transaction status codes using the javax.transaction.Status
class. Use the getStatusAsString
method in weblogic.transaction.Transaction
to return the status of the transaction as a string. The string contains the major state as specified in javax.transaction.Status
with an additional minor state (such as logging
or pre-preparing
).
Transaction statistics are provided for all transactions handled by the transaction manager on a server. These statistics include the number of total transactions, transactions with a specific outcome (such as committed, rolled back, or heuristic completion), rolled back transactions by reason, and the total time that transactions were active. For detailed information about transaction statistics, see "Monitor JTA" in the Oracle WebLogic Server Administration Console Help.
The Administration Console enables you to monitor transactions. Monitoring tasks are performed at the server level. Transaction statistics are displayed for a specific server.
Once you have narrowed the problem down to a specific application, you can activate WebLogic Server's debugging features to track down the specific problem within the application.
You can enable debugging by setting the appropriate ServerDebug
configuration attribute to "true
." Optionally, you can also set the server StdoutSeverity
to "Debug
".
You can modify the configuration attribute in any of the following ways.
Set the appropriate properties on the command line. For example,
-Dweblogic.debug.DebugJDBCJTA=true -Dweblogic.log.StdoutSeverity="Debug"
This method is static and can only be used at server startup.
Use the WebLogic Server Administration Console to set the debugging values:
If you have not done so, in the Change Center of the Administration Console, click Lock & Edit (see "Use the Change Center" in Oracle WebLogic Server Administration Console Help).
In the left pane of the console, expand Environment and select Servers.
On the Summary of Servers page, click the server on which you want to enable or disable debugging to open the settings page for that server.
Click Debug.
Expand default.
Select the check box for the debug scopes or attributes you want to modify.
Select Enable to enable (or Disable to disable) the debug scopes or attributes you have checked.
To activate these changes, in the Change Center of the Administration Console, click Activate Changes.
Not all changes take effect immediately—some require a restart (see "Use the Change Center" in Oracle WebLogic Server Administration Console Help).
This method is dynamic and can enable debugging while the server is running.
Use the WebLogic Scripting Tool (WLST) to set the debugging values. For example, the following command runs a program for setting debugging values called debug.py
:
java weblogic.WLST debug.py
The debug.py program contains the following code:
user='user1' password='password' url='t3://localhost:7001' connect(user, password, url) edit() cd('Servers/myserver/ServerDebug/myserver') startEdit() set('DebugJDBCJTA','true') save() activate()
Note that you can also use WLST from Java. The following example shows a Java file used to set debugging values:
import weblogic.management.scripting.utils.WLSTInterpreter; import java.io.*; import weblogic.jndi.Environment; import javax.naming.Context; import javax.naming.InitialContext; import javax.naming.NamingException; public class test { public static void main(String args[]) { try { WLSTInterpreter interpreter = null; String user="user1"; String pass="pw12ab"; String url ="t3://localhost:7001"; Environment env = new Environment(); env.setProviderUrl(url); env.setSecurityPrincipal(user); env.setSecurityCredentials(pass); Context ctx = env.getInitialContext(); interpreter = new WLSTInterpreter(); interpreter.exec ("connect('"+user+"','"+pass+"','"+url+"')"); interpreter.exec("edit()"); interpreter.exec("startEdit()"); interpreter.exec ("cd('Servers/myserver/ServerDebug/myserver')"); interpreter.exec("set('DebugJDBCJTA','true')"); interpreter.exec("save()"); interpreter.exec("activate()"); } catch (Exception e) { System.out.println("Exception "+e); } } }
Using the WLST is a dynamic method and can enable debugging while the server is running.
Changes in debugging characteristics, through console, or WLST, or command line are persisted in the config.xml
file. See Example 13-1:
Example 13-1 Example Debugging Stanza for JTA
. . . <server> <name>myserver</name> <server-debug> <debug-scope> <name>weblogic.transaction</name> <enabled>true</enabled> </debug-scope> <debug-jdbcjta>true</debug-jdbcjta> </server-debug> </server> . . .
This sample config.xml
fragment shows a transaction debug scope (set of debug attributes) and a single JTA attribute.
It is possible to see the tree view of the DebugScope definitions using java weblogic.diagnostics.debug.DebugScopeViewer
.
You can enable the following registered debugging scopes for JTA:
DebugJDBCJTA
(scope weblogic.jdbc.transaction) - not currently used.
DebugJTAXA
(scope weblogic.transaction.xa) - traces for XA resources.
DebugJTANonXA
(scope weblogic.transaction.nonxa) - traces for non-XA resources.
DebugJTAXAStackTrace
(scope weblogic.transaction.stacktrace) - detailed tracing that prints stack traces at various critical locations.
DebugJTARMI
(scope weblogic.transaction.rmi) - not currently used.
DebugJTA2PC
(scope weblogic.transaction.twopc) - traces all 2-phase commit operations.
DebugJTA2PCStackTrace
(scope weblogic.transaction.twopcstacktrace) - detailed two-phase commit tracing that prints stack traces.
DebugJTATLOG
(scope weblogic.transaction.tlog) - traces transaction logging information.
DebugJTAJDBC
(scope weblogic.transaction.jdbc, weblogic.jdbc.transaction) - traces information about reading/writing JTA records.
DebugJTARecovery
(scope weblogic.transaction.recovery) - traces recovery information.
DebugJTAGateway
(scope weblogic.transaction.gateway) - traces information about imported transactions.
DebugJTAGatewayStackTrace
(scope weblogic.transaction.gatewaystacktrace) - stack traces related to imported transactions.
DebugJTANaming
(scope weblogic.transaction.naming) - traces transaction naming information.
DebugJTANamingStackTrace
(scope weblogic.transaction.namingstacktrace) - traces transaction naming information.
DebugJTAResourceHealth
(scope weblogic.transaction.resourcehealth) - traces information about XA transaction resource health.
DebugJTAMigration
(scope weblogic.transaction.migration) - traces information about Transaction Log migration.
DebugJTALifecycle
(scope weblogic.transaction.lifecycle) - traces information about the transaction server lifecycle (initialization, suspension, resuming, and shutdown).
DebugJTALLR
(scope weblogic.transaction.llr) - traces all Logging Last Resource operations.
DebugJTAHealth
(scope weblogic.transaction.health) - traces information about transaction subsystem health.
DebugJTATransactionName
(scope weblogic.transaction.name) - traces transaction names.
DebugJTAResourceName
(scope weblogic.transaction.resourcename) - traces transaction resource names.
This chapter describes the information used to write transactional applications to be used with WebLogic Server. Topics include the capabilities and limitations of the transaction service and how to use it with EJBs, RMI applications, and the Object Transaction Service (OTS).
This section discusses the following topics:
WebLogic Server provides a Transaction Service that supports transactions in EJB and RMI applications. In the WebLogic Server EJB container, the Transaction Service provides an implementation of the transaction services described in the Enterprise JavaBeans Specification 3.0 at http://www.oracle.com/technetwork/java/javaee/ejb/index.html
.
For EJB and RMI applications, WebLogic Server also provides the javax.transaction
and javax.transaction.xa
packages, which implement the Java Transaction API (JTA) for Java applications. For more information about JTA, see the Java Transaction API (JTA) Specification 1.1, published at http://www.oracle.com/technetwork/java/javaee/jta/index.html
. For more information about the UserTransaction
object that applications use to demarcate transaction boundaries, see weblogic.transaction.UserTransaction
in the Oracle WebLogic Server API Reference.
This section includes the following sections:
These sections describe the capabilities and limitations of the Transaction Service that supports EJB and RMI applications:
A lightweight client runs on a single-user, unmanaged desktop system that has irregular availability. Owners may turn their desktop systems off when they are not in use. These single-user, unmanaged desktop systems should not be required to perform network functions such as transaction coordination. In particular, unmanaged systems should not be responsible for ensuring atomicity, consistency, isolation, and durability (ACID) properties across failures for transactions involving server resources. WebLogic Server remote clients are lightweight clients.
The Transaction Service allows lightweight clients to do a delegated commit, which means that the Transaction Service allows lightweight clients to begin and terminate transactions while the responsibility for transaction coordination is delegated to a transaction manager running on a server machine. Client applications do not require a local transaction server. The remote implementation of UserTransaction
that EJB or RMI clients use delegates the actual responsibility of transaction coordination to the transaction manager on the server.
A client, such as an applet, can obtain a reference to the UserTransaction
and TransactionManager
objects using JNDI. A client can begin a transaction using either object reference. To get the Transaction
object for the current thread, the client program must invoke the ((TransactionManager)tm).getTransaction()
method.
Checked transaction behavior provides transaction integrity by guaranteeing that a commit
does not succeed unless all transactional objects involved in the transaction have completed the processing of their transactional requests. The Transaction Service provides checked transaction behavior that is equivalent to that provided by the request/response inter-process communication models defined by The Open Group.
WebLogic Server allows transactions to be terminated only by the client that created the transaction.
Note: The client may be a server object that requests the services of another object. |
WebLogic Server implements the flat transaction model. Nested transactions are not supported.
The Transaction Service relates to various transaction processing servers, interfaces, protocols, and standards in the following ways:
Support for The Open Group XA interface.The Open Group Resource Managers are resource managers that can be involved in a distributed transaction by allowing their two-phase commit protocol to be controlled using The Open Group XA interface. WebLogic Server supports interaction with The Open Group Resource Managers.
Support for the OSI TP protocol. Open Systems Interconnect Transaction Processing (OSI TP) is the transactional protocol defined by the International Organization for Standardization (ISO). WebLogic Server does not support interactions with OSI TP transactions.
Support for the LU 6.2 protocol. Systems Network Architecture (SNA) LU 6.2 is a transactional protocol defined by IBM. WebLogic Server does not support interactions with LU 6.2 transactions.
Support for the ODMG standard. ODMG-93 is a standard defined by the Object Database Management Group (ODMG) that describes a portable interface to access Object Database Management Systems. WebLogic Server does not support interactions with ODMG transactions.
WebLogic Server supports multithreaded transactional clients. Clients can make transaction requests concurrently in multiple threads.
The Transaction Service assigns a transaction identifier (XID
) to each transaction. This ID can isolate information about a specific transaction in a log file. You can retrieve the transaction identifier using the getXID
method in the weblogic.transaction.Transaction
interface. For detailed information on methods for getting the transaction identifier, see weblogic.transaction.Transaction
in the Oracle WebLogic Server API Reference.
WebLogic JTA provides extensions to javax.transaction.Transaction
that support transaction naming and user-defined properties. These extensions are included in the weblogic.transaction.Transaction
interface.
The transaction name indicates a type of transaction (for example, funds transfer or ticket purchase) and should not be confused with the transaction ID, which identifies a unique transaction on a server. The transaction name makes it easier to identify a transaction type in the context of an exception or a log file.
User-defined properties are key/value pairs, where the key is a string identifying the property and the value is the current value assigned to the property. Transaction property values must be objects that implement the Serializable
interface. You manage properties in your application using the set and get methods defined in the weblogic.transaction.Transaction
interface. Once set, properties stay with a transaction during its entire lifetime and are passed between machines as the transaction travels through the system. Properties are saved in the transaction log, and are restored during crash recovery processing. If a transaction property is set more than once, the latest value is retained.
For detailed information on methods for setting and getting the transaction name and transaction properties, see weblogic.transaction.Transaction
in the Oracle WebLogic Server API Reference.
The Java Transaction API provides transaction status codes using the javax.transaction.Status
class. Use the getStatusAsString
method in weblogic.transaction.Transaction
to return the status of the transaction as a string. The string contains the major state as specified in javax.transaction.Status
with an additional minor state (such as logging
or pre-preparing
).
Transaction statistics are provided for all transactions handled by the transaction manager on a server. These statistics include the number of total transactions, transactions with a specific outcome (such as committed, rolled back, or heuristic completion), rolled back transactions by reason, and the total time that transactions were active. For detailed information on transaction statistics, see Monitoring Transactions.
The following constraints apply to the Transaction Service:
In WebLogic Server, a client or a server object cannot invoke methods on an object that is infected with (or participating in) another transaction. The method invocation issued by the client or the server instance returns an exception.
In WebLogic Server, clients using third-party implementations of the Java Transaction API (for Java applications) are not supported.
The transaction log buffer is limited to 250 KB. If your application includes very large transactions that require transaction log writes that exceed this value, WebLogic Server instance throws an exception. In that case, you must reconfigure your application to work around the buffer size.
The scope of a transaction refers to the environment in which the transaction is performed. WebLogic Server supports transactions on standalone servers, between non-clustered servers, between clustered servers within a domain, and between domains. To enable inter-domain transaction support, see Configuring Secure Inter-Domain and Intra-Domain Transaction Communication.
The WebLogic Server EJB container provides a Transaction Service that supports the two types of transactions in WebLogic Server EJB applications:
Container-managed transactions. In container-managed transactions, the WebLogic Server EJB container manages the transaction demarcation. Transaction attributes in the EJB deployment descriptor determine how the WebLogic Server EJB container handles transactions with each method invocation.
Bean-managed transactions. In bean-managed transactions, the EJB manages the transaction demarcation. The EJB makes explicit method invocations on the UserTransaction
object to begin, commit, and roll back transactions. For more information about UserTransaction
methods, see weblogic.transaction.UserTransaction
in the Oracle WebLogic Server API Reference.
For an introduction to transaction management in EJB applications, see Transactions in WebLogic Server EJB Applications and Transactions Sample EJB Code.
WebLogic Server provides a Transaction Service that supports transactions in WebLogic Server RMI applications. In RMI applications, the client or server application makes explicit method invocations on the UserTransaction
object to begin, commit, and roll back transactions.
For more information about UserTransaction
methods, see the online javadoc. For an introduction to transaction management in RMI applications, see Transactions in WebLogic Server RMI Applications and Transactions Sample RMI Code.
WebLogic Server provides a Transaction Service that supports interoperation with the Object Transaction Service (OTS). See the Java Transaction Service (JTS) Specification at http://www.oracle.com/technetwork/java/javaee/jts-spec095-1508547.pdf
. For this release, WebLogic Server interoperates with OTS in the following scenarios:
In this situation, a server-to-server 2PC transaction is completed using interposition. The originating server creates an Xid and propagates the transaction to the target server. The target server registers itself as a resource with the originating server. The originating server drives the completion of the transaction. Logging Last Resource (LLR) transaction optimization, as described in Chapter 7, "Logging Last Resource Transaction Optimization," is not supported.
The client starts a transaction on the server using the OTS client APIs. The client then retrieves the Xid from this transaction and then propagates this per-request until the transaction is committed. Although the client initiates the transaction, all the commit processing occurs on the server.