Package com.tailf.notif

Class Notif

Object
com.tailf.notif.Notif
public class Notif extends Object
This class implements the Notifications API in Java.

Applications can subscribe to certain events generated by the system. The API to receive events from the system is a socket based API whereby the application connects to ConfD/NCS and receives events on a socket. There are several types of events that can be subscribed to:

  • NotificationType.NOTIF_AUDIT - all audit log events are sent from ConfD/NCS on the event notification socket.
  • NotificationType.NOTIF_COMMIT_DIFF - an event indicating that a user has somehow modified the configuration. The main difference between this event and the above mentioned NOTIF_COMMIT_SIMPLE is that this event is synchronous, i.e. the entire transaction hangs until we have explicitly called diffNotificationDone(int). The purpose of this event is to give the applications a chance to read the configuration diffs from the transaction before it commits. A user subscribing to this event can use the MAAPI api to attach (Maapi.attach())to the running transaction and use Maapi.diffIterate() to iterate through the diff.
  • NotificationType.NOTIF_COMMIT_FAILED - This event is generated when a data provider fails in its commit callback. ConfD executes a two-phase commit procedure towards all data providers when committing transactions. When a provider fails in commit, the system is an unknown state. If the provider is "external", the name of failing daemon is provided. If the provider is another NETCONF agent, the IP address and port of that agent is provided.
  • NotificationType.NOTIF_COMMIT_SIMPLE - an event indicating that a user has somehow modified the configuration.
  • NotificationType.NOTIF_COMMIT_PROGRESS - This event provides progress information about the commit of a transaction.
  • NotificationType.NOTIF_PROGRESS - This event provides progress information about the commit of a transaction or an action being applied. Subscribing to this notification type means that all notifications of the type NotificationType.NOTIF_COMMIT_PROGRESS are subscribed to as well.
  • NotificationType.NOTIF_CONFIRMED_COMMIT - This event is generated when a user has started a confirmed commit, when a confirming commit is issued, or when a confirmed commit is aborted; represented by ConfirmNotification.confirm_type.

    For a confirmed commit, the timeout value is also present in the notification.

  • NotificationType.NOTIF_FORWARD_INFO - This event is generated whenever whenever the server forwards (proxies) a northbound agent.
  • NotificationType.NOTIF_HA_INFO - an event related to ConfDs perception of the current cluster configuration.
  • NotificationType.NOTIF_HEARTBEAT - This event can be be used by applications that wish to monitor the health and liveness of the server itself. It needs to be requested through a Notif instance which has been constructed with a heartbeat_interval. The server will continuously generate heartbeat events on the notification socket. If the server fails to do so, the server is hung. The timeout interval is measured in milliseconds. Recommended value is 10000 milliseconds to cater for truly high load situations. Values less than 1000 are changed to 1000.
  • NotificationType.NOTIF_SNMPA - This event is generated whenever an SNMP pdu is processed by the server. The application receives an SnmpaNotification with a list of all varbinds in the pdu. Each varbind contains subclasses that are internal to the SnmpaNotification.
  • NotificationType.NOTIF_SUBAGENT_INFO - only sent if ConfD runs as a primary agent with subagents enabled. This event is sent when the subagent connection is lost or reestablished. There are two event types, defined in SubagentNotification: subagent up and subagent down.
  • NotificationType.NOTIF_DAEMON - all log events that also goes to the /confdConf/logs/confdLog log are sent from ConfD on the event notification socket.
  • NotificationType.NOTIF_NETCONF - all log events that also goes to the /confdConf/logs/netconfLog log are sent from ConfD on the event notification socket.
  • NotificationType.NOTIF_DEVEL - all log events that also goes to the /confdConf/logs/develLog log are sent from ConfD on the event notification socket.
  • NotificationType.NOTIF_JSONRPC - all log events that also goes to the /confdConf/logs/jsonrpcLog log are sent from ConfD on the event notification socket.
  • NotificationType.NOTIF_WEBUI - all log events that also goes to the /confdConf/logs/webuiAccessLog log are sent from ConfD on the event notification socket.
  • NotificationType.NOTIF_TAKEOVER_SYSLOG - If this flag is present, ConfD will stop syslogging. The idea behind the flag is that we want to configure syslogging for ConfD in order to let ConfD log its startup sequence. Once ConfD is started we wish to subsume the syslogging done by ConfD. Typical applications that use this flag want to pick up all log messages, reformat them and use some local logging method. Once all subscriber sockets with this flag set are closed, ConfD will resume to syslog.
  • NotificationType.NOTIF_UPGRADE_EVENT - This event is generated for the different phases of an in-service upgrade, i.e. when the data model is upgraded while the server is running. The application receives an UpgradeNotification where the UpgradeNotification.event_type gives the specific upgrade event. The events correspond to the invocation of the Maapi functions that drive the upgrade.
  • NotificationType.NOTIF_COMPACTION - This event is generated when a CDB compaction has completed.
  • NotificationType.NOTIF_USER_SESSION - an event related to user sessions. There are 6 different user session related event types, defined in UserSessNotification: session starts/stops, session locks/unlocks database, session starts/stop database transaction.
  • NotificationType.NOTIF_PACKAGE_RELOAD - an event indicating that NCS has completed a package reload.
  • NotificationType.NOTIF_CQ_PROGRESS - an event reporting the progress of commit queue entries.
  • NotificationType.NOTIF_REOPEN_LOGS - an event indicating that ConfD/NCS will close and reopen its log files.
  • NotificationType.NOTIF_CALL_HOME_INFO - an event reporting call home connections.
  • NotificationType.NOTIF_AUDIT_NETWORK - an event reporting config changes sent southbound towards devices.

