Access Keys:
Skip to content (Access Key - 0)









How Do I Use Stateful Alarms in SLEE 1.1

Print this page

Introduction

Alarm management has changed significantly with Rhino 2.0. In SLEE 1.0, Alarms were stateless and the Alarm Facility was used by SBBs (and other components as determined by the SLEE vendor) to generate alarm notifications for management clients. In SLEE 1.1, Alarms are uniquely identifiable objects which have their own lifecycles within the SLEE. The Alarm Facility is also now usable by more SLEE components (including SBBs, ResourceAdaptors, and Profiles), and new management operations are available for raising and clearing Alarms.

It is highly recommended that the new 1.1 Alarm management APIs are used in preference to the now deprecated 1.0 APIs. This document is intended to describe the important differences between SLEE 1.0 and SLEE 1.1 Alarm management models.

Stateless Alarms in SLEE 1.0

In SLEE 1.0, SBBs accessed the Alarm Facility through an AlarmFacility object obtained via a JNDI lookup. Typically this would be done in an SBB's setSbbContext() lifecycle method to set an instance variable that could be used later.

For example:

import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.facilities.AlarmFacility;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public abstract class MySbb implements Sbb {
    private static final String JNDI_ALARMFACILITY_NAME = "java:comp/env/slee/facilities/alarm";
    private AlarmFacility alarmFacility;
    private SbbContext context;

    public void setSbbContext(SbbContext context) {
        this.context = context;
        try {
            this.alarmFacility = (AlarmFacility) new InitialContext().lookup(JNDI_ALARMFACILITY_NAME);
        } catch (NamingException e) { ... }
    }

When the SBB wanted to emit an alarm notification containing the specified alarm message, it would call AlarmFacility.createAlarm(), passing a ComponentID (such as the SBB's SbbID or ServiceID), an alarm level, an alarm type, the message string, and a timestamp:

// Emit an alarm notification with INFO level using the SBB's SbbID as the component ID
alarmFacility.createAlarm(context.getSbb(), Level.INFO, "javax.slee.management.alarm", "An event has occurred", System.currentTimeMillis());

This is not an ideal for several reasons. It is unnecessarily complicated by the fact that createAlarm(ComponentIDalarmSource, Level alarmLevel, String alarmType, String message, long timestamp) could throw a checked exception, UnrecognizedComponentException, if alarmSource was not a recognizable ComponentID object for the SLEE or it did not correspond with a component installed in the SLEE. Applications could of course wrap createAlarm() with other methods to simplify generating alarms, but this was more work for the application developer.

Another problem is that it was not clear who was the source of an alarm message. The createAlarm() method requires a ComponentID parameter to identify the source. In principle the SBB could use a ServiceID, SbbID or any other valid SLEE component ID when generating a trace. This was a problem because the same SBB could potentially be deployed in several services, so if an SBB generates traces using its SbbID, a management client cannot tell which service the SBB is being used in. Applications could encode additional contextual information about the source, but this is more work and should be automatic.

The last but most important problem was that the Alarms generated by the Alarm Facility were stateless. The SLEE was not required to keep an internal representation of which Alarms were active, it was only required to notify management clients when one of the appropriate alarm management methods was called, meaning that each management client was required to do all alarm state tracking itself.

The SLEE 1.1 alarms APIs remove these problems while still providing the benefits of a standardised SLEE alarm facility.

Stateful Alarm in SLEE 1.1

AlarmFacility Interface in SLEE 1.1

In SLEE 1.1, there are more components that may use alarms. In addition to SBBs, alarms can now be generated by Resource Adaptors, Profiles, and potentially various subsystems and facilities internal to the SLEE.

All of these components may use the SLEE 1.1 javax.slee.facilities.AlarmFacility interface. SBB and Resource Adaptor objects access the Alarm Facility through an AlarmFacility object that implements the AlarmFacility interface. An AlarmFacility object can be found at a SLEE specification defined location in every SBB, Profile, and Resource Adaptor Entity's component environment. The Alarm Facility is also available to a Resource Adaptor Entity via its ResourceAdaptorContext. The AlarmFacility object automatically provides notification source information to the SLEE when methods on the AlarmFacility are invoked.

The AlarmFacility interface provides the following methods:

  • raiseAlarm methods: There are two raiseAlarm methods. These methods are used to request that an alarm is raised with the specified message if an alarm with the same identifying attributes is not currently active. These methods take a String identifier specifying the type of the alarm, a String identifier specifying the particular instance of the alarm type, an AlarmLevel indicating the severity of the alarm, a String message, and an optional Throwable parameter.
  • clearAlarm: This method is used to request that the alarm with the specified alarm identifier be cleared.
  • clearAlarms(String): This method is used to request that all alarms of the specified type be cleared.
  • clearAlarms(): This method is used to request that all alarms belonging to the notification source associated with the AlarmFacility object be cleared.

The new AlarmFacility methods in SLEE 1.1 are shown below:

package javax.slee.facilities;
...
public interface AlarmFacility {
    ...
    public String raiseAlarm(String alarmType, String instanceID, AlarmLevel alarmLevel, String message);
    public String raiseAlarm(String alarmType, String instanceID, AlarmLevel alarmLevel, String message, Throwable cause);
    public boolean clearAlarm(String alarmID);
    public int clearAlarms(String alarmType);
    public int clearAlarms() ;
    ...
}

AlarmFacility Examples

An SBB or profile object obtains access to an AlarmFacility object via its JNDI environment. The AlarmFacility is bound into JNDI using the name specified by JNDI_NAME (the value of this constant is "java:comp/env/slee/facilities/alarm"). A Resource Adaptor Entity obtains access to an AlarmFacility object via the ResourceAdaptorContext interface which provides a Resource Adaptor Object with access to SLEE Facilities.

Obtaining an AlarmFacility

The example SLEE 1.0 SBB from earlier would look like this using SLEE 1.1 AlarmFacility:

import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.facilities.AlarmFacility;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public abstract class MySbb implements Sbb {
    private AlarmFacility alarmFacility;
    private SbbContext context;

    public void setSbbContext(SbbContext context) {
        this.context = context;
        try {
            this.alarmFacility = (AlarmFacility) new InitialContext().lookup(AlarmFacility.JNDI_NAME);
        } catch (NamingException e) { ... }
    }
    ...

Raising an Alarm

An alarm will be raised if there is no existing alarm with matching identifying attributes raised. The alarm will remain active until it is cleared, either via a call to any of the clearAlarm methods on this interface, or by management client use of the javax.slee.management.AlarmMBean object. When an alarm is raised an alarm notification is emitted by the Alarm MBean.

// Raise a INFO alarm
    try {
       String alarmID = alarmFacility.raiseAlarm("javax.slee.management.Alarm", "TestAlarmInstanceID", AlarmLevel.INFO, "An event has occurred");
     } catch (Exception e) { ... }

The raiseAlarm method returns a String value which is used to uniquely identify the raised alarm. If an alarm with the same identifying attributes (notification source, alarm type, instanceID) is already raised then this method has no effect, and the identifier of the existing raised alarm is returned. If no such alarm is raised, then a new alarm is raised, the SLEE's AlarmMBean object emits an alarm notification, and a SLEE generated alarm identifier for the new alarm is returned.

Clearing an existing Alarm

If no alarms of this type are active this method returns silently. The return value of this method is the number of alarms that were cleared. This method only clears alarms associated with the notification source of the alarm facility object. If one or more alarms are cleared by this method, the SLEE's AlarmMBean object emits an alarm notification for each cleared alarm with the alarm level set to AlarmLevel.CLEAR.

// Clear the raised alarm
 try {
    alarmFacility.clearAlarms("javax.slee.management.Alarm");
 } catch (Exception e) { ... }

Notification Sources

In the code example above, nowhere did the SBB have to specify its SbbID or ServiceID as the source of the alarms as this is automatic in SLEE 1.1. SLEE 1.1 introduces the NotificationSource interface, which the SLEE automatically adds to JMX notifications generated by SLEE alarms, so that JMX clients can easily identify the source. The NotificationSource explicitly identifies the component that generated the alarms, so a management client can easily see which service and SBB the alarms came from, allowing filtering by service or SBB. This solves the problem of identifying which SBB in which service generated an alarm.

AlarmNotification Class (changed in SLEE 1.1)

The AlarmNotification class has been changed in SLEE 1.1 to reflect changes to the AlarmMBean, and allow the source of the alarm to be any notification source defined in SLEE 1.1. Alarm notifications are emitted by an AlarmMBean to indicate that some component or subsystem is experiencing a problem. Notifications of this type are emitted by an AlarmMBean to indicate that some component or subsystem in the SLEE is experiencing a problem. Typically, a SLEE component uses the AlarmFacility to manage alarms.

Alarm notifications contain a NotificationSource object that can be used to obtain information about the object that raised the alarm. The type of an alarm notification can be used to infer the type of the notification source object contained in the notification:

  • if Notification.getType()==SbbNotification.ALARM_NOTIFICATION_TYPE then the type of the notification source object is SbbNotification.
  • if Notification.getType()==ResourceAdaptorEntityNotification.ALARM_NOTIFICATION_TYPE then the type of the notification source object is ResourceAdaptorEntityNotification.
  • if Notification.getType()==ProfileTableNotification.ALARM_NOTIFICATION_TYPE then the type of the notification source object is ProfileTableNotification.
  • if Notification.getType()==SubsystemNotification.ALARM_NOTIFICATION_TYPE then the type of the notification source object is SubsystemNotification.
package javax.slee.management;

public final class AlarmNotification extends Notification implements VendorExtensions {
// constructor
public AlarmNotification(String type, AlarmMBean alarmMBean, String alarmID,
                         NotificationSource notificationSource, String alarmType,
                         String instanceId, AlarmLevel alarmLevel, String message, 
                         Throwable cause, long sequenceNumber, long timestamp) { ... }
// deprecated constructor
public AlarmNotification(AlarmMBean alarmMBean, String alarmType, Object alarmSource, 
                         Level alarmLevel, String message, Throwable cause, long sequenceNumber, 
                         long timestamp) { ... }
// accessors
public String getAlarmID() { ... }
public NotificationSource getNotificationSource() { ... }
public String getAlarmType() { ... }
public String getInstanceID() { ... }
public AlarmLevel getAlarmLevel() { ... }
public Throwable getCause() { ... }
 // vendor-specific extension data support
public static void enableVendorDataSerialization() { ... }
public static void disableVendorDataSerialization() { ... }
public static void enableVendorDataDeserialization() { ... }
public static void disableVendorDataDeserialization() { ... }
public void setVendorData(Object vendorData) { ... }
public Object getVendorData() { ... }
// deprecated methods
public Object getAlarmSource() { ... }
public Level getLevel() { ... }

public boolean equals(Object obj) { ... }
public int hashCode() { ... }
public String toString() { ... }
}

In SLEE 1.1, the SLEE 1.0 constructor for AlarmNotification has been deprecated. Alarm notifications have been expanded with new attributes to take advantage of the new features provided by the SLEE specification. The AlarmNotification(String, AlarmMBean, String, NotificationSource, String, String, AlarmLevel, String, Throwable, long, long) constructor should be used instead of this constructor.

In SLEE 1.1, the getAlarmSource() method and getLevel() have been deprecated and replaced with getNotificationSource() and getAlarmLevel(). The deprecated methods will return null for SLEE 1.1-compliant notifications.

Management Interface

AlarmMBean Interface (changed in SLEE 1.1)

The AlarmMBean interface defines the management interface for the SLEE alarm subsystem. The AlarmMBean management interface has been extended in SLEE 1.1 so that management clients can easily obtain information about the alarms currently active in the SLEE, and may selectively clear alarms as required. Whenever an alarm is raised or cleared an AlarmNotification of the relevant type is generated.

package javax.slee.management;
...
public interface AlarmMBean {
    // methods
    public String[] getAlarms() throws ManagementException;
    public String[] getAlarms(NotificationSource source)
                          throws NullPointerException, UnrecognizedNotificationSourceException, ManagementException;
    public Alarm getDescriptor(String alarmId)
                          throws NullPointerException, ManagementException;
    public Alarm getDescriptors(String[] alarmIds)
                          throws NullPointerException, ManagementException;
    public boolean isActive(String alarmID)
                          throws NullPointerException, ManagementException;
    public boolean clearAlarm(String alarmID)
                          throws NullPointerException, ManagementException;
    public int clearAlarms(NotificationSource notificationSource) 
                          throws NullPointerException, UnrecognizedNotificationSourceException, ManagementException;
    public int clearAlarms(NotificationSource notificationSource, String alarmType) 
                          throws NullPointerException, UnrecognizedNotificationSourceException, ManagementException;

Since an AlarmMBean object can emit alarm notifications, it is required that the AlarmMBean object implement the javax.management.NotificationBroadcaster interface. In SLEE 1.0 an Alarm MBean emitted only one type of notification, defined by ALARM_NOTIFICATION_TYPE. As of SLEE 1.1, an AlarmMBean object may emit alarm notifications of different types, depending on the notification source of the object that raised the alarm. The SLEE-defined classes that implement NotificationSource each specify the type of alarm notification that is generated for the notification source.

Method Descriptions Returns
getAlarms() This method returns the identifiers of the active alarms in the SLEE. If no alarms are active in the SLEE this method returns an empty array. an array containing the alarm identifiers of all the alarms currently active in the SLEE.
getAlarms(NotificationSource) This method returns the identifiers of active alarms raised by the specified notification source. If no alarms are active this method returns an empty array. an array containing the alarm identifiers of all the alarms currently active in the SLEE that were raised by the specified notification source.
isActive() This method determines if the alarm specified by the alarmID parameter is active in the SLEE. true if an alarm with the specified alarm identifier is currently active in the SLEE, false otherwise.
getDescriptor This method returns the Alarm object for the alarm with the identifier specified by the alarmID argument. the alarm descriptor for the alarm, or null if the specified alarm is not currently active in the SLEE.
getDescriptors This method performs the function of the above getDescriptor method over an array of alarm identifiers. an array of alarm descriptor objects. This array will be the same length as the supplied array, and if descriptors = getDescriptors(alarmIDs) then descriptors[RAD:i] == getDescriptor(alarmIDs[RAD:i]). Any alarm identifier present in ids that does not identify a activty alarm in the SLEE results in a null value at the corresponding array index in this array.
clearAlarm This method clears the alarm with the identifier specified by the alarmID argument. true if the specified alarm existed and was cleared as a result of this method, false otherwise.
clearAlarms(NotificationSource) This method clears all active alarms raised by the specified notification source. the number of alarms cleared by this method call. May be zero if no alarms were cleared.
clearAlarms(NotificationSource, String) This method clears all active alarms of the specified type raised by the specified notification source. the number of alarms cleared by this method call. May be zero if no alarms were cleared.
New SLEE 1.1 commands via the web-console.
Operations Descriptions Values SLEE 1.1
clearAlarm Clear the specified alarm alarmID=[101:94193209650:0] unchanged in SLEE 1.1
clearAlarms Clear all active alarms of the specified type raised by the specified notification source
notificationsource=RAEntityNotification[RAD:entity=simplera]
 alarmType=
changed in SLEE 1.1
clearAlarms Clear all active alarms raised by the specified notification source notificationsource=RAEntityNotification[RAD:entity=simplera] added in SLEE 1.1
getAlarms Get the unique alarm identifier for stateful alarms currently active in the SLEE that
were raised by the specified notification source
notificationsource=RAEntityNotification[RAD:entity=simplera] added in SLEE 1.1
getDescriptor Get the alarm descriptor for an alarm identifier
alarmID=[101:94193209650:0] added in SLEE 1.1
getDescriptors
Get an array of alarm descriptors corresponding to an array of alarm identifiers
alarmIDs=[Select multiple options
101:94193209650:0]
added in SLEE 1.1
isActive Determine if a specified alarm is (still) currently active in the SLEE alarmID=[101:94193209650:0] added in SLEE 1.1
logAllActiveAlarms Log alarm information for each active alarm in the cluster
  unchanged in  SLEE 1.1
rebroadcastActiveAlarmNotifications Rebroadcast alarm notifications for each active alarm in the cluster
  added in SLEE 1.1
New SLEE 1.1 commands via the command line console.
Commands Descriptions
Examples SLEE 1.1
clearalarm <alarmid> Clear the specified alarm [RAD:Rhino@localhost (#1)] clearalarm 101:94193209650:0
Alarm 101:94193209650:0 cleared
unchanged in SLEE 1.
clearalarms <type> <notification-source> <alarm type> Clear all alarms of the specified type raised by the notification source [RAD:Rhino@localhost (#2)] clearalarms resourceadaptorentity entity=simplera
noconnection
1 alarm cleared
changed in SLEE 1.1
listactivealarms List the alarms currently active in the SLEE

[RAD:Rhino@localhost (#0)] listactivealarms
Alarm[id=101:94193209650:0,source=RAEntityNotification[RAD:entity=simplera],
alarmType=noconnection,instanceID=localhost:14477,level=Minor,message
=No connection to load generator, retrying with a period of 5000ms,cause=null,
timestamp=1193705959931]

unchanged in  SLEE 1.

Alarm Class (added in SLEE 1.1)

In SLEE 1.1, the Alarm class contains information about an alarm that has been raised. This class has been added since SLEE 1.1. The public interface of the Alarm class is as follows:

package javax.slee.management;
import java.io.Serializable;
public final class Alarm implements VendorExtensions, Serializable, Cloneable, Comparable
{
// constructors
public Alarm(String alarmId, NotificationSource notificationSource, String alarmType,
             String instanceId, AlarmLevel level, String message, Throwable cause, long timestamp) { ... }
// accessors
public String getAlarmID() { ... }
public NotificationSource getNotificationSource() { ... }
public String getAlarmType() { ... }
public String getInstanceID() { ... }
public AlarmLevel getAlarmLevel() { ... }
public String getMessage() { ... }
public Throwable getCause() { ... }
public long getTimestamp() { ... }
// vendor-specific extension data support
public static void enableVendorDataSerialization() { ... }
public static void disableVendorDataSerialization() { ... }
public static void enableVendorDataDeserialization() { ... }
public static void disableVendorDataDeserialization() { ... }
public final void setVendorData(Object vendorData) { ... }
public final Object getVendorData() { ... }
public boolean equals(Object obj) { ... }
public int hashCode() { ... }
public String toString() { ... }
public int compareTo(Object obj) { ... }
public Object clone() { ... }
}

Please refers to SLEE 1.1 specification or javadoc for complete descriptions of the Alarm class.

AlarmLevelFilter Class (changed in SLEE 1.1)

The AlarmLevelFilter has been changed to support all notification sources defined in SLEE 1.1, and filters using both the new AlarmLevel class as well as the deprecated Level class. The AlarmLevelFilter class filters alarm notifications based on the severity of the alarm level in the notification. Only alarm notifications of the specified severity level or greater will be allowed through this filter. There are two variants of this filter as described below:

  • The first variant uses the AlarmLevel class introduced in the SLEE 1.1 specification to compare alarm levels.
    AlarmLevelFilter alarmLevelFilter = new AlarmLevelFilter(AlarmLevel.WARNING);
  • The second variant is the version originally defined in the SLEE 1.0 specification, and is deprecated in the SLEE 1.1 specification as it uses the deprecated Level class to compare alarm levels.

The public interface of the AlarmLevelFilter class is as follows:

package javax.slee.management;
...
public class AlarmLevelFilter implements NotificationFilter {
// constructor
public AlarmLevelFilter(AlarmLevel minLevel) { ... }
// deprecated constructor
public AlarmLevelFilter(Level minLevel) { ... }
// methods
public boolean isNotificationEnabled(Notification notification) { ... }
}

Backward compatibility

SLEE 1.1 still supports the createAlarm methods of the AlarmFacility interface for backward compatibility, but it has been deprecated and may be removed in a future version of the specification.

Adaptavist Theme Builder Powered by Atlassian Confluence