com.tailf.navu

Class NavuContext

Object

com.tailf.navu.NavuContextBase

com.tailf.navu.NavuContext

public class NavuContext
extends NavuContextBase

This class controls how NAVU should read/write data to ncs. With data we mean configuration and/or operational data.

All data (config/oper) can be read using a Maapi transaction towards the DB_RUNNING database. If this transaction is opened in MODE_READ_WRITE mode, then configuration data can be written with this same transaction.

Another constructor NavuContext(Maapi) exists as an option. This constructor prepares a context and expects a Maapi instance with a started user session. Before using this type of context it is mandatory to call either NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int) to retrieve a maapi transaction. The user must manage the transaction which are started using the NavuContext. This can be done either by the user storing the retrieved transaction id and calling the low level Maapi methods Maapi.applyTrans(int, boolean) and/or Maapi.finishTrans(int) to commit and end the transaction. There are also a set of convenience methods in the NavuContext to handle the transaction like NavuContext.applyClearTrans() and NavuContext.finishClearTrans() etc. Using NavuContext.startRunningTrans(int) is equivalent to using a context created with the NavuContext(Maapi, int) constructor which is kept for backward compatibility.

A typical scenario using the NavuContext(Maapi) constructor would be something like.

      NavuContext context = new NavuContext(maapi);
      int th context.startRunningTrans(Conf.MODE_READ_WRITE);
      // if operational data should be written the above line should be
      // replaced with:
      // int th = context.startOperationalTrans(Conf.MODE_READ_WRITE);

      ... Using Navu ....

      context.applyClearTrans();
      // if nothing has been written to the transaction then nothing should
      // be applied and and following call should be used instead
      // context.finishClearTrans();
 

Nested Class Summary

Nested classes/interfaces inherited from class com.tailf.navu.NavuContextBase

NavuContextBase.UnSetCaseInChoice

Field Summary

Fields inherited from class com.tailf.navu.NavuContextBase

unsetCaseInChoice

Constructor Summary

Constructors

Constructor and Description
NavuContext(Cdb cdb) Deprecated.
NavuContext(CdbSession session) Deprecated.
NavuContext(CdbSubscription cdbsub) Deprecated.
NavuContext(Maapi m) This constructor prepares a context to be used with a maapi transaction towards either Conf.DB_RUNNING or Conf.DB_OPERATIONAL.
NavuContext(Maapi m, int confTh) Constructor for running NAVU with a transaction towards DB_RUNNING.
NavuContext(Maapi readWrite, int readWriteTid, Maapi readOnly, int readOnlyTid) Deprecated.

Method Summary

Modifier and Type	Method and Description
void	applyClearTrans() This method applies any changes in this transaction (Commit) using Maapi.applyTrans(int, boolean).
void	applyReplaceTrans() This method applies (commit) and finish the transaction using Maapi.applyTrans(int, boolean) and Maapi.finishTrans(int).
void	attachRunningTrans(int th) Attach an existing transaction towards the Conf.DB_RUNNING database to be used in the context.
int	clearTrans() Clears the internal transaction defined by NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int) The previous transaction id if any is returned but left unattended.
void	detachRunningTrans() For an context with an attached transaction using NavuContext.attachRunningTrans(int) this method will detach the transaction from the NavuContext maapi instance
void	finishClearTrans() Finishes current trans using Maapi.finishTrans(int) and clears the trans from this NavuContext.
MountIdInterface	getMountIdInterface()
void	set(NavuContext context) Set the context attributes using another context object.
int	startOperationalTrans(int mode) This method starts a transaction towards the Conf.DB_OPERATIONAL database to be used in the context.
int	startOperationalTrans(int mode, String vendor, String product, String version, String clientId)
int	startPreCommitRunningTrans() This method starts a transaction towards the PRE_COMMIT_RUNNING datastore.
int	startPreCommitRunningTrans(String vendor, String product, String version, String clientId)
int	startRunningTrans(int mode) This method starts a transaction towards the Conf.DB_RUNNING database to be used in the context.
int	startRunningTrans(int mode, String vendor, String product, String version, String clientId)
String	toString()

Methods inherited from class com.tailf.navu.NavuContextBase

