Package com.tailf.cdb

Class Cdb

Object
com.tailf.cdb.Cdb
All Implemented Interfaces:
MountIdInterface, AutoCloseable
public class Cdb extends Object implements MountIdInterface, AutoCloseable
This class represents a connection to ConfD/NCS built in XML database.

A connection is established upon a new instance of this class providing a Socket as its argument to the constructor. An object of this class is usually called a "cdb socket".

There are mainly two things that can be achieved through a connection to CDB:

  • Starting a CDB Session - A CDB session is used to read configuration data, or read/write operational data. These are short-lived sessions that are established though a call to startSession(). The entire configuration part of CDB is locked for writing while any CDB read session is active. Use the startSession(CdbDBType) method to create a new session to read configuration data and read and write operational data.

    It is important to consider that a CdbSession has one-to-one relationship with a Cdb so before opening additional CdbSession one has to close previous opened. 

         Cdb cdbReadSocket = new Cdb ( "MyReadCdbSocket",
                             new Socket ( host ,port) );

     // Start Cdb session against running
      CdbSession cdbSession =
             cdbReadSocket.startSession ( CdbDBType.CDB_RUNNING );


       // read some values from CDB .
       cdbSession.endSession();
     cdbReadSocket.getSocket().close();

  • CDB Subscription - The subscription functionality makes it possible to receive events/notifications of CDB configuration changes. newSubscription() method to create a new Cdb subscription to subscribe on CDB configuration changes.

