NavuCdbSubscribers (CONF API Version 6.4)

Object
- com.tailf.navu.NavuCdbSubscribers

All Implemented Interfaces:

NavuCdbSubscriber

Direct Known Subclasses:

NavuCdbConfigSubscriber, NavuCdbOperSubscriber

Deprecated.
```
@Deprecated
public abstract class NavuCdbSubscribers
extends Object
implements NavuCdbSubscriber
```
This class provides general base implementation to the NavuCdbSubscriber interface.
The NAVU Cdb subscription API provides a convenient way for using the Cdb Subscription API.
It handles the thread and polling maintenance i.e minimize the effort to setup a Cdb Subscription and explicit thread creation.
The NavuCdbSubscriber is declared abstract and there is mainly two subclasses:
- NavuCdbConfigSubscriber - Handles notifications of configuration changes.
- NavuCdbOperSubscriber - Handles notifications of operation data changes, nodes that is annotated with tailf:cdb-oper in the yang model.
- NavuCdbTwoPhaseSubscriber - Handles notifications of configuration changes and in the PREPARE phase of a two phase commit. A two phase subscriber can participate in a transaction and abort a current transaction in the PREPARE phase. NOTE: The NavuCdbTwoPhaseSubscriber is only available in ConfD.
Instance of either NavuCdbConfigSubscriber or NavuCdbConfigSubscriber is retrieved through static factory configSubscriber(String,int), operSubscriber(String,int) where host name and a port should be provided.
Creating a NavuCdbConfigSubscriber:
```
       //Creation of Configuration data subscriber
      NavuCdbSubscriber confSubscr =
          NavuCdbSubscribers.configSubscriber("localhost",
                                              Conf.PORT);
 
```
Creating a NavuCdbOperSubscriber:
```
     //Creation of Operation data subscriber
      NavuCdbSubscriber operSubscr =
          NavuCdbSubscribers.operSubscriber("localhost",
                                            Conf.PORT);
 
```
Creating a NavuCdbTwoPhaseSubscriber:
```
     //Creation of Operation data subscriber
      NavuCdbSubscriber twoPhaseSubscr =
          NavuCdbSubscribers.twoPhaseSubscriber("localhost",
                                            Conf.PORT);
 
```
Before a NavuCdbSubscriber is started a user need to register a user provided callback which either implements NavuCdbConfigDiffIterate for configuration data, NavuCdbOperDiffIterate for Cdb oper data or NavuCdbTwoPhaseDiffIterate for a two phase subscriber.
A user provided callback and a path is registered to a NavuCdbSubscriber through one of the register methods.
A path to config data node must be registered with a user provided implementation of NavuCdbConfigDiffIterate into NavuCdbConfigSubscriber or NavuCdbTwoPhaseSubscriber. A path to Cdb oper data node must be registered with a user provided implementation of NavuCdbOperDiffIterate into NavuCdbOperSubscriber.
A NavuCdbSubscriber maintains multiple registration points associated with provided callbacks. The same user provided callback could be associated with different subscription points.
When registration have been done on the NavuCdbSubscriber it needs to be started in order to receive notifications from Cdb. This is done with the NavuCdbSubscriber.subscriberStart() which registers the provided paths to Cdb and starts to read from the underlying Cdb socket for notifications.
It should be noted that the NavuCdbSubscriber.subscriberStart()/ NavuCdbSubscriber.subscriberStop() starts/stop the subscriber asynchronously. There is however convenient methods to perform blocking on the calling thread when a subscriber has been started NavuCdbSubscriber.awaitRunning() and when a subscriber has been stopped NavuCdbSubscriber.awaitStopped().
A NavuCdbSubscribers maintains a ExecutorService which executes NavuCdbConfigSubscriber or a NavuCdbOperSubscriber in a new single thread. The ExecutorService is obtained through NavuCdbSubscriber.executor().
There is functionality to restart a NavuCdbSubscriber with the NavuCdbSubscriber.subscriberStop()/ NavuCdbSubscriber.subscriberStart() .
A NavuCdbSubscriber could be restarted after it has been stopped as long as the underlying ExecutorService is not stopped. The ExecutorService is stopped when shutdown() or shutdownNow() is invoked.
When a subscriber has been started it does a select on the underlying SocketChannel in a separate thread this means that the user does not need to explicitly start a new thread.
When a subscriber receives notification of Cdb change the user provided callback will be invoked for each diff entry (iteration) in the diff set that match the particular subscription point.
For each iteration a user callback is provided with a NavuCdbSubscriptionContext where the user callback could extract information for the current iteration. When a user provided callback gets invoked the user callback have the ability to access the affected NavuNode in a iteration process. The provided NavuNode is created with a Cdb NavuContext. The modified flag could be accessed through NavuNode.getChangeFlag() as well as through NavuCdbSubscriptionContext.getOperFlag().
There is ability to access a deleted node (i.e when getOperFlag() of NavuCdbSubscriptionContext returns MOP_DELETED) , the library will implicitly set up a temporally Cdb read socket against CdbDBType.CDB_PRE_COMMIT_RUNNING and will close it after the current iteration. Note that the deleted NavuNode is only valid in a iteration after that it will be invalid thus further processing of the NavuNode will throw exceptions and will be in a bad state. This means it is important for a implementation to not hold a NavuNode reference in a instance field for late usage after the current iteration has been made.
Access a deleted node:
```
 
 @IterateFlags(flags={
            DiffIterateFlags.ITER_WANT_PREV,
            DiffIterateFlags.ITER_WANT_SCHEMA_ORDER,
            DiffIterateFlags.ITER_WANT_ANCESTOR_DELETE} )
        public void iterate (NavuCdbSubscriptionConfigContext ctx ) {
         // the scope of the retrieved NavuNode should be
        // held within the iterate method.
        switch( ctx.getOperFlag() ) {
        case MOP_DELETED:
            NavuNode deletedNode = ctx.getNode();
             // Do something with the deleted node
            break;
        }
        ctx.iterRecurse();
    }
   
```
The IterateFlags sets the default iteration behavior for the callback.
There is also the ability to access the rendering of CLI commands equivalent to the current keypath/operation for each iteration. The CLITokens is obtained through NavuCdbSubscriptionContext.getCLITokens() it contains the CLI string broken down by token. To access the CLITokens the callback needs to annotate iterate callback method with the DiffIterateFlags.ITER_WANT_CLI_STR.
When the user callback have finally processed the iteration it may chose how the next traversal of the diff set should be done NavuCdbSubscriptionContext.iterContinue() , for continuing with the sibling nodes NavuCdbSubscriptionContext.iterRecurse() , for continuing down the child nodes or NavuCdbSubscriptionContext.iterStop() for stopping the iteration.
NOTE: A sync call to Cdb is done implicitly by the NavuCdbSubscriber.
NOTE: To be able to stop the JVM after the subscriber has been stopped it is important to shutdown the ExecutorService. The single worker thread inside the ExectuorService will not die unless the underlying ExectuorService is shutdown.
Shutdown the subscriber method 1:
```
 
        NavuCdbSubscriber x = ..;
        x.subscriberStart();
        x.awaitRunning();  //block the current thread until subscriber runs

        x.subscriberStop();
        x.awaitStopped();

        //the below method has no affect if the subscriberStop()
        //is not called
        x.executor().shutdown();

   
```
Shutdown the subscriber method 2:
```
 
        NavuCdbSubscriber x = ..;
        x.subscriberStart();
        x.awaitRunning();  //block the current thread until subscriber runs

       //interrupt the subscriber thread and shutdown the subscriber
        x.executor().shutdownNow();

   
```

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`awaitRunning()` Deprecated. Wait or Blocks the calling thread until this `NavuSubscriber` is running ( when `isRunning()` returns true).
`void`	`awaitStopped()` Deprecated. Blocks until this subscriber have stopped.
`static NavuCdbSubscriber`	`configSubscriber(Cdb cdb)` Deprecated. Retrieve a new instance of a `NavuCdbConfigSubscriber`.
`static NavuCdbSubscriber`	`configSubscriber(InetSocketAddress addr)` Deprecated.
`static NavuCdbSubscriber`	`configSubscriber(String host, int port)` Deprecated. Retrieve a new instance of a `NavuCdbConfigSubscriber`.
`static NavuCdbSubscriber`	`configSubscriber(String host, int port, String name)` Deprecated. Retrieve a new instance of a `NavuCdbConfigSubscriber`.
`ExecutorService`	`executor()` Deprecated. Retrieve the underlying `ExecutorService`.
`NavuCdbSubscriptionIterQueue`	`getIterationQueue()` Deprecated. Retrieve a notification queue where additional thread can poll for summary information about a iteration and react appropriately.
`boolean`	`isRunning()` Deprecated. Return true if this subscriber is running.
`boolean`	`isStopped()` Deprecated. Return true if this subscriber is stopped.
`static NavuCdbSubscriber`	`operSubscriber(Cdb cdb)` Deprecated. Retrieve a new instance of a `NavuCdbConfigSubscriber`.
`static NavuCdbSubscriber`	`operSubscriber(InetSocketAddress addr)` Deprecated.
`static NavuCdbSubscriber`	`operSubscriber(InetSocketAddress addr, String subName)` Deprecated.
`static NavuCdbSubscriber`	`operSubscriber(String host, int port)` Deprecated. Retrieve a new instance of a `NavuCdbOperSubscriber`.
`static NavuCdbSubscriber`	`operSubscriber(String host, int port, String name)` Deprecated. Retrieve a new instance of a `NavuCdbConfigSubscriber`.
`void`	`registerStoppedHandler(NavuCdbStoppedHandler handler)` Deprecated. Register a stop handler when the subscriber will be stopped.
`boolean`	`subscriberStop()` Deprecated. Sends a Stop signal to the underlying subscription process without shutting down the underlying `ExecutorService`.
`static NavuCdbSubscriber`	`twoPhaseSubscriber(String host, int port)` Deprecated. Retrieve a new instance of a `NavuCdbTwoPhaseSubscriber`.
`static NavuCdbSubscriber`	`twoPhaseSubscriber(String host, int port, String name)` Deprecated.

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