currentCdbSession, getBackingStoreCdb, getBackingStoreCdbSession, getCdb, getCdbOperSession, getCdbOperSession, getCdbSession, getCdbSession, getCdbSubscriber, getMaapi, getMaapiHandle, getMaapiReadOnlyHandle, getNsList, getReadConfSession, getReadOnlyMaapi, getReadOperSession, getWriteOperSession, hasCdbSubscriber, isCdb, isCdbSession, isMaapi, isOnline, removeCdbSessions, set, setLockingMode, setOption, setReadConfLocks, setReadOperLocks, setWriteOperLocks

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NavuContext

public NavuContext(Maapi m,
                   int confTh)

Constructor for running NAVU with a transaction towards DB_RUNNING. If the supplied transaction is opened with MODE_READ, then both config and oper data can be read but no data can be written. If instead the supplied transaction is opened in MODE_READ_WRITE the config data can be both read and written while operational data only can be read.

Parameters:

m - the Maapi instance to be used

confTh - the transaction handle towards DB_RUNNING used for this NavuContext

NavuContext

public NavuContext(Maapi m)

This constructor prepares a context to be used with a maapi transaction towards either Conf.DB_RUNNING or Conf.DB_OPERATIONAL. This transactions has to be started with one of NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int) before the context can be used in NAVU.

Parameters:

m - the Maapi instance to be used

NavuContext

@Deprecated
public NavuContext(Cdb cdb)

Deprecated.

This constructor has been deprecated

Constructor for running NAVU with the Cdb mode.

As this constructor takes a Cdb but it is never touched i.e no new Cdb sessions are opened on the supplied socket. Instead a new Cdb socket is constructed and used for new sessions.

The Cdb sockets will be named "supplied-name"-pool:x where "supplied-name" is the name of the supplied Cdb socket name ( cdb.getName() ). The string "-pool:x" is appended where x is a internal integer counter.

Parameters:

cdb - The Cdb socket used as the template or NavuContext

NavuContext

@Deprecated
public NavuContext(CdbSubscription cdbsub)

Deprecated.

NavuContext

@Deprecated
public NavuContext(CdbSession session)

Deprecated.

This constructor has been deprecated CDB Session constructor.

Parameters:

session -

NavuContext

@Deprecated
public NavuContext(Maapi readWrite,
                               int readWriteTid,
                               Maapi readOnly,
                               int readOnlyTid)

Deprecated.

This constructor is deprecated.

This constructor was formerly used to make the context delta-aware This was necessary when retrieving difference between current transaction and the data already committed into the database. Normally, deleted nodes are lost when we're in the scope of a transaction. The second Maapi socket provided ghost copies of deleted data allowing to read all data that has been deleted.

The context created by the NavuContext(Maapi, int) or NavuContext(Maapi) constructor are now implicitly delta-aware. Therefore this constructor has become obsolete.

The readOnly Maapi and readOnly transaction is not used and therefore obsolete.

Parameters:

readWrite - - a read write socket.

readWriteTid -

readOnly - - a read only on the RUNNING.

readOnlyTid -

Method Detail

attachRunningTrans

public void attachRunningTrans(int th)
                        throws NavuException

Attach an existing transaction towards the Conf.DB_RUNNING database to be used in the context. Because the transaction is attached and not started by the NavuContext no finish or apply operations are allowed from the context. For example the NavuContext.finishClearTrans() will throw an exception for this type of context.

Parameters:

th - transaction id

Throws:

NavuException

detachRunningTrans

public void detachRunningTrans()
                        throws NavuException

For an context with an attached transaction using NavuContext.attachRunningTrans(int) this method will detach the transaction from the NavuContext maapi instance

Throws:

NavuException

startRunningTrans

public int startRunningTrans(int mode)
                      throws NavuException

This method starts a transaction towards the Conf.DB_RUNNING database to be used in the context. This method or its counterpart NavuContext.startOperationalTrans(int) is mandatory to call for a context created by the NavuContext(Maapi) constructor before the context is being used in NAVU. Calling this method on contexts that already started an transaction will throw an NavuException. The user will need to manage the started transaction (apply/finish).

Parameters:

mode - one of Conf.MODE_READ_WRITE, Conf.MODE_READ

Returns:

transaction id for the started transaction

Throws:

NavuException

startRunningTrans

public int startRunningTrans(int mode,
                             String vendor,
                             String product,
                             String version,
                             String clientId)
                      throws NavuException

