com.ibm.datapower.wamt.amp
Class Notification

java.lang.Object
  extended by com.ibm.datapower.wamt.amp.Notification

public class Notification
extends java.lang.Object

A POJO representation of an event from a DataPower device.

The Manager should be notified when the following events occur on a subscribed device:

For an exact list of events that are included in an AMP subscription, please refer to the list in the DataPower firmware source file dp_src/datapower/webgui/Support/ampSubscriptions.xml.

When these events occur, the Manager may need to take action, such as deploying the changed Domain/Settings to the rest of the devices in the ManagedSet, update the op-state of a Domain, etc.

The NotificationCatcher reads these events from the device, and enqueues them to the Manager for further action. Refer to the NotificationCatcher javadoc for how the events are sent by the device. The events will be sent from the device to the subscriber using CBE (Common Base Event) format. The NotificationCatcher handles the transport of the event, and the Notification handles the data of the event.

Note that for a Save Config action, notification is not expected when a running (non-persisted) service configuration object is changed, only when the administrator invokes Save Config or if one of the other conditions in the bulleted list occurs.

All the values returned from the gettr methods will be extracted from CBE fields.

One of the values in the Notification is a sequence number. The sequence number should be a monotomically increasing integer which indicates the sequence of the events. This sequence number is used to verify that events are processed in order and that any missing events are detected. The sequence number is on a per log target basis, which means that the sequence number will be reset (to "0") when a new target is created on the device. When the device creates the events, the sequence number should be in order. However, the events are transmitted from the device asynchronously: there is a linear event buffer in which events are enqueued but they may get transmitted slightly out-of-sequence within a small time window. Whoever reads the Notifications needs to handle out-of-sequence Notifications. If the device's event buffer overflows (which is highly unlikely) then the next serial number will be last serial number plus number of events dropped. So you can have the following seqeunces:

0 1 2 3 4 ... n
(normal case)
n (n+1) ... 0 1 2 3
(normal roll over or target has been modified)
n (n+1) (n+m) (n+m+1)
(m events got lost because the buffer was full)

See Also:
NotificationCatcher, NotificationCatcherFactory, Commands

Field Summary
static java.lang.String COPYRIGHT_2009_2010
           
 
Constructor Summary
Notification(java.io.BufferedReader rawReader)
          Constructor for a new Notification object.
Notification(java.lang.String deviceSerialNumber, int sequenceNumber, java.lang.String objectClass, java.lang.String objectName, java.lang.String timestamp, java.lang.String clientIpaddress, java.lang.String msgId)
          Deprecated. This should be used only for internal debugging and testcases. It should not be invoked by production code.
 
Method Summary
 java.lang.String getClientIPAddress()
          Get the IP address of the administrative client that made the change on the device that triggered this notification.
 java.lang.String getDeviceSerialNumber()
          Get the serialNumber of the device that triggered the notification.
 java.lang.String getObjectClass()
          Get the class of the configuration object on the device that triggered the notification.
 java.lang.String getObjectName()
          Get the instance name of the configuration on the device that triggered the notification.
 int getSequenceNumber()
          Get the CBE sequence number for this subscription.
 java.lang.String getTimestamp()
          Get the device's timestamp of when the notification was triggered on the device.
 boolean isBootScheduled()
          Check if the notification was triggered by an impending reboot or device restart.
 boolean isFirmwareChange()
          Check if the notification was triggered by a firmware change.
 boolean isModifiedConfigOfDomain()
          Check if the notification was triggered by a domain modification on the device that persists the domain.
 boolean isModifiedConfigOfSettings()
          Check if the notification was triggered by a modification of device that persisted the clonable device-specific settings.
 boolean isOpStateChangeDown()
          Check if the notification was triggered by a change in an op-state of a domain that made it down now.
 boolean isOpStateChangeUp()
          Check if the notification was triggered by a change in an op-state of a domain that made it up now.
 boolean isSaveConfigOfDomain()
          Check if the notification was triggered by a "Save Config" action on the device that persists the domain.
 boolean isSaveConfigOfSettings()
          Check if the notification was triggered by a "Save Config" action on the device that persisted the clonable device-specific settings.
 boolean isTest()
           
 java.lang.String toString()
          Get a human-readable String representation of this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COPYRIGHT_2009_2010

public static final java.lang.String COPYRIGHT_2009_2010
See Also:
Constant Field Values
Constructor Detail

Notification

public Notification(java.io.BufferedReader rawReader)
Constructor for a new Notification object. This will also parse the raw SOAP message into the individual class members that have gettr methods. It is assumed that the NotificationCatcher already verified that the device's SSL certificate used for the HTTPS transport is signed by a trusted certificate authority before invoking this constructor. This construction should be invoked by the NotificationCatcher.