Methods inherited from interface com.tailf.navu.NavuCdbSubscriber
register, register, register, register, shutDownOnException, subscriberStart

- Method Detail
  - awaitRunning
```
public void awaitRunning()
                  throws InterruptedException
```
    Deprecated.
    
    Wait or Blocks the calling thread until this NavuSubscriber is running ( when isRunning() returns true).
    The subscriber is running when its ready for Incoming CDB subscription changes. This method is useful when needs to monitor the state of the subscriber.
    
    Specified by:
    
    awaitRunning in interface NavuCdbSubscriber
    
    Throws:
    
    InterrupedException - if the waiting process got interrupted
    
    InterruptedException
  - awaitStopped
```
public void awaitStopped()
                  throws InterruptedException
```
    Deprecated.
    
    Blocks until this subscriber have stopped. The subscriber is stopped when it is not running under its cleaning phase.
    
    Specified by:
    
    awaitStopped in interface NavuCdbSubscriber
    
    Throws:
    
    InterrupedException - if the waiting process got interrupted
    
    InterruptedException
  - configSubscriber
```
public static NavuCdbSubscriber configSubscriber(Cdb cdb)
                                          throws IOException,
                                                 ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbConfigSubscriber.
    
    Parameters:
    cdb - instance as the CdbSubscription socket
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException
    
    ConfException
  - configSubscriber
```
public static NavuCdbSubscriber configSubscriber(InetSocketAddress addr)
                                          throws IOException,
                                                 ConfException
