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:

Dp.registerAnnotatedCallbacks(Object)

Field Summary

Fields

Modifier and Type	Field and Description
static int	M_ABORT Bit flag for the abort(DpTrans) method.
static int	M_ALL
static int	M_COMMIT Bit flag for the commit(DpTrans) method.
static int	M_FINISH Bit flag for the finish(DpTrans) method.
static int	M_INIT Bit flag for the init(DpTrans) method.
static int	M_PREPARE Bit flag for the prepare(DpTrans) method.
static int	M_TRANS_LOCK Bit flag for the transLock(DpTrans) method.
static int	M_TRANS_UNLOCK Bit flag for the transUnlock(DpTrans) method.
static int	M_WRITE_START Bit flag for the writeStart(DpTrans) method.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort(DpTrans trans) This callback is responsible for undoing whatever was done in the prepare() phase.
void	commit(DpTrans trans) This callback is responsible for undoing whatever was done in the prepare() phase.
void	finish(DpTrans trans) This callback is responsible for releasing resources allocated in the init() phase.
void	init(DpTrans trans) The callback must indicate which WORKER_SOCKET should be used for future communications in this transaction.
int	mask() Mask of flags for each method that is supported by this callback: M_INIT M_TRANS_LOCK M_TRANS_UNLOCK M_WRITE_START M_PREPARE M_ABORT M_COMMIT M_FINISH
void	prepare(DpTrans trans) If we have multiple sources of data it is highly recommended that the callback is implemented.
void	transLock(DpTrans trans) This callback is invoked when the validation phase of the transaction starts.
void	transUnlock(DpTrans trans) This callback is called when the validation of the transaction failed, or the validation is triggered explicitly (i.e.
void	writeStart(DpTrans trans) This callback is invoked when the validation succeeded and the write phase of the transaction starts.

Field Detail

M_ABORT

static final int M_ABORT

Bit flag for the abort(DpTrans) method.

See Also:

Constant Field Values

M_ALL

static final int M_ALL

See Also:

Constant Field Values

M_COMMIT

static final int M_COMMIT

Bit flag for the commit(DpTrans) method.

See Also:

Constant Field Values

M_FINISH

static final int M_FINISH

Bit flag for the finish(DpTrans) method.

See Also:

Constant Field Values

M_INIT

static final int M_INIT

Bit flag for the init(DpTrans) method.

See Also:

Constant Field Values

M_PREPARE

static final int M_PREPARE

Bit flag for the prepare(DpTrans) method.

See Also:

Constant Field Values

M_TRANS_LOCK

static final int M_TRANS_LOCK

Bit flag for the transLock(DpTrans) method.

See Also:

Constant Field Values

M_TRANS_UNLOCK

static final int M_TRANS_UNLOCK

Bit flag for the transUnlock(DpTrans) method.

See Also:

Constant Field Values

M_WRITE_START

static final int M_WRITE_START

Bit flag for the writeStart(DpTrans) method.

See Also:

Constant Field Values

Method Detail

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.

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.

mask

int mask()

Mask of flags for each method that is supported by this callback:

• M_INIT
• M_TRANS_LOCK
• M_TRANS_UNLOCK
• M_WRITE_START
• M_PREPARE
• M_ABORT
• M_COMMIT
• M_FINISH

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.

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.