Package com.tailf.dp

Interface DpDbCallback

All Known Implementing Classes:

DBCallbackProxy

public interface DpDbCallback

This interface is used for the user database callbacks. It only applies to ConfD, not NCS

We may also optionally have a set of callback methods which span over several transactions.

If the system is configured in such a way so that the external database owns the candidate data store we must implement callback methods to do this. If ConfD owns the candidate the candidate callbacks can be skipped. Additionally, the lock() callback should be implemented (see more below).

If ConfD owns the candidate, and ConfD has been configured to support confirmed-commit, then three checkpointing methods must be implemented. When confirmed-commit is enabled, the user can commit the candidate with a timeout. Unless a confirming commit is given by the user before the timer expires, the system must rollback to the previous running configuration. This mechanism is controlled by the checkpoint callbacks. See further below.

An external database may also (optionally) support the lock/unlock and lockPartial/unlockPartial operations. This is only interesting if there exists additional locking mechanisms towards the database - such as an external CLI which can lock the database, or if the external database owns the candidate.

Finally, the external database may optionally validate a configuration. Configuration validation is preferably done through ConfD - however if a system already has implemented extensive configuration validation - the validate() callback can be used.

See Also:

• Dp.registerAnnotatedCallbacks(Object)

Field Summary

Fields

Modifier and Type	Field	Description
static final int	M_ACTIVATE_CHECKPOINT_RUNNING	Bit flag for the activateCheckpointRunning(DpDbContext) method.
static final int	M_ADD_CHECKPOINT_RUNNING	Bit flag for the addCheckpointRunning(DpDbContext) method.
static final int	M_ALL
static final int	M_CANDIDATE_CHK_NOT_MODIFIED	Bit flag for the candidateChkNotModified(DpDbContext) method.
static final int	M_CANDIDATE_COMMIT	Bit flag for the candidateCommit(DpDbContext,int) method.
static final int	M_CANDIDATE_CONFIRMING_COMMIT	Bit flag for the candidateConfirmingCommit(DpDbContext) method.
static final int	M_CANDIDATE_RESET	Bit flag for the candidateReset(DpDbContext) method.
static final int	M_CANDIDATE_ROLLBACK_RUNNING	Bit flag for the candidateRollbackRunning(DpDbContext) method.
static final int	M_CANDIDATE_VALIDATE	Bit flag for the candidateValidate(DpDbContext) method.
static final int	M_COPY_RUNNING_TO_STARTUP	Bit flag for the copyRunningToStartup(DpDbContext) method.
static final int	M_DEL_CHECKPOINT_RUNNING	Bit flag for the delCheckpointRunning(DpDbContext) method.
static final int	M_DELETE_CONFIG	Bit flag for the deleteConfig(DpDbContext,int) method.
static final int	M_LOCK	Bit flag for the lock(DpDbContext,int) method.
static final int	M_LOCK_PARTIAL	Bit flag for the lockPartial(DpDbContext,int,int,ConfObject[][]) method.
static final int	M_RUNNING_CHK_NOT_MODIFIED	Bit flag for the runningChkNotModified(DpDbContext) method.
static final int	M_UNLOCK	Bit flag for the unlock(DpDbContext,int) method.
static final int	M_UNLOCK_PARTIAL	Bit flag for the unlockPartial(DpDbContext,int,int) method.

Method Summary

