Package 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 startRunningTrans(int) or 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 applyClearTrans() and finishClearTrans() etc. Using 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();

  • Constructor Details

    • 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 startRunningTrans(int) or 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 Details

    • 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 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 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 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 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 startRunningTrans(int) or 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 startRunningTrans(int) or 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 startRunningTrans(int) or 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 startRunningTrans(int) or 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()