Programming WebLogic JTA

Transaction Service

This section provides information that programmers need to write transactional applications for the WebLogic Server system.

This section discusses the following topics:

About the Transaction Service

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 2.0, published by Sun Microsystems, Inc.

For EJB and RMI applications, WebLogic Server also provides the javax.transaction and javax.transaction.xa packages, from Sun Microsystems, Inc., which implements the Java Transaction API (JTA) for Java applications. For more information about JTA, see the Java Transaction API (JTA) Specification 1.0.1B, published by Sun Microsystems, Inc. For more information about the UserTransaction object that applications use to demarcate transaction boundaries, see the WebLogic Server Javadoc.

Capabilities and Limitations

This section includes the following sections:

These sections describe the capabilities and limitations of the Transaction Service that supports EJB and RMI applications:

Lightweight Clients with Delegated Commit

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.

Client-initiated Transactions

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.

Transaction Integrity

Checked transaction behavior provides transaction integrity by guaranteeing that a commit will 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 interprocess communication models defined by The Open Group.

Transaction Termination

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.

Flat Transactions

WebLogic Server implements the flat transaction model. Nested transactions are not supported.

Relationship of the Transaction Service to Transaction Processing

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

Multithreaded Transaction Client Support

WebLogic Server supports multithreaded transactional clients. Clients can make transaction requests concurrently in multiple threads.

Transaction Id

The Transaction Service assigns a transaction identifier (XID) to each transaction. This ID can be used to 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 the weblogic.transaction.Transaction Javadoc.

Transaction Name and Properties

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 the weblogic.transaction.Transaction Javadoc.

Transaction Status

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

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.

General Constraints

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 will return 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 will throw an exception. In that case, you must reconfigure your application to work around the buffer size.

Transaction Scope

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 Domains for Inter-Domain Transactions.

Transaction Service in EJB Applications

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 the online Javadoc.

For an introduction to transaction management in EJB applications, see Transactions in WebLogic Server EJB Applications, and Transactions Sample EJB Code in the Introducing Transactions section.

Transaction Service in RMI Applications

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 in the Introducing Transactions section.

Transaction Service Interoperating with OTS

WebLogic Server provides a Transaction Service that supports interoperation with the Object Transaction Service (OTS). See the Java Transaction Service (JTS) Specification. For this release, WebLogic Server interoperates with OTS in the following scenarios:

Server-Server 2PC

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 Transaction Optimization is not supported.

Client Demarcated Transactions

The client starts a transaction on the server via the OTS client APIs. The client then retrieves the Xid from this transaction and then propagates this per-request until the transaction is commited. Although the client initiates the transaction, all the commit processing is done on the server.