Parameters:
rawReader - the the BufferedReader that holds the contents of the SOAP message that was received by the NotificationCatcher

Notification

public Notification(java.lang.String deviceSerialNumber,
                    int sequenceNumber,
                    java.lang.String objectClass,
                    java.lang.String objectName,
                    java.lang.String timestamp,
                    java.lang.String clientIpaddress,
                    java.lang.String msgId)
Deprecated. This should be used only for internal debugging and testcases. It should not be invoked by production code.

Al alternate constructor for bypassing the NotificationCatcher. This should be used only for internal debugging and testcases.

Parameters:
deviceSerialNumber - hardware serial number of the device
sequenceNumber - the CBE sequence number for this subscription
objectClass - the name of the device's configuration class of the object that triggered the notification
objectName - the instance name of the device's configuration object that triggered the notification
timestamp - the timestamp of when the notification was triggered on the device
clientIpaddress - IP address of the administrative client that made the change.
msgId - the AMP event type, which drives the results of the is* methods. See the private member msgConstants
Method Detail

getDeviceSerialNumber

public java.lang.String getDeviceSerialNumber()
Get the serialNumber of the device that triggered the notification.

Returns:
the serialNumber of the device that triggered the notification. This serialNumber should match the return value of DeviceMetaInfo.getSerialNumber(), after it has been retrieved via Commands.getDeviceMetaInfo(DeviceContext).

getSequenceNumber

public int getSequenceNumber()
Get the CBE sequence number for this subscription.

Returns:
the CBE sequence number for this subscription. This is a monotomically increasing integer. A gap in this number from previous notifications indicates lost notifications from the device, or reception of notifications in a different order than they were sent from the device. The sequence number will reset to zero upon a device reboot. Also, a subscription state that is in error or has been lost indicates lost notifications from the device.

isSaveConfigOfDomain

public boolean isSaveConfigOfDomain()
Check if the notification was triggered by a "Save Config" action on the device that persists the domain.

Returns:
true if the notification was triggered by a "Save Config" action that affected a domain, false otherwise.

isModifiedConfigOfDomain

public boolean isModifiedConfigOfDomain()
Check if the notification was triggered by a domain modification on the device that persists the domain.

Returns:
true if the notification was triggered by a domain modification that affected a domain, false otherwise.

isSaveConfigOfSettings

public boolean isSaveConfigOfSettings()
Check if the notification was triggered by a "Save Config" action on the device that persisted the clonable device-specific settings.

Returns:
true if the notification was triggered by a "Save Config" action that affected the settings, false otherwise.

isModifiedConfigOfSettings

public boolean isModifiedConfigOfSettings()
Check if the notification was triggered by a modification of device that persisted the clonable device-specific settings.

Returns:
true if the notification was triggered by a modification that affected the settings, false otherwise.

isOpStateChangeUp

public boolean isOpStateChangeUp()
Check if the notification was triggered by a change in an op-state of a domain that made it up now.

Returns:
true if the notification was triggered by a domain op-state change that made it up, false otherwise.

isOpStateChangeDown

public boolean isOpStateChangeDown()
Check if the notification was triggered by a change in an op-state of a domain that made it down now.

Returns:
true if the notification was triggered by a domain op-state change that made it down, false otherwise.

isBootScheduled

public boolean isBootScheduled()
Check if the notification was triggered by an impending reboot or device restart.

Returns:
true if the notification was triggered by an impending reboot or device restart.

isFirmwareChange

public boolean isFirmwareChange()
Check if the notification was triggered by a firmware change.

Returns:
true if the notification was triggered by a firmware change.

isTest

public boolean isTest()

getObjectClass

public java.lang.String getObjectClass()
Get the class of the configuration object on the device that triggered the notification.

Returns:
the name of the device's configuration class of the object that triggered the notification.

getObjectName

public java.lang.String getObjectName()
Get the instance name of the configuration on the device that triggered the notification.

Returns:
the instance name of the device's configuration object that triggered the notification.

getTimestamp

public java.lang.String getTimestamp()
Get the device's timestamp of when the notification was triggered on the device.

Returns:
the timestamp of when the notification was triggered on the device. This is the device's timestamp, not the subscriber's timestamp.

getClientIPAddress

public java.lang.String getClientIPAddress()
Get the IP address of the administrative client that made the change on the device that triggered this notification.

Returns:
IP address of the administrative client that made the change. If the administrator was using the WebGUI, this would be the browser's IP address. If the administrator was using the CLI, this would be the ssh/telnet client IP address, or serial port number if locally attached. If the administrator was using SOMA or AMP, this would be the web service client IP address.

toString

public java.lang.String toString()
Get a human-readable String representation of this object.

Overrides:
toString in class java.lang.Object
Returns:
a human-readable String representation of this object


© Copyright IBM Corp. 2006, 2010 All Rights Reserved.