Example: 

      // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS
      // create new notifications socket
      Socket notif_sock = new Socket("127.0.0.1", port);
      // init and connect the notification socket
      final Notif notif =
          new Notif(notif_sock,
                    EnumSet.of(NotificationType.NOTIF_AUDIT,
                               NotificationType.NOTIF_USER_SESSION));

       // read input from the notification socket
      Thread notifThread = new Thread(new Runnable() {
          public void run() {
              try {
                  while (true) notif.read();
              } catch (Exception e) {
                    e.printStackTrace();
                    return;
              }
          }
      });
      notifThread.start();
See Also:

  • Constructor Details

    • Notif

      public Notif(Socket socket, EnumSet<NotificationType> eventTypes, NotificationCfg cfg) throws ConfException, IOException
      Creates a notification instance. The events will be read from the provided socket. The the configurated notifications are passed as an EnumSet<NotificationType> This constructor expects a NotificationCfg argument which is used to set extra configuration data necessary for notifications of type Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      socket - A socket connected to ConfD.
      eventTypes - EnumSet of NotificationType
      cfg - event configuration data
      Throws:
      NotifException - Failed to initialize notification instance.
      IOException - Failed to read from notifications socket
      ConfException
      See Also:

    • Notif

      public Notif(Socket socket, EnumSet<NotificationType> eventTypes, int heartbeatInterval, int healthCheckInterval) throws ConfException, IOException
      Same functionality as for Notif(socket, eventTypes, cfg) except that only heartbeat and healtcheck notifications are expected to require to be configured. Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      socket - A socket connected to ConfD.
      eventTypes - EnumSet of NotificationType
      heartbeatInterval - interval in seconds (<= 0 if not active)
      healthCheckInterval - interval in seconds (<= 0 if not active)
      Throws:
      NotifException - Failed to initialize notification instance.
      IOException - Failed to read from notifications socket
      ConfException
      See Also:

    • Notif

      public Notif(Socket socket, EnumSet<NotificationType> eventTypes, int heartbeatInterval) throws ConfException, IOException
      Same functionality as for Notif(socket, eventTypes, cfg) except that only heartbeat notifications are expected to require to be configured Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      socket - notification socket
      eventTypes - set of all subscribed notification types
      heartbeatInterval - interval in seconds (<= 0 if not active)
      Throws:
      ConfException
      IOException

    • Notif

      public Notif(Socket socket, EnumSet<NotificationType> eventTypes) throws ConfException, IOException
      Same functionality as for Notif(socket, eventTypes, cfg) except that no extra configuration is expected to be set in eventTypes. Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      socket - notification socket
      eventTypes - set of all subscribed notification types
      Throws:
      ConfException
      IOException

  • Method Details