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

   1 /**
   2  * Copyright (c) 2010-2023 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.digitalstrom.internal.lib.manager;
  14
  15 import org.openhab.binding.digitalstrom.internal.lib.event.EventHandler;
  16 import org.openhab.binding.digitalstrom.internal.lib.listener.ConnectionListener;
  17 import org.openhab.binding.digitalstrom.internal.lib.listener.DeviceStatusListener;
  18 import org.openhab.binding.digitalstrom.internal.lib.listener.ManagerStatusListener;
  19 import org.openhab.binding.digitalstrom.internal.lib.listener.SceneStatusListener;
  20 import org.openhab.binding.digitalstrom.internal.lib.listener.TotalPowerConsumptionListener;
  21 import org.openhab.binding.digitalstrom.internal.lib.listener.stateenums.ManagerStates;
  22 import org.openhab.binding.digitalstrom.internal.lib.listener.stateenums.ManagerTypes;
  23 import org.openhab.binding.digitalstrom.internal.lib.sensorjobexecutor.sensorjob.SensorJob;
  24 import org.openhab.binding.digitalstrom.internal.lib.structure.devices.Device;
  25 import org.openhab.binding.digitalstrom.internal.lib.structure.devices.deviceparameters.DeviceStateUpdate;
  26 import org.openhab.binding.digitalstrom.internal.lib.structure.scene.InternalScene;
  27
  28 /**
  29  * <p>
  30  * The {@link DeviceStatusManager} is responsible for the synchronization between the internal model of the
  31  * digitalSTROM-devices and the real existing digitalSTROM-devices. You can change the state of a device by sending a
  32  * direct command to the devices or by calling a scene. Furthermore the {@link DeviceStatusManager} get informed over
  33  * the {@link SceneManager} by the {@link EventListener} if scenes are called by external sources. All
  34  * configurations of the physically device will be synchronized to the internally managed model and updated as required.
  35  * The {@link DeviceStatusManager} also initializes {@link SensorJob}'s with the {@link SensorJobExecutor} and
  36  * {@link SceneReadingJobExecutor} to update required sensor and scene data.
  37  *
  38  * <p>
  39  * Therefore the {@link DeviceStatusManager} uses the {@link StructureManager} for the internal management of the
  40  * structure of the digitalSTROM-system, {@link ConnectionManager} to check the connectivity,
  41  * {@link SceneManager} to identify externally called scenes and to update the affected devices of these
  42  * called scenes to the internal model. The most methods of the above-named managers will be directly called over the
  43  * {@link DeviceStatusManager}, because they are linked to the affected managers.
  44  *
  45  * <p>
  46  * To get informed by all relevant information you can register some useful listeners. Here the list of all listeners
  47  * which can registered or unregistered:
  48  * </p>
  49  * <ul>
  50  * <li>{@link DeviceStatusListener} over {@link #registerDeviceListener(DeviceStatusListener)} respectively
  51  * {@link #unregisterDeviceListener(DeviceStatusListener)}</li>
  52  * <li>{@link SceneStatusListener} over {@link #registerSceneListener(SceneStatusListener)} respectively
  53  * {@link #unregisterSceneListener(SceneStatusListener)}</li>
  54  * <li>{@link TotalPowerConsumptionListener} over
  55  * {@link #registerTotalPowerConsumptionListener(TotalPowerConsumptionListener)} respectively
  56  * {@link #unregisterTotalPowerConsumptionListener()}</li>
  57  * <li>{@link ManagerStatusListener} over {@link #registerStatusListener(ManagerStatusListener)}
  58  * respectively {@link #unregisterStatusListener()}</li>
  59  * <li>{@link ConnectionListener} over {@link #registerDeviceListener(DeviceStatusListener)} respectively
  60  * {@link #unregisterDeviceListener(DeviceStatusListener)}</li>
  61  * </ul>
  62  * For what the listener can be used please have a look at the listener.
  63  *
  64  * @author Michael Ochel - Initial contribution
  65  * @author Matthias Siegele - Initial contribution
  66  */
  67 public interface DeviceStatusManager extends EventHandler {
  68
  69     /**
  70      * Starts the working process for device synchronization. It also starts the {@link SensorJobExecutor} and the
  71      * {@link SceneReadingJobExecutor} and the {@link SceneManager}.
  72      */
  73     void start();
  74
  75     /**
  76      * Stops the working process for device synchronization. It also stops the {@link SensorJobExecutor} and the
  77      * {@link SceneReadingJobExecutor} and the {@link SceneManager}.
  78      */
  79     void stop();
  80
  81     /**
  82      * This method sends a call scene command for the given {@link InternalScene}, if call_undo is true otherwise it
  83      * sends a undo command.
  84      * <br>
  85      * It also updates the scene state, if the command was send successful.
  86      *
  87      * @param scene to call
  88      * @param call_undo (true = call | false = undo)
  89      */
  90     void sendSceneComandsToDSS(InternalScene scene, boolean call_undo);
  91
  92     /**
  93      * This method sends a stop command for the given {@link Device}.
  94      * <br>
  95      * It also reads out the current output value of the device and updates it, if the command was send successful.
  96      *
  97      * @param device which will send a stop command
  98      */
  99     void sendStopComandsToDSS(Device device);
 100
 101     /**
 102      * This method sends the command for the given {@link DeviceStateUpdate} for the given {@link Device}. Please have a
 103      * look at {@link DeviceStateUpdate} to see what types is there and how the value {@link DeviceStateUpdate} will be
 104      * evaluated.
 105      * <br>
 106      * It also updates the device if the command was send successful.
 107      *
 108      * @param device device which will send a command
 109      * @param deviceStateUpdate command to send
 110      */
 111     void sendComandsToDSS(Device device, DeviceStateUpdate deviceStateUpdate);
 112
 113     /**
 114      * This method adds a {@link SensorJob} with the appropriate priority to the {@link SensorJob}.
 115      *
 116      * @param sensorJob to update sensor data
 117      * @param priority to update
 118      */
 119     void updateSensorData(SensorJob sensorJob, String priority);
 120
 121     /**
 122      * This method adds a {@link SensorJob} with the appropriate priority to the {@link SceneReadingJobExecutor}.
 123      *
 124      * @param device device which will update scene data
 125      * @param deviceStateUpdate scene data to update
 126      */
 127     void updateSceneData(Device device, DeviceStateUpdate deviceStateUpdate);
 128
 129     /**
 130      * Registers the given {@link DeviceStatusListener} to the {@link Device}, if it exists or registers it as a
 131      * device discovery, if the id of the {@link DeviceStatusListener} is {@link DeviceStatusListener#DEVICE_DISCOVERY}.
 132      *
 133      * @param deviceListener to rigister
 134      */
 135     void registerDeviceListener(DeviceStatusListener deviceListener);
 136
 137     /**
 138      * Unregisters the given {@link DeviceStatusListener} from the {@link Device}, if it exists or unregisters the
 139      * device discovery, if the id of the {@link DeviceStatusListener} is {@link DeviceStatusListener#DEVICE_DISCOVERY}.
 140      *
 141      * @param deviceListener to unregister
 142      */
 143     void unregisterDeviceListener(DeviceStatusListener deviceListener);
 144
 145     /**
 146      * Registers the given {@link TotalPowerConsumptionListener} to this {@link DeviceStatusManager}.
 147      *
 148      * @param totalPowerConsumptionListener to register
 149      */
 150     void registerTotalPowerConsumptionListener(TotalPowerConsumptionListener totalPowerConsumptionListener);
 151
 152     /**
 153      * Unregisters the {@link TotalPowerConsumptionListener} from this {@link DeviceStatusManager}.
 154      */
 155     void unregisterTotalPowerConsumptionListener();
 156
 157     /**
 158      * Registers the given {@link SceneStatusListener} to the {@link InternalScene}, if it exists or registers it as a
 159      * scene discovery to the {@link SceneManager}, if the id of the {@link SceneStatusListener} is
 160      * {@link SceneStatusListener#SCENE_DISCOVERY}.
 161      *
 162      * @param sceneListener to register
 163      */
 164     void registerSceneListener(SceneStatusListener sceneListener);
 165
 166     /**
 167      * Unregisters the given {@link SceneStatusListener} from the {@link InternalScene} if it exist or unregisters the
 168      * scene discovery from the {@link SceneManager}, if the id of the {@link SceneStatusListener} is
 169      * {@link SceneStatusListener#SCENE_DISCOVERY}.
 170      *
 171      * @param sceneListener to unregister
 172      */
 173     void unregisterSceneListener(SceneStatusListener sceneListener);
 174
 175     /**
 176      * Registers the given {@link ConnectionListener} to the {@link ConnectionManager}.
 177      *
 178      * @param connectionListener to register
 179      */
 180     void registerConnectionListener(ConnectionListener connectionListener);
 181
 182     /**
 183      * Unregisters the {@link ConnectionListener} from the {@link ConnectionManager}.
 184      */
 185     void unregisterConnectionListener();
 186
 187     /**
 188      * Removes the {@link Device} with the given dSID from the internal model, if it exists.
 189      *
 190      * @param dSID of the {@link Device} which will be removed
 191      */
 192     void removeDevice(String dSID);
 193
 194     /**
 195      * Registers the given {@link ManagerStatusListener} to all available managers. What manager are available please
 196      * have a look at {@link ManagerTypes}.
 197      *
 198      * @param statusListener to register
 199      */
 200     void registerStatusListener(ManagerStatusListener statusListener);
 201
 202     /**
 203      * Unregisters the {@link ManagerStatusListener} from all available managers. What manager are available please have
 204      * a look at {@link ManagerTypes}.
 205      */
 206     void unregisterStatusListener();
 207
 208     /**
 209      * Returns the {@link ManagerTypes} of this class.
 210      *
 211      * @return these {@link ManagerTypes}
 212      */
 213     ManagerTypes getManagerType();
 214
 215     /**
 216      * Returns the current {@link ManagerStates}.
 217      *
 218      * @return current {@link ManagerStates}
 219      */
 220     ManagerStates getManagerState();
 221
 222     /**
 223      * Reads the current total power consumption out and returns it.
 224      *
 225      * @return the current total power consumption
 226      */
 227     int getTotalPowerConsumption();
 228
 229     /**
 230      * Reads the current total energy meter value in Wh out and returns it.
 231      *
 232      * @return the current total energy meter value Wh
 233      */
 234     int getTotalEnergyMeterValue();
 235
 236     /**
 237      * Reads the current total energy meter value in Ws out and returns it.
 238      *
 239      * @return the current total energy meter value in Ws
 240      */
 241     int getTotalEnergyMeterWsValue();
 242 }