com.tailf.cdb

Class CdbSubscription

Object

com.tailf.cdb.CdbSubscription

public class CdbSubscription
extends Object

This class provides subscription functionality to CDB.

The subscription functionality makes it possible to receive events/notifications of CDB configuration/operational changes. Subscriptions are always towards the running datastore (it is not possible to subscribe to changes to the startup datastore). Subscriptions towards the operational data kept in CDB are also possible, but the mechanism is slightly different.

Subscription to configuration or operational data is specified with the CdbSubscriptionType type.

To subscribe to a particular path the subscribe(CdbSubscriptionType,int,ConfNamespace,String,Object...) should be used. For each invocation of the method a subscription identifier (subscription point) is returned.

Every subscription point is defined through a path similar to the paths we use for read operations, with the exception that instead of fully instantiated paths to list instances we can also selectively use tagpaths.

Each subscriber can have multiple subscription points, and there can be many different subscribers.

The subscription process After establishing a connection against CDB the process is as follow:

• Registering on path(s) trough the subscribe method specifying Subscription type and priority which in turns returns a subscription point.

• When a client is done subscribing it needs to inform that it is ready to receive notifications. This is done by first calling subscribeDone method, after which the subscription socket is ready to receive notifications.

• A direct call to read will retrieve a subscription notification. The read call will block on the socket until an notification is received.

• As a subscriber has read its subscription notifications using read() it will receive points that was affected by a transaction and it can iterate through the changes that caused the particular subscription notification using the diffIterate method. It is also possible to start a new read-session to the CDB_PRE_COMMIT_RUNNING database to read the running database as it was before the pending transaction.

• Once we have read the subscription notification through a call to read and optionally used the diffIterate to iterate through the changes as well as acted on the changes to CDB, we must synchronize sync(CdbSubscriptionSyncType) with CDB so that CDB can continue and deliver further subscription messages to subscribers with higher priority numbers.

Subscription code snippet

  // create new socket and Cdb instance
  Socket sock = new Socket("localhost", Conf.PORT);
  Cdb cdb2 = new Cdb("test",sock);
  // create new CdbSubscription instance
  final CdbSubscription sub2= cdb2.newSubscription();
  // subscribe on a path
  int subid2 = sub2.subscribe(1,new mtest(), "/mtest/servers");
  // tell CDB we are ready for notifications
  sub2.subscribeDone();

  Thread subThread2 = new Thread(new Runnable() {

      public void run() {
          // now do the blocking read
          try {
              while (true) {
                  int[] points= sub2.read();
                  // now do something here like diffIterate
                  // Synchronize with CDB so that we do not
                  // block CDB and can receive new subscriptions.
                  sub2.sync(CdbSubscriptionSyncType.DONE_PRIORITY);
              }
          } catch (Exception e) {
              e.printStackTrace();
              return;
          }
      }
  });

  subThread2.start();
 

Constructor Summary

Constructors

Constructor and Description
CdbSubscription(Cdb cdb) Creates a CDB subscription instance, with the specified Cdb socket.

Method Summary

Methods

