Programmers Guide

JBTA-PG-3/31/06

 

 

 

 

 

 

 

 

 

 

 

 

 

Legal Notices

The information contained in this documentation is subject to change without notice.

JBoss Inc. makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. JBoss Inc. shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

Java� and J2EE is a U.S. trademark of Sun Microsystems, Inc. Microsoft� and Windows NT� are registered trademarks of Microsoft Corporation. Oracle� is a registered U.S. trademark and Oracle9�, Oracle9 Server� Oracle9 Enterprise Edition� are trademarks of Oracle Corporation. Unix is used here as a generic term covering all versions of the UNIX� operating system. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

Arjuna is a trademark of Hewlett-Packard Company and used here under licence.

Copyright

JBoss, Home of Professional Open Source Copyright 2006, JBoss Inc., and individual contributors as indicated by the @authors tag.� All rights reserved.

See the copyright.txt in the distribution for a full listing of individual contributors. This copyrighted material is made available to anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the GNU General Public License, v. 2.0. This program is distributed in the hope that it will be useful, but WITHOUT A WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A� PARTICULAR PURPOSE.

See the GNU General Public License for more details. You should have received a copy of the GNU General Public License, v. 2.0 along with this distribution; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,� * MA� 02110-1301, USA.

Software Version

JBoss Transactions API 4.2

Restricted Rights Legend

Use, duplication, or disclosure is subject to restrictions as set forth in contract subdivision (c)(1)(ii) of the Rights in Technical Data and Computer Software clause 52.227-FAR14.

� Copyright 2006 JBoss Inc.

 

Contents

About This Guide. 5

What This Guide Contains 5

Audience. 5

Prerequisites 5

Organization. 5

Documentation Conventions 6

Additional Documentation. 6

Contacting Us 7

An introduction to the JTA.. 9

The Java Transaction API 9

Transactions 11

The API 11

UserTransaction. 11

TransactionManager 11

Suspending and resuming a transaction. 12

The Transaction interface. 13

Resource enlistment 13

Transaction synchronization. 14

Transaction equality. 14

The Resource Manager. 15

The XAResource interface. 15

Extended XAResource control 16

Opening a Resource Manager 16

Closing a Resource Manager 17

Threads of control 17

Transaction association. 17

Externally controlled connections 18

Resource sharing. 18

Local and global transactions 19

Dynamic Registration. 19

Transaction recovery. 20

Failure recovery. 20

Recovering non-JBossJTA XAConnections 21

JDBC and transactions 23

Using the transactional JDBC driver 23

Managing transactions 23

Restrictions 23

Transactional drivers 23

Loading drivers 24

Connections 24

Making the connection. 25

JDBC 2.0. 25

XADataSources 25

Java Naming and Directory Interface (JNDI) 25

Dynamic class instantiation. 26

Using the connection. 27

Connection pooling. 28

Reusing connections 28

Terminating the transaction. 28

AutoCommit 28

Setting isolation levels 29

Examples 30

JDBC example. 30

Failure recovery example. 32

Configuring JBossJTA.. 37

Configuration options 37

Using JBossJTA in application servers 38

JBOSS Application Server 38

Configuration. 38

The services 39

Ensuring Transactional Context is Propagated to the Server 39

Index. 40

 

About This Guide

This document describes how to use the Arjuna Technologies JTA and JDBC implementations, referred to within this document as JBoss Transactions API 4.2 (JBossJTA).

This guide is most relevant to engineers who are responsible for administering JBoss Transactions API 4.2 installations.

Knowledge of JTA and JDBC.

This guide contains the following chapters:

�        Chapter 1, An introduction to the JTA: An introduction to JTA by describing the concept of the high level interface to manage transactions.

�        Chapter 2, Transactions: contains an overview of the interfaces defined by JTA demarcate and manage transactions from the user view and from the application server view.

�        Chapter 3, The Resource Manager: gives an overview of the way to manage Resource Managers compliant to the X/Open XA protocol.

�        Chapter 4, Transaction Recovery: This chapter, gives an overview of the behavior applied to recovery XA resource managers, and describes information needed by JBossJTA to manage� the recovery.�

