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}. /ncs:devices/device{device-name}/netconf-notifications /received-notifications/notification{event-time sequence-no}.

  • Field Details

  • Constructor Details

    • NavuEventHandler

      @Deprecated public NavuEventHandler(Socket socket, String notifSubscriberName) throws IOException, ConfException
      Deprecated.
      Create an instance of the NavuEventHandler with specified socket connected to NCS IPC port. This method only reads the socket instance for the host and port and should be avoided.
      Parameters:
      socket - The connected socket to NCS IPC port.
      Throws:
      IOException
      ConfException

    • NavuEventHandler

      public NavuEventHandler(InetSocketAddress addr, String notifSubscriberName) throws IOException, ConfException
      Create an instance of the NavuEventHandler with a InetSocketAddress to NCS host and IPC port.
      Parameters:
      addr - The InetSocketAddress to NCS host and IPC port
      Throws:
      IOException
      ConfException

    • NavuEventHandler

      public NavuEventHandler(String host, int port, String notifSubscriberName) throws IOException, ConfException
      Create an instance of the NavuEventHandler with a specified host and port.
      Parameters:
      host - The host to NCS
      port - The port to IPC port on host
      Throws:
      IOException
      ConfException

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

    • isStarted

      @Deprecated public boolean isStarted()
      Deprecated.
      Use isRunning() Check whether the subscriber thread of the NavuEventHandler is stated.
      Returns:
      boolean

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

    • awaitRunning

      @Deprecated public void awaitRunning() throws InterruptedException
      Deprecated.
      Throws:
      InterruptedException

    • awaitStoped

      @Deprecated public void awaitStoped() throws InterruptedException
      Deprecated.
      Throws:
      InterruptedException

    • 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