Modifier and Type	Method and Description
void	abortTransaction(CdbExtendedException ex) Abort the transaction.
void	CLIdiffIterate(int subid, CdbCLIDiffIterate iter) (CLI)Iterate over changes made in CDB.
void	CLIdiffIterate(int subid, CdbCLIDiffIterate iter, EnumSet<DiffIterateFlags> flags, Object initstate) (CLI)Iterate over changes made in CDB.
void	diffIterate(int subid, CdbDiffIterate iter) Iterate over changes made in CDB.
void	diffIterate(int subid, CdbDiffIterate iter, EnumSet<DiffIterateFlags> flags, Object initstate) Iterate over changes made in CDB with additional supplied flags.
EnumSet<CdbSubscriptionFlagType>	getFlags() Returns an EnumSet of current flags for this subscription.
CdbNotificationType	getLatestNotificationType() Retrieve the latest notification type.
CdbSubscriptionFlagType	getLatestSubscriptionFlag() Deprecated.
List<ConfXMLParam>	getModifications(CdbGetModificationFlag flag) Deprecated.
List<ConfXMLParam>	getModifications(EnumSet<CdbGetModificationFlag> flags) Retrieve changes that caused by subscription notification.
List<ConfXMLParam>	getModifications(int subid, CdbGetModificationFlag flag, ConfPath path) Deprecated.
List<ConfXMLParam>	getModifications(int subid, CdbGetModificationFlag flag, String fmt, Object... args) Deprecated.
List<ConfXMLParam>	getModifications(int subid, EnumSet<CdbGetModificationFlag> flags, ConfPath path) Retrieve changes that caused by subscription notification.
List<ConfXMLParam>	getModifications(int subid, EnumSet<CdbGetModificationFlag> flags, String fmt, Object... args) Retrieve changes that caused by subscription notification.
String	getModificationsCLI(int subid) Return a string with the CLI commands that corresponds to the changes that triggered subscription.
String	getModificationsCLI(int subid, int flags) CLI string that corresponds to the changes that triggered subscription.
long	getUserSession()
int[]	read() Reads the Cdb subscription socket for events and blocks.
void	setMandatory(String mandatoryName) Attaches a mandatory attribute and a mandatory name to this subscriber CDB keeps a list of mandatory subscribers for infinite extent, i.e.
int	subscribe(CdbSubscriptionType subscriptionType, EnumSet<CdbSubscrConfigFlag> flags, int priority, ConfNamespace ns, String fmt, Object... args) Subscribe to a path.
int	subscribe(CdbSubscriptionType subscriptionType, EnumSet<CdbSubscrConfigFlag> flags, int priority, int nshash, String fmt, Object... args) Subscribe to a path.
int	subscribe(CdbSubscriptionType subscriptionType, int priority, ConfNamespace ns, String fmt, Object... args) Subscribe to a path.
int	subscribe(CdbSubscriptionType subscriptionType, int priority, int nshash, String fmt, Object... args) Subscribe to a path.
int	subscribe(int priority, ConfNamespace ns, String fmt, Object... args) Subscribe to a given path.
int	subscribe(int priority, int nshash, String fmt, Object... args) Subscribe to given path.
void	subscribeDone() Finishing the subscription setup.
void	sync(CdbSubscriptionSyncType subscriptionSyncType) Synchronize the subscriber.

Methods inherited from class Object

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

Constructor Detail

CdbSubscription

public CdbSubscription(Cdb cdb)

Creates a CDB subscription instance, with the specified Cdb socket.

Parameters:

cdb - A cdb instance connected to ConfD/NCS

Method Detail

abortTransaction

public void abortTransaction(CdbExtendedException ex)
                      throws ConfException,
                             IOException

Abort the transaction.

This method is used when a two phase subscriber wishes to abort an transaction (the opposite to acknowledge it with sync(CdbSubscriptionSyncType)). The abortTransaction call is only valid for notifications with notificationType CdbNotificationType.SUB_PREPARE.

The subscriber is required to supply an instance of the CdbExtendedException which will be used to notify the clients on the reason for the transaction abort.

Parameters:

ex - an CdbExtendedException instance supplied by the subscriber

Throws:

ConfException

IOException

CLIdiffIterate

public void CLIdiffIterate(int subid,
                  CdbCLIDiffIterate iter)
                    throws IOException,
                           ConfException

(CLI)Iterate over changes made in CDB.

Works just like the diffIterate(int,CdbDiffIterate) except the takes one additional parameter, prompt.

The prompt is a string containing the (C-style) rendering of the CLI commands equivalent to the current keypath/operation.

Note that the CLI commands are independent of whether the originating request actually came in over the CLI or some other northbound interface.

Parameters:

subid - Subscription identifier

iter - A CLICdbDiffIterate object

Throws:

CdbException - Failed to CLI diff iterate

IOException - Failed to read/write cdb socket

ConfException

CLIdiffIterate

public void CLIdiffIterate(int subid,
                  CdbCLIDiffIterate iter,
                  EnumSet<DiffIterateFlags> flags,
                  Object initstate)
                    throws IOException,
                           ConfException

(CLI)Iterate over changes made in CDB.

Works just like the diffIterate(int,CdbDiffIterate) except the takes one additional parameter, prompt.

The prompt is a string containing the (C-style) rendering of the CLI commands equivalent to the current keypath/operation.

Note that the CLI commands are independent of whether the originating request actually came in over the CLI or some other northbound interface.

Parameters:

subid - Subscription identifier

iter - A CLICdbDiffIterate object

flags - A flag that specifies if what is wanted

initstate - An arbitrary object passed iterate() method

Throws:

CdbException - Failed to CLI diff iterate

IOException - Failed to read/write cdb socket

ConfException

diffIterate

public void diffIterate(int subid,
               CdbDiffIterate iter)
                 throws IOException,
                        ConfException