�        Chapter 5, JDBC and transaction: This chapter, describes how JBossJTA supports transactional applications that access databases using JDBC.

�        Chapter 6, Example: illustrates how to build transactional applications with JBossJTA- accessing a database with JDBC and managing recovery.

�        Chapter 7, Configuring JBossJTA: describes how to configure JBossJTA features.

�        Chapter 8, Using JBossJTA in the application servers: describes how to use and configure JBossJTA when embedded in an application server, particularly JBoss.

 

The following conventions are used in this guide:

Convention	Description
Italic	In paragraph text, italic identifies the titles of documents that are being referenced.� When used in conjunction with the Code text described below, italics identify a variable that should be replaced by the user with an actual value.
Bold	Emphasizes items of particular importance.
Code	Text that represents programming code.
Function | Function	A path to a function or dialog box within an interface.� For example, �Select File | Open.� indicates that you should select the Open function from the File menu.
( ) and |	Parentheses enclose optional items in command syntax. The vertical bar separates syntax items in a list of choices. For example, any of the following three items can be entered in this syntax: persistPolicy (Never | OnTimer | OnUpdate | NoMoreOftenThan)
Note: Caution:	A note highlights important supplemental information. A caution highlights procedures or information that is necessary to avoid damage to equipment, damage to software, loss of data, or invalid test results.

Table 1 ����� Formatting Conventions

In addition to this guide, the following guides are available in the JBoss Transactions API 4.2 documentation set:

�        JBoss Transactions API 4.2 Release Notes:� Provides late-breaking information about JBoss Transactions API 4.2.

�        JBoss Transactions API 4.2 Installation Guide:� This guide provides instructions for installing JBoss Transactions API 4.2.

�        JBoss Transactions API 4.2 Administrators Guide:� Provides guidance for administering the system.

Questions or comments about JBoss Transactions API 4.2should be directed to our support team.

 

Chapter 1  

An introduction to the JTA

The interfaces specified by the many transaction standards are typically too low-level for most application programmers. Therefore, Sun Microsystems has specified higher-level interfaces to assist in the development of distributed transactional applications. Note, these interfaces are still low-level, and require, for example, the programmer to be concerned with state management and concurrency for transactional application. In addition, they are geared more for applications which require XA resource integration capabilities, rather than the more general resources which the other APIs allow.

With reference to [JTA99], distributed transaction services typically involve a number of participants:

�        application server: which provides the infrastructure required to support the application run-time environment which includes transaction state management, e.g., an EJB server.

�        transaction manager: provides the services and management functions required to support transaction demarcation, transactional resource management, synchronisation and transaction context propagation.

�        resource manager: (through a resource adapter[1]) provides the application with 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.

�        a communication resource manager (CRM): supports transaction context propagation and access to the transaction service for incoming and outgoing requests.

From the transaction manager�s perspective, the actual implementation of the transaction services does not need to be exposed; only high-level interfaces need to be defined to allow transaction demarcation, resource enlistment, synchronization and recovery process to be driven from the users of the transaction services. The JTA is a high-level application interface that allows a transactional application to demarcate transaction boundaries, and contains also contains a mapping of the X/Open XA protocol.

Chapter 2  

Transactions

The Java Transaction API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction manager interface intended for application server, and a standard Java mapping of the X/Open XA protocol intended for transactional resource manager. All of the JTA classes and interfaces occur within the javax.transaction package, and the corresponding�JBossJTA implementations within the com.arjuna.ats.jta package.

UserTransaction

The UserTransaction interface provides applications with the ability to control transaction boundaries. It has methods for beginning, committing, and rolling back top-level transactions: nested transactions are not supported, and begin throws the NotSupportedException when the calling thread is already associated with a transaction. UserTransaction automatically associates newly created transactions with the invoking thread.

In order to select the local JTA implementation it is necessary to perform the following steps:

1.      make sure the property com.arjuna.ats.jta.jtaTMImplementation is set to com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple.

2.      make sure the property com.arjuna.ats.jta.jtaUTImplementation is set to com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple.

TransactionManager

