# Package org.qi4j.library.alarm

Alarm Systems.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AlarmCategory | AlarmCategory is intended to be sub-interfaced, to create an explicit type for the domain where it is used.
  AlarmEvent | Event for indicating change of AlarmStatus of an AlarmPoint.
  AlarmHistory | History of an AlarmPoint.
  AlarmListener | Listener for AlarmEvents.
  AlarmModel | Definition of the behaviour of the alarm model.
  AlarmPoint | Defines the basic AlarmPoint 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.
  AlarmPointEntity |
  AlarmPointFactory |
  AlarmProxy |
  AlarmProxy.Factory |
  AlarmStatus | Status of an AlarmPoint.
  AlarmStatus.State |
  AlarmSystem | Defines the AlarmSystem interface.
  AlarmSystemService |
  ExtendedAlarmModelService | The Standard Model is centered around the Normal, Activated, Acknowledged Deactivated, Reactivated, Blocked and Disabled states, and the triggers "activate", "deactivate", "acknowledge", "block", "unblock", "enable" and "disable".
  SimpleAlarmCategory | The SimpleAlarmCategory only defines an optional Description property, and is provided more as an example of how `AlarmCategory` may be extended.
  SimpleAlarmModelService |
  StandardAlarmModelService | The Standard AlarmPoint Model is centered around the Normal, Activated, Acknowledged and Deactivated states, and the triggers "activate", "deactivate", and "acknowledge".

- Class Summary
  Class | Description
  --- | ---
  AlarmEvent.Mixin |
  AlarmHistory.AlarmHistoryMixin |
  AlarmModelDescriptor |
  AlarmNameFormat.AlarmNameConstraint |
  AlarmPoint.AlarmPointMixin |
  AlarmPointFactory.Mixin |
  AlarmProxy.FactoryMixin |
  AlarmProxy.Mixin |
  AlarmStatus.AlarmStatusMixin |
  AlarmSystem.AlarmSystemMixin | AlarmSystem implementation.
  AlarmSystemAssembler |
  ExtendedAlarmModelService.ExtendedAlarmModelMixin |
  SimpleAlarmModelService.SimpleAlarmModelMixin | The Simple AlarmPoint Model is centered around the Normal and Activated.
  StandardAlarmModelService.StandardAlarmModelMixin |

- Enum Summary
  Enum | Description
  --- | ---
  AlarmClass | AlarmClass is required attribute for Alarms, to indicate the urgency of the AlarmPoint.

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  AlarmNameFormat | The definition of the format of AlarmPoint system names.

## Package org.qi4j.library.alarm Description

# Alarm Systems.

Alarm Systems are originally used in Industrial Automation and Process Control systems, to monitor the health of external devices and software functions in large scale plants. The semantics in an Alarm system are well-defined and allows for excellent aggregation and overviews, fine-grained workflow of system health issues and rich data sets around any issues.

This Alarm System, that is based on Zest's excellent persistence support, is an attempt at bringing a first-class model from the industrial automation world into the enterprise of large-scale software systems, that nowadays are so large and un-wieldly that log files, syslog and emails can no longer cope with the burden of management needs.

# The Conceptual Model

Although the inner details of an alarm system can be hard to fully understand, the conceptual model is fairly straight forward, and can be described with Alarm,Alarm Trigger, Alarm Status and Alarm Event. The behavior of the Alarm state machine, hence the workflow, is dictated by an Alarm Model.

Looking at each of these in greater detail.

## Alarm

An Alarm is a tiny state-machine that tracks the Alarm Status (see below). An Alarm has certain attributes that are always present and custom attributes that are suitable for the domain in which the Alarm is being used. The Alarm Class and Alarm Category are attributes that are always present, together with an Alarm Name and an Alarm Description.

## Alarm Class

There are 4 Alarm Classes, A to D, indicating the urgency if an Alarm Event is occurring on the Alarm.

## Alarm Category

Alarm Category is a required attribute on the Alarm to indicate the target audience that needs to be informed about it. This can be used to differentiate between infrastructure concerns versus domain model issues, or direct Alarm Events to different recipients.

## Alarm Model

The Alarm Model defines which Alarm Status types, Alarm Event types, Alarm Triggers and the behavior of the state machine in the Alarm itself.

The Alarm Model is an Zest™ `Service` and located via the normal `Visibility` rules, making it possible to have a different Alarm Model in each Zest™ module.

## Alarm Status

The Alarm always has an Alarm Status. Most Alarm Models will have a Normal status which the Alarm is set to initially, and Activated is likely to be present as well. The Alarm Status only changes from one status to another through the use of an Alarm Trigger, but all triggers doesn't cause the Alarm Status to change.

## Alarm Event

Whenever an Alarm changes its Alarm Status an Alarm Event is sent to all Alarm Listeners. Alarm Listeners are registered to the Alarm System. Alarm Event types are defined by the Alarm Model. Some common Alarm Event types/names are "activation", "acknowledgement" and "deactivation".

## Alarm Trigger

Alarm Triggers are used to forward the workflow. The Alarm Model defines the available Alarm Triggers which are all plain Strings. Alarm Triggers are "commanding" such as "block", "activate" and "disable".

# State Management

Alarm instances are Zest™ Entities, so the Alarm Status is preserved over time in persisted storage. This in turn means that the Alarm must be accessed within a `UnitOfWork` and the Alarm is not valid outside the `UnitOfWork`.

For Entities that needs Alarms, this is fairly straight forward, by making an `@Aggregated Association<Alarm> alarm;` and have it being created in the Entity `LifeCycle`. For non-entities, this becomes a little bit trickier. After the Alarm is created the `Identity` of the Alarm needs to be preserved and used to retrieve the Alarm when it needs to be Triggered. It is NOT possible to put an Alarm `Association` in a Service's `configuration`, since you will not be able to access the `Configuration` members within the `UnitOfWork` managed by the configuration system.