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.
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
Modifier and Type | Method and Description |
---|---|
long |
getUOWExpiration()
Returns the time in milliseconds since the epoch
at which the current unit of work is set to timeout.
|
int |
getUOWTimeout()
Returns the total timeout, in seconds, as set when the current unit
of work was begun.
|
java.lang.Object |
runUnderUOW(int uowType,
boolean join,
ExtendedUOWAction uowAction,
java.lang.Class<?>[] rollbackOn,
java.lang.Class<?>[] dontRollbackOn)
Causes the work encapsulated by the uowAction run
method to be executed under the requested UOW.
|
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.
|
getLocalUOWId, getResource, getRollbackOnly, getUOWName, getUOWStatus, getUOWType, putResource, registerInterposedSynchronization, setRollbackOnly
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. }
uowType
- The type of UOW to run the work underjoin
- 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 UOWUOWActionException
- Thrown if the given action's run method threw a
checked exceptionUOWException
- Thrown if completion of a new UOW
fails unexpectedly.UOWAction.run()
,
UOWSynchronizationRegistry.UOW_TYPE_ACTIVITYSESSION
,
UOWSynchronizationRegistry.UOW_TYPE_GLOBAL_TRANSACTION
,
UOWSynchronizationRegistry.UOW_TYPE_LOCAL_TRANSACTION
int getUOWTimeout() throws java.lang.IllegalStateException
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_TRANSACTIONlong getUOWExpiration() throws java.lang.IllegalStateException
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_TRANSACTIONvoid setUOWTimeout(int uowType, int timeout)
uowType
- The type of UOW for which the timeout is to be settimeout
- The timeout, in seconds, for the UOW typejava.lang.IllegalArgumentException
- Thrown if the specified type of UOW
does not support timeout, e.g. UOW_TYPE_LOCAL_TRANSACTION.UOWSynchronizationRegistry.UOW_TYPE_ACTIVITYSESSION
,
UOWSynchronizationRegistry.UOW_TYPE_GLOBAL_TRANSACTION
,
UOWSynchronizationRegistry.UOW_TYPE_LOCAL_TRANSACTION
java.lang.Object runUnderUOW(int uowType, boolean join, ExtendedUOWAction uowAction, java.lang.Class<?>[] rollbackOn, java.lang.Class<?>[] dontRollbackOn) throws java.lang.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:
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.
java.lang.Exception