javax.slee.facilities
Interface AlarmFacility

public interface AlarmFacility

The Alarm Facility is used to indicate to the SLEE requests 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.

Each AlarmFacility object is associated with a particular NotificationSource, an object that identifies the SLEE component or subsystem that the alarm facility belongs to. For example, the AlarmFacility object that a particular SBB obtains from its JNDI environment is associated with a notification source that identifies the SBB that that JNDI environment was created for and the service that that SBB belongs to.

Each occurrence of an alarm is uniquely identified by an alarm identifier generated by the SLEE. Each alarm identifier is associated to an alarm with three identifying attributes:

• the NotificationSource object associated to the AlarmFacility where the alarm was raised. This attribute is implicitly provided by the alarm facility when the alarm is raised.
• an alarm type, specified by the notification source that raised the alarm. This attribute identifies the particular type of alarm, e.g. a database connection failure.
• an instance ID, specified by the notification source that raised the alarm. This attribute identifies a particular instance of the alarm type, e.g. the name of the host where connection failures are being experienced.

All operations invoked on the AlarmFacility interface only apply to alarms belonging to the notification source associated with the AlarmFacility object.

The Alarm Facility is non-transactional. The effects of operations invoked on this facility occur immediately regardless of the state or outcome of any enclosing transaction.

An SBB or profile object obtains access to an AlarmFacility object via its JNDI environment. The Alarm Facility is bound into JNDI using the name specified by JNDI_NAME. A resource adaptor entity obtains access to an AlarmFacility object via the ResourceAdaptorContext.

See Also:

AlarmMBean, AlarmNotification

Field Summary

static java.lang.String

JNDI_NAME Constant declaring the JNDI name where an AlarmFacility object is bound into an SBB, profile object's, or resource adaptor object's JNDI environment.

Method Summary

boolean	clearAlarm(java.lang.String alarmID) Request that the alarm with the specified alarm identifier be cleared.
int	clearAlarms() Request that all alarms belonging to the notification source associated with the AlarmFacility object be cleared.
int	clearAlarms(java.lang.String alarmType) Request that all alarms of the specified type be cleared.
void	createAlarm(ComponentID alarmSource, Level alarmLevel, java.lang.String alarmType, java.lang.String message, long timestamp) Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the alarm subsystem in SLEE 1.1. In addition the levels provided by the Level class were not practical for stateful alarm use. This method has been replaced with raiseAlarm(String,String,AlarmLevel,String).
void	createAlarm(ComponentID alarmSource, Level alarmLevel, java.lang.String alarmType, java.lang.String message, java.lang.Throwable cause, long timestamp) Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the alarm subsystem in SLEE 1.1. In addition the levels provided by the Level class were not practical for stateful alarm use. This method has been replaced with raiseAlarm(String,String,AlarmLevel,String,Throwable).
java.lang.String	raiseAlarm(java.lang.String alarmType, java.lang.String instanceID, AlarmLevel alarmLevel, java.lang.String message) Request that an alarm be raised with the specified message if an alarm with the same identifying attributes is not currently active.
java.lang.String	raiseAlarm(java.lang.String alarmType, java.lang.String instanceID, AlarmLevel alarmLevel, java.lang.String message, java.lang.Throwable cause) Request that an alarm be raised with the specified message and cause throwable if an alarm with the same identifying attributes is not currently active.

Field Detail

JNDI_NAME

static final java.lang.String JNDI_NAME

Constant declaring the JNDI name where an AlarmFacility object is bound into an SBB, profile object's, or resource adaptor object's JNDI environment.

The value of this constant is "java:comp/env/slee/facilities/alarm".

Since:

SLEE 1.1

See Also:

Constant Field Values

Method Detail

createAlarm

void createAlarm(ComponentID alarmSource,
                 Level alarmLevel,
                 java.lang.String alarmType,
                 java.lang.String message,
                 long timestamp)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        UnrecognizedComponentException,
                        FacilityException

Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the alarm subsystem in SLEE 1.1. In addition the levels provided by the Level class were not practical for stateful alarm use. This method has been replaced with raiseAlarm(String,String,AlarmLevel,String).

Emit an alarm notification containing the specified alarm message.

This method is a non-transactional method.

Parameters:

alarmSource - the identifier of the component that is emitting the alarm.

alarmLevel - the level of the alarm.

alarmType - a string denoting the type of the alarm. Refer to the SLEE specification for recommended formatting of alarm type strings.

message - the alarm message.

timestamp - the time (in ms since January 1, 1970 UTC) that the alarm was generated.

Throws:

java.lang.NullPointerException - if any parameter is null.

java.lang.IllegalArgumentException - if alarmLevel == Level.OFF.

UnrecognizedComponentException - if alarmSource is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

FacilityException - if the alarm could not be generated due to a system-level failure.

createAlarm

void createAlarm(ComponentID alarmSource,
                 Level alarmLevel,
                 java.lang.String alarmType,
                 java.lang.String message,
                 java.lang.Throwable cause,
                 long timestamp)
                 throws java.lang.NullPointerException,
                        java.lang.IllegalArgumentException,
                        UnrecognizedComponentException,
                        FacilityException

Deprecated. This method uses a ComponentID to identify a notification source and thus is not compatible with the changes made to the alarm subsystem in SLEE 1.1. In addition the levels provided by the Level class were not practical for stateful alarm use. This method has been replaced with raiseAlarm(String,String,AlarmLevel,String,Throwable).

Emit an alarm notification containing the specified alarm message and cause throwable.

This method is a non-transactional method.

Parameters:

alarmSource - the identifier of the component that is emitting the alarm.

alarmLevel - the level of the alarm.

alarmType - a string denoting the type of the alarm. Refer to the SLEE specification for recommended formatting of alarm type strings.

message - the alarm message.

cause - the reason (if any) this alarm was generated.

timestamp - the time (in ms since January 1, 1970 UTC) that the alarm was generated.

Throws:

java.lang.NullPointerException - if any parameter is null.

java.lang.IllegalArgumentException - if alarmLevel == Level.OFF.

UnrecognizedComponentException - if alarmSource is not a recognizable ComponentID object for the SLEE or it does not correspond with a component installed in the SLEE.

FacilityException - if the alarm could not be generated due to a system-level failure.

raiseAlarm

java.lang.String raiseAlarm(java.lang.String alarmType,
                            java.lang.String instanceID,
                            AlarmLevel alarmLevel,
                            java.lang.String message)
                            throws java.lang.NullPointerException,
                                   java.lang.IllegalArgumentException,
                                   FacilityException

Request that an alarm be raised with the specified message if an alarm with the same identifying attributes is not currently active. The alarm will remain active until it is cleared, either via a call to any of the clearAlarm methods in this interface, or by a management client interacting with an AlarmMBean object.

If an alarm with the same identifying attributes (notification source, alarm type, and instance ID) is already active in the SLEE, this method has no effect and the alarm identifier of the existing active alarm is returned. If no such alarm exists, the alarm is raised, the SLEE's AlarmMBean object emits an AlarmNotification, and a SLEE-generated alarm identifier for the new alarm is returned.

This method is equivalent to:

raiseAlarm(alarmType, instanceID, alarmLevel, message, null);

This method is a non-transactional method.

Parameters:

alarmType - an identifier specifying the type of the alarm.

instanceID - an identifier specifying the particular instance of the alarm type that is occurring.

alarmLevel - the level of the alarm. The level cannot be AlarmLevel.CLEAR.

message - the message to include in the alarm if the alarm is raised as a result of this method call.

Returns:

a unique alarm identifier for the alarm. If the alarm was raised as a result of this operation, a new alarm identifier is generated by the SLEE and returned from this method. Otherwise the alarm identifier which identifies the existing alarm with the same identifying attributes is returned.

Throws:

java.lang.NullPointerException - if any argument is null.

java.lang.IllegalArgumentException - if alarmLevel is AlarmLevel.CLEAR.

FacilityException - if the alarm could not be raised due to a system-level failure.

Since:

SLEE 1.1

raiseAlarm

