JTA support

Java™ Transaction API (JTA) support provides application programming interfaces (APIs) in addition to the UserTransaction interface that is defined in the JTA 1.1 specification.

These interfaces include the TransactionSynchronizationRegistry interface, which is defined in the JTA 1.1 specification, and the following API extensions:
  • SynchronizationCallback interface
  • ExtendedJTATransaction interface
  • UOWSynchronizationRegistry interface
  • UOWManager interface
The APIs provide the following functions:
  • Access to global and local transaction identifiers associated with the thread.

    The global identifier is based on the transaction identifier in the CosTransactions::PropagationContext: object and the local identifier identifies the transaction uniquely in the local Java virtual machine (JVM).

  • A transaction synchronization callback that any enterprise application component can use to register an interest in transaction completion.

    Advanced applications can use this callback to flush updates before transaction completion and clear up state after transaction completion. Java EE (and related) specifications position this function typically as the domain of the enterprise application containers.

    Components such as persistence managers, resource adapters, enterprise beans, and web application components can register with a JTA transaction.

The following information is an overview of the interfaces that the JTA support provides. For more detailed information, see the generated API documentation.

SynchronizationCallback interface

An object implementing this interface is enlisted once through the ExtendedJTATransaction interface, and receives notification of transaction completion.

Although an object implementing this interface can run on a Java platform for enterprise applications server, there is no specific enterprise application component active when this object is called. So, the object has limited direct access to any enterprise application resources. Specifically, the object has no access to the java: namespace or to any container-mediated resource. Such an object can cache a reference to an enterprise application component (for example, a stateless session bean) that it delegates to. The object would then have all the usual access to enterprise application resources. For example, you might use the object to acquire a Java Database Connectivity (JDBC) connection and flush updates to a database during the beforeCompletion method.

ExtendedJTATransaction interface

This interface is a WebSphere® programming model extension to the Java EE JTA support. An object implementing this interface is bound, by enterprise application containers in WebSphere Application Server that support this interface, at java:comp/websphere/ExtendedJTATransaction. Access to this object, when called from an Enterprise JavaBeans (EJB) container, is not restricted to component-managed transactions.

