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 java.util.List;
  16
  17 import org.openhab.binding.digitalstrom.internal.lib.event.EventHandler;
  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.stateenums.ManagerStates;
  21 import org.openhab.binding.digitalstrom.internal.lib.listener.stateenums.ManagerTypes;
  22 import org.openhab.binding.digitalstrom.internal.lib.structure.devices.Device;
  23 import org.openhab.binding.digitalstrom.internal.lib.structure.scene.InternalScene;
  24
  25 /**
  26  * The {@link SceneManager} manages all functions concerning scenes without sending the commands itself.
  27  *
  28  * <p>
  29  * So it manages a list of all {@link InternalScene} they called in the past or was generated by calling
  30  * {@link #generateScenes()}.<br>
  31  * Through this class you can also register {@link SceneStatusListener}'s to the {@link InternalScene}'s or register a
  32  * scene discovery. With {@link #addEcho(String)} or {@link #addEcho(String, short)} scene calls form the library can be
  33  * ignored. To update the state of an {@link InternalScene} or {@link Device} the methods
  34  * {@link #callInternalScene(InternalScene)}, {@link #callInternalScene(String)},
  35  * {@link #callDeviceScene(Device, Short)}
  36  * , {@link #callDeviceScene(String, Short)} etc. can be used.
  37  *
  38  * <p>
  39  * If you call the {@link #start()} method an {@link org.openhab.binding.digitalstrom.internal.lib.event.EventListener}
  40  * will be started to handle scene calls and undos from the outside.
  41  *
  42  * @author Michael Ochel - Initial contribution
  43  * @author Matthias Siegele - Initial contribution
  44  *
  45  */
  46 public interface SceneManager extends EventHandler {
  47
  48     /**
  49      * Activates the given {@link InternalScene}, if it exists. Otherwise it will be added to the scene list and
  50      * activated, if it is a callable scene.
  51      *
  52      * @param scene to call
  53      */
  54     void callInternalScene(InternalScene scene);
  55
  56     /**
  57      * Activates an {@link InternalScene} with the given id, if it exists. Otherwise a new
  58      * {@link InternalScene} will be created and activated, if it is a callable scene.
  59      *
  60      * @param sceneID of the scene to call
  61      */
  62     void callInternalScene(String sceneID);
  63
  64     /**
  65      * Call the given sceneID on the {@link Device} with the given dSID, if the {@link Device} exists.
  66      *
  67      * @param dSID of the {@link Device} to call
  68      * @param sceneID of the scene to call
  69      */
  70     void callDeviceScene(String dSID, Short sceneID);
  71
  72     /**
  73      * Call the given sceneID on the given {@link Device}, if the {@link Device} exists.
  74      *
  75      * @param device to call
  76      * @param sceneID to call
  77      */
  78     void callDeviceScene(Device device, Short sceneID);
  79
  80     /**
  81      * Deactivates the given {@link InternalScene}, if it exists. Otherwise it will added to the scene list and
  82      * deactivated, if it is a callable scene.
  83      *
  84      * @param scene to undo
  85      */
  86     void undoInternalScene(InternalScene scene);
  87
  88     /**
  89      * Deactivates an {@link InternalScene} with the given sceneID, if it exists. Otherwise a new
  90      * {@link InternalScene} will be created and deactivated, if it is a callable scene.
  91      *
  92      * @param sceneID of the scene to undo
  93      */
  94     void undoInternalScene(String sceneID);
  95
  96     /**
  97      * Undo the last scene on the {@link Device} with the given dSID, if the {@link Device} exists.
  98      *
  99      * @param dSID of the {@link Device} to undo
 100      */
 101     void undoDeviceScene(String dSID);
 102
 103     /**
 104      * Undo the last scene on the {@link Device}, if the {@link Device} exists.
 105      *
 106      * @param device the {@link Device} to undo
 107      */
 108     void undoDeviceScene(Device device);
 109
 110     /**
 111      * Registers the given {@link SceneStatusListener} to the {@link InternalScene}, if it exists or registers it as a
 112      * Scene-Discovery if the id of the {@link SceneStatusListener} is {@link SceneStatusListener#SCENE_DISCOVERY}.
 113      *
 114      * @param sceneListener to register
 115      */
 116     void registerSceneListener(SceneStatusListener sceneListener);
 117
 118     /**
 119      * Unregisters the given {@link SceneStatusListener} from the {@link InternalScene}, if it exists or unregisters the
 120      * Scene-Discovery, if the id of the {@link SceneStatusListener} is {@link SceneStatusListener#SCENE_DISCOVERY}.
 121      *
 122      * @param sceneListener to register
 123      */
 124     void unregisterSceneListener(SceneStatusListener sceneListener);
 125
 126     /**
 127      * Adds the given {@link InternalScene} to the scene list, if it is a callable scene.
 128      *
 129      * @param intScene to add
 130      */
 131     void addInternalScene(InternalScene intScene);
 132
 133     /**
 134      * Adds the scene call with the given dSID and sceneId as an echo to ignore them by detecting the
 135      * {@link org.openhab.binding.digitalstrom.internal.lib.event.types.EventItem}.
 136      *
 137      * @param dSID of the {@link Device} that will be ignored
 138      * @param sceneId of the scene that will be ignored
 139      */
 140     void addEcho(String dSID, short sceneId);
 141
 142     /**
 143      * Adds the scene call with the given internal scene id as an echo to ignore them by detecting the
 144      * {@link org.openhab.binding.digitalstrom.internal.lib.event.types.EventItem}
 145      * .
 146      *
 147      * @param internalSceneID to ignore
 148      */
 149     void addEcho(String internalSceneID);
 150
 151     /**
 152      * Returns the list of all {@link InternalScene}.
 153      *
 154      * @return list of all scenes
 155      */
 156     List<InternalScene> getScenes();
 157
 158     /**
 159      * Returns true, if all reachable scenes are already generated, otherwise false.
 160      *
 161      * @return true = reachable scenes generated, otherwise false
 162      */
 163     boolean scenesGenerated();
 164
 165     /**
 166      * Generates all reachable scenes.
 167      *
 168      */
 169     void generateScenes();
 170
 171     /**
 172      * Will be called from the {@link org.openhab.binding.digitalstrom.internal.lib.structure.scene.SceneDiscovery},
 173      * if a scene type is generated or is fail.<br>
 174      * For that the scenesGenerated char array has four chars. Each char represents one scene type in the following
 175      * direction:
 176      * <ul>
 177      * <li><b>first:</b> named scenes</li>
 178      * <li><b>second:</b> apartment scenes</li>
 179      * <li><b>third:</b> zone scenes</li>
 180      * <li><b>fourth</b>: group scenes, if they can call by push buttons</li>
 181      * </ul>
 182      * If a scene type is not generated the char is "0". If a scene type is generated the char is "1" and, if it is fail
 183      * the char is "2".
 184      *
 185      * @param scenesGenerated array
 186      */
 187     void scenesGenerated(char[] scenesGenerated);
 188
 189     /**
 190      * Returns true, if a discovery is registered, otherwise false.
 191      *
 192      * @return true discovery is registered, otherwise false
 193      */
 194     boolean isDiscoveryRegistrated();
 195
 196     /**
 197      * Starts the {@link org.openhab.binding.digitalstrom.internal.lib.event.EventListener}.
 198      */
 199     void start();
 200
 201     /**
 202      * Stops the {@link org.openhab.binding.digitalstrom.internal.lib.event.EventListener}.
 203      */
 204     void stop();
 205
 206     /**
 207      * Removes the {@link InternalScene} with the given sceneID.
 208      *
 209      * @param sceneID of the {@link InternalScene} to remove
 210      */
 211     void removeInternalScene(String sceneID);
 212
 213     /**
 214      * Returns the {@link InternalScene} with the given sceneID.
 215      *
 216      * @param sceneID of the {@link InternalScene}
 217      * @return internal scenes
 218      */
 219     InternalScene getInternalScene(String sceneID);
 220
 221     /**
 222      * Registers the given {@link ManagerStatusListener} to this class.
 223      *
 224      * @param statusListener to register
 225      */
 226     void registerStatusListener(ManagerStatusListener statusListener);
 227
 228     /**
 229      * Unregisters the {@link ManagerStatusListener} from this class.
 230      */
 231     void unregisterStatusListener();
 232
 233     /**
 234      * Returns the {@link ManagerTypes} of this class.
 235      *
 236      * @return these {@link ManagerTypes}
 237      */
 238     ManagerTypes getManagerType();
 239
 240     /**
 241      * Returns the current {@link ManagerStates}.
 242      *
 243      * @return current {@link ManagerStates}
 244      */
 245     ManagerStates getManagerState();
 246
 247     /**
 248      * Calls a scene without inform the scene discovery about the conceivably new {@link InternalScene}.
 249      *
 250      * @param zoneID to call
 251      * @param groupID to call
 252      * @param sceneID to call
 253      */
 254     void callInternalSceneWithoutDiscovery(Integer zoneID, Short groupID, Short sceneID);
 255 }