Package com.tailf.ncs

Class NavuEventHandler

Object
com.tailf.ncs.NavuEventHandler
All Implemented Interfaces:
Runnable
public class NavuEventHandler extends Object implements Runnable

This class represents the a running daemon where it provides the means for user callback to react on NCS CDB notification that arrives asynchronously from a device.

The NCS device manager has built-in support for device notifications. Notifications are a means for the managed devices to send structured data asynchronously to the manager. NCS has native support for NETCONF event notifications (see RFC 5277) but can also receive notifications from other protocols implemented by the Network Element Drivers.

The basic mode of operation is that the manager subscribes to one or more named notification channels that are announced by the managed device. A user needs to setup a subscription to a named notification channel announced by the managed device. This is done for example with the CLI: 

  > configure
  %> set device device "device-name" notifications subscription \
     "if" stream "interface"
Where "if" is the unique name of a subscription and the interface is the announced stream name by the managed device.

When the managed device sends notifications northbound the notifications arrives at the path: /ncs:devices/device{device-name}/notifications /received-notifications/notification{event-time sequence-no} where the device-name is the managed device that sent the notification and event-time the time when the specific notification was generated at the device.

A NavuEventHandler make use of a CdbSubscriber which subscribe to the notification table at
/ncs:devices/device/notifications/received-notifications /notification.

To be able to react on the received notifications we need to start a instance of NavuEventHandler after a user has registered the reacting callback. 

 NavuEventHandler neh = new NavuEventHandler(s);

 MyEventCB mycb = new MyEventCB();
 neh.registerInterfaceCallback(deviceName, subscriptionName,
  new NavuEventCallback () {
         public void notifReceieved ( NavuContainer event )
                     throws NcsException {
                ..
           }

     });


   neh.start();
A user provided implementation of a NavuEventCallback is registered with the registerInterfaceCallback(String,String,NavuEventCallback) method. Optionally a plain java pojo could be annotated with the annotation EventCallback and registered the annotated instance with registerAnnotatedCallbacks(Object).

When registering a reacting callback user needs to provide the device name and the stream name in either the explicitly registerInterfaceCallback method or through the annotated java pojo. If the callback needs to received notifications from all the device and to all the streams annotated an asterisk could be supplied ( or annotated ) as the parameter to the registered methods.

As soon as the notifications arrives the user implementation of the NavuEventCallback NavuEventCallback.notifReceived(NavuContainer) is invoked by the NavuEventHandler for the device and stream the callback is interested in.

The NavuContainer represents the list entries:
/ncs:devices/device{device-name}/notifications /received-notifications/notification{event-time sequence-no}.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    NOTIFICATION_EVENT_PATH
    This path has been deprecated in the YANG model.

  • Constructor Summary

    Constructors
    Constructor
    Description
    NavuEventHandler(String host, int port, String notifSubscriberName)
    Deprecated.
    NavuEventHandler(SocketAddress address, String notifSubscriberName)
    Create an instance of the NavuEventHandler with a SocketAddress with the address to NCS

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    awaitStopped()
     
    boolean
    isRunning()
     
    boolean
    isStopped()
     
    static void
    main(String[] args)
    The main method of the NavuEventHandler is a notification probe that makes it possible to retrieve any notification without programming By running the NavuEventHandler and submitting deviceName and subscription name the notifications will then be written on standard output.
    void
    registerAnnotatedCallbacks(Object obj)
    Method to register pojo classes as notification callbacks.
    void
    registerInterfaceCallback(String deviceName, String subscriptionName, NavuEventCallback callback)
    Method to register classes that implements the NavuEventHandler interface.
    void
    run()
     
    void
    start()
    Starts this NavuEventHandler to receive notifications.
    void
    stop()
    Stop the underlying subscriber that this NavuEventHandler is using.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • NOTIFICATION_EVENT_PATH

      public static final String NOTIFICATION_EVENT_PATH
      This path has been deprecated in the YANG model. Once this part of the model has been removed this variable will point to the same path as in NOTIFICATION_EVENT_PATH.
      See Also:

  • Constructor Details

  • Method Details

    • start

      public void start()
      Starts this NavuEventHandler to receive notifications.

      After the registration of user provided callbacks has been done this method must be called to be able for this NavuEventhandler to receive notifications when it arrives to NCS CDB.

      This method will start the underlying CdbSubscriber asynchronously, if the underlying subscriber is not has already started.

    • stop

      public void stop()
      Stop the underlying subscriber that this NavuEventHandler is using.

      This call will end retrieval of notifications, stopping the underlying CdbSubscriber. A restart of this NavuEventHandler is not possible as long as the underlying CdbSubscriber is not shut down.

      When using a NavuEventHandler in a ApplicationComponent where a finish call by the Finish-Thread is issued it is important to release or kill all the threads that the ApplicationComponent has started thus a stop call must followed by a shutdown on the underlying ExectuorService.

    • awaitStopped

      public void awaitStopped() throws InterruptedException
      Throws:
      InterruptedException

    • isRunning

      public boolean isRunning()

    • isStopped

      public boolean isStopped()

    • registerAnnotatedCallbacks

      public void registerAnnotatedCallbacks(Object obj) throws NcsException
      Method to register pojo classes as notification callbacks. This method expects the callback method in the pojo class to be annotated using the EventCallback annotation. Example : 
       public class myclass {
 ...
    @EventCallback(deviceName="xyz", subscriptionName="sub1",
 callType=EventCBType.NOTIF_RECEIVED)
    public void myNotifReceived(NavuContainer event) throws NcsException {
    ...
    }
 }
      This technique makes it possible to use any pojo as callback object. Note, however that invocation of the callback method is performed using reflection
      Parameters:
      obj - The annotated user provided object.
      Throws:
      NcsException

    • registerInterfaceCallback

      public void registerInterfaceCallback(String deviceName, String subscriptionName, NavuEventCallback callback)
      Method to register classes that implements the NavuEventHandler interface. This register method requires the deviceName and subscriptionName of the triggering notification to be given by the call - NOT as annotations. if the register callback method has annotations these will be disregarded.
      Parameters:
      deviceName - The interest device name to received notifications from.
      subscriptionName - The announced stream name from the device.
      callback - User provided implementation of the NavuEventCallback.

    • main

      public static void main(String[] args)
      The main method of the NavuEventHandler is a notification probe that makes it possible to retrieve any notification without programming By running the NavuEventHandler and submitting deviceName and subscription name the notifications will then be written on standard output. Example (with wildcard for deviceName and subscriptionName): 
      
 $java com.tailf.ncs.NavuEventHandler <DeviceName> <SubscriptionName>

 or if all notification should be retrieved

 $java com.tailf.ncs.NavuEventHandler "\*" "\*"
      Parameters:
      args -

    • run

      public void run()
      Specified by:
      run in interface Runnable