com.tailf.cdb

Class Cdb

Object

com.tailf.cdb.Cdb

public class Cdb
extends Object

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 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:

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

Methods

Modifier and Type	Method and Description
void	close() Closes the resources held by this Cdb socket.
CdbSession	getCurrentSession() Retrieve the current CdbSession started on this Cdb socket.
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.
String	toString()
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

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

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.

getName

public String getName()

Retrieve the name of this Cdb socket.

Returns:

The name of this Cdb socket instance

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

getSelectionKey

@Deprecated
public SelectionKey getSelectionKey()

Deprecated.

Retrieve the SelectionKey used by this Cdb instance

Returns:

The underlying SelectionKey

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

getSocket

public Socket getSocket()

Retrieve the underlying socket used by this Cdb instance

Returns:

The underlying socket

getSocketChannel

@Deprecated
public SocketChannel getSocketChannel()

Deprecated.

Retrieve the underlying SocketChannel used by this Cdb instance

Returns:

The underlying SocketChannel or null if no available

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

newSubscription

public CdbSubscription newSubscription()

Creates a new CDB Subscription.

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

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

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

toString

public String toString()

Overrides:

toString in class Object

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.

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