```
    Deprecated.
    
    Throws:
    
    IOException
    
    ConfException
  - configSubscriber
```
public static NavuCdbSubscriber configSubscriber(String host,
                                 int port)
                                          throws IOException,
                                                 ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbConfigSubscriber.
    
    Parameters:
    host - to connect to
    port - to connect to
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException
    
    ConfException
  - configSubscriber
```
public static NavuCdbSubscriber configSubscriber(String host,
                                 int port,
                                 String name)
                                          throws IOException,
                                                 ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbConfigSubscriber.
    
    Parameters:
    host - to connect to
    port - to connect to
    name - A name to associate this subscriber to. When the subscriber will start in a thread the thread name will be named name.
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException
    
    ConfException
  - executor
```
public ExecutorService executor()
```
    Deprecated.
    
    Retrieve the underlying ExecutorService.
    
    Specified by:
    
    executor in interface NavuCdbSubscriber
    
    Returns:
    The ExecutorService for this subscriber
  - getIterationQueue
```
public NavuCdbSubscriptionIterQueue getIterationQueue()
```
    Deprecated.
    
    Retrieve a notification queue where additional thread can poll for summary information about a iteration and react appropriately.
    This is a convenient method used inside a implementation of a ApplicationComponent where the running thread could poll this queue to retrieve iteration summary of the last iteration.
    This method will return the same instance for a subscriber and should only be used by one thread at the time.
    
    Specified by:
    
    getIterationQueue in interface NavuCdbSubscriber
    
    Returns:
    iteration queue to poll for iteration summary
  - isRunning
```
public boolean isRunning()
```
    Deprecated.
    
    Description copied from interface: NavuCdbSubscriber
    
    Return true if this subscriber is running.
    
    Specified by:
    
    isRunning in interface NavuCdbSubscriber
    
    Returns:
    true/false whether this subscriber is running
  - isStopped
```
public boolean isStopped()
```
    Deprecated.
    
    Description copied from interface: NavuCdbSubscriber
    
    Return true if this subscriber is stopped.
    
    Specified by:
    
    isStopped in interface NavuCdbSubscriber
    
    Returns:
    true/false whether this subscriber is stopped
  - operSubscriber
```
public static NavuCdbSubscriber operSubscriber(Cdb cdb)
                                        throws IOException,
                                               ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbConfigSubscriber.
    
    Parameters:
    cdb - instance as the CdbSubscription socket
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException - if the operation encountered and I/O Error.
    
    ConfException
  - operSubscriber
