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 Notif.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 master 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_info_type: 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_USER_SESSION - an event related to user sessions. There are 6 different user session related event types, defined in UserSessNotification.user_sess_type: 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:

AuditNotification, CommitDiffNotification, CommitFailedNotification, CommitNotification, CommitProgressNotification, ProgressNotification, ConfirmNotification, ForwardNotification, HaNotification, HeartbeatNotification, SnmpaNotification, SubagentNotification, SyslogNotification, UpgradeNotification, UserSessNotification, HealtCheckNotification, PackageReloadNotification, CommitQueueProgressNotification, ReopenLogsNotification, CallHomeInfoNotification

Constructor Summary

Constructors

Constructor and Description
Notif(Socket socket, EnumSet<NotificationType> eventTypes) Same functionality as for Notif(socket, eventTypes, cfg) except that no extra configuration is expected to be set in eventTypes.
Notif(Socket socket, EnumSet<NotificationType> eventTypes, int heartbeatInterval) 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.
Notif(Socket socket, EnumSet<NotificationType> eventTypes, int heartbeatInterval, int healthCheckInterval) Same functionality as for Notif(socket, eventTypes, cfg) except that only heartbeat and healtcheck notifications are expected to require to be configured.
Notif(Socket socket, EnumSet<NotificationType> eventTypes, NotificationCfg cfg) Creates a notification instance.

Method Summary

Modifier and Type	Method and Description
void	diffNotificationDone(int thandle) If the received event from Notif.read() was a CommitDiffNotification it is important that we call this function when we are done reading the transaction diffs over MAAPI.
Notification	read() Read in the data.
void	syncAuditNetworkNotification(int usid) If the received event from Notif.read() was a AuditNetworkNotification which was subscribed using the notification type NotificationType.NOTIF_AUDIT_NETWORK in combination with NotificationType.NOTIF_AUDIT_NETWORK_SYNC it is important that we call this function or else the user session will hang indefinitely.
void	syncAuditNotification(int usid) If the received event from Notif.read() was a AuditNotification which was subscribed using the notification type NotificationType.NOTIF_AUDIT in combination with NotificationType.NOTIF_AUDIT_SYNC it is important that we call this function or else the user session will hang indefinitely.
void	syncHaNotification() If the received event from Notif.read() was a HaNotification which was subscribed using the notification type NotificationType.NOTIF_HA_INFO in combination with NotificationType.NOTIF_HA_INFO_SYNC it is important that we call this function or else the user session will hang indefinitely.

Methods inherited from class Object

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

Constructor Detail

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 This constructor expects a NotificationCfg argument which is used to set extra configuration data necessary for notifications of type

• NotificationType.NOTIF_HEALTH_CHECK
• NotificationType.NOTIF_HEARTBEAT
• NotificationType.NOTIF_STREAM_EVENT
• NotificationType.NOTIF_COMMIT_PROGRESS
• NotificationType.NOTIF_PROGRESS

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.read()

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.read()

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 Detail

read

public Notification read()
                  throws ConfException,
                         IOException

Read in the data. The application is responsible for reading the notification socket. The method read() will return a Notification of the following types:

• AuditNotification
• CommitDiffNotification
• CommitFailedNotification
• CommitNotification
• CommitProgressNotification
• ProgressNotification
• ConfirmNotification
• ForwardNotification
• HaNotification
• HeartbeatNotification
• SnmpaNotification
• SubagentNotification
• SyslogNotification
• UpgradeNotification
• UserSessNotification
• HealtCheckNotification
• PackageReloadNotification
• CommitQueueProgressNotification
• ReopenLogsNotification
• CallHomeInfoNotification

Throws:

NotifException - Failed to read notification.

IOException - Failed to read from notification socket

ConfException

diffNotificationDone

public void diffNotificationDone(int thandle)
                          throws IOException

If the received event from Notif.read() was a CommitDiffNotification it is important that we call this function when we are done reading the transaction diffs over MAAPI. The transaction is hanging until this function gets called.

Parameters:

thandle - The transaction handle. (given in the notification)

Throws:

IOException - Failed to write to the notification socket.

syncAuditNotification

public void syncAuditNotification(int usid)
                           throws IOException

If the received event from Notif.read() was a AuditNotification which was subscribed using the notification type NotificationType.NOTIF_AUDIT in combination with NotificationType.NOTIF_AUDIT_SYNC it is important that we call this function or else the user session will hang indefinitely.

Parameters:

usid - The user id. (given in the notification)

Throws:

IOException - Failed to write to the notification socket.

syncHaNotification

public void syncHaNotification()
                        throws IOException

If the received event from Notif.read() was a HaNotification which was subscribed using the notification type NotificationType.NOTIF_HA_INFO in combination with NotificationType.NOTIF_HA_INFO_SYNC it is important that we call this function or else the user session will hang indefinitely.

Throws:

IOException

syncAuditNetworkNotification

public void syncAuditNetworkNotification(int usid)
                                  throws IOException

If the received event from Notif.read() was a AuditNetworkNotification which was subscribed using the notification type NotificationType.NOTIF_AUDIT_NETWORK in combination with NotificationType.NOTIF_AUDIT_NETWORK_SYNC it is important that we call this function or else the user session will hang indefinitely.

Parameters:

usid - The user id. (given in the notification)

Throws:

IOException - Failed to write to the notification socket.