Iterate over changes made in CDB.

After reading the subscription socket the diffIterate method can be used to iterate over the changes made in CDB that matched the particular subid. The supplied user implementation of the CdbDiffIterate , iter corresponding method CdbDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) will be invoked by the library for each element that has been modified and matches the subscription.

The iterate callback receives an ConfObject[] kp array (reversed keypath) which uniquely identifies which node in the data tree that has been affected, the operation, and optionally the values it has before and after the transaction DiffIterateFlags.ITER_WANT_PREV.

A modification op DiffIterateOperFlag is supplied to the iterate method and it gives the modification as:

• MOP_CREATED: The list entry, presence container, or leaf of type empty given by kp has been created.
• MOP_DELETED: The list entry, presence container, or optional leaf given by kp has been deleted. If the subscription was triggered because an ancestor was deleted, the iterate method will not called at all if the delete was above the subscription point. However if the flag DiffIterateFlags.ITER_WANT_ANCESTOR_DELETE is passed to diffIterate then deletes that trigger a descendant subscription will also generate a call to iterate, and in this case kp will be the path that was actually deleted.
• MOP_MODIFIED: A descendant of the list entry given by kp has been modified.
• MOP_VALUE_SET: The value of the leaf given by kp has been set.
• MOP_MOVED_AFTER: The list entry given by kp, in an ordered-by user list, has been moved. If new value is null, the entry has been moved first in the list, otherwise it has been moved after the entry given by the new value.

For configuration subscriptions, the previous value of the node can also be passed to iterate if the flags parameter contains ITER_WANT_PREV, in which case the old value is supplied ,otherwise it will be null.

For operational data subscriptions, the ITER_WANT_PREV flag is ignored, and old value is always null - there is no equivalent to CdbDBType.CDB_PRE_COMMIT_RUNNING that holds "old" operational data.

If iterate returns DiffIterateResultFlag.ITER_STOP, no more iteration is done, is returned. If iterate returns DiffIterateResultFlag.ITER_RECURSE iteration continues with all children to the node.

If iterate returns DiffIterateResultFlag.ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

This version sends passes ITER_WANT_PREV as default. If the ITER_WANT_PREV is not desired or additional flags is require use diffIterate(int,CdbDiffIterate,EnumSet, Object)

Parameters:

subid - Subscription identifier point

iter - A User implementation CdbDiffIterate interface.

Throws:

CdbException - Failed to diff iterate

IOException - Failed to read/write cdb socket

ConfException

diffIterate

public void diffIterate(int subid,
               CdbDiffIterate iter,
               EnumSet<DiffIterateFlags> flags,
               Object initstate)
                 throws IOException,
                        ConfException

Iterate over changes made in CDB with additional supplied flags.

After reading the subscription socket the diffIterate method can be used to iterate over the changes made in CDB that matched the particular subid. The supplied user implementation of the CdbDiffIterate interface, iter corresponding method CdbDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) will be invoked by the library for each element that has been modified and matches the subscription.

The iterate callback receives an ConfObject[] kp array (reversed keypath) which uniquely identifies which node in the data tree that has been affected, the operation, and optionally the values it has before (old value) and after the transaction ( new value ) DiffIterateFlags.ITER_WANT_PREV.

A modification op DiffIterateOperFlag is supplied to the iterate method and it gives the modification as:

• DiffIterateOperFlag.MOP_CREATED: The list entry, presence container, or leaf of type empty given by kp has been created.
• DiffIterateOperFlag.MOP_DELETED: The list entry, presence container, or optional leaf given by kp has been deleted. If the subscription was triggered because an ancestor was deleted, the iterate method will not called at all if the delete was above the subscription point. However if the flag DiffIterateFlags.ITER_WANT_ANCESTOR_DELETE is passed to diffIterate then deletes that trigger a descendant subscription will also generate a call to iterate, and in this case kp will be the path that was actually deleted.
• MOP_MODIFIED: A descendant of the list entry given by kp has been modified.
• MOP_VALUE_SET: The value of the leaf given by kp has been set.
• MOP_MOVED_AFTER The list entry given by kp, in an ordered-by user list, has been moved. If new value is null, the entry has been moved first in the list, otherwise it has been moved after the entry given by the new value.

For configuration subscriptions, the previous value of the node can also be passed to iterate if the flags parameter contains ITER_WANT_PREV, in which case the old value is supplied ,otherwise it will be null.