Modifier and Type	Method	Description
void	activateCheckpointRunning(DpDbContext dbx)	This method should rollback running to the checkpoint created by addCheckpointRunning().
void	addCheckpointRunning(DpDbContext dbx)	This method should be implemented only when ConfD owns the candidate, and confirmed-commit is enabled.
void	candidateChkNotModified(DpDbContext dbx)	This method should check to see if the candidate has been modified or not.
void	candidateCommit(DpDbContext dbx, int timeout)	This method should copy the candidate DB into the running DB.
void	candidateConfirmingCommit(DpDbContext dbx)	If the timeout in the candidate_commit() method is != 0, we will be either invoked here or in the candidateRollbackRunning() method within timeout seconds.
void	candidateReset(DpDbContext dbx)	This method is intended to copy the current running configuration into the candidate.
void	candidateRollbackRunning(DpDbContext dbx)	If for some reason, apart from a timeout, something goes wrong, we get invoked in the candidateRollbackRunning() method.
void	candidateValidate(DpDbContext dbx)	This callback is optional.
void	copyRunningToStartup(DpDbContext dbx)	Copies the 'running' database to 'startup'.
void	delCheckpointRunning(DpDbContext dbx)	This method should delete a checkpoint created by addCheckPointRunning().
void	deleteConfig(DpDbContext dbx, int dbname)	Will be called for 'startup' or 'candidate' only.
void	lock(DpDbContext dbx, int dbname)	This should only be implemented if our database supports locking from other sources than through ConfD.
void	lockPartial(DpDbContext dbx, int dbname, int lockid, ConfObject[][] paths)	This should only be implemented if our database supports locking from other sources than through ConfD, see lock(DpDbContext,int) above.
int	mask()	Mask of flags for methods that are supported by this callback: M_CANDIDATE_COMMIT M_CANDIDATE_CONFIRMING_COMMIT M_CANDIDATE_RESET M_CANDIDATE_CHK_NOT_MODIFIED M_CANDIDATE_ROLLBACK_RUNNING M_CANDIDATE_VALIDATE M_ADD_CHECKPOINT_RUNNING M_DEL_CHECKPOINT_RUNNING M_ACTIVATE_CHECKPOINT_RUNNING M_COPY_RUNNING_TO_STARTUP M_LOCK M_UNLOCK M_DELETE_CONFIG M_LOCK_PARTIAL M_UNLOCK_PARTIAL M_RUNNING_CHK_NOT_MODIFIED
void	runningChkNotModified(DpDbContext dbx)	This function should check to see if running has been modified or not.
void	unlock(DpDbContext dbx, int dbname)	Unlocks the database.
void	unlockPartial(DpDbContext dbx, int dbname, int lockid)	Unlocks the partial locks that where previously locked with lockPartial(DpDbContext,int,int,ConfObject[][]).

Field Details

M_CANDIDATE_COMMIT

static final int M_CANDIDATE_COMMIT

Bit flag for the candidateCommit(DpDbContext,int) method.

See Also:

• Constant Field Values

M_CANDIDATE_CONFIRMING_COMMIT

static final int M_CANDIDATE_CONFIRMING_COMMIT

Bit flag for the candidateConfirmingCommit(DpDbContext) method.

See Also:

• Constant Field Values

M_CANDIDATE_RESET

static final int M_CANDIDATE_RESET

Bit flag for the candidateReset(DpDbContext) method.

See Also:

• Constant Field Values

M_CANDIDATE_CHK_NOT_MODIFIED

static final int M_CANDIDATE_CHK_NOT_MODIFIED

Bit flag for the candidateChkNotModified(DpDbContext) method.

See Also:

• Constant Field Values

M_CANDIDATE_ROLLBACK_RUNNING

static final int M_CANDIDATE_ROLLBACK_RUNNING

Bit flag for the candidateRollbackRunning(DpDbContext) method.

See Also:

• Constant Field Values

M_CANDIDATE_VALIDATE

static final int M_CANDIDATE_VALIDATE

Bit flag for the candidateValidate(DpDbContext) method.

See Also:

• Constant Field Values

M_ADD_CHECKPOINT_RUNNING

static final int M_ADD_CHECKPOINT_RUNNING

Bit flag for the addCheckpointRunning(DpDbContext) method.

See Also:

• Constant Field Values

M_DEL_CHECKPOINT_RUNNING

static final int M_DEL_CHECKPOINT_RUNNING

Bit flag for the delCheckpointRunning(DpDbContext) method.

See Also:

• Constant Field Values

M_ACTIVATE_CHECKPOINT_RUNNING

static final int M_ACTIVATE_CHECKPOINT_RUNNING

Bit flag for the activateCheckpointRunning(DpDbContext) method.

See Also:

• Constant Field Values

M_COPY_RUNNING_TO_STARTUP

static final int M_COPY_RUNNING_TO_STARTUP

Bit flag for the copyRunningToStartup(DpDbContext) method.

See Also:

• Constant Field Values

M_LOCK

static final int M_LOCK

Bit flag for the lock(DpDbContext,int) method.

