com.ibm.websphere.uow

Interface UOWSynchronizationRegistry



  • public interface UOWSynchronizationRegistry

    This interface provides functionality equivalent to javax.transaction.TransactionSynchronizationRegistry for all types of unit of work (UOW) supported by WebSphere Application Server (WAS) in a UOW-agnostic fashion. It is intended for use by system level application server components such as persistence managers, resource adapters, as well as EJB and Web application components and provides the ability to register synchronization objects with special ordering semantics, associate resource objects with the UOW, get the context of the current UOW, get current UOW status, and mark the current UOW for rollback.

    In the event of multiple units of work being bound to the current thread, e.g. a global or local transaction nested within an ActivitySession, the unit of work that is accessed by invocation of methods on an instance of this interface will occur against the unit of work that is responsible for coordinating enlisted resources. When there is a global transaction bound to the current thread it will always be responsible for such coordination irrespective of the presence or otherwise of an ActivitySession. In the case of a local transaction and an ActivitySession the unit of work that is coordinating resource is dependent on the configuration settings for the local transaction. If the local transaction is configured with a resolver of container-at-boundary and a boundary of ActivitySession the ActivitySession will be responsible for coordination of enlisted resources, otherwise the local transaction is responsible for such coordination.

    This interface is implemented by the application server by a stateless service 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/UOWSynchronizationRegistry. Note that UOWSynchronizationRegistry is only available in a server environment.

    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int UOW_STATUS_ACTIVE
      Indicates that a UOW is bound to the current thread and it is in the active state.
      static int UOW_STATUS_COMMITTED
      Indicates that a UOW is bound to the current thread and that it has been committed.
      static int UOW_STATUS_COMPLETING
      Indicates that a UOW is bound to the current thread and that it is in the process of completing.
      static int UOW_STATUS_NONE
      Indicates that no UOW is bound to the current thread.
      static int UOW_STATUS_ROLLBACKONLY
      Indicates that a UOW is bound to the current thread and it has been marked for rollback, perhaps as a result of a setRollbackOnly operation.
      static int UOW_STATUS_ROLLEDBACK
      Indicates that a UOW is bound to the current thread and that it has been rolled back.
      static int UOW_TYPE_ACTIVITYSESSION
      Identifies that the UOW is an ActivitySession.
      static int UOW_TYPE_GLOBAL_TRANSACTION
      Identifies that the UOW is a global transaction.
      static int UOW_TYPE_LOCAL_TRANSACTION
      Identifies that the UOW bound to the current thread is a local transaction.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      long getLocalUOWId()
      Returns a long that uniquely identifies the unit of work bound to the current thread at the time this method is called.
      java.lang.Object getResource(java.lang.Object key)
      Get an object from the map of resources being managed by the current unit of work.
      boolean getRollbackOnly()
      Get the rollbackOnly status of the current unit of work.
      java.lang.String getUOWName()
      Returns the human-readable name that identifies the current unit of work, or null if no UOW is bound to the thread.
      int getUOWStatus()
      Returns the status of the current unit of work.
      int getUOWType()
      Returns the type of the current unit of work.
      void putResource(java.lang.Object key, java.lang.Object value)
      Add or replace an object in the Map of resources being managed by the current unit of work.
      void registerInterposedSynchronization(javax.transaction.Synchronization sync)
      Register a Synchronization instance with special ordering semantics.
      void setRollbackOnly()
      Set the rollbackOnly status of the current unit of work such that the only possible outcome of the unit of work is rollback.
    • Field Detail

      • UOW_STATUS_ACTIVE

        static final int UOW_STATUS_ACTIVE
        Indicates that a UOW is bound to the current thread and it is in the active state.
        See Also:
        getUOWStatus(), Constant Field Values
      • UOW_STATUS_ROLLBACKONLY

        static final int UOW_STATUS_ROLLBACKONLY
        Indicates that a UOW is bound to the current thread and it has been marked for rollback, perhaps as a result of a setRollbackOnly operation.
        See Also:
        getUOWStatus(), Constant Field Values
      • UOW_STATUS_COMPLETING

        static final int UOW_STATUS_COMPLETING
        Indicates that a UOW is bound to the current thread and that it is in the process of completing.
        See Also:
        getUOWStatus(), Constant Field Values
      • UOW_STATUS_COMMITTED

        static final int UOW_STATUS_COMMITTED
        Indicates that a UOW is bound to the current thread and that it has been committed.
        See Also:
        getUOWStatus(), Constant Field Values
      • UOW_STATUS_ROLLEDBACK

        static final int UOW_STATUS_ROLLEDBACK
        Indicates that a UOW is bound to the current thread and that it has been rolled back.
        See Also:
        getUOWStatus(), Constant Field Values
      • UOW_TYPE_LOCAL_TRANSACTION

        static final int UOW_TYPE_LOCAL_TRANSACTION
        Identifies that the UOW bound to the current thread is a local transaction.
        See Also:
        getUOWType(), Constant Field Values
    • Method Detail

      • getLocalUOWId

        long getLocalUOWId()
        Returns a long that uniquely identifies the unit of work bound to the current thread at the time this method is called.
        Returns:
        The unique identifier for the current unit of work
        Throws:
        java.lang.IllegalStateException - Thrown if no UOW is bound to the thread
      • getResource

        java.lang.Object getResource(java.lang.Object key)
                                     throws java.lang.NullPointerException

        Get an object from the map of resources being managed by the current unit of work. The key should have been supplied earlier by a call to putResouce in the same unit of work. If the key cannot be found in the current resource Map, null is returned.

        The general contract of this method is that of Map.get(Object) for a Map that supports non-null keys and null values. For example, the returned value is null if there is no entry for the parameter key or if the value associated with the key is actually null.

        Parameters:
        key - The key for the Map entry
        Returns:
        The value from the Map
        Throws:
        java.lang.NullPointerException - Thrown if the key is null
        java.lang.IllegalStateException - Thrown if no UOW is bound to the thread
      • getRollbackOnly

        boolean getRollbackOnly()
        Get the rollbackOnly status of the current unit of work.
        Returns:
        The current unit of work's rollbackOnly status.
        Throws:
        java.lang.IllegalStateException - Thrown if no UOW is bound to the thread
      • putResource

        void putResource(java.lang.Object key,
                       java.lang.Object value)

        Add or replace an object in the Map of resources being managed by the current unit of work. The supplied key should be of a caller-defined class so as not to conflict with other users. The class of the key must guarantee that the hashCode and equals methods are suitable for use as a keys in a Map. The key and value are not examined or used by the implementation.

        The general contract of this method is that of Map.put(Object, Object) for a Map that supports non-null keys and null values. For example, if there is already an value associated with the key, it is replaced by the value parameter.

        Parameters:
        key - The key for the Map entry.
        value - The value for the Map entry.
        Throws:
        java.lang.NullPointerException - If the parameter key is null.
        java.lang.IllegalStateException - Thrown if no UOW is bound to the thread
      • registerInterposedSynchronization

        void registerInterposedSynchronization(javax.transaction.Synchronization sync)

        Register a Synchronization instance with special ordering semantics. Its beforeCompletion will be called after all SessionSynchronization beforeCompletion callbacks and callbacks registered directly with the unit of work, but before commit processing starts. Similarly, the afterCompletion callback will be called after commit completes but before any SessionSynchronization and directly-registered afterCompletion callbacks.

        The beforeCompletion callback will be invoked in the unit of work context of the unit of work bound to the current thread at the time this method is called. Allowable methods include access to resources, e.g. Connectors. No access is allowed to "user components" (e.g. timer services or bean methods), as these might change the state of data being managed by the caller, and might change the state of data that has already been flushed by another caller of registerInterposedSynchronization. The general context is the component context of the caller of registerInterposedSynchronization.

        The afterCompletion callback will be invoked in an undefined context. No access is permitted to "user components" as defined above. Resources can be closed but no work can be performed with them.

        Parameters:
        sync - The Synchronization instance.
        Throws:
        java.lang.IllegalStateException - Thrown if the UOW is in not in a state to accept synchronization registration, e.g. a global transaction that is preparing, or if no UOW is bound to the thread.
        java.lang.NullPointerException - Thrown if the given synchronization is null
      • setRollbackOnly

        void setRollbackOnly()
        Set the rollbackOnly status of the current unit of work such that the only possible outcome of the unit of work is rollback.
        Throws:
        java.lang.IllegalStateException - Thrown if no UOW is bound to the thread
      • getUOWName

        java.lang.String getUOWName()

        Returns the human-readable name that identifies the current unit of work, or null if no UOW is bound to the thread. The format of the name is undefined.

        Returns:
        The name of the current unit of work
IBM WebSphere Application ServerTM
Release 9.0