The TransactionManager interface allows the application server to control transaction boundaries on behalf of the application being managed.

The Transaction Manager maintains the transaction context association with threads as part of its internal data structure. A thread�s transaction context is either null or it refers to a specific global transaction. Multiple threads may be associated with the same global transaction. As noted above, nested transactions are not supported.

Each transaction context is encapsulated by a Transaction object, which can be used to perform operations which are specific to the target transaction, regardless of the calling thread�s transaction context.

The begin method of TransactionManager starts a new top-level transaction and associates the transaction context with the calling thread. If the calling thread is already associated with a transaction then it throws the NotSupportedException.

The getTransaction method returns the Transaction object that represents the transaction context currently associated with the calling thread. This object can be used to perform various operations on the target transaction, described later.

The commit method is used to complete the transaction currently associated with the calling thread. After it returns, the calling thread is associated with no transaction. If commit is called when the thread is not associated with any transaction context, the TM throws an exception. In some implementation, the commit operation is restricted to the transaction originator only. If the calling thread is not allowed to commit the transaction, the TM throws an exception.�JBossJTA does not currently impose any restriction on the ability of threads to terminate transactions.

The rollback method is used to rollback the transaction associated with the current thread. After the rollback method completes, the thread is associated with no transaction.

Suspending and resuming a transaction

The JTA supports the concept of a thread temporarily suspending and resuming transactions to enable it to perform non-transactional work. The suspend method is called to temporarily suspend the current transaction that is associated with the calling thread, i.e., so that the thread is no longer operating within its scope. If the thread is not associated with any transaction, a null object reference is returned; otherwise, a valid Transaction object is returned. The Transaction object can later be passed to the resume method to reinstate the transaction context.

The resume method associates the specified transaction context with the calling thread. If the transaction specified is a valid transaction, the transaction context is associated with the calling thread; otherwise, the thread is associated with no transaction.

Transaction tobj = TransactionManager.suspend();

..

TransactionManager.resume(tobj);

When a transaction is suspended the application server must ensure that the resources in use by the application are no longer registered with the suspended transaction. When a resource is de-listed this triggers the Transaction Manager to inform the resource manager to disassociate the transaction from the specified resource object. When the application�s transaction context is resumed, the application server must ensure that the resources in use by the application are again enlisted with the transaction. Enlisting a resource as a result of resuming a transaction triggers the Transaction Manager to inform the resource manager to re-associate the resource object with the resumed transaction.

The Transaction interface

The Transaction interface allows operations to be performed on the transaction associated with the target object. Every top-level transaction is associated with one Transaction object when the transaction is created. The Transaction object can be used to:

�        enlist the transactional resources in use by the application.

�        register for transaction synchronization call backs.

�        commit or rollback the transaction.

�        obtain the status of the transaction.

The commit and rollback methods allow the target object to be committed or rolled back. The calling thread is not required to have the same transaction associated with the thread. If the calling thread is not allowed to commit the transaction, the transaction manager throws an exception.�At present JBossJTA does not impose restrictions on threads terminating transactions.

Resource enlistment

Transactional resources such as database connections are typically managed by the application server in conjunction with some resource adapter and optionally with connection pooling optimization. In order for an external transaction manager to co-ordinate transactional work performed by the resource managers, the application server must enlist and de-list the resources used in the transaction. These resources (participants) are enlisted with the transaction so that they can be informed when the transaction terminates, e.g., are driven through the two-phase commit protocol.

As stated previously, the JTA is much more closely integrated with the XA concept of resources than the arbitrary objects. For each resource in-use by the application, the application server invokes the enlistResource method with an XAResource object which identifies the resource in use. See Chapter 4 for details on how the implementation of the XAResource can affect recovery in the event of a failure.

The enlistment request results in the transaction manager informing the resource manager to start associating the transaction with the work performed through the corresponding resource. The transaction manager is responsible for passing the appropriate flag in its XAResource.start method call to the resource manager.

The delistResource method is used to disassociate the specified resource from the transaction context in the target object. The application server invokes the method with the two parameters: the XAResource object that represents the resource, and a flag to indicate whether the operation is due to the transaction being suspended (TMSUSPEND), a portion of the work has failed (TMFAIL), or a normal resource release by the application (TMSUCCESS).