For operational data subscriptions, the ITER_WANT_PREV flag is ignored, and old value is always null - there is no equivalent to CdbDBType.CDB_PRE_COMMIT_RUNNING that holds "old" operational data.

If iterate returns DiffIterateResultFlag.ITER_STOP, no more iteration is done, is returned. If iterate returns DiffIterateResultFlag.ITER_RECURSE iteration continues with all children to the node.

If iterate returns DiffIterateResultFlag.ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

Parameters:

subid - Subscription identifier point

iter - A User implementation CdbDiffIterate interface

Throws:

CdbException - Failed to diff iterate

IOException - Failed to read/write cdb socket

ConfException

getFlags

public EnumSet<CdbSubscriptionFlagType> getFlags()

Returns an EnumSet of current flags for this subscription.

Returns:

EnumSet

getLatestNotificationType

public CdbNotificationType getLatestNotificationType()

Retrieve the latest notification type.

Each notification retrieved by the read() method has a notificationType. This method retrieves the notification type from the latest read call.

If no read call has been performed then this method returns null.

Returns:

notificationType or null if not applicable

getLatestSubscriptionFlag

@Deprecated
public CdbSubscriptionFlagType getLatestSubscriptionFlag()

Deprecated.

This method is deprecated. Use getFlags() instead.

Returns:

CdbSubscriptionFlagType

getModifications

@Deprecated
public List<ConfXMLParam> getModifications(CdbGetModificationFlag flag)
                                    throws IOException,
                                           ConfException

Deprecated.

This method is deprecated, instead use getModifications(EnumSet)

Throws:

IOException

ConfException

getModifications

public List<ConfXMLParam> getModifications(EnumSet<CdbGetModificationFlag> flags)
                                    throws IOException,
                                           ConfException

Retrieve changes that caused by subscription notification. Convenient short-hand of the getModifications(int,CdbGetModificationFlag,ConfPath) method intended to be used from within a iteration started by diffIterate(int,CdbDiffIterate).

In this case no subscription id is needed, and the path is implicitly the current position in the iteration.

Combining this call with diffIterate makes it for example possible to iterate over a list, and for each list instance fetch the changes using getModifications, and then return DiffIterateResultFlag.ITER_CONTINUE to process next instance.

Throws:

IOException

ConfException

See Also:

getModifications(int,EnumSet,ConfPath)

getModifications

@Deprecated
public List<ConfXMLParam> getModifications(int subid,
                                             CdbGetModificationFlag flag,
                                             ConfPath path)
                                    throws IOException,
                                           ConfException

Deprecated.