An application uses a Java Naming and Directory Interface (JNDI) lookup of java:comp/websphere/ExtendedJTATransaction to get an ExtendedJTATransaction object, which the application uses as shown in the following example:
ExtendedJTATransaction exJTA = (ExtendedJTATransaction)ctx.lookup("
	java:comp/websphere/ExtendedJTATransaction");
SynchronizationCallback sync = new SynchronizationCallback();
exJTA.registerSynchronizationCallback(sync);
The ExtendedJTATransaction object supports the registration of one or more application-provided SynchronizationCallback objects. Depending on how the callback is registered, each registered callback is called at one of the following points:
  • At the end of every transaction that runs on the application server, whether the transaction is started locally or imported
  • At the end of the transaction for which the callback was registered
Deprecated feature: In this release, the registerSynchronizationCallbackForCurrentTran method is deprecated. Use the registerInterposedSynchronization method of the TransactionSynchronizationRegistry interface instead.

TransactionSynchronizationRegistry interface

This interface is defined in the JTA 1.1 specification. System-level application components, such as persistence managers, resource adapters, enterprise beans, and web application components, can use this interface to register with a JTA transaction. Then, for example, the component can flush a cache when a transaction completes.

To obtain the TransactionSynchronizationRegistry interface, use a JNDI lookup of java:comp/TransactionSynchronizationRegistry.

Note: Use the registerInterposedSynchronization method to register a synchronization instance, rather than the registerSynchronizationCallbackForCurrentTran method of the ExtendedJTATransaction interface, which is deprecated in this release.

UOWSynchronizationRegistry interface

This interface provides the same functions as the TransactionSynchronizationRegistry interface, but applies to all types of units of work (UOWs) that WebSphere Application Server supports:
  • JTA transactions
  • local transaction containments (LTCs)
  • ActivitySession contexts
System-level application server components such as persistence managers, resource adapters, enterprise beans, and web application components can use this interface to register with a JTA transaction. The component can do the following:
  • Register synchronization objects with special ordering semantics.
  • Associate resource objects with the UOW.
  • Get the context of the current UOW.
  • Get the current UOW status.
  • Mark the current UOW for rollback.

To obtain the UOWSynchronizationRegistry interface, use a JNDI lookup of java:comp/websphere/UOWSynchronizationRegistry. This interface is available only in a server environment.

The following example registers an interposed synchronization with the current UOW:
// Retrieve an instance of the UOWSynchronizationRegistry interface from JNDI.
final InitialContext initialContext = new InitialContext();
final UOWSynchronizationRegistry uowSyncRegistry =
		(UOWSynchronizationRegistry)initialContext.lookup("java:comp/websphere/UOWSynchronizationRegistry");

// Instantiate a class that implements the javax.transaction.Synchronization interface
final Synchronization sync = new SynchronizationImpl();

// Register the Synchronization object with the current UOW.
uowSynchronizationRegistry.registerInterposedSynchronization(sync);

UOWManager interface

The UOWManager interface is equivalent to the JTA TransactionManager interface, which defines the methods that allow an application server to manage transaction boundaries. Applications can use the UOWManager interface to manipulate UOW contexts in the product. The UOWManager interface applies to all types of UOWs that WebSphere Application Server supports; that is, JTA transactions, local transaction containments (LTCs), and ActivitySession contexts. Application code can run in a particular type of UOW without needing to use an appropriately configured enterprise bean. Typically, the logic that is performed in the scope of the UOW is encapsulated in an anonymous inner class. System-level application server components such as persistence managers, resource adapters, enterprise beans, and web application components can use this interface.

WebSphere Application Server does not provide a TransactionManager interface in the API or the system programming interface (SPI). The UOWManager interface provides equivalent functions, but WebSphere Application Server maintains control and integrity of the UOW contexts.

To obtain the UOWManager interface in a container-managed environment, use a JNDI lookup of java:comp/websphere/UOWManager. To obtain the UOWManager interface outside a container-managed environment, use the UOWManagerFactory class. This interface is available only in a server environment.

You can use the UOWManager interface to migrate a web application to use web components rather than enterprise beans, but maintain control over the UOWs. For example, a web application currently uses the UserTransaction interface to begin a global transaction, makes a call to a method on a session enterprise bean that is configured as not supported to undertake some non-transactional work, and then completes the global transaction. You can move the logic that is encapsulated in the session EJB method to the run method of a UOWAction implementation. Then, you replace the code in the web component that calls the session enterprise bean with a call to the runUnderUOW method of a UOWManager interface to request that this logic is run in a local transaction. In this way, you maintain the same level of control over the UOWs as you had with the original application.

The following example performs some transactional work in the scope of a new global transaction. The transactional work is performed in an anonymous inner-class that implements the run method of the UOWAction interface. Any checked exceptions that the run method creates do not affect the outcome of the transaction. 
// Retrieve an instance of the UOWManager interface from JNDI.
final InitialContext initialContext = new InitialContext();
final UOWManager uowManager = (UOWManager)initialContext.lookup("java:comp/websphere/UOWManager");

try
{
	// Invoke the runUnderUOW method, indicating that the logic should be run in a global 
	// transaction, and that any existing global transaction should not be joined, that is, 
	// the work must be performed in the scope of a new global transaction.
	uowManager.runUnderUOW(UOWSynchronizationRegistry.UOW_TYPE_GLOBAL_TRANSACTION, false, new UOWAction()
	{
 		public void run() throws Exception
 		{
			// Perform transactional work here.
 		}
	});
}

catch (UOWActionException uowae)
{
	// Transactional work resulted in a checked exception being thrown.
}

catch (UOWException uowe)
{
	// The completion of the UOW failed unexpectedly. Use the getCause method of the 
	// UOWException to retrieve the cause of the failure.
}