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