org.qi4j.library.alarm

## Interface AlarmPoint

- All Known Subinterfaces:
    AlarmPointEntity, AlarmProxy
  All Known Implementing Classes:
    AlarmPoint.AlarmPointMixin, AlarmProxy.Mixin

      public interface AlarmPoint

  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.

  - ### 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`

  - ### Method Summary

    Methods
    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.

- - ### 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 `AlarmEvent`s 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`.