com.ibm.wsspi.batch.parallel.logicalTX

Class Synchronization

  • All Implemented Interfaces:
    java.lang.Comparable


    public abstract class Synchronization
    extends SPI
    Synchronization is the abstract base class for the ParallelJobManager logical transaction Synchronization System Programming Interface (SPI). Use the Synchronization SPI to receive callbacks that demarcate the lifecycle of a parallel job logical transaction. A logical transaction provides a logical unit of work scope that spans all subjobs belonging to a parallel job. The ParallelJobManager starts a logical transaction before the subjobs are submitted and completes the logical transaction after all subjobs have completed.

    Note: logical transactions provide a containment scope only - resource enlistment and coordination with resource manager JTA transactions is not provided.

    Rollback is initiated in the following ways:

    1. When any SPI in the com.ibm.wsspi.batch.parallel family throws declared exception RollbackLogicalTXException.
    2. When any subjob completes in the Restartable or Failed state.

    When rollback is triggered, the following actions are taken:

    1. In-flight subjobs are cancelled. This includes subjobs still executing on endpoints, as well as subjobs that may be awaiting dispatch.
    2. The rollBack method on this SPI is invoked. It is the responsibility of the rollBack method to undo any work done by subjobs that have successfully completed one or more checkpoints. Note this includes subjobs that have completed successfully - i.e. are in the "ended" state.

    Implement the Synchronization SPI, by extending this class and implementing the begin, beforeCompletion, afterCompletion, and rollBack methods.

    Configure this SPI with the following declaration in the xd.spi.properties file:

     spi.parallel.logicalTX.Synchronization=<fully-qualified implementation class name>
     

    Notes:

    1. The xd.spi.properties file is located in:

       <WAS install root>/properties.  E.g.
       
             /WebSphere/AppServer/properties
       
    2. The jar file containing the implementation of this SPI should be stored in:

       <WAS install root>/lib/classes.  E.g.
       
             /WebSphere/AppServer/lib/classes
       

      You are responsible for creating the classes directory if it does not already exist.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      static class  Synchronization.TXStatus
      Specifies status values for logical transaction outcome.
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static boolean TX_NOT_RESTARTABLE
      Specifies that the logical transaction is not restartable.
      static boolean TX_RESTARTABLE
      Specifies that the logical transaction is restartable.
    • Constructor Summary

      Constructors 
      Constructor and Description
      Synchronization() 
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      abstract void afterCompletion(java.lang.String logicalTXID, Synchronization.TXStatus status)
      Indicates the specified logical transaction has completed with the indicated status.
      abstract void beforeCompletion(java.lang.String logicalTXID)
      Indicates all subjobs have ended and that the specified logical transaction is about to commit.
      abstract void begin(java.lang.String logicalTXID)
      Indicates the specified logical transaction has begun.
      java.lang.String getName()
      Returns the name of this SPI instance.
      abstract com.ibm.wsspi.batch.parallel.logicalTX.RestartInstructions rollBack(java.lang.String logicalTXID, boolean restartable)
      Invoked to undo changes made by subjobs within the unit of work scope of the specified logical transaction.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • TX_RESTARTABLE

        public static boolean TX_RESTARTABLE
        Specifies that the logical transaction is restartable.
      • TX_NOT_RESTARTABLE

        public static boolean TX_NOT_RESTARTABLE
        Specifies that the logical transaction is not restartable.
    • Constructor Detail

      • Synchronization

        public Synchronization()
    • Method Detail

      • begin

        public abstract void begin(java.lang.String logicalTXID)
        Indicates the specified logical transaction has begun.
        Parameters:
        logicalTXID - specifies the unique identity of the logical transaction.
      • beforeCompletion

        public abstract void beforeCompletion(java.lang.String logicalTXID)
                                       throws com.ibm.wsspi.batch.parallel.logicalTX.RollbackLogicalTXException
        Indicates all subjobs have ended and that the specified logical transaction is about to commit. This method may force logical transaction to rollback by throwing RollBackLogicalTXException.
        Parameters:
        logicalTXID - specifies the unique identity of the logical transaction.
        Throws:
        com.ibm.wsspi.batch.parallel.logicalTX.RollbackLogicalTXException
      • afterCompletion

        public abstract void afterCompletion(java.lang.String logicalTXID,
                           Synchronization.TXStatus status)
        Indicates the specified logical transaction has completed with the indicated status.
        Parameters:
        logicalTXID - specifies the unique identity of the logical transaction.
        status - specifies the outcome of the logical transaction - either COMMIT or ROLLBACK
      • rollBack

        public abstract com.ibm.wsspi.batch.parallel.logicalTX.RestartInstructions rollBack(java.lang.String logicalTXID,
                                                                          boolean restartable)
        Invoked to undo changes made by subjobs within the unit of work scope of the specified logical transaction.
        Parameters:
        logicalTXID - specifies the unique identity of the logical transaction.
        restartable - specifies whether or not this logical transaction is restartable as follows:
        • true

          Indicates this logical transaction is restartable. A logical transaction is restartable if and only if none of its subjobs have completed in the failed state. This means the subjobs have completed in only the restartable and/or ended states. This also means the parallel job itself will complete in the restartable state.

        • false

          Indicates this logical transaction is NOT restartable. A logical transaction is not restartable if at least one of its subjobs has completed in the failed state. In this case, the parallel job itself will complete in the failed state and is not restartable.

        Returns:
        RestartInstructions, which indicates which subjobs must restart when the parallel job instance associated with logicalTXID is restarted.
      • getName

        public java.lang.String getName()
        Description copied from class: SPI
        Returns the name of this SPI instance. Should return a unique identifier.
        Specified by:
        getName in class SPI
IBM WebSphere Application ServerTM
Release 8.5