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 EventListener} will be started to handle scene calls and undos from
  40  * 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 {@link EventItem}.
 135      *
 136      * @param dSID of the {@link Device} that will be ignored
 137      * @param sceneId of the scene that will be ignored
 138      */
 139     void addEcho(String dSID, short sceneId);
 140
 141     /**
 142      * Adds the scene call with the given internal scene id as an echo to ignore them by detecting the {@link EventItem}
 143      * .
 144      *
 145      * @param internalSceneID to ignore
 146      */
 147     void addEcho(String internalSceneID);
 148
 149     /**
 150      * Returns the list of all {@link InternalScene}.
 151      *
 152      * @return list of all scenes
 153      */
 154     List<InternalScene> getScenes();
 155
 156     /**
 157      * Returns true, if all reachable scenes are already generated, otherwise false.
 158      *
 159      * @return true = reachable scenes generated, otherwise false
 160      */
 161     boolean scenesGenerated();
 162
 163     /**
 164      * Generates all reachable scenes.
 165      *
 166      */
 167     void generateScenes();
 168
 169     /**
 170      * Will be called from the {@link SceneDiscovery}, if a scene type is generated or is fail.<br>
 171      * For that the scenesGenerated char array has four chars. Each char represents one scene type in the following
 172      * direction:
 173      * <ul>
 174      * <li><b>first:</b> named scenes</li>
 175      * <li><b>second:</b> apartment scenes</li>
 176      * <li><b>third:</b> zone scenes</li>
 177      * <li><b>fourth</b>: group scenes, if they can call by push buttons</li>
 178      * </ul>
 179      * 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
 180      * the char is "2".
 181      *
 182      * @param scenesGenerated array
 183      */
 184     void scenesGenerated(char[] scenesGenerated);
 185
 186     /**
 187      * Returns true, if a discovery is registered, otherwise false.
 188      *
 189      * @return true discovery is registered, otherwise false
 190      */
 191     boolean isDiscoveryRegistrated();
 192
 193     /**
 194      * Starts the {@link EventListener}.
 195      */
 196     void start();
 197
 198     /**
 199      * Stops the {@link EventListener}.
 200      */
 201     void stop();
 202
 203     /**
 204      * Removes the {@link InternalScene} with the given sceneID.
 205      *
 206      * @param sceneID of the {@link InternalScene} to remove
 207      */
 208     void removeInternalScene(String sceneID);
 209
 210     /**
 211      * Returns the {@link InternalScene} with the given sceneID.
 212      *
 213      * @param sceneID of the {@link InternalScene}
 214      * @return internal scenes
 215      */
 216     InternalScene getInternalScene(String sceneID);
 217
 218     /**
 219      * Registers the given {@link ManagerStatusListener} to this class.
 220      *
 221      * @param statusListener to register
 222      */
 223     void registerStatusListener(ManagerStatusListener statusListener);
 224
 225     /**
 226      * Unregisters the {@link ManagerStatusListener} from this class.
 227      */
 228     void unregisterStatusListener();
 229
 230     /**
 231      * Returns the {@link ManagerTypes} of this class.
 232      *
 233      * @return these {@link ManagerTypes}
 234      */
 235     ManagerTypes getManagerType();
 236
 237     /**
 238      * Returns the current {@link ManagerStates}.
 239      *
 240      * @return current {@link ManagerStates}
 241      */
 242     ManagerStates getManagerState();
 243
 244     /**
 245      * Calls a scene without inform the scene discovery about the conceivably new {@link InternalScene}.
 246      *
 247      * @param zoneID to call
 248      * @param groupID to call
 249      * @param sceneID to call
 250      */
 251     void callInternalSceneWithoutDiscovery(Integer zoneID, Short groupID, Short sceneID);
 252 }