IBM WebSphere Application ServerTM
Release 7

com.ibm.wsspi.uow
Interface UOWManager

All Superinterfaces:
com.ibm.websphere.uow.UOWSynchronizationRegistry

public interface UOWManager
extends com.ibm.websphere.uow.UOWSynchronizationRegistry

This interface provides functionality to execute application logic under a specific unit of work (UOW). Application logic is encapsulted in a UOWAction instance and is executed under the specified type of UOW, either a new UOW or an existing UOW. If the work is executed under a new UOW, then the existing UOW is suspended for the duration of the new UOW and resumed once the new UOW is completed. The UOW on the thread before a runUnderUOW is always the same as the UOW on the thread after completion of runUnderUOW.

This interface is intended for use by system level application server components such as persistence managers, resource adapters, as well as EJB and Web application components.

This interface is implemented by the application server using a stateless object. The same object can be used by any number of components with thread safety.

An instance implementing this interface can be looked up via JNDI by using the name java:comp/websphere/UOWManager when executed within a container environment. If the UOWManager is required outside of a container managed environment, then an instance can be obtained using UOWManagerFactory. Note that UOWManager is only available in a server environment.


Field Summary
 
Fields inherited from interface com.ibm.websphere.uow.UOWSynchronizationRegistry
UOW_STATUS_ACTIVE, UOW_STATUS_COMMITTED, UOW_STATUS_COMPLETING, UOW_STATUS_NONE, UOW_STATUS_ROLLBACKONLY, UOW_STATUS_ROLLEDBACK, UOW_TYPE_ACTIVITYSESSION, UOW_TYPE_GLOBAL_TRANSACTION, UOW_TYPE_LOCAL_TRANSACTION
 
Method Summary
 int getUOWTimeout()
          Returns the total timeout, in seconds, as set when the current unit of work was begun.
 void runUnderUOW(int uowType, boolean join, UOWAction uowAction)
           Causes the work encapsulated by the uowAction run method to be executed under the requested UOW.
 void setUOWTimeout(int uowType, int timeout)
          Sets the timeout, in seconds, for the given UOW type to be used by the current thread when programmatically beginning a new UOW.
 
Methods inherited from interface com.ibm.websphere.uow.UOWSynchronizationRegistry
getLocalUOWId, getResource, getRollbackOnly, getUOWName, getUOWStatus, getUOWType, putResource, registerInterposedSynchronization, setRollbackOnly
 

Method Detail

runUnderUOW

void runUnderUOW(int uowType,
                 boolean join,
                 UOWAction uowAction)
                 throws UOWActionException,
                        UOWException

Causes the work encapsulated by the uowAction run method to be executed under the requested UOW. The UOW that is requested is controlled by both the uowType and join parameters.

The uowType parameter determines under what type of UOW the work will be run, i.e. under a local transaction containment, a global transaction, or an ActivitySession. If the current unit of work is not of the requested type then the current unit of work is suspended and a new UOW, of the requested type, is begun. When a new UOW of type UOW_TYPE_ACTIVITYSESSION is started, an associated container-resolved local transaction containment is also started with a boundary that is scoped to the ActivitySession. When a new UOW of type UOW_TYPE_LOCAL_TRANSACTION is started, an application-resolved local transaction containment is started.

In the event of the current UOW being of the same type as the requested UOW, the join parameter determines whether or not the current UOW is joined. With a join parameter of true the existing UOW will be used. With a join parameter of false the existing UOW will be suspended and a new UOW begun. Note that when requesting to run under a local transaction the join parameter has no effect and a new application-resolved local transaction containment will always be begun.

Exceptions thrown by the given action's run method are handled as follows:

In the event of a new UOW being begun it will run for the duration of the call to this method. Upon completion of this method's execution the new UOW will be committed unless the action's run method marked the transaction rollback-only or threw an unchecked exception, in which case the new UOW is rolled back. Should the action's run method complete successfuly but the commit processing fail unexpectedly, a UOWException will be thrown which will contain, as its cause, the exception that caused the failure. In all cases the previously suspended UOW is resumed.

In the event of the caller's UOW being joined then the transaction is never ended as a result of processing the action's run method, although the UOW is marked rollback-only if the action's run method throws an unchecked exception.

The action may be defined as an in-line anonymous class as follows. This example illustrates performing some logic in the scope of a new global transaction:

 try
 {
     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.
     // The UOW was not affected.
 }
 catch (RuntimeException re)
 {
     // Transactional work resulted in an unchecked exception being thrown.
     // The UOW was rolled back
 }
 catch (UOWException uowe)
 {
     // The completion of the UOW failed unexpectedly.
 }
 

Parameters:
uowType - The type of UOW to run the work under
join - Whether the current UOW, if it is of the required type, should be joined or a new UOW must be begun.
uowAction - The work to be executed under the requested UOW
Throws:
UOWActionException - Thrown if the given action's run method threw a checked exception
UOWException - Thrown if completion of a new UOW fails unexpectedly.
See Also:
UOWAction.run(), UOWSynchronizationRegistry.UOW_TYPE_ACTIVITYSESSION, UOWSynchronizationRegistry.UOW_TYPE_GLOBAL_TRANSACTION, UOWSynchronizationRegistry.UOW_TYPE_LOCAL_TRANSACTION

getUOWTimeout

int getUOWTimeout()
                  throws java.lang.IllegalStateException
Returns the total timeout, in seconds, as set when the current unit of work was begun.

Returns:
The current unit of work's initial timeout value in seconds.
Throws:
java.lang.IllegalStateException - Thrown if no UOW is bound to the thread or if the type of UOW bound to the thread does not support timeout, e.g. UOW_TYPE_LOCAL_TRANSACTION

setUOWTimeout

void setUOWTimeout(int uowType,
                   int timeout)
Sets the timeout, in seconds, for the given UOW type to be used by the current thread when programmatically beginning a new UOW. A value of zero will restore the default timeout. For global transactions, this default will be the total transaction timeout value configured on the transaction service.

Parameters:
uowType - The type of UOW for which the timeout is to be set
timeout - The timeout, in seconds, for the UOW type
Throws:
java.lang.IllegalArgumentException - Thrown if the specified type of UOW does not support timeout, e.g. UOW_TYPE_LOCAL_TRANSACTION.
See Also:
UOWSynchronizationRegistry.UOW_TYPE_ACTIVITYSESSION, UOWSynchronizationRegistry.UOW_TYPE_GLOBAL_TRANSACTION, UOWSynchronizationRegistry.UOW_TYPE_LOCAL_TRANSACTION

IBM WebSphere Application ServerTM
Release 7