See Also:

  • Constructor Details

    • Cdb

      public Cdb(String name, Socket socket) throws IOException, ConfException
      Creates a new instance of a Cdb socket supplying a established open socket to ConfD/NCS daemon.

      The name parameter is just a string which may occur in certain error/debug messages i.e for example in the devel.log.

      When establishing a connection to ConfD/NCS the MaapiSchemas will be loaded once automatically by the library.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      name - name of the Cdb instance
      socket - A socket connected to ConfD/NCS
      Throws:
      ConfException - If ConfD/NCS refuses to establish connection the reason could be obtained through Throwable.getMessage()
      IOException - signals I/O exception on the underlying socket

    • Cdb

      public Cdb(String name, SocketAddress address) throws IOException, ConfException
      Creates a new instance of a Cdb socket supplying an address to the ConfD/NCS server.

      The name parameter is just a string which may occur in certain error/debug messages i.e for example in the devel.log.

      When establishing a connection to ConfD/NCS the MaapiSchemas will be loaded once automatically by the library.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      name - name of the Cdb instance
      address - An adddres to connect to
      Throws:
      ConfException - If ConfD/NCS refuses to establish connection the reason could be obtained through Throwable.getMessage()
      IOException - signals I/O exception on the underlying socket

  • Method Details

    • setUseForCdbUpgrade

      public void setUseForCdbUpgrade()
      Sets this Cdb and the session it creates to be used for Cdb data upgrades. This is a specific startphase 0 use case.

    • setUseForCdbUpgrade

      public void setUseForCdbUpgrade(List<ConfNamespace> removedNs)
      Sets this Cdb and the session it creates to be used for Cdb data upgrades. This is a specific startphase 0 use case. If a yang model is completely removed it needs to be temporarily reinstalled for CDB to be able to refer to it.
      Parameters:
      removedNs - List of removed ConfNamespace used earlier

    • getName

      public String getName()
      Retrieve the name of this Cdb socket.
      Returns:
      The name of this Cdb socket instance

    • getSocket

      public Socket getSocket()
      Retrieve the underlying socket used by this Cdb instance
      Returns:
      The underlying socket

    • getCurrentSession

      public CdbSession getCurrentSession()
      Retrieve the current CdbSession started on this Cdb socket.
      Returns:
      The current CdbSession started on this Cdb, null if no current CdbSession is started on this Cdb Socket.

    • startSession

      public CdbSession startSession() throws ConfException, IOException
      Starts a new CDB Session on an already established Cdb against CdbDBType.CDB_RUNNING datastore with CdbLockType.LOCK_SESSION lock.
      Throws:
      IOException
      ConfException

    • startSession

      public CdbSession startSession(CdbDBType dbtype) throws ConfException, IOException
      Starts a new CDB Session on an already established Cdb.

      The method starts a new session against the datastore specified by dbtype.

      Parameters:
      dbtype - Datastore to establish session to
      Throws:
      IOException
      ConfException

    • startSession

      public CdbSession startSession(CdbDBType dbtype, EnumSet<CdbLockType> lockflags) throws ConfException, IOException
      Starts a new CDB Session on an already established Cdb.

      The method starts a new session against the datastore specified by dbtype with the locktype specified by the lockflags.

      While it is possible to use this method to start a session towards a configuration database type with no locking at all, this is strongly discouraged in general, since it means that even the values read in a single multi-value request (e.g. getObject()) may be inconsistent with each other. However it is necessary to do this if we want to have a session open during semantic validation, see the "Semantic Validation" chapter in the User Guide - and in this particular case it is safe, since the transaction lock prevents changes to CDB during validation.

      Parameters:
      dbtype - Datastore to establish session to
      lockflags - EnumSet of CdbLockType flags
      Throws:
      IOException
      ConfException

    • startUpgradeSession

      public CdbUpgradeSession startUpgradeSession() throws ConfException, IOException
      Similar to startSession() but always returns a CdbUpgradeSession.
      Throws:
      ConfException
      IOException

    • startUpgradeSession

      public CdbUpgradeSession startUpgradeSession(CdbDBType dbtype) throws ConfException, IOException
      Similar to startSession(CdbDBType) but always returns a CdbUpgradeSession.
      Parameters:
      dbtype - Datastore to establish session to
      Throws:
      ConfException
      IOException

    • startUpgradeSession

      public CdbUpgradeSession startUpgradeSession(CdbDBType dbtype, EnumSet<CdbLockType> lockflags) throws ConfException, IOException
      Similar to startSession(CdbDBType, EnumSet) but always returns a CdbUpgradeSession.
      Parameters:
      dbtype - Datastore to establish session to
      lockflags - EnumSet of CdbLockType flags
      Throws:
      ConfException
      IOException

    • newSubscription

      public CdbSubscription newSubscription()
      Creates a new CDB Subscription.

    • waitStart

      public void waitStart() throws ConfException, IOException
      This call waits until start-phase 1 is completed and CDB is available.

      If CDB already is available (i.e. start-phase >= 1) the call returns immediately. This can be used by a CDB client who is not synchronously started and only wants to wait until it can read its configuration.

      Throws:
      CdbException - Failed to waitStart for some reason
      IOException - Failed to read/write on the underlying socket
      ConfException

    • getPhase

      public CdbPhase getPhase() throws ConfException, IOException
      Returns the start-phase CDB database is currently in.

      Also if CDB is in phase 0 and has initiated an init transaction (to load any init files) the flag CdbPhase.FLAG_INIT is set in the flags field correspondingly if an upgrade session is started the CdbPhase.FLAG_UPGRADE is set.

      Throws:
      CdbException - Failed to get phase
      IOException - Failed to read/write cdb socket
      ConfException

    • getTxId

      public CdbTxId getTxId() throws ConfException, IOException
      Returns a CdbTxid object which represents the last transaction id from CDB.

      This function can be used if we are forced to reconnect to CDB. If the transaction id we read is identical to the last id we had prior to loosing the CDB sockets we don't have to reload our managed object data.

      Throws:
      CdbException - Failed to get the last transaction id
      IOException - Failed to read/write cdb socket
      ConfException

    • triggerSubscriptions

      public void triggerSubscriptions(int[] spointArray) throws ConfException, IOException
      Triggers Cdb subscription for configuration data.

      This method makes it possible to trigger CDB subscriptions for configuration data even though the configuration has not been modified.

      The caller will trigger all subscription points passed in the spointArray array (or all subscribers if the array is of zero length) in priority order, and the call will not return until the last subscriber has called CdbSubscription.sync(CdbSubscriptionSyncType).

      The call is blocking and doesn't return until all subscribers have acknowledged the notification. That means that it is not possible to use the method in a cdb subscriber thread since it would cause a deadlock.

      The subscription notification generated by this "synthetic" trigger will seem like a regular subscription notification to a subscription client. As such, it is possible to use diffIterate to traverse the changeset. CDB will make up this changeset in which all leafs in the configuration will appear to be set, and all list entries and presence containers will appear as if they are created.

      If the client is a two-phase subscriber, a prepare notification will first be delivered and if any client aborts this synthetic transaction further delivery of subscription notification is suspended and an exception is returned to the caller of triggerSubscriptions. The error is the result of mapping the CONFD_ERRCODE as set by the aborting client. Note however that the configuration is still the way it is - so it is up to the caller of triggerSubscriptions to take appropriate action (for example: raising an alarm, restarting a subsystem, or even rebooting the system).

      Parameters:
      spointArray - subscription points to trigger
      Throws:
      ConfException - If one or more subscription ids is passed in the subids array that are not valid, an CdbException will be thrown with error code (getErrorCode) set to CONFD_ERR_PROTOUSAGE will be returned and no subscriptions will be triggered
      IOException - On I/O error.

    • triggerOperSubscriptions

      public void triggerOperSubscriptions(int[] spointArray) throws ConfException, IOException
      Function similar to triggerOperSubscriptions(int[], EnumSet) with the difference that this function will never wait to acquire a lock and therefore fail and throw an Exception if Cdb is locked.
      Parameters:
      spointArray - int[] array of subscription points or null
      Throws:
      ConfException
      IOException

    • triggerOperSubscriptions

      public void triggerOperSubscriptions(int[] spointArray, EnumSet<CdbLockType> lockflags) throws ConfException, IOException
      Function to trigger operational subscriptions in similar to triggerSubscriptions(int[]). The caller will trigger all subscription points passed in the spointArray (or all operational data subscribers if this array is null), and the call will not return until the last subscriber has called CdbSubscription.sync(CdbSubscriptionSyncType). Since the generation of subscription notifications for operational data requires that the subscription lock is taken, this function implicitly attempts to take a "global" subscription lock. If the subscription lock is already taken, the function will by default return an Exception. o instead have it wait until the lock becomes available, EnumSet.of(CdbLockType.LOCK_WAIT) can be passed as lockflags parameter.
      Parameters:
      spointArray - int[] array of subscription points or null
      lockflags - null or EnumSet.of(CdbLockType.LOCK_WAIT)
      Throws:
      ConfException
      IOException

    • setTimeout

      public void setTimeout(int timeoutSecs) throws ConfException, IOException
      A timeout for cdb client actions can be specified via the config file. This function can be used to dynamically extend (or shorten) the timeout for the current action. This function can be called either for a Cdb instance used for a cdb subscription or a Cdb instance used in an CdbSession. The timeout is given in seconds from the point in time when the function is called. Note The timeout for subscription delivery is common for all the subscribers receiving notifications at a given priority. Thus calling the function during subscription delivery changes the timeout for all the subscribers that are currently processing notifications.
      Parameters:
      timeoutSecs - timeout in seconds
      Throws:
      ConfException
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • close

      public void close() throws IOException
      Closes the resources held by this Cdb socket.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - If I/O Error when closing resources held by this Cdb socket

    • getMountId

      public List<String> getMountId(ConfPath path) throws ConfException
      Specified by:
      getMountId in interface MountIdInterface
      Throws:
      ConfException

    • acceptTagPath

      public boolean acceptTagPath()
      Specified by:
      acceptTagPath in interface MountIdInterface

    • initiateCompaction

      public void initiateCompaction() throws ConfException, IOException
      Initiates compaction on CDB files:

      The method initiates compaction on all CDB files defined as CdbDbfileType.

      Throws:
      CdbException - Failed to initiate the compaction
      IOException - Failed to read/write on the cdb socket
      ConfException

    • initiateDbfileCompaction

      public void initiateDbfileCompaction(CdbDbfileType dbfile) throws ConfException, IOException
      Initiates compaction on a CDB file.

      The method initiates compaction on the CDB file specified by dbfile.

      Parameters:
      dbfile - CDB file to compact
      Throws:
      CdbException - Failed to initiate the compaction
      IOException - Failed to read/write on the cdb socket
      ConfException

    • getCompactionInfo

      public CdbCompactionInfo getCompactionInfo(CdbDbfileType dbfile) throws ConfException, IOException
      Retrieves compaction information on a CDB file

      The method retrieves compaction information on the CDB file specified by dbfile.

      Parameters:
      dbfile - CDB file to collect info
      Throws:
      CdbException - Failed to get compaction info
      IOException - Failed to read/write on the cdb socket
      ConfException