org.apache.polygene.library.alarm

Interface AlarmPoint

All Superinterfaces:

HasIdentity

All Known Subinterfaces:

AlarmPointEntity, AlarmProxy

All Known Implementing Classes:

AlarmPoint.AlarmPointMixin, AlarmProxy.Mixin

public interface AlarmPoint
extends HasIdentity

Defines the basic AlarmPoint interface.

This is the basic interface for the whole AlarmPoint System. The AlarmPoint is created by calling createAlarm() method in the AlarmSystem or the AlarmModel.

• All alarms carries a set of attributes, runtime extendable.
• All alarms can be activated (on), deactivated (off) and acknowledged.
• All alarms have an AlarmStatus.
• All alarms generates AlarmEvents.
• The behaviour of the AlarmPoint is defined by an AlarmModel.
• Every AlarmPoint can have its own AlarmModel.
• Any number of AlarmStates and AlarmEvents can be defined in an AlarmModel.

Alarms can be triggered by an standard trigger, which are java.lang.Strings. 3 triggers are pre-defined; activate,deactivate and acknowledge and must be present in all standard systems and standard impl.

The basic usage looks like this;

     // Creation
     AlarmPoint ala1 = alarmService.createAlarm( "My AlarmPoint" );
       :
       :
     // use
     if( alarmcondition )  // The condition should only detect transitions.
         ala1.trigger( this, "activate" );
 

It is important to know that every call to trigger() will generate an AlarmEvent, so the trigger() should only be called when the standard condition changes. For this purpose, there is a convenience method, that will create/generate the trigger method calls when a boolean standard condition changes. The usage is fairly simple.

Example;

     ala1.updateCondition( value > highlimit );
 

It is possible to mix and match the usage of updateCondition() and trigger() methods without any concerns.

To create alarms with different AlarmModels, other than the default as shown above, you need to retrieve the AlarmModel that fulfill the needs required. This can be done in the following manner;

     AlarmModel[] impl = alarmService.getAlarmModelsAvailable();
     // selection algorithm
     AlarmPoint ala2 = impl[selected].createAlarm( "My AlarmPoint" );
 

The default AlarmModel can be changed by a call to the AlarmSystem.setDefaultAlarmModel() and ALL ALARMS that has the old AlarmModel assigned to it, will be transferred to the new default AlarmModel. It is important to understand that this is done irregardless of whether the AlarmPoint was created from the AlarmSystem.createAlarm() method or the AlarmModel.createAlarm() method. If distinct different behaviours are required for certain Alarms, and yet want to allow users to freely select AlarmModel for all other Alarms, one need to create two instances of the same AlarmModels, one used solely for the pre-defined AlarmPoint behaviours, and the others for the rest of the Alarms.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	AlarmPoint.AlarmPointMixin
static interface	AlarmPoint.AlarmState The AlarmState is an internal type, used inside the AlarmPoint for all state that needs to be persisted on disk and/or transferred across networks.

Nested classes/interfaces inherited from interface org.apache.polygene.api.identity.HasIdentity

HasIdentity.HasIdentityMixin

Field Summary

Fields

Modifier and Type	Field and Description
static String	EVENT_ACKNOWLEDGEMENT
static String	EVENT_ACTIVATION
static String	EVENT_BLOCKING
static String	EVENT_DEACTIVATION
static String	EVENT_DISABLING
static String	EVENT_ENABLING
static String	EVENT_UNBLOCKING
static String	STATUS_ACKNOWLEDGED
static String	STATUS_ACTIVATED
static String	STATUS_BLOCKED
static String	STATUS_DEACTIVATED
static String	STATUS_DISABLED
static String	STATUS_NORMAL
static String	STATUS_REACTIVATED
static String	TRIGGER_ACKNOWLEDGE
static String	TRIGGER_ACTIVATE
static String	TRIGGER_BLOCK
static String	TRIGGER_DEACTIVATE
static String	TRIGGER_DISABLE
static String	TRIGGER_ENABLE
static String	TRIGGER_UNBLOCK

Fields inherited from interface org.apache.polygene.api.identity.HasIdentity

IDENTITY_METHOD, IDENTITY_STATE_NAME

Method Summary

Modifier and Type	Method and Description
void	acknowledge() Acknowledges an AlarmPoint.
void	activate() Activates an AlarmPoint.
Property<AlarmClass>	alarmClass() The AlarmClass of the AlarmPoint.
String	attribute(String name) Return the attribute of the given name.
List<String>	attributeNames() Return all attribute names
Property<AlarmCategory>	category() The AlarmCategory of this AlarmPoint.
boolean	currentCondition() Get AlarmPoint condition.
AlarmStatus	currentStatus() Returns the current state of the standard.
void	deactivate() Deactivates an AlarmPoint.
String	description(Locale locale) Returns a Description of the AlarmPoint.
String	descriptionInDefaultLocale() Returns a Description of the AlarmPoint.
AlarmHistory	history() Returns the AlarmHistory of the standard.
String	name() Returns the Name of the AlarmPoint.
void	setAttribute(String name, String value) Sets the attribute of the given name.
void	trigger(String trigger) Trigger a state change.
void	updateCondition(boolean condition) Set AlarmPoint condition.

Methods inherited from interface org.apache.polygene.api.identity.HasIdentity

identity

Field Detail

STATUS_NORMAL

static final String STATUS_NORMAL

See Also:

Constant Field Values

STATUS_ACTIVATED

static final String STATUS_ACTIVATED

See Also:

Constant Field Values

STATUS_DEACTIVATED

static final String STATUS_DEACTIVATED

