DpTransCallback (NSO Java API Version 5.8.4)

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 `DpTransCallback.abort(DpTrans)` method.
`static int`	`M_ALL`
`static int`	`M_COMMIT` Bit flag for the `DpTransCallback.commit(DpTrans)` method.
`static int`	`M_FINISH` Bit flag for the `DpTransCallback.finish(DpTrans)` method.
`static int`	`M_INIT` Bit flag for the `DpTransCallback.init(DpTrans)` method.
`static int`	`M_PREPARE` Bit flag for the `DpTransCallback.prepare(DpTrans)` method.
`static int`	`M_TRANS_LOCK` Bit flag for the `DpTransCallback.transLock(DpTrans)` method.
`static int`	`M_TRANS_UNLOCK` Bit flag for the `DpTransCallback.transUnlock(DpTrans)` method.
`static int`	`M_WRITE_START` Bit flag for the `DpTransCallback.writeStart(DpTrans)` method.

Method Summary

All Methods Instance Methods Abstract 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: `DpTransCallback.M_INIT` `DpTransCallback.M_TRANS_LOCK` `DpTransCallback.M_TRANS_UNLOCK` `DpTransCallback.M_WRITE_START` `DpTransCallback.M_PREPARE` `DpTransCallback.M_ABORT` `DpTransCallback.M_COMMIT` `DpTransCallback.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_INIT
```
static final int M_INIT
```
    Bit flag for the DpTransCallback.init(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_TRANS_LOCK
```
static final int M_TRANS_LOCK
```
    Bit flag for the DpTransCallback.transLock(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_TRANS_UNLOCK
```
static final int M_TRANS_UNLOCK
```
    Bit flag for the DpTransCallback.transUnlock(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_WRITE_START
```
static final int M_WRITE_START
```
    Bit flag for the DpTransCallback.writeStart(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_PREPARE
```
static final int M_PREPARE
```
    Bit flag for the DpTransCallback.prepare(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_ABORT
```
static final int M_ABORT
```
    Bit flag for the DpTransCallback.abort(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_COMMIT
```
static final int M_COMMIT
```
    Bit flag for the DpTransCallback.commit(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_FINISH
```
static final int M_FINISH
```
    Bit flag for the DpTransCallback.finish(DpTrans) method.
    
    See Also:
    
    Constant Field Values
  - M_ALL
```
static final int M_ALL
```
    See Also:
    
    Constant Field Values
- Method Detail
  - 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.

Interface DpTransCallback

Field Summary

Method Summary

Field Detail

M_INIT

M_TRANS_LOCK

M_TRANS_UNLOCK

M_WRITE_START

M_PREPARE

M_ABORT

M_COMMIT

M_FINISH

M_ALL

Method Detail

mask

init

transLock

transUnlock

writeStart

prepare

abort

commit

finish