git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2024 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.mqtt.generic;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17
  18 /**
  19  * Interface to keep track of the availability of device using an availability topic or messages received
  20  *
  21  * @author Jochen Klein - Initial contribution
  22  * @author Cody Cutrer - Support all/any/latest
  23  */
  24 @NonNullByDefault
  25 public interface AvailabilityTracker {
  26     /**
  27      * controls the conditions needed to set the entity to available
  28      */
  29     enum AvailabilityMode {
  30         /**
  31          * payload_available must be received on all configured availability topics before the entity is marked as
  32          * online
  33          */
  34         ALL,
  35
  36         /**
  37          * payload_available must be received on at least one configured availability topic before the entity is marked
  38          * as online
  39          */
  40         ANY,
  41
  42         /**
  43          * the last payload_available or payload_not_available received on any configured availability topic controls
  44          * the availability
  45          */
  46         LATEST
  47     }
  48
  49     /**
  50      * Sets how multiple availability topics are treated
  51      */
  52     void setAvailabilityMode(AvailabilityMode mode);
  53
  54     /**
  55      * Adds an availability topic to determine the availability of a device.
  56      * <p>
  57      * Availability topics are usually set by the device as LWT.
  58      *
  59      * @param availability_topic
  60      * @param payload_available
  61      * @param payload_not_available
  62      */
  63     void addAvailabilityTopic(String availability_topic, String payload_available, String payload_not_available);
  64
  65     /**
  66      * Adds an availability topic to determine the availability of a device.
  67      * <p>
  68      * Availability topics are usually set by the device as LWT.
  69      *
  70      * @param availability_topic The MQTT topic where availability is published to.
  71      * @param payload_available The value for the topic to indicate the device is online.
  72      * @param payload_not_available The value for the topic to indicate the device is offline.
  73      * @param transformation_pattern A transformation pattern to process the value before comparing to
  74      *            payload_available/payload_not_available.
  75      * @param transformationServiceProvider The service provider to obtain the transformation service (required only if
  76      *            transformation_pattern is not null).
  77      */
  78     void addAvailabilityTopic(String availability_topic, String payload_available, String payload_not_available,
  79             @Nullable String transformation_pattern,
  80             @Nullable TransformationServiceProvider transformationServiceProvider);
  81
  82     void removeAvailabilityTopic(String availability_topic);
  83
  84     void clearAllAvailabilityTopics();
  85
  86     /**
  87      * resets the indicator, if messages have been received.
  88      * <p>
  89      * This is used to time out the availability of the device after some time without receiving a message.
  90      */
  91     void resetMessageReceived();
  92 }