In-transaction capabilities are being added to the netconfd-pro server API to allow an application to update the configuration data and perform additional actions while the transaction is in progress. This can be a vital solution to implement many services in switch/router management operations.

The netconfd-pro server uses 3 phases database editing model with In-Transaction APIs, as defined in section 6 "SIL Callback Interface" of the YumaPro Developer Manual.

  • Validate Phase
  • Apply Phase
  • Commit or Rollback Phase


However, this model is enhanced with callbacks and validation mechanism to support all the In-Transactions APIs. The following diagram illustrates what callbacks are invoked and when to expect them to be invoked during the transaction.

 


The following callback APIs are supported:

  • Set HookSimilar to the EDIT-1 or EDIT-2 callbacks, except this callback is only invoked once at the start of the edit for a particular data node. This callback can alter the data in the current edit and also add new edits to the current transaction. This callback will be invoked BEFORE EDIT-1 or EDIT-2 callbacks for the same object.
  • Post Set Hook: Similar to the Set Hook callback except that it is invoked when an object is modified but AFTER EDIT callback is done for the same object. This callback will be invoked AFTER EDIT-1 or EDIT-2 callbacks for the same object.
  • Transaction Hook: Similar to the Set Hook except this callback is invoked just before the data is committed to the running datastore. This callback will be invoked after EDIT-1 or EDIT-2 callbacks for the same object.
  • Transaction StartThe callback that is intended to provide access to the transaction control block and its parameters right before the transaction is started.
  • Transaction CompleteThe callback that is intended to provide access to the transaction control block and its parameters right after the transaction is completed. Called for every transaction completion, not just transactions that complete without errors.  
  • Validate CompleteThe callback is intended to allow manipulations with the running and candidate configurations (equivalent to completion of Validation Phase during <commit>).
  • Apply Complete:  The callback is intended to allow manipulations with the running and candidate configurations (equivalent to completion of Apply Phase during <commit>).
  • Commit CompleteThe callback is a user/system callback that is invoked when the <commit> operation completes without errors or the internal <replay-config> operation completes without errors.
  • Rollback CompleteThe callback is the user/system callback that is invoked after and if the Rollback Phase has been processed during the <commit> operation.
  • Set Order Hook: Set the secondary SIL priority for instances of the same list object that is being set in the same edit.  This allows the instance SIL callback order to be set in addition to the object priority.
  • Startup Hook: The callback function that is invoked before any changes done to the <startup> datastore. It is invoked only if the <startup> capability is enabled.


The following API functions are supported that can be called from the Set Hook, EDIT-1 or EDIT-2 callbacks:

  • Add Edit (agt_val_add_edit): Add an edit operation to the current transaction.
  • Get Data (agt_val_get_data): Retrieve an instance of a data node from the server.


The netconfd-pro provides the following SIL-SA support for In-Transaction APIs:

  • SA Transaction StartThe callback that is intended to provide access to the transaction control block and its parameters right before the transaction is started. For SIL-SA usage the server does not provide transaction control block, instead it passes the transaction ID for reference and some crucial information about the transaction, such as the information about whether the current transaction is for the running datastore, is the transaction for validate operation, or if it is  for Rollback Phase.
  • SA Transaction CompleteThe callback that is intended to provide access to the transaction control block and its parameters right after the transaction is completed. Called for every transaction completion, not just transactions that complete without errors. For SIL-SA usage the server does not provide transaction control block, instead it passes only the transaction ID for reference.


If an application needs to write more data in the datastore in the same transaction, there are mechanisms implemented in the form of API functions called Set Hook and Post Set Hook.

The Set Hook and Post Set Hook callbacks are the ways for the application to manipulate with the datastore in the same transaction. For example, whenever the specific node is created, the hook registered on that node gets called and the specific list can be updated with additional list entry or entries.

If an application needs to perform additional validations, security check or any other manipulations with datastore in the same transaction, there are mechanisms implemented in the form of API functions called Transaction Hook, Start Transaction, and Complete Transaction.

If an application needs to perform additional actions and manipulations with datastore in the same transaction during <commit> operation, there are mechanisms implemented in the form of API functions called Startup HookValidate CompleteApply Complete, Commit Complete or Rollback Complete callbacksThese callbacks are called Commit Completeness callbacks.

Manipulation with configuration data are only allowed for Set Hook and Post Set Hook callbacks, however. If Transaction Hook, Start/Complete Transaction, or Commit Completeness callbacks are trying to adjust configuration data via add_edit() API, the operation will be skipped. However, this action will not generate an error, just a warning message in the log with log-level equals debug2.



NOTE:

In-Transaction callbacks are NOT part of the yangdump-sdk code generation. After the make_sil_dir_pro script is run, In-Transaction callbacks will NOT be auto-generated. All the In-Transaction callbacks are optional and merely intend to provide more efficient way to manipulate with the database and give an access to the database at the specific phase, transaction, and an edit.


Callback Invocation Order


Callbacks on Candidate datastore


Assume we register all the possible callbacks and the edit is complex as possible. The possible invocation order may look as followsprocessing on the candidate datastore (before the <commit>):

  1. Transaction Start
  2. Set Order Hook
  3. Set Hook and then Set Order Hook for the added edit, if any
  4. SIL Callbacks (only during Validate Phase)
  5. Transaction Complete

Callbacks on Running datastore


The possible invocation order during the <commit> operation may look as followsprocessing on the running datastore (after the <commit>):

  1. Transaction Start
  2. Set Order Hook
  3. SIL Callback (Validate Phase)
  4. Validate Complete
  5. SIL Callback (Apply Phase)
  6. Apply Complete
  7. SIL Callback (Commit Phase)
  8. Transaction Hook
  9. Commit/Rollback Complete
  10. Transaction Complete

Callbacks when target=running 


The <commit> operation is not available if the default target is set to running. Thus, the possible invocation order during the edit operation may look as follows, processing on the running datastore only (the same invocation order will be during Load, Reload and Restart operations):

  1. Transaction Start
  2. Set Order Hook
  3. Set Hook and then Set Order Hook for the added edit, if any
  4. SIL Callback (Validate Phase)
  5. SIL Callback (Apply Phase)
  6. SIL Callback (Commit Phase)
  7. Transaction Hook
  8. Transaction Complete

Callbacks during <validate>


The possible invocation order during the <validate> operation may look as followsprocessing on the running datastore only:

  1. Transaction Start
  2. Set Order Hook
  3. SIL Callbacks (only during Validate Phase)
  4. Transaction Complete

Set Hook and Transaction Hook callbacks will not be invoke during explicit <validate> operation and in case of the following netconfd-pro parameters are set to TRUE: 

 --sil-validate-candidate (only relevant to Set Hook) 

 --sil-skip-load


Callbacks during <restore>


The possible invocation order during the <restore> operation may look as followsprocessing on the running datastore only:

  1. Transaction Start
  2. Set Order Hook
  3. Set Hook and then Set Order Hook for the added edit, if any
  4. SIL Callback (Validate Phase)
  5. SIL Callback (Apply Phase)
  6. SIL Callback (Commit Phase)
  7. Transaction Hook
  8. Transaction Complete