See Also:

• Constant Field Values

M_UNLOCK

static final int M_UNLOCK

Bit flag for the unlock(DpDbContext,int) method.

See Also:

• Constant Field Values

M_DELETE_CONFIG

static final int M_DELETE_CONFIG

Bit flag for the deleteConfig(DpDbContext,int) method.

See Also:

• Constant Field Values

M_LOCK_PARTIAL

static final int M_LOCK_PARTIAL

Bit flag for the lockPartial(DpDbContext,int,int,ConfObject[][]) method.

See Also:

• Constant Field Values

M_UNLOCK_PARTIAL

static final int M_UNLOCK_PARTIAL

Bit flag for the unlockPartial(DpDbContext,int,int) method.

See Also:

• Constant Field Values

M_RUNNING_CHK_NOT_MODIFIED

static final int M_RUNNING_CHK_NOT_MODIFIED

Bit flag for the runningChkNotModified(DpDbContext) method.

See Also:

• Constant Field Values

M_ALL

static final int M_ALL

See Also:

• Constant Field Values

Method Details

mask

int mask()

Mask of flags for methods that are supported by this callback:

• M_CANDIDATE_COMMIT
• M_CANDIDATE_CONFIRMING_COMMIT
• M_CANDIDATE_RESET
• M_CANDIDATE_CHK_NOT_MODIFIED
• M_CANDIDATE_ROLLBACK_RUNNING
• M_CANDIDATE_VALIDATE
• M_ADD_CHECKPOINT_RUNNING
• M_DEL_CHECKPOINT_RUNNING
• M_ACTIVATE_CHECKPOINT_RUNNING
• M_COPY_RUNNING_TO_STARTUP
• M_LOCK
• M_UNLOCK
• M_DELETE_CONFIG
• M_LOCK_PARTIAL
• M_UNLOCK_PARTIAL
• M_RUNNING_CHK_NOT_MODIFIED

candidateCommit

void candidateCommit(DpDbContext dbx,
 int timeout)
              throws DpCallbackException

This method should copy the candidate DB into the running DB. If timeout != 0, we should be prepared to do a rollback or act on a candidateConfirmingCommit(). The timeout parameter can not be used to set a timer for when to rollback; this timer is handled by the ConfD daemon. If we terminate without having acted on the candidateConfirmingCommit(), we MUST restart with a rollback. Thus we must remember that we are waiting for a candidateConfirmingCommit() and we must do so on persistent storage. Must only be implemented when the external database owns the candidate.

Parameters:

dbx - The database context

timeout - Timeout value

Throws:

DpCallbackException - Callback method failed.

candidateConfirmingCommit

void candidateConfirmingCommit(DpDbContext dbx)
                        throws DpCallbackException

If the timeout in the candidate_commit() method is != 0, we will be either invoked here or in the candidateRollbackRunning() method within timeout seconds. candidateConfirmingCommit() should make the commit persistent, whereas a call to candidateRollbackRunning() would copy back the previous running configuration to running.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

candidateRollbackRunning

void candidateRollbackRunning(DpDbContext dbx)
                       throws DpCallbackException

If for some reason, apart from a timeout, something goes wrong, we get invoked in the candidateRollbackRunning() method. The method should copy back the previous running configuration to running.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

candidateReset

void candidateReset(DpDbContext dbx)
             throws DpCallbackException

This method is intended to copy the current running configuration into the candidate. It is invoked whenever the NETCONF operation <discard-changes> is executed or when a lock is released without committing.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

candidateChkNotModified

void candidateChkNotModified(DpDbContext dbx)
                      throws DpCallbackException

This method should check to see if the candidate has been modified or not. Returns if no modifications has been done since the last commit or reset, and throws a DpCallbackException (error) if any uncommitted modifications exist.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

candidateValidate

void candidateValidate(DpDbContext dbx)
                throws DpCallbackException

This callback is optional. If implemented, the task of the callback is to validate the candidate configuration. Note that the running database can be validated by the database in the prepare() callback. candidateValidate() is only meaningful when an explicit validate operation is received, e.g. through NETCONF.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

addCheckpointRunning

void addCheckpointRunning(DpDbContext dbx)
                   throws DpCallbackException