The de-list request results in the transaction manager informing the resource manager to end the association of the transaction with the target XAResource. The flag value allows the application server to indicate whether it intends to come back to the same resource whereby the resource states must be kept intact. The transaction manager passes the appropriate flag value in its XAResource.end method call to the underlying resource manager.

Transaction synchronization

Transaction synchronization allows the application server to be notified before and after the transaction completes. For each transaction started, the application server may optionally register a Synchronization call back object to be invoked by the transaction manager:

�        The beforeCompletion method is called prior to the start of the two-phase transaction complete process. This call is executed in the same transaction context of the caller who initiates the TransactionManager.commit or the call is executed with no transaction context if Transaction.commit is used.

�        The afterCompletion method is called after the transaction has completed. The status of the transaction is supplied in the parameter. This method is executed without a transaction context.

Transaction equality

The transaction manager implements the Transaction object�s equals method to allow comparison between the target object and another Transaction object. The equals method should return true if the target object and the parameter object both refer to the same global transaction.

Transaction txObj = TransactionManager.getTransaction();

Transaction someOtherTxObj = ..

..

boolean isSame = txObj.equals(someOtherTxObj);

Chapter 3  

The Resource Manager

Whereas some transaction specifications and systems define a generic resource which can be used to register arbitrary resources with a transaction, the JTA is much more XA specific. The javax.transaction.xa.XAResource interface is a Java mapping of the XA interface. The XAResource interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing environment. A resource adapter for a resource manager implements the XAResource interface to support association of a top-level transaction to a resource such as a relational database.

The XAResource interface can be supported by any transactional resource adapter that is intended to be used in an environment where transactions are controlled by an external transaction manager, e.g., a database management system. An application may access data through multiple database connections. Each database connection is associated with an XAResource object that serves as a proxy object to the underlying resource manager instance. The transaction manager obtains an XAResource for each resource manager participating in a top-level transaction. It uses the start method to associate the transaction with the resource, and it uses the end method to disassociate the transaction from the resource.

The resource manager is responsible for associating the transaction with all work performed on its data between the start and end invocations. At transaction commit time, these transactional resource managers are informed by the transaction manager to prepare, commit, or rollback the transaction according to the two-phase commit protocol.

In order to be better integrated with Java, the XAResource differs from the standard XA interface in the following ways:

�        The resource manager initialization is done implicitly by the resource adapter when the resource (connection) is acquired. There is no xa_open equivalent.

�        Rmid is not passed as an argument. Each Rmid is represented by a separate XAResource object.

�        Asynchronous operations are not supported because Java supports multi-threaded processing and most databases do not support asynchronous operations.

�        Error return values that are caused by the transaction manager�s improper handling of the XAResource object are mapped to Java exceptions via the XAException class.

�        The DTP concept of �Thread of Control� maps to all Java threads that are given access to the XAResource and Connection objects. For example, it is legal for two different threads to perform the start and end operations on the same XAResource object.

Extended XAResource control

By default, whenever an XAResource object is registered with a JTA compliant transaction service, you have no control over the order in which it will be invoked during the two-phase commit protocol, with respect to other XAResource objects. In JBossTS, however, there is support for controlling the order via the two interfaces com.arjuna.ats.jta.resources.StartXAResource and com.arjuna.ats.jta.resources.EndXAResource. By inheriting your XAResource instance from either of these interfaces, you control whether an instance of your class will be invoked first or last, respectively.

In the TxCore manual we discussed the Last Resource Commit optimization (LRCO), whereby a single resource that is only one-phase aware (does not support prepare), can be enlisted with a transaction that is manipulating two-phase aware participants. This optimization is also supported within the JTA aspect of JBossTS.

In order to use the LRCO, your XAResource implementation must extend the com.arjuna.ats.jta.resources.LastResourceCommitOptimisation marker interface (it provides no methods). When enlisting the resource via Transaction.enlistResource, JBossTS will ensure that only a single instance of this type of participant is used