See Also:

Constant Field Values

STATUS_REACTIVATED

static final String STATUS_REACTIVATED

See Also:

Constant Field Values

STATUS_ACKNOWLEDGED

static final String STATUS_ACKNOWLEDGED

See Also:

Constant Field Values

STATUS_DISABLED

static final String STATUS_DISABLED

See Also:

Constant Field Values

STATUS_BLOCKED

static final String STATUS_BLOCKED

See Also:

Constant Field Values

EVENT_ENABLING

static final String EVENT_ENABLING

See Also:

Constant Field Values

EVENT_DISABLING

static final String EVENT_DISABLING

See Also:

Constant Field Values

EVENT_BLOCKING

static final String EVENT_BLOCKING

See Also:

Constant Field Values

EVENT_UNBLOCKING

static final String EVENT_UNBLOCKING

See Also:

Constant Field Values

EVENT_ACTIVATION

static final String EVENT_ACTIVATION

See Also:

Constant Field Values

EVENT_DEACTIVATION

static final String EVENT_DEACTIVATION

See Also:

Constant Field Values

EVENT_ACKNOWLEDGEMENT

static final String EVENT_ACKNOWLEDGEMENT

See Also:

Constant Field Values

TRIGGER_ACTIVATE

static final String TRIGGER_ACTIVATE

See Also:

Constant Field Values

TRIGGER_DEACTIVATE

static final String TRIGGER_DEACTIVATE

See Also:

Constant Field Values

TRIGGER_ACKNOWLEDGE

static final String TRIGGER_ACKNOWLEDGE

See Also:

Constant Field Values

TRIGGER_BLOCK

static final String TRIGGER_BLOCK

See Also:

Constant Field Values

TRIGGER_UNBLOCK

static final String TRIGGER_UNBLOCK

See Also:

Constant Field Values

TRIGGER_ENABLE

static final String TRIGGER_ENABLE

See Also:

Constant Field Values

TRIGGER_DISABLE

static final String TRIGGER_DISABLE

See Also:

Constant Field Values

Method Detail

trigger

void trigger(String trigger)
      throws IllegalArgumentException

Trigger a state change.

When the AlarmPoint object receives a trigger, it must consult the AlarmModel and figure out if there is an actual state change occurring and if any AlarmEvents should be fired.

Parameters:

trigger - The trigger to execute if existing in the AlarmModel.

Throws:

IllegalArgumentException - if a trigger is not a known one.

activate

void activate()

Activates an AlarmPoint.

Convenience method for:

       trigger( "activate" );
 
 

deactivate

void deactivate()

Deactivates an AlarmPoint. Convinience method for:

     trigger( "deactivate" );
 

acknowledge

void acknowledge()

Acknowledges an AlarmPoint. Convinience method for:

     trigger( source, "acknowledge" );
 

currentCondition

boolean currentCondition()

Get AlarmPoint condition. To reduce AlarmPoint condition calculations for Implementors, each AlarmPoint should be able to work with a "true/false" trigger. Only changes to this trigger will cause an event.

Returns:

The condition of the AlarmPoint, which is used to simplify trigging of activate and deactivate.

updateCondition

void updateCondition(boolean condition)

Set AlarmPoint condition. To reduce AlarmPoint condition calculations for Implementors, each AlarmPoint should be able to work with a "true/false" trigger. Only changes to this trigger will cause an event. Causes an Activation or Deactivation if state of condition changes.

Parameters:

condition - Sets the AlarmPoint condition.

currentStatus

AlarmStatus currentStatus()

Returns the current state of the standard.

Returns:

The AlarmStatus (interface) object

history

AlarmHistory history()

Returns the AlarmHistory of the standard.

Returns:

The AlarmHistory object, or null if AlarmHistory is not supported.

attributeNames

List<String> attributeNames()

Return all attribute names

Returns:

the names of the attributes of this AlarmPoint.

attribute

String attribute(String name)

Return the attribute of the given name.

Parameters:

name - The name of the attribute to return.

Returns:

the named attribute of this AlarmPoint.

setAttribute

void setAttribute(String name,
                  @Optional
                  String value)

Sets the attribute of the given name.

Parameters:

name - The name of the attribute to set.

value - The value to set the named attribute to.

name

String name()

Returns the Name of the AlarmPoint. This normally returns the human readable technical name of the AlarmPoint.

Returns:

the name of the AlarmPoint.

descriptionInDefaultLocale

String descriptionInDefaultLocale()

Returns a Description of the AlarmPoint. This normally returns a full Description of the AlarmPoint in the default Locale.

Returns:

a human-readable description of the AlarmPoint in the default locale.

description

String description(Locale locale)

Returns a Description of the AlarmPoint. This normally returns a full Description of the AlarmPoint in the Locale. If Locale is null, then the default Locale is used.

Parameters:

locale - The locale to return the description in, or null to use default locale.

Returns:

a human-readable description of the AlarmPoint in the given locale.

alarmClass

@UseDefaults
Property<AlarmClass> alarmClass()

The AlarmClass of the AlarmPoint. The AlarmClass indicates the urgency of AlarmEvents emitted from the AlarmPoint. The property has UseDefaults annotation so that the application developer can set the default during assembly. The default Assembler in this library defaults alarms to AlarmClass B.

Returns:

the property instance that contains the AlarmClass.

category

Property<AlarmCategory> category()

The AlarmCategory of this AlarmPoint. AlarmCategory is used to group Alarms together, which can be used to forward AlarmEvent to different destinations, produce reports for different target audiences or separation of aggregation.

Returns:

the property instance that contains the AlarmCategory.