java.lang.String raiseAlarm(java.lang.String alarmType,
                            java.lang.String instanceID,
                            AlarmLevel alarmLevel,
                            java.lang.String message,
                            java.lang.Throwable cause)
                            throws java.lang.NullPointerException,
                                   java.lang.IllegalArgumentException,
                                   FacilityException

Request that an alarm be raised with the specified message and cause throwable if an alarm with the same identifying attributes is not currently active. The alarm will remain active until it is cleared, either via a call to any of the clearAlarm methods in this interface, or by a management client interacting with an AlarmMBean object.

If an alarm with the same identifying attributes (notification source, alarm type, and instance ID) is already active in the SLEE, this method has no effect and the alarm identifier of the existing active alarm is returned. If no such alarm exists, the alarm is raised, the SLEE's AlarmMBean object emits an AlarmNotification, and a SLEE-generated alarm identifier for the new alarm is returned.

This method is a non-transactional method.

Parameters:

alarmType - an identifier specifying the type of the alarm.

instanceID - an identifier specifying the particular instance of the alarm type that is occurring.

alarmLevel - the level of the alarm. The level cannot be AlarmLevel.CLEAR.

message - the message to include in the alarm if the alarm is raised as a result of this method call.

cause - an optional Throwable object that caused this alarm to be raised, included in the alarm descriptor if the alarm is raised as a result of this method call.

Returns:

a unique alarm identifier for the alarm. If the alarm was raised as a result of this operation, a new alarm identifier is generated by the SLEE and returned from this method. Otherwise the alarm identifier which identifies the existing alarm with the same identifying attributes is returned.

Throws:

java.lang.NullPointerException - if alarmType, instanceID, alarmLevel, or message is null.

java.lang.IllegalArgumentException - if alarmLevel is AlarmLevel.CLEAR.

FacilityException - if the alarm could not be raised due to a system-level failure.

Since:

SLEE 1.1

clearAlarm

boolean clearAlarm(java.lang.String alarmID)
                   throws java.lang.NullPointerException,
                          FacilityException

Request that the alarm with the specified alarm identifier be cleared. If the alarm has already been cleared, or no such alarm exists in the SLEE, this method returns with no effect.

This method only affects alarms belonging to the notification source associated with the AlarmFacility object. If the specified alarm is cleared, the SLEE's AlarmMBean object emits an AlarmNotification for the alarm with the alarm level in the notification set to AlarmLevel.CLEAR.

This method is a non-transactional method.

Parameters:

alarmID - the unique alarm identifier for the alarm.

Returns:

true if the specified alarm existed and was cleared as a result of this method, false otherwise.

Throws:

java.lang.NullPointerException - if alarmID is null.

FacilityException - if the alarm could not be cleared due to a system-level failure.

Since:

SLEE 1.1

clearAlarms

int clearAlarms(java.lang.String alarmType)
                throws java.lang.NullPointerException,
                       FacilityException

Request that all alarms of the specified type be cleared. If no active alarms of the specified type are found, this method returns with no effect.

This method only affects alarms belonging to the notification source associated with the AlarmFacility object. If one or more alarms are cleared by this method, the SLEE's AlarmMBean object emits an AlarmNotification for each alarm with the alarm level in each notification set to AlarmLevel.CLEAR.

This method is a non-transactional method.

Parameters:

alarmType - the type of the alarms to clear.

Returns:

the number of alarms cleared by this method call. May be zero if no alarms were cleared.

Throws:

java.lang.NullPointerException - if alarmType is null.

FacilityException - if the alarms could not be cleared due to a system-level failure.

Since:

SLEE 1.1

clearAlarms

int clearAlarms()
                throws FacilityException

Request that all alarms belonging to the notification source associated with the AlarmFacility object be cleared.

This method only affects alarms belonging to the notification source associated with the AlarmFacility object instance. If one or more alarms are cleared by this method, the SLEE's AlarmMBean object emits an AlarmNotification for each alarm with the alarm level in each notification set to AlarmLevel.CLEAR.

This method is a non-transactional method.

Returns:

the number of alarms cleared by this method call. May be zero if no alarms were cleared.

Throws:

FacilityException - if the alarms could not be cleared due to a system-level failure.

Since:

SLEE 1.1