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

  // 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 Details

    • 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 Details

    • 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 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 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 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(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(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<CdbSubscrConfigFlag> 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, 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<CdbSubscrConfigFlag> 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 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:

      • {@link DiffIterateOperFlag#MOP_CREATED}: The list entry, presence container, or leaf of type empty given by kp has been created.
      • {@link 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 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 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<CdbSubscriptionFlagType> of current flags for this subscription.
      Returns:
      EnumSet<CdbSubscriptionFlagType>

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

      @Deprecated public List<ConfXMLParam> getModifications(CdbGetModificationFlag flag) throws IOException, ConfException
      Deprecated.
      This method is deprecated, instead use 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:

    • 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

    • 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

    • 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()