```
public static NavuCdbSubscriber operSubscriber(InetSocketAddress addr)
                                        throws IOException,
                                               ConfException
```
    Deprecated.
    
    Throws:
    
    IOException
    
    ConfException
  - operSubscriber
```
public static NavuCdbSubscriber operSubscriber(InetSocketAddress addr,
                               String subName)
                                        throws IOException,
                                               ConfException
```
    Deprecated.
    
    Throws:
    
    IOException
    
    ConfException
  - operSubscriber
```
public static NavuCdbSubscriber operSubscriber(String host,
                               int port)
                                        throws IOException,
                                               ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbOperSubscriber.
    
    Parameters:
    host - to connect to
    port - to connect to
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException - if the operation encountered and I/O Error.
    
    ConfException
  - operSubscriber
```
public static NavuCdbSubscriber operSubscriber(String host,
                               int port,
                               String name)
                                        throws IOException,
                                               ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbConfigSubscriber.
    
    Parameters:
    host - to connect to
    port - to connect to
    name - A name to associate this subscriber to. When the subscriber will start in a thread the thread name will be named name.
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException - if the operation encountered and I/O Error.
    
    ConfException
  - registerStoppedHandler
```
public void registerStoppedHandler(NavuCdbStoppedHandler handler)
```
    Deprecated.
    
    Register a stop handler when the subscriber will be stopped.
    
    Specified by:
    
    registerStoppedHandler in interface NavuCdbSubscriber
    
    Parameters:
    handler - provided stop handler that will be invoked when this subscriber stops.
  - subscriberStop
```
public boolean subscriberStop()
```
    Deprecated.
    
    Sends a Stop signal to the underlying subscription process without shutting down the underlying ExecutorService. If the subscriber is already stopped this method always return false This makes it possible to restart the Subscriber with NavuCdbSubscriber.subscriberStart().
    
    Specified by:
    
    subscriberStop in interface NavuCdbSubscriber
    
    Returns:
    true if the sending of the stop signal was successful. and false if the process of waiting before subscription process was interrupted.
  - twoPhaseSubscriber
```
public static NavuCdbSubscriber twoPhaseSubscriber(String host,
                                   int port)
                                            throws IOException,
                                                   ConfException
```
    Deprecated.
    
    Retrieve a new instance of a NavuCdbTwoPhaseSubscriber.
    
    Parameters:
    host - to connect to
    port - to connect to
    
    Returns:
    A new instance of a config subscriber
    
    Throws:
    
    IOException - if the operation encountered and I/O Error.
    
    ConfException
  - twoPhaseSubscriber
```
public static NavuCdbSubscriber twoPhaseSubscriber(String host,
                                   int port,
                                   String name)
                                            throws IOException,
                                                   ConfException
```
    Deprecated.
    
    Throws:
    
    IOException
    
    ConfException

Class NavuCdbSubscribers

Method Summary

Methods inherited from class Object

Methods inherited from interface com.tailf.navu.NavuCdbSubscriber

Method Detail

awaitRunning

awaitStopped

configSubscriber

configSubscriber

configSubscriber

configSubscriber

executor

getIterationQueue

isRunning

isStopped

operSubscriber

operSubscriber

operSubscriber

operSubscriber

operSubscriber

registerStoppedHandler

subscriberStop

twoPhaseSubscriber

twoPhaseSubscriber