Cdb (NCS Java API Version 5.6)

Object
- com.tailf.cdb.Cdb

All Implemented Interfaces:

MountIdInterface
```
public class Cdb
extends Object
implements MountIdInterface
```
This class represents a connection to ConfD/NCS built in XML database.
A connection is established upon a new instance of this class providing either a Socket or a SocketChannel 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 Cdb.startSession(). The entire configuration part of CDB is locked for writing while any CDB read session is active. Use the Cdb.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. Cdb.newSubscription() method to create a new Cdb subscription to subscribe on CDB configuration changes.
See Also:

CdbSession, CdbSubscription

Constructor Summary

Constructors
Constructor and Description
`Cdb(String name, Socket socket)` Creates a new instance of a `Cdb` socket supplying a established open socket to ConfD/NCS daemon.
`Cdb(String name, SocketChannel channel)` Deprecated.
`Cdb(String name, SocketChannel channel, int buffsize)` Deprecated.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`acceptTagPath()`
`void`	`close()` Closes the resources held by this `Cdb` socket.
`CdbSession`	`getCurrentSession()` Retrieve the current `CdbSession` started on this `Cdb` socket.
`List<String>`	`getMountId(ConfPath path)`
`String`	`getName()` Retrieve the name of this `Cdb` socket.
`CdbPhase`	`getPhase()` Returns the start-phase CDB database is currently in.
`SelectionKey`	`getSelectionKey()` Deprecated.
`Selector`	`getSelector()` Deprecated.
`Socket`	`getSocket()` Retrieve the underlying socket used by this `Cdb` instance
`SocketChannel`	`getSocketChannel()` Deprecated.
`CdbTxId`	`getTxId()` Returns a CdbTxid object which represents the last transaction id from CDB.
`CdbSubscription`	`newSubscription()` Creates a new CDB Subscription.
`void`	`setTimeout(int timeoutSecs)` A timeout for cdb client actions can be specified via the config file.
`void`	`setUseForCdbUpgrade()` Sets this Cdb and the session it creates to be used for Cdb data upgrades.
`void`	`setUseForCdbUpgrade(List<ConfNamespace> removedNs)` Sets this Cdb and the session it creates to be used for Cdb data upgrades.
`CdbSession`	`startSession()` Starts a new CDB Session on an already established `Cdb` against `CdbDBType.CDB_RUNNING` datastore with `CdbLockType.LOCK_SESSION` lock.
`CdbSession`	`startSession(CdbDBType dbtype)` Starts a new CDB Session on an already established `Cdb`.
`CdbSession`	`startSession(CdbDBType dbtype, EnumSet<CdbLockType> lockflags)` Starts a new CDB Session on an already established `Cdb`.
`CdbUpgradeSession`	`startUpgradeSession()` Similar to `Cdb.startSession()` but always returns a CdbUpgradeSession.
`CdbUpgradeSession`	`startUpgradeSession(CdbDBType dbtype)` Similar to `Cdb.startSession(CdbDBType)` but always returns a CdbUpgradeSession.
`CdbUpgradeSession`	`startUpgradeSession(CdbDBType dbtype, EnumSet<CdbLockType> lockflags)` Similar to `Cdb.startSession(CdbDBType, EnumSet)` but always returns a CdbUpgradeSession.
`String`	`toString()`
`void`	`triggerOperSubscriptions(int[] spointArray)` Function similar to `Cdb.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.
`void`	`triggerOperSubscriptions(int[] spointArray, EnumSet<CdbLockType> lockflags)` Function to trigger operational subscriptions in similar to `Cdb.triggerSubscriptions(int[])`.
`void`	`triggerSubscriptions(int[] spointArray)` Triggers Cdb subscription for configuration data.
`void`	`waitStart()` This call waits until start-phase 1 is completed and CDB is available.

Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - 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
```
@Deprecated
public Cdb(String name,
                       SocketChannel channel)
                throws IOException,
                       ConfException
```
    Deprecated.
    
    Same as Cdb(String, SocketChannel, int) with the buffsize set to the default which is 4Kb.
    
    Parameters:
    
    name -
    
    channel -
    
    Throws:
    
    IOException
    
    ConfException
  - Cdb
```
@Deprecated
public Cdb(String name,
                       SocketChannel channel,
                       int buffsize)
                throws IOException,
                       ConfException
```
    Deprecated.
    
    Creates a new Cdb socket in a non blocking mode.
    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.
    The name is just a string which may occur in certain error/debug messages for example in devel.log.
    
    Parameters:
    
    name - The name of the Cdb instance
    
    channel - A socket connected to ConfD/NCS
    
    buffsize - The size of the bytebuffer
    
    Throws:
    
    IOException - signals I/O exception on the underlying socket
    
    ConfException - If ConfD/NCS refuses to establish connection the reason could be obtained through Throwable.getMessage()
- Method Detail
  - 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
  - getSelectionKey
```
@Deprecated
public SelectionKey getSelectionKey()
```
    Deprecated.
    
    Retrieve the SelectionKey used by this Cdb instance
    
    Returns:
    
    The underlying SelectionKey
  - getSocketChannel
```
@Deprecated
public SocketChannel getSocketChannel()
```
    Deprecated.
    
    Retrieve the underlying SocketChannel used by this Cdb instance
    
    Returns:
    
    The underlying SocketChannel or null if no available
  - 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.
  - getSelector
```
@Deprecated
public Selector getSelector()
```
    Deprecated.
    
    Retrieve the underlying (internal) Selector used by this Cdb socket.
    
    Returns:
    
    The underlying selector used by this Cdb instance
  - 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 Cdb.startSession() but always returns a CdbUpgradeSession.
    
    Throws:
    
    ConfException
    
    IOException
  - startUpgradeSession
```
public CdbUpgradeSession startUpgradeSession(CdbDBType dbtype)
                                      throws ConfException,
                                             IOException
```
    Similar to Cdb.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 Cdb.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 Cdb.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 Cdb.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.
    
    Throws:
    
    IOException - If I/O Error when closing resources held by this Cdb socket
  - getMountId
```
public List<String> getMountId(ConfPath path)
                        throws ConfException,
                               IOException
```
    Specified by:
    
    getMountId in interface MountIdInterface
    
    Throws:
    
    ConfException
    
    IOException
  - acceptTagPath
```
public boolean acceptTagPath()
```
    Specified by:
    
    acceptTagPath in interface MountIdInterface

Class Cdb

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

Cdb

Cdb

Cdb

Method Detail

setUseForCdbUpgrade

setUseForCdbUpgrade

getName

getSocket

getSelectionKey

getSocketChannel

getCurrentSession

getSelector

startSession

startSession

startSession

startUpgradeSession

startUpgradeSession

startUpgradeSession

newSubscription

waitStart

getPhase

getTxId

triggerSubscriptions

triggerOperSubscriptions

triggerOperSubscriptions

setTimeout

toString

close

getMountId

acceptTagPath