Package com.ibm.wsspi.uow

Interface UOWManager

All Superinterfaces:
UOWSynchronizationRegistry
public interface UOWManager extends 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.

  • Method Details

    • 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:

      • Any checked exception is wrapped in a UOWActionException instance which is then thrown to this method's caller and the UOW is unaffected, i.e. it is not marked rollback only and it may be committed.
      • Any unchecked exception is passed to this method's caller as-is and the UOW is marked rollback only.

      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:

    • getUOWTimeout

      int getUOWTimeout() throws 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:
      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

    • getUOWExpiration

      long getUOWExpiration() throws IllegalStateException
      Returns the time in milliseconds since the epoch at which the current unit of work is set to timeout.
      Returns:
      The time at which the current unit of work is set to timeout
      Throws:
      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:
      IllegalArgumentException - Thrown if the specified type of UOW does not support timeout, e.g. UOW_TYPE_LOCAL_TRANSACTION.
      See Also:

    • runUnderUOW

      Object runUnderUOW(int uowType, boolean join, ExtendedUOWAction uowAction, Class<?>[] rollbackOn, Class<?>[] dontRollbackOn) throws Exception

      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. This method returns the value returned by the run method.

      The uowType parameter determines under what type of UOW the work will be run, i.e. under a local transaction containment or a global transaction. 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_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:

      • Any checked exception is thrown to this method's caller. Unless the exception is in the rollbackOn list the UOW is unaffected, i.e. it is not marked rollback-only and it may be committed.
      • Any RuntimeException or Error is thrown to this method's caller and the UOW is marked rollback-only unless it is in the dontRollbackOn list.

      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 is committed unless the run method threw something that caused the UOW to be marked rollback-only. Any exception thrown by the commit processing is thrown to the caller. 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 could be marked rollback-only if the action's run method throws an exception.

      Throws:
      Exception