Package com.tailf.dp

Class DpNotifStream

Object
Thread
com.tailf.dp.DpNotifStream
All Implemented Interfaces:
Runnable

public class DpNotifStream extends Thread
The application can generate notifications that are sent via the northbound protocols. Currently NETCONF notification streams are supported. The application generates the content for each notification and sends it via a socket to ConfD/NCS, which in turn manages the stream subscriptions and distributes the notifications accordingly.

A stream always has a "live feed", which is the sequence of new notifications, sent in real time as they are generated. Subscribers may also request "replay" of older, logged notifications if the stream supports this, perhaps transition to the live feed when the end of the log is reached. There may be one or more replays active simultaneously with the live feed. ConfD/NCS forwards replay requests from subscribers to the application via callbacks if the stream supports replay.

Each notification has an associated time stamp, the "event time". This is the time when the event that generated the notification occurred, rather than the time the notification is logged or sent, in case these times differ. The application must pass the event time to ConfD/NCS when sending a notification, and it is also needed when replaying logged events.

This class implements the Notification streams. The purpose of this class to provide a mechanism for sending notifications.

Example: Consider the following yang model of a notification:

  module mynotif {
    namespace "http://tail-f.com/test/mynotif/1.0";
    prefix myn;

    import ietf-yang-types {
      prefix yang;
    }

    notification my_notif {
      leaf arg1 {
        type string;
      }
      leaf arg2 {
        type int64;
      }
    }
  }
 
For a netconf notification stream to be valid it must be defined in the ConfD/NCS config file. For NCS this example needs the following definitions in the config (there are small differences in the tagnames for ConfD)
   <notifications>
     <event-streams>
       <stream>
         <name>mystream</name>
         <description>my test stream</description>
         <replay-support>false</replay-support>
       </stream>
     </event-streams>
   </notifications>
 
If we want to sent a NETCONF notification based on the above model we can do the following:
  // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS
  // create new control socket
  Socket ctrlSocket = new Socket("127.0.0.1", port);
  // This is the main Data Provider instance. "dp"
  Dp dp = new Dp("hosts_daemon", ctrlSocket);
  mynotif myn = new mynotif();
  // create Dp Notification stream (you may create many)
  DpNotifStream stream = dp.createNotifStream("mystream");
  // send a notification
  ConfXMLParam[] vals =
      new ConfXMLParam[] {
          new ConfXMLParamStart(myn.hash(), mynotif.myn_my_notif),
          new ConfXMLParamValue(myn.hash(), mynotif.myn_arg1,
                                new ConfBuf("Hello")),
          new ConfXMLParamValue(myn.hash(), mynotif.myn_arg2,
                                new ConfInt64(32)),
          new ConfXMLParamStop(myn.hash(), mynotif.myn_my_notif)
      };
  stream.send(ConfDatetime.getConfDatetime(), vals);
 
  • Method Details

    • getDp

      public Dp getDp()
      The Data Provider main class. provided when registering with a Dp.
    • getSocket

      public Socket getSocket()
      The worker socket which is connected to ConfD/NCS. This socket will be used for sending notifications to ConfD/NCS. Set when allocated by Dp.
    • setSocket

      public void setSocket(Socket socket)
    • getFD

      public int getFD()
      file descriptor
    • setFD

      public void setFD(int fd)
      file descriptor
    • getQRef

      public int getQRef()
      last qref
    • setQRef

      public void setQRef(int qref)
      last qref
    • getSubId

      public int getSubId()
      last subid. subid>0 is a replay
    • setSubId

      public void setSubId(int subid)
      last subid. subid>0 is a replay
    • getReplayCb

      public DpNotifReplayCallback getReplayCb()
      The replay callback
    • getStreamName

      public String getStreamName()
    • send

      public void send(ConfDatetime time, ConfXMLParam params) throws IOException, ConfException
      Send a notification defined at the top level of a YANG module on this notification stream to ConfD/NCS.
      Parameters:
      time - ConfDatetime event time for the notification
      params - ConfXMLParam structure of data
      Throws:
      IOException
      ConfException
    • send

      public void send(ConfDatetime time, ConfXMLParam[] params) throws IOException, ConfException
      Send a notification defined at the top level of a YANG module on this notification stream to ConfD/NCS.
      Parameters:
      time - ConfDatetime event time for the notification
      params - ConfXMLParam structure of data
      Throws:
      IOException
      ConfException
    • send

      public void send(ConfDatetime time, ConfXMLParam[] params, String fmt, Object... arguments) throws IOException, ConfException
      Send a notification defined as a child of a container or list in a YANG 1.1 module on this notification stream to ConfD/NCS.
      Parameters:
      time - ConfDatetime event time for the notification
      params - ConfXMLParam structure of data
      fmt - path string the fully instantiated path for the container or list entry that is the parent of the notification in the data tree
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException
    • send

      public void send(ConfDatetime time, ConfXMLParam[] params, ConfPath path) throws IOException, ConfException
      Send a notification defined as a child of a container or list in a YANG 1.1 module on this notification stream to ConfD/NCS.
      Parameters:
      time - ConfDatetime event time for the notification
      params - ConfXMLParam structure of data
      path - ConfPath the fully instantiated path for the container or list entry that is the parent of the notification in the data tree
      Throws:
      IOException
      ConfException
    • flush

      public void flush() throws IOException, ConfException
      Notifications are sent asynchronously, i.e. normally without blocking the caller of the send functions described above. This means that in some cases, the servers sending of the notifications on the northbound interfaces may lag behind the send calls. If we want to make sure that the notifications have actually been sent out, e.g. in some shutdown procedure, we can call DpNotifStream.flush(). This function will block until all notifications sent using the given notification stream have been fully processed by the server. It can be used both for notification streams and for SNMP notifications (however it will not wait for replies to SNMP inform-requests to arrive).
      Throws:
      IOException
      ConfException