JTA support

 

+

Search Tips   |   Advanced Search

 

JTA support provides APIs in addition to the UserTransaction interface that is defined in the JTA 1.1 specification.

These interfaces include the interface...

TransactionSynchronizationRegistry

...which is defined in the JTA 1.1 specification, and the following API extensions...

• SynchronizationCallback
• ExtendedJTATransaction
• UOWSynchronizationRegistry
• UOWManager

New feature: WAS V7.0 features additional JTA support. JTA 1.1 is supported through the introduction of the TransactionSynchronizationRegistry interface.

System-level application components, such as...

• persistence managers
• resource adapters
• enterprise beans
• Web app components

...can use the TransactionSynchronizationRegistry interface to register with a JTA transaction.

Also, the UOWSynchronizationRegistry interface and the UOWManager interface are introduced so that all types of units of work (UOWs) that WAS supports can register with a JTA transaction and can be manipulated

The APIs provide the following functionality:

• Access to global and local transaction identifiers associated with the thread.

  The global identifier is based on the transaction identifier in the object...

  CosTransactions::PropagationContext:

  ...and the local identifier identifies the transaction uniquely in the local 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 app components can register with a JTA transaction.

 

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 apps 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 could use the object to acquire a 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 WAS that support this interface, at...

java:comp/websphere/ExtendedJTATransaction

Access to this object, when called from an EJB container, is not restricted to component-managed transactions.

An application uses a 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 appserver, 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.depfeat

 

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 app 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

Deprecated feature: Use the registerInterposedSynchronization method to register a synchronization instance, rather than the method...

registerSynchronizationCallbackForCurrentTran

...of the ExtendedJTATransaction interface, which is deprecated in this release.

 

UOWSynchronizationRegistry interface

This interface provides the same functionality as the TransactionSynchronizationRegistry interface, but applies to all types of units of work (UOWs) that WAS supports:

• JTA transactions
• local transaction containments (LTCs)
• ActivitySession contexts

System-level appserver components such as persistence managers, resource adapters, enterprise beans, and Web app 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 appserver to manage transaction boundaries. Applications can use the UOWManager interface to manipulate UOW contexts in WAS ND. The UOWManager interface applies to all types of UOWs that WAS 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 appserver components such as persistence managers, resource adapters, enterprise beans, and Web app components can use this interface.

WAS does not provide a TransactionManager interface in the API or the system programming interface (SPI). The UOWManager interface provides equivalent functionality, but WAS 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.

We can use the UOWManager interface to migrate a Web app to use Web components rather than enterprise beans, but maintain control over the UOWs. For example, a Web app currently uses the UserTransaction interface to begin a global transaction, makes a call to a method on a session enterprise bean configured as not supported to perform some non-transactional work, and then completes the global transaction. We 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.
}

---

 

Related concepts

Global transactions
Transaction support and the Spring Framework
Transaction support in WAS

 

Related information

Additional Application Programming Interfaces (APIs)
JTA 1.1 specification