Package com.tailf.dp

Interface DpTransCallback

All Known Implementing Classes:
TransCallbackProxy
public interface DpTransCallback
This interface is used for the user transaction callbacks.

In order to orchestrate transactions with multiple sources of data, ConfD/NCS implements a two-phase commit protocol towards all data sources that participate in a transaction.

Each NETCONF operation will be an individual transaction. These transactions are typically very short lived. Transactions originating from the CLI or the Web UI have longer life. The transaction can be viewed as a conceptual state machine where the different phases of the transaction are different states and the invocations of the callback functions are state transitions. The following ASCII art depicts the state machine. 


                   +-------+
                   | START |
                   +-------+
                       | init()
                       |
                       v
          read()   +------+          finish()
          ------>  | READ | --------------------> START
                   +------+
                    ^  |
     trans_unlock() |  | trans_lock()
                    |  v
         read()  +----------+       finish()
         ------> | VALIDATE | -----------------> START
                 +----------+
                      | write_start()
                      |
                      v
         write()  +-------+          finish()
         -------> | WRITE | -------------------> START
                  +-------+
                      | prepare()
                      |
                      v
                 +----------+   commit()   +-----------+
                 | PREPARED | -----------> | COMMITTED |
                 +----------+              +-----------+
                      | abort()                  |
                      |                          | finish()
                      v                          |
                  +---------+                    v
                  | ABORTED |                  START
                  +---------+
                      | finish()
                      |
                      v
                    START

Example: Callback class MyTransCb 

  * public class MyTransCb {

   @TransCallback(callType=TransCBType.INIT)
     public void init(DpTrans trans) throws DpCallbackException {
       trace("init(): userinfo= " + trans.getUserInfo());
     }

   @TransCallback(callType=TransCBType.FINISH)
     public void finish(DpTrans trans) throws DpCallbackException {
       trace("finish()");
     }
  }
  // And so on ...
See Also:

  • Field Details

  • Method Details

    • mask

      int mask()
      Mask of flags for each method that is supported by this callback:

    • init

      void init(DpTrans trans) throws DpCallbackException
      The callback must indicate which WORKER_SOCKET should be used for future communications in this transaction. This is the mechanism which is used by Conf to distribute work among multiple worker threads in the database application.
      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • transLock

      void transLock(DpTrans trans) throws DpCallbackException
      This callback is invoked when the validation phase of the transaction starts. If the underlying database supports real transactions, it is usually appropriate to start such a native transaction here.

      The transaction enters VALIDATE state, where the system will perform a series of read() operations.

      The trans lock is set until either transUnlock() or finish() is called. the system ensures that a transLock is set on a single transaction only.

      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • transUnlock

      void transUnlock(DpTrans trans) throws DpCallbackException
      This callback is called when the validation of the transaction failed, or the validation is triggered explicitly (i.e. not part of a user can enter invalid data. Transactions that originate from NETCONF will never trigger this callback. If the underlying database supports real transactions and they are used, the transaction should be aborted here.

      The transaction re-enters READ state.

      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • writeStart

      void writeStart(DpTrans trans) throws DpCallbackException
      This callback is invoked when the validation succeeded and the write phase of the transaction starts. If the underlying database supports real transactions, it is usually appropriate to start such a native transaction here.

      The transaction enters the WRITE state. No more read() operations will be performed by the system.

      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • prepare

      void prepare(DpTrans trans) throws DpCallbackException
      If we have multiple sources of data it is highly recommended that the callback is implemented. The callback is called at the end of the transaction, when all read and write operations for the transaction have been performed and the transaction should prepare to commit.
      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • abort

      void abort(DpTrans trans) throws DpCallbackException
      This callback is responsible for undoing whatever was done in the prepare() phase.
      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • commit

      void commit(DpTrans trans) throws DpCallbackException
      This callback is responsible for undoing whatever was done in the prepare() phase.
      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.

    • finish

      void finish(DpTrans trans) throws DpCallbackException
      This callback is responsible for releasing resources allocated in the init() phase.
      Parameters:
      trans - Transaction
      Throws:
      DpCallbackException - Callback method failed.