Throws:

NavuException

startPreCommitRunningTrans

public int startPreCommitRunningTrans()
                               throws NavuException

This method starts a transaction towards the PRE_COMMIT_RUNNING datastore. This datastore only exists between a CdbSubscription.read() and the following CdbSubscription.sync(com.tailf.cdb.CdbSubscriptionSyncType). The normal use for this transaction type is to be used in a diffIteration where the operation is DiffIterateOperFlag.MOP_DELETED and the deleted data values are of interest. This datastore can only be open in Conf.MODE_READ Calling this method on contexts that already started an transaction will throw an NavuException. The user will need to manage the finish of this transaction.

Returns:

transaction id for the started transaction

Throws:

NavuException

startPreCommitRunningTrans

public int startPreCommitRunningTrans(String vendor,
                                      String product,
                                      String version,
                                      String clientId)
                               throws NavuException

Throws:

NavuException

startOperationalTrans

public int startOperationalTrans(int mode)
                          throws NavuException

This method starts a transaction towards the Conf.DB_OPERATIONAL database to be used in the context. This method or its counterpart NavuContext.startRunningTrans(int) is mandatory to call for a context created by the NavuContext(Maapi) constructor before the context is being used in NAVU. Calling this method on contexts that already started an transaction will throw an NavuException. The user will need to manage the started transaction (apply/finish).

Parameters:

mode - one of Conf.MODE_READ_WRITE, Conf.MODE_READ

Returns:

transaction id for the started transaction

Throws:

NavuException

startOperationalTrans

public int startOperationalTrans(int mode,
                                 String vendor,
                                 String product,
                                 String version,
                                 String clientId)
                          throws NavuException

Throws:

NavuException

clearTrans

public int clearTrans()
               throws NavuException

Clears the internal transaction defined by NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int) The previous transaction id if any is returned but left unattended. If the transaction needs to be committed or finished this has to be performed outside of Navu. After clearing the transaction it is possible to start a new transaction using NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int). If no new transaction is started further navigation with this context will not be possible.

Returns:

the previous transaction id or -1 if no transaction was started

Throws:

NavuException

finishClearTrans

public void finishClearTrans()
                      throws NavuException

Finishes current trans using Maapi.finishTrans(int) and clears the trans from this NavuContext. After finish and clear of the transaction using this method it is possible to start a new transaction using NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int). If no new transaction is started further navigation with this context will not be possible.

Throws:

NavuException

applyClearTrans

public void applyClearTrans()
                     throws NavuException

This method applies any changes in this transaction (Commit) using Maapi.applyTrans(int, boolean). Afterwards the transaction is finished using Maapi.finishTrans(int) and cleared form this NavuContext. After apply and clear of the transaction using this method it is possible to start a new transaction using NavuContext.startRunningTrans(int) or NavuContext.startOperationalTrans(int). If no new transaction is started further navigation with this context will not be possible. finishes the transaction. The NavuConn

Throws:

NavuException

applyReplaceTrans

public void applyReplaceTrans()
                       throws NavuException

This method applies (commit) and finish the transaction using Maapi.applyTrans(int, boolean) and Maapi.finishTrans(int). Afterwards an new transaction of same type (operational or running) and mode (Conf.MODE_READ or Conf.MODE_READ_WRITE) is created and replaces the old applied transaction. Hence, navigation using this context can be resumed directly after this method call. Note, however that the depending of the committed transaction the Navu tree migth or migth not be up to date. There is no automatic sync or validation of the present Navu tree against the new transaction.

Throws:

NavuException

set

public void set(NavuContext context)

Set the context attributes using another context object.

This this operation will make an abrupt change in connection type, transactions etc. Therefore it is the responsibility of the user to handle open transactions, locks, socket or any other resources that otherwise will be left orphaned.

Note, that the context is normally set at the creation of the NAVU root node. The context is then shared between all child nodes and a change of context attributes will therefore affect all nodes in the current NAVU tree. This implies that data can become stale between maapi transactions or cdb locks and the it is the responsibility of the user to handle when and how stale data should be dismissed.

Parameters:

context -

toString

public String toString()

Overrides:

toString in class NavuContextBase

getMountIdInterface

public MountIdInterface getMountIdInterface()