alma.acs.alarmsystem.source

Interface AlarmSource

All Known Implementing Classes:

AlarmSourceImpl

public interface AlarmSource

The AlarmSource interface offers a set of useful methods to handle alarms from a source.

This class, on one side, allows the sending of alarms with a shorter syntax compared to the original API and, on the other side, offers some common functionalities useful while sending alarms in ACS.

This class implements a guard in the sense that a active (terminated) alarm is not sent to the alarm service if it has been already activated (terminated).

To damp the effect of oscillation an active alarm is immediately forwarded to the alarm service but the sending of a terminated alarm is delayed of approximately one second to catch a reactivation in that period of time.

AlarmSource allows to queue the alarms instead of sending them immediately by calling queueAlarms(...). To stop queuing the alarms and send them to the alarm service the method flushAlarms() must be executed. The queuing of the alarms has the advantage that if an alarm is activated and then deactivated during the queuing time, it is not sent to the alarm service. This functionalities can be useful for example when starting up a piece of software connected to an hardware device. In that case it is quite common that before initialization some of the values returned by the device are wrong and can trigger the sending of alarms that will be cleared only when the device is fully operative. With the queuing the operator does not receive this kind of (false) alarms. It is left to developer the responsibility to enable/disable the queuing at the right moment.
If queueAlarms(long, TimeUnit) is called twice, the the new time interval is used to flush the queue and the old one is discarded.

Alarm sending can be inhibited by calling disableAlarms(): all the alarm events submitted after calling this method are discarded. To revert just call enableAlarms(). The inhibition of the alarms does not interfere with the queuing: alarms queued before inhibit alarms remain queued and will be sent when flushing.

Life cycle: start() must be called before using methods of this class. tearDown() must be called when finished using this class.

Author:

acaproni

Method Summary

Modifier and Type	Method and Description
void	clearAlarm(java.lang.String faultFamily, java.lang.String faultMember, int faultCode) Clear the alarm with the passed triplet.
void	disableAlarms() Disable the sending of alarms.
void	enableAlarms() Enable the sending of alarms.
void	flushAlarms() Flush the alarms queued and stop queuing.
void	queueAlarms() Start queuing the alarms.
void	queueAlarms(long delayTime, java.util.concurrent.TimeUnit unit) Start queuing the alarms.
void	raiseAlarm(java.lang.String faultFamily, java.lang.String faultMember, int faultCode) Raise an alarm with the given triplet.
void	raiseAlarm(java.lang.String faultFamily, java.lang.String faultMember, int faultCode, java.util.Properties properties) Raise an alarm with the given triplet and a set of properties.
void	setAlarm(java.lang.String faultFamily, java.lang.String faultMember, int faultCode, boolean active) Send the alarm with the passed triplet to the alarm service.
void	setAlarm(java.lang.String faultFamily, java.lang.String faultMember, int faultCode, java.util.Properties alarmProps, boolean active) Send the alarm with the passed triplet and properties to the alarm service.
void	start() Life-cycle: this method must be called before using this class.
void	tearDown() Life-cycle: tearDown must be called when terminated using this class
void	terminateAllAlarms() Terminate all the active alarms.

Method Detail

raiseAlarm

void raiseAlarm(java.lang.String faultFamily,
                java.lang.String faultMember,
                int faultCode)

Raise an alarm with the given triplet.

If the alarm is already active, it is not sent again to the alarm service.

Parameters:

faultFamily - The FaultFamily

faultMember - The FaultMember

faultCode - The FaultCode

raiseAlarm

void raiseAlarm(java.lang.String faultFamily,
                java.lang.String faultMember,
                int faultCode,
                java.util.Properties properties)

Raise an alarm with the given triplet and a set of properties.

If the alarm is already active, it is not sent again to the alarm service.

Parameters:

faultFamily - The FaultFamily

faultMember - The FaultMember

faultCode - The FaultCode

properties - The user properties. It can be null or empty.

clearAlarm

void clearAlarm(java.lang.String faultFamily,
                java.lang.String faultMember,
                int faultCode)

Clear the alarm with the passed triplet.

If the alarm is already terminated, it is not sent again to the alarm service.

Parameters:

faultFamily - The FaultFamily

faultMember - The FaultMember

faultCode - The FaultCode

setAlarm

void setAlarm(java.lang.String faultFamily,
              java.lang.String faultMember,
              int faultCode,
              java.util.Properties alarmProps,
              boolean active)

Send the alarm with the passed triplet and properties to the alarm service. The state activate/terminate of the alarm depends on the passed boolean.

This method is the most complete way to send an alarm.

If the alarm is already active, it is not sent again to the alarm service. If the alarm is already terminated, it is not sent again to the alarm service.

Parameters:

faultFamily - The FaultFamily

faultMember - The FaultMember

faultCode - The FaultCode

alarmProps - The user properties. It can be null or empty.

active - if true the alarm is activated otherwise it is terminated.

setAlarm

void setAlarm(java.lang.String faultFamily,
              java.lang.String faultMember,
              int faultCode,
              boolean active)

Send the alarm with the passed triplet to the alarm service. The state activate/terminate of the alarm depends on the passed boolean.

This method is the most complete way to send an alarm.

If the alarm is already active, it is not sent again to the alarm service. If the alarm is already terminated, it is not sent again to the alarm service.

Parameters:

faultFamily - The FaultFamily

faultMember - The FaultMember

faultCode - The FaultCode

active - if true the alarm is activated otherwise it is terminated.

terminateAllAlarms

void terminateAllAlarms()

Terminate all the active alarms.

queueAlarms

void queueAlarms(long delayTime,
                 java.util.concurrent.TimeUnit unit)

Start queuing the alarms.

The alarms are flushed when the passed time expires or flush gets called.

The purpose of the queuing is to avoid alarms flickering for example during the initialization phase of a device where spurious states could trigger the event of false alarms

Parameters:

delayTime - The time to queue alarms

unit - The unit of the delay

queueAlarms

void queueAlarms()

Start queuing the alarms.

The alarms are queued until flushAlarms() is executed.

The purpose of the queuing is to avoid alarms flickering for example during the initialization phase of a device where spurious states could trigger the event of false alarms.

See Also:

flushAlarms()

flushAlarms

void flushAlarms()

Flush the alarms queued and stop queuing.

See Also:

AlarmSource#queueAlarms()}

disableAlarms

void disableAlarms()

Disable the sending of alarms.

When the alarms are disabled, all the alarms submitted with raise, clear and set are discarded. This means that those alarms are immediately discarded. They are not queued, and will never arrive at the alarm service.

See Also:

enableAlarms()

enableAlarms

void enableAlarms()

Enable the sending of alarms.

Better just "This method reverts the effect of a previous call to disableAlarms(), so that alarms will get processed again.

Alarms are enabled by default.

See Also:

disableAlarms()

start

void start()

Life-cycle: this method must be called before using this class.

tearDown

void tearDown()

Life-cycle: tearDown must be called when terminated using this class