This method is deprecated, instead use {link getModifications(int, EnumSet, ConfPath)

Throws:

IOException

ConfException

getModifications

@Deprecated
public List<ConfXMLParam> getModifications(int subid,
                                             CdbGetModificationFlag flag,
                                             String fmt,
                                             Object... args)
                                    throws IOException,
                                           ConfException

Deprecated.

This method is deprecated, instead use getModifications(int, EnumSet, String, Object...)

Throws:

IOException

ConfException

getModifications

public List<ConfXMLParam> getModifications(int subid,
                                  EnumSet<CdbGetModificationFlag> flags,
                                  ConfPath path)
                                    throws IOException,
                                           ConfException

Retrieve changes that caused by subscription notification.

The getModifications can be called after reception of a subscription notification to retrieve all the changes that caused the subscription notification.

The subscription id subid must be provide Optionally a path path can be used to limit what is returned further (only changes below the supplied path will be returned), if this isn't needed a null could be provided.

Only the values that were modified in this transaction are included. In addition to that these are the different values of the tags depending on what happened in the transaction:

• A leaf of type empty that has been deleted has the value of ConfNoExists, and when it is created it has the value ConfXMLParamLeaf.

• A leaf or a leaf-list that has been set to a new value (or its default value) is included with that new value. If the leaf or leaf-list is optional, then when it is deleted the value is ConfNoExists.
• Presence containers are included when they are created or when they have modifications below them (by the usual ConfXMLParamStart, ConfXMLParamStop pair). If a presence container have been deleted its tag is included, but is set to ConfNoExists.

By default getModifications does not include list instances (created, deleted, or modified) - but if the flags parameter is set to CdbGetModificationFlag.CDB_GET_MODS_INCLUDE_LISTS then list instances will be included. Created and modified instances are included wrapped in the ConfXMLParamStart / ConfXMLParamStop pair, with the keys first. Deleted list instances instead begin with C_XMLBEGINDEL, then follows the keys, immediately followed by a C_XMLEND.

Parameters:

subid - Subscription id

flags - enumset of CdbGetModificationFlag

path -

Throws:

ConfException

IOException

getModifications

public List<ConfXMLParam> getModifications(int subid,
                                  EnumSet<CdbGetModificationFlag> flags,
                                  String fmt,
                                  Object... args)
                                    throws IOException,
                                           ConfException

Retrieve changes that caused by subscription notification.

The getModifications can be called after reception of a subscription notification to retrieve all the changes that caused the subscription notification.

The subscription id subid must be provide Optionally a path path can be used to limit what is returned further (only changes below the supplied path will be returned), if this isn't needed a null could be provided.

Only the values that were modified in this transaction are included. In addition to that these are the different values of the tags depending on what happened in the transaction:

• A leaf of type empty that has been deleted has the value of ConfNoExists, and when it is created it has the value ConfXMLParamLeaf.

• A leaf or a leaf-list that has been set to a new value (or its default value) is included with that new value. If the leaf or leaf-list is optional, then when it is deleted the value is ConfNoExists.
• Presence containers are included when they are created or when they have modifications below them (by the usual ConfXMLParamStart, ConfXMLParamStop pair). If a presence container have been deleted its tag is included, but is set to ConfNoExists.

By default getModifications does not include list instances (created, deleted, or modified) - but if the flags parameter is set to CdbGetModificationFlag.CDB_GET_MODS_INCLUDE_LISTS then list instances will be included. Created and modified instances are included wrapped in the ConfXMLParamStart / ConfXMLParamStop pair, with the keys first. Deleted list instances instead begin with C_XMLBEGINDEL, then follows the keys, immediately followed by a C_XMLEND.

If the flags parameter is set to CdbGetModificationFlag.CDB_GET_MODS_SUPPRESS_DEFAULTS, a default value that comes into effect for a leaf due to an ancestor list entry or presence container being created will not be included, and a default value that comes into effect for a leaf due to a set value being deleted will be included as a deletion (i.e. with value ConfNoExists.

Parameters:

subid - Subscription id

flags - EnumSet of CdbGetModificationFlag

fmt -

args -

Throws:

ConfException

IOException

getModificationsCLI

public String getModificationsCLI(int subid)
                           throws IOException,
                                  ConfException

Return a string with the CLI commands that corresponds to the changes that triggered subscription.

Throws:

IOException

ConfException

See Also:

getModificationsCLI(int, int)

getModificationsCLI

public String getModificationsCLI(int subid,
                         int flags)
                           throws IOException,
                                  ConfException

CLI string that corresponds to the changes that triggered subscription.

Throws:

IOException

ConfException

getUserSession

public long getUserSession()
                    throws ConfException,
                           IOException

Throws:

ConfException

IOException

read

public int[] read()
           throws IOException,
                  ConfException

Reads the Cdb subscription socket for events and blocks.

Returns the subscription points that triggered a change.

The triggering notification is of a type. This information in important in two-phase subscriptions. The notificationType can be retrieved using getLatestNotificationType()

Throws:

CdbException - Failed to read.

IOException - Failed to read/write cdb socket

ConfException

setMandatory

public void setMandatory(String mandatoryName)
                  throws IOException,
                         ConfException

Attaches a mandatory attribute and a mandatory name to this subscriber CDB keeps a list of mandatory subscribers for infinite extent, i.e. until ConfD/NCS is restarted. The function is idempotent. Absence of one or more mandatory subscribers will result in abort of all transactions. A mandatory subscriber must be present during the entire PREPARE delivery phase. If a mandatory subscriber crash during a PREPARE delivery phase, the subscriber should be restarted and the commit operation should be retried. A mandatory subscriber is present if the subscriber has issued at least one subscribe() call followed by a subscribeDone() call.

A call to setMandatory() is only allowed before subscribe() has been called. Note, this functionality is only applicable for two-phase subscribers.

Parameters:

mandatoryName -

Throws:

IOException

ConfException

subscribe

public int subscribe(CdbSubscriptionType subscriptionType,
            EnumSet<CdbSubscrConfigFlag> flags,
            int priority,
            ConfNamespace ns,
            String fmt,
            Object... args)
              throws IOException,
                     ConfException

Subscribe to a path. Same as the subscribe(CdbSubscriptionType,EnumSet,int,int,String,Object...) with the difference that the namespace is given as a ConfNamespace.

Parameters:

subscriptionType - The subscription type

flags - EnumSet controlling the subscription

priority - The priority of the subscription

ns - Namespace where the path belongs to

fmt - subscription path

args - arguments to be substituted into fmt string

Returns:

The final subscription point which is used to identify this particular subscription

Throws:

IOException

ConfException

subscribe

public int subscribe(CdbSubscriptionType subscriptionType,
            EnumSet<CdbSubscrConfigFlag> flags,
            int priority,
            int nshash,
            String fmt,
            Object... args)
              throws IOException,
                     ConfException

Subscribe to a path. Same as the subscribe(CdbSubscriptionType, int, int, String, Object...) with the addition of the flags parameter which is an EnumSet of configuration flags for the subscription see CdbSubscrConfigFlag

Parameters:

subscriptionType - subscription type

flags - EnumSet controlling the subscription

priority - subscription priority

nshash - namespace hash

fmt - subscription path

args - arguments to be substituted into fmt string

Returns:

The final subscription point which is used to identify this particular subscription

Throws:

IOException

ConfException - If failed to subscribe to the given path for some reason

subscribe

public int subscribe(CdbSubscriptionType subscriptionType,
            int priority,
            ConfNamespace ns,
            String fmt,
            Object... args)
              throws IOException,
                     ConfException

Subscribe to a path.

Sets up a CDB subscription so that we are notified when CDB configuration data changes. There can be multiple subscription points from different sources, that is a single client daemon can have many subscriptions and there can be many client daemons.

Each subscription point is defined through a path similar to the paths we use for read operations. We can subscribe either to specific leafs or entire subtrees. Subscribing to list entries can be done using fully qualified paths, or tagpaths to match multiple entries. A path which isn't a leaf element automatically matches the subtree below that path. When specifying keys to a list entry it is possible to use the wild card character * which will match any key value.

When subscribing to a leaf with a tailf:default-ref statement, or to a subtree with elements that have tailf:default-ref, implicit subscriptions to the referred leafs are added. This means that a change in a referred leaf will generate a notification for the subscription that has referring leaf(s) - but currently such a change will not be reported by diffIterate(int, CdbDiffIterate, EnumSet, Object). Thus to get the new "effective" value of a referring leaf in this case, it is necessary to either read the value of the leaf with e.g. CdbSession.getElem(ConfPath) - or to use a subscription that includes the referred leafs, and use diffIterate() when a notification for that subscription is received. Some examples

 /hosts
         Means that we subscribe to any changes in the subtree - rooted
         at /hosts. This includes additions or removals of host
         entries as well as changes to already  existing host entries.

 /hosts/host{www}/interfaces/interface{eth0}/ip
         Means we are notified when host www changes its IP address on
         eth0.

 /hosts/host/interfaces/interface/ip
         Means we are notified when any host changes any of its IP
         addresses.

 /hosts/host/interfaces
         Means we are notified when either an interface is
         added/removed or when an individual leaf element in an
         existing interface is changed.

  

The priority value is an integer. When CDB is changed, the change is performed inside a transaction. Either a commit operation from the CLI or a candidate-commit operation in NETCONF means that the running database is changed. These changes occur inside a transaction. CDB will handle the subscriptions in lock-step priority order. First all subscribers at the lowest priority are handled, once they all have replied and synchronized through calls to sync(CdbSubscriptionSyncType) the next set - at the next priority level is handled by CDB.

Priority numbers are global, i.e. if there are multiple client daemons notifications will still be delivered in priority order per all subscriptions, not per daemon. See diffIterate(int,CdbDiffIterate,EnumSet,Object) for ways of filtering subscription notifications and finding out what changed. The easiest way is though to solely rely on the positioning of the subscription points in the tree to figure out what changed.

subscribe returns a subscription point This integer value is used to identify this particular subscription.

Because there can be many subscriptions on the same socket the client must notify when it is done subscribing and ready to receive notifications. This is done using subscribeDone().

Parameters:

subscriptionType - The subscription type

priority - The priority of the subscription

ns - Namespace where the path belongs to

fmt - subscription path

args - arguments to be substituted into fmt string

Returns:

The final subscription point which is used to identify this particular subscription

Throws:

IOException

ConfException

subscribe

public int subscribe(CdbSubscriptionType subscriptionType,
            int priority,
            int nshash,
            String fmt,
            Object... args)
              throws IOException,
                     ConfException

Subscribe to a path.

Sets up a CDB subscription so that we are notified when CDB configuration data changes. There can be multiple subscription points from different sources, that is a single client daemon can have many subscriptions and there can be many client daemons.

Each subscription point is defined through a path similar to the paths we use for read operations. We can subscribe either to specific leafs or entire subtrees. Subscribing to list entries can be done using fully qualified paths, or tagpaths to match multiple entries. A path which isn't a leaf element automatically matches the subtree below that path. When specifying keys to a list entry it is possible to use the wild card character '*' which will match any key value.

When subscribing to a leaf with a tailf:default-ref statement, or to a subtree with elements that have tailf:default-ref, implicit subscriptions to the referred leafs are added. This means that a change in a referred leaf will generate a notification for the subscription that has referring leaf(s) - but currently such a change will not be reported by diffIterate(int,CdbDiffIterate,EnumSet,Object). Thus to get the new "effective" value of a referring leaf in this case, it is necessary to either read the value of the leaf with e.g. CdbSession.getElem(ConfPath) - or to use a subscription that includes the referred leafs, and use diffIterate when a notification for that subscription is received. Some examples

 /hosts
         Means that we subscribe to any changes in the subtree - rooted
         at /hosts. This includes additions or removals of host
         entries as well as changes to already  existing host entries.

 /hosts/host{www}/interfaces/interface{eth0}/ip
         Means we are notified when host www changes its IP address on
         eth0.

 /hosts/host/interfaces/interface/ip
         Means we are notified when any host changes any of its IP
         addresses.

 /hosts/host/interfaces
         Means we are notified when either an interface is
         added/removed or when an individual leaf element in an
         existing interface is changed.

  

The priority value is an integer. When CDB is changed, the change is performed inside a transaction. Either a commit operation from the CLI or a candidate-commit operation in NETCONF means that the running database is changed. These changes occur inside a transaction. CDB will handle the subscriptions in lock-step priority order. First all subscribers at the lowest priority are handled, once they all have replied and synchronized through calls to sync(CdbSubscriptionSyncType) the next set - at the next priority level is handled by CDB.

Priority numbers are global, i.e. if there are multiple client daemons notifications will still be delivered in priority order per all subscriptions, not per daemon. See diffIterate(int,CdbDiffIterate,EnumSet,Object) for ways of filtering subscription notifications and finding out what changed. The easiest way is though to solely rely on the positioning of the subscription points in the tree to figure out what changed.

subscribe returns a subscription point This integer value is used to identify this particular subscription.

Because there can be many subscriptions on the same socket the client must notify when it is done subscribing and ready to receive notifications. This is done using subscribeDone().

Parameters:

subscriptionType - subscription type

priority - subscription priority

nshash - namespace hash

fmt - subscription path

args - arguments to be substituted into fmt string

Returns:

The final subscription point which is used to identify this particular subscription

Throws:

IOException

ConfException - If failed to subscribe to the given path for some reason

subscribe

public int subscribe(int priority,
            ConfNamespace ns,
            String fmt,
            Object... args)
              throws ConfException,
                     IOException

Subscribe to a given path.

Sets up a CDB subscription so that we are notified when CDB configuration data changes. There can be multiple subscription points from different sources, that is a single client daemon can have many subscriptions and there can be many client daemons.

Each subscription point is defined through a path similar to the paths we use for read operations. We can subscribe either to specific leafs or entire subtrees. Subscribing to list entries can be done using fully qualified paths, or tagpaths to match multiple entries. A path which isn't a leaf element automatically matches the subtree below that path. When specifying keys to a list entry it is possible to use the wild card character * which will match any key value.

When subscribing to a leaf with a tailf:default-ref statement, or to a subtree with elements that have tailf:default-ref, implicit subscriptions to the referred leafs are added. This means that a change in a referred leaf will generate a notification for the subscription that has referring leaf(s) - but currently such a change will not be reported by diffIterate(int,CdbDiffIterate,EnumSet,Object). Thus to get the new "effective" value of a referring leaf in this case, it is necessary to either read the value of the leaf with e.g. CdbSession.getElem(ConfPath) - or to use a subscription that includes the referred leafs, and use diffIterate when a notification for that subscription is received. Some examples

 /hosts
         Means that we subscribe to any changes in the subtree - rooted
         at /hosts. This includes additions or removals of host
         entries as well as changes to already  existing host entries.

 /hosts/host{www}/interfaces/interface{eth0}/ip
         Means we are notified when host www changes its IP address on
         eth0.

 /hosts/host/interfaces/interface/ip
         Means we are notified when any host changes any of its IP
         addresses.

 /hosts/host/interfaces
         Means we are notified when either an interface is
         added/removed or when an individual leaf element in an
         existing interface is changed.

  

The priority value is an integer. When CDB is changed, the change is performed inside a transaction. Either a commit operation from the CLI or a candidate-commit operation in NETCONF means that the running database is changed. These changes occur inside a transaction. CDB will handle the subscriptions in lock-step priority order. First all subscribers at the lowest priority are handled, once they all have replied and synchronized through calls to sync(CdbSubscriptionSyncType) the next set - at the next priority level is handled by CDB.

Priority numbers are global, i.e. if there are multiple client daemons notifications will still be delivered in priority order per all subscriptions, not per daemon. See diffIterate(int,CdbDiffIterate,EnumSet,Object) for ways of filtering subscription notifications and finding out what changed. The easiest way is though to solely rely on the positioning of the subscription points in the tree to figure out what changed.

subscribe returns a subscription point This integer value is used to identify this particular subscription.

Because there can be many subscriptions on the same socket the client must notify when it is done subscribing and ready to receive notifications. This is done using subscribeDone().

Parameters:

priority - subscription priority

ns - namespace

fmt - subscription path

args - arguments to be substituted into fmt string

Returns:

subscription point which is used to identify this particular subscription

Throws:

IOException

ConfException

subscribe

public int subscribe(int priority,
            int nshash,
            String fmt,
            Object... args)
              throws IOException,
                     ConfException

Subscribe to given path. Sets up a CDB description so that we are notified when CDB changes. There can be multiple subscription points from different sources, that is a single client daemon can have many subscriptions and there can be many client daemons.

Each subscription point is defined through a path similar to the paths we use for read operations. We can subscribe either to specific leaf elements or entire subtrees. Subscribing to YANG list entries can be done using fully qualified paths, or tagpaths to match multiple list entries. A path which isn't a leaf automatically matches the subtree below that path.

Some examples:

• /hosts - Means that we subscribe to any changes in the subtree - rooted at "/hosts". This includes additions or removals of "host" entries as well as changes to already existing "host" entries.
• /hosts/host{www}/interfaces/interface{eth0}/ip - Means we are notified when host www changes its IP address on eth0.
• /hosts/host/interfaces/interface/ip - Means we are notified when any host changes any of its IP addresses.
• /hosts/host/interfaces - Means we are notified when either an interface is added/removed or when an individual leaf in an existing interface is changed.

The priority value is an integer. When CDB is changed, the change is performed inside a transaction. Either a commit operation from the CLI or a candidate-commit operation in NETCONF means that the running database is changed. These changes occur inside a transaction. CDB will handle the subscriptions in lock-step priority order. First all subscribers at the lowest priority are handled, once they all have replied and synchronized through calls to sync(CdbSubscriptionSyncType) the next set - at the next priority level is handled by CDB. Priority numbers are global, i.e. if there are multiple client daemons notifications will still be delivered in priority order per all subscriptions, not per daemon.

See diffIterate(int,CdbDiffIterate) for ways of filtering subscription notifications and finding out what changed.

Parameters:

priority - Subscription priority

nshash - namespace hash

fmt - subscription path

Returns:

A subscription point. This integer value is used to identify this particular subscription.

Throws:

CdbException - Failed to subscribe to the specified path

IOException - Failed to read/write cdb socket

ConfException

subscribeDone

public void subscribeDone()
                   throws IOException,
                          ConfException

Finishing the subscription setup.

When a client is done registering all its subscriptions on a particular subscription socket it must call subscribeDone.

No notifications will be delivered until then.

Throws:

IOException

ConfException

sync

public void sync(CdbSubscriptionSyncType subscriptionSyncType)
          throws ConfException,
                 IOException

Synchronize the subscriber.

Once we have read the subscription notification through a call to read() and also have acted on the changes to CDB, we must synchronize with CDB so that CDB can continue and deliver further subscription messages to subscribers with higher priority numbers.

There are three different types of synchronization replies the application can use in the subscriptionSyncType parameter: see CdbSubscriptionSyncType

CDB is locked for writing while subscriptions are delivered.

Throws:

CdbException - Failed to sync

IOException - Failed to read/write cdb socket

ConfException