This method should be implemented only when ConfD owns the candidate, and confirmed-commit is enabled.

It is responsible for creating a checkpoint of the current running configuration and storing the checkpoint in non-volatile memory. When the system restarts this method should check if there is a checkpoint available, and use the checkpoint instead of running.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

delCheckpointRunning

void delCheckpointRunning(DpDbContext dbx)
                   throws DpCallbackException

This method should delete a checkpoint created by addCheckPointRunning(). It is called by ConfD when a confirming commit is received.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

activateCheckpointRunning

void activateCheckpointRunning(DpDbContext dbx)
                        throws DpCallbackException

This method should rollback running to the checkpoint created by addCheckpointRunning(). It is called by ConfD when the timer expires or if the user session expires.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

copyRunningToStartup

void copyRunningToStartup(DpDbContext dbx)
                   throws DpCallbackException

Copies the 'running' database to 'startup'.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed.

lock

void lock(DpDbContext dbx,
 int dbname)
   throws DpCallbackException

This should only be implemented if our database supports locking from other sources than through ConfD. If a lock is set through e.g. NETCONF, ConfD will first make sure that no other ConfD transaction has locked the database. Then it will call lock() to make sure that the database is not locked by some other source (such as a CLI). Throws a DpCallbackException (error) if the lock was already held by an external entity.

The dbname constants:

• Conf.DB_NONE
• Conf.DB_CANDIDATE
• Conf.DB_RUNNING
• Conf.DB_STARTUP

Parameters:

dbx - The database context

dbname - The database type

Throws:

DpCallbackException - Callback method failed.

unlock

void unlock(DpDbContext dbx,
 int dbname)
     throws DpCallbackException

Unlocks the database. The dbname constants:

• Conf.DB_NONE
• Conf.DB_CANDIDATE
• Conf.DB_RUNNING
• Conf.DB_STARTUP

Parameters:

dbx - The database context

dbname - The database type

Throws:

DpCallbackException - Callback method failed.

lockPartial

void lockPartial(DpDbContext dbx,
 int dbname,
 int lockid,
 ConfObject[][] paths)
          throws DpCallbackException

This should only be implemented if our database supports locking from other sources than through ConfD, see lock(DpDbContext,int) above. This callback is invoked if a northbound agent requests a partial lock. The paths[] argument is an array of keypaths that identify the leafs and/or subtrees that are to be locked. The lockid is a reference that will be used on a subsequent corresponding unlockPartial() invocation. Throws a DpCallbackException (error) if the lock was already held by an external entity.

The dbname constants:

• Conf.DB_NONE
• Conf.DB_CANDIDATE
• Conf.DB_RUNNING
• Conf.DB_STARTUP

Parameters:

dbx - The database context

dbname - the database

lockid - The lock reference

paths - Paths to lock

Throws:

DpCallbackException - Callback method failed

unlockPartial

void unlockPartial(DpDbContext dbx,
 int dbname,
 int lockid)
            throws DpCallbackException

Unlocks the partial locks that where previously locked with lockPartial(DpDbContext,int,int,ConfObject[][]). The dbname constants:

• Conf.DB_NONE
• Conf.DB_CANDIDATE
• Conf.DB_RUNNING
• Conf.DB_STARTUP

Parameters:

dbx - The database context

dbname - The database type

lockid - The lock reference

Throws:

DpCallbackException - Callback method failed.

deleteConfig

void deleteConfig(DpDbContext dbx,
 int dbname)
           throws DpCallbackException

Will be called for 'startup' or 'candidate' only. The database is supposed to be set to erased. The dbname constants:

• Conf.DB_NONE
• Conf.DB_CANDIDATE
• Conf.DB_RUNNING
• Conf.DB_STARTUP

Parameters:

dbx - The database context

dbname - The database type

Throws:

DpCallbackException - Callback method failed.

runningChkNotModified

void runningChkNotModified(DpDbContext dbx)
                    throws DpCallbackException

This function should check to see if running has been modified or not. It only needs to be implemented if the startup data store is enabled. Return silently if no modifications have been done since the last copy of running to startup, and should throw an DpCallbackException if any modifications exist.

Parameters:

dbx - The database context

Throws:

DpCallbackException - Callback method failed