com.tailf.cdb

Class CdbSubscription

Object

com.tailf.cdb.CdbSubscription

All Implemented Interfaces:

MountIdInterface

public class CdbSubscription
extends Object
implements MountIdInterface

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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.sync(CdbSubscriptionSyncType) with CDB so that CDB can continue and deliver further subscription messages to subscribers with higher priority numbers.

Subscription code snippet

  // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS
  // create new socket and Cdb instance
  Socket sock = new Socket("localhost", 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

Modifier and Type	Method and Description
void	abortTransaction(CdbExtendedException ex) Abort the transaction.
boolean	acceptTagPath()
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.
Cdb	getCdb()
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.
List<String>	getMountId(ConfPath path)
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

getUserSession

public long getUserSession()
                    throws ConfException,
                           IOException

Throws:

ConfException

IOException

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 CdbSubscription.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.

Operational and configuration subscriptions can be done on the same socket, but in that case the notifications may be arbitrarily interleaved, including operational notifications arriving between different configuration notifications for the same transaction. If this is a problem, use separate CdbSubscription instances with separate Cdb instances for operational and configuration subscriptions.

See CdbSubscription.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

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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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(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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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(CdbSubscriptionType subscriptionType,
                     EnumSet<CdbSubscrConfigFlag> flags,
                     int priority,
                     int nshash,
                     String fmt,
                     Object... args)
              throws IOException,
                     ConfException

Subscribe to a path. Same as the CdbSubscription.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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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 CdbSubscription.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,
                     EnumSet<CdbSubscrConfigFlag> flags,
                     int priority,
                     ConfNamespace ns,
                     String fmt,
                     Object... args)
              throws IOException,
                     ConfException

Subscribe to a path. Same as the CdbSubscription.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

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

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 CdbSubscription.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

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 CdbSubscription.getLatestNotificationType()

Throws:

CdbException - Failed to read.

IOException - Failed to read/write cdb socket

ConfException

getLatestNotificationType

public CdbNotificationType getLatestNotificationType()

Retrieve the latest notification type.

Each notification retrieved by the CdbSubscription.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

getFlags

public EnumSet<CdbSubscriptionFlagType> getFlags()

Returns an EnumSet of current flags for this subscription.

Returns:

EnumSet

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, modified and moved instances are included wrapped in the ConfXMLParamStart / ConfXMLParamStop pair, with the keys first. To receive information about where a list instance in an ordered-by user list is moved, the CdbGetModificationFlag.CDB_GET_MODS_INCLUDE_MOVES flag must also be included in the flags parameter. To receive information about ancestor list entry or presence container deleion CdbGetModificationFlag.CDB_GET_MODS_INCLUDE_MOVES flag must also be included in the flags parameter. A list instance moved to the beginning of the list is indicated by C_XMLMOVEFIRST after the keys. A list instance moved elsewhere is indicated by C_XMLMOVEAFTER after the keys, with the after-keys following directly after. 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

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

Deprecated.

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

Throws:

IOException

ConfException

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.

If the flags parameter is set to CdbGetModificationFlag.CDB_GET_MODS_CLI_NO_BACKQUOTES, Then backslash quotes will not be used when formatting string values. This means that certain values cannot be represented (like newlines and tabs) but also that there is no need to remove backslash quotes if the target for the configuration does not support it.

If the flags parameter is set to CdbGetModificationFlag.CDB_GET_MODS_WANT_ANCESTOR_DELETE, Then a node that comes into effect due to an ancestor list entry or presence container being deleted will be included,

Parameters:

subid - Subscription id

flags - EnumSet of CdbGetModificationFlag

fmt -

args -

Throws:

ConfException

IOException

getModifications

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

Deprecated.

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

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 CdbSubscription.getModifications(int,CdbGetModificationFlag,ConfPath) method intended to be used from within a iteration started by CdbSubscription.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:

CdbSubscription.getModifications(int,EnumSet,ConfPath)

getModifications

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

Deprecated.

This method is deprecated, instead use CdbSubscription.getModifications(EnumSet)

Throws:

IOException

ConfException

getModificationsCLI

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

CLI string that corresponds to the changes that triggered subscription.

Throws:

IOException

ConfException

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:

CdbSubscription.getModificationsCLI(int, int)

sync

public void sync(CdbSubscriptionSyncType subscriptionSyncType)
          throws ConfException,
                 IOException

Synchronize the subscriber.

Once we have read the subscription notification through a call to CdbSubscription.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

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 CdbSubscription.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

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

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

getCdb

public Cdb getCdb()