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 NavuEventHandler.registerInterfaceCallback(String,String,NavuEventCallback) method. Optionally a plain java pojo could be annotated with the annotation EventCallback and registered the annotated instance with NavuEventHandler.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 Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
NavuEventHandler(InetSocketAddress addr, String notifSubscriberName) Create an instance of the NavuEventHandler with a InetSocketAddress to NCS host and IPC port.
NavuEventHandler(Socket socket, String notifSubscriberName) Deprecated.
NavuEventHandler(String host, int port, String notifSubscriberName) Create an instance of the NavuEventHandler with a specified host and port.

Method Summary

Modifier and Type	Method and Description
void	awaitRunning() Deprecated.
void	awaitStoped() Deprecated.
void	awaitStopped()
boolean	isRunning()
boolean	isStarted() Deprecated. Use isRunning() Check whether the subscriber thread of the NavuEventHandler is stated.
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 Object

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

Field Detail

NOTIFICATION_PATH

public static final String NOTIFICATION_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:

Constant Field Values

NOTIFICATION_EVENT_PATH

public static final String NOTIFICATION_EVENT_PATH

See Also:

Constant Field Values

Constructor Detail

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 Detail

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  

 or if all notification should be retrieved

 $java com.tailf.ncs.NavuEventHandler "\*" "\*"
 

Parameters:

args -

run

public void run()

Specified by:

run in interface Runnable