13.2 Alarm Facility
The Alarm Facility is used by SBBs, Resource Adaptors, and Profiles to request the SLEE to raise or clear alarms. If a request is made to raise an alarm and the identified alarm has not already been raised, the alarm is raised and a corresponding alarm notification is generated by the AlarmMBean. If a request is made to clear an alarm and the identified alarm is currently raised, the alarm is cleared and a corresponding alarm notification is generated by the AlarmMBean. Requests to raise an alarm that is already raised or to clear an alarm that is not currently raised cause no further action in the SLEE, ie. notifications are not generated in this case.
Alarm notifications are intended for consumption by management clients external to the SLEE. For example, these management clients may be a network management console or a management policy engine. In any case, the management client is responsible for registering to receive alarm notifications generated by the Alarm Facility through the external management interface of the Alarm Facility (see Section 14.14). The management client may optionally provide notification filters so that only the alarm notifications that the management client would like to receive are transmitted to the management client. These notification filters reduce alarm related network traffic and the processing that the management client has to perform to filter unwanted alarm notifications.
The external management interface of the Alarm Facility is defined by the AlarmMBean interface. Each alarm notification generated by the Alarm Facility is emitted through an AlarmMBean object as an AlarmNotification object. See Section 14.14 for detailed description of the AlarmMBean interface and the AlarmNotification class.
The Alarm Facility may be used by other alarm sources within the SLEE to generate alarm notifications. These alarm sources include the various subsystems and Facilities of the SLEE. The SLEE specification does not define the interface that these alarm sources use to emit alarm notifications. However, each alarm notification is emitted through the same AlarmMBean object and as an AlarmNotification object. Each AlarmNotification object contains a NotificationSource object (see Section 14.16.1) that identifies the alarm source.
13.2.1 Alarms and alarm identifiers
Alarms are either raised or clear. When raised the alarm level specifies the severity of the alarm. The Java type for an alarm is javax.slee.management.Alarm.
Every alarm has a notification source. The notification source identifies the component that raised the alarm. This may be either an SBB component and Service ID pair, a resource adaptor entity, a Profile Table, or a SLEE implementation defined internal sub-system.
Every alarm has an alarm type. The Java type for an alarm type is java.lang.String. The Alarm type allows the user of the Alarm Facility to provide classification information about the alarm messages emit-ted. The management client can use this classification information to filter the alarm notifications. Examples of alarm types could be "Database Connection Failed", or "Registration Missing". The same alarm type can be used by different notification sources.
Every alarm has an instance ID. The instance ID allows the user of the Alarm Facility to provide additional information about the particular alarm, within the classification. For example if the alarm type was "Data-base Connection Failed" the instance ID might indicate which database server has failed. For the example of the "Registration Missing" alarm type, the identifier of the user might be supplied as the instance ID.
An alarm is considered the same as another alarm if its notification source, alarm type and instance ID are the same.
Each raised alarm is uniquely identified by an alarm identifier generated by the SLEE. The Java type for an alarm identifier is java.lang.String. Each alarm identifier is associated with an alarm, and uniquely identifies the particular occurrence of the alarm being raised. For example if we consider an alarm which is raised, cleared and then raised again the two different periods where the alarm is raised are distinguished by different alarm identifiers.
13.2.2 AlarmFacility interface
SBB, Profile, 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 and Profile component environment and is also available to each resource adaptor entity via its ResourceAdaptorContext. An AlarmFacility object automatically provides notification source information to the SLEE when methods on the AlarmFacility interface are invoked.
22.214.171.124 raiseAlarm methods
There are two raiseAlarm methods. These methods are used to request that an alarm is raised. 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.
The identifying attributes of an alarm are the notification source, the alarm type, and the instance ID.
The following arguments may be passed to these methods:
- The alarmType argument.
This argument specifies the type of alarm being generated. It will be included in the AlarmNotification object emitted by the AlarmMBean object for the alarm notification. A management client can use the alarm type of the AlarmNotification object to filter the alarm notification.
- The instanceID argument.
This argument specifies the particular instance of the alarm type that is occuring.
- The alarmlevel argument.
This argument takes an AlarmLevel object that specifies the alarm level of the alarm notification. All the AlarmLevel objects defined in Section 13.2.3 can be specified except the AlarmLevel.CLEAR object.
- The message argument.
This argument specifies the message that will be placed into the message attribute of the AlarmNotification object emitted by the AlarmMBean object for the alarm notification if the alarm is raised as a result of this method. The AlarmNotification object inherits its message attribute from the standard JMX Notification class.
- The optional cause argument.
This argument is typically used to propagate an exception in the alarm notification.
The raiseAlarm method returns a String value which is used to 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. The raiseAlarm method throws a java.lang.NullPointerException if any of the arguments, except cause, are null. It throws a java.lang.IllegalArgumentException if the specified alarm level is AlarmLevel.CLEAR. It throws the javax.slee.facilities.FacilityException if the requested operation cannot be completed because of a system-level failure.
3. 126.96.36.199 clearAlarms(String) method
This method requests that all alarms of a certain alarm type are cleared. 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.
This method takes the following argument:
- The alarmType argument.
This argument specifies the alarm type of the alarms to be cleared.
The clearAlarms(String) method throws a java.lang.NullPointerException if the alarmID argument is null. It throws the javax.slee.facilities.FacilityException if the alarms can not be cleared because of a system-level failure.
13.2.3 AlarmLevel objects
The AlarmLevel class defines an enumerated type for the levels supported by the Alarm Facility. A singleton instance of each enumerated value is guaranteed (via an implementation of the readResolve method, see java.io.Serializable for more details), so that equality tests using == are always evaluated correctly. For convenience, an integer representation of AlarmLevel objects is also available.
The following singleton AlarmLevel objects define the valid arguments that may be provided to methods that take a AlarmLevel object as argument and may be returned by methods that return Alarm-Level objects. The alarm levels, in order of relative severity from highest to least, are: