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.bticinosmarther.internal.account;
  14
  15 import java.util.List;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18 import org.openhab.binding.bticinosmarther.internal.api.dto.Location;
  19 import org.openhab.binding.bticinosmarther.internal.api.dto.Module;
  20 import org.openhab.binding.bticinosmarther.internal.api.dto.ModuleStatus;
  21 import org.openhab.binding.bticinosmarther.internal.api.dto.Plant;
  22 import org.openhab.binding.bticinosmarther.internal.api.dto.Program;
  23 import org.openhab.binding.bticinosmarther.internal.api.dto.Subscription;
  24 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherGatewayException;
  25 import org.openhab.binding.bticinosmarther.internal.model.ModuleSettings;
  26 import org.openhab.core.thing.ThingUID;
  27 import org.openhab.core.thing.binding.ThingHandler;
  28
  29 /**
  30  * The {@code SmartherAccountHandler} interface is used to decouple the Smarther account handler implementation from
  31  * other Bridge code.
  32  *
  33  * @author Fabio Possieri - Initial contribution
  34  */
  35 @NonNullByDefault
  36 public interface SmartherAccountHandler extends ThingHandler {
  37
  38     /**
  39      * Returns the {@link ThingUID} associated with this Smarther account handler.
  40      *
  41      * @return the thing UID associated with this Smarther account handler
  42      */
  43     ThingUID getUID();
  44
  45     /**
  46      * Returns the label of the Smarther Bridge associated with this Smarther account handler.
  47      *
  48      * @return a string containing the bridge label associated with the account handler
  49      */
  50     String getLabel();
  51
  52     /**
  53      * Returns the available locations associated with this Smarther account handler.
  54      *
  55      * @return the list of available locations, or an empty {@link List} in case of no locations found
  56      */
  57     List<Location> getLocations();
  58
  59     /**
  60      * Checks whether the given location is managed by this Smarther account handler
  61      *
  62      * @param plantId
  63      *            the identifier of the location to search for
  64      *
  65      * @return {@code true} if the given location is found, {@code false} otherwise
  66      */
  67     boolean hasLocation(String plantId);
  68
  69     /**
  70      * Returns the plants registered under the Smarther account the bridge has been configured with.
  71      *
  72      * @return the list of registered plants, or an empty {@link List} in case of no plants found
  73      *
  74      * @throws {@link SmartherGatewayException}
  75      *             in case of communication issues with the Smarther API
  76      */
  77     List<Plant> getPlants() throws SmartherGatewayException;
  78
  79     /**
  80      * Returns the subscriptions registered to the C2C Webhook, where modules status notifications are currently sent
  81      * for all the plants.
  82      *
  83      * @return the list of registered subscriptions, or an empty {@link List} in case of no subscriptions found
  84      *
  85      * @throws {@link SmartherGatewayException}
  86      *             in case of communication issues with the Smarther API
  87      */
  88     List<Subscription> getSubscriptions() throws SmartherGatewayException;
  89
  90     /**
  91      * Subscribes a plant to the C2C Webhook to start receiving modules status notifications.
  92      *
  93      * @param plantId
  94      *            the identifier of the plant to be subscribed
  95      * @param notificationUrl
  96      *            the url notifications will have to be sent to for the given plant
  97      *
  98      * @return the identifier this subscription has been registered under
  99      *
 100      * @throws {@link SmartherGatewayException}
 101      *             in case of communication issues with the Smarther API
 102      */
 103     String subscribePlant(String plantId, String notificationUrl) throws SmartherGatewayException;
 104
 105     /**
 106      * Unsubscribes a plant from the C2C Webhook to stop receiving modules status notifications.
 107      *
 108      * @param plantId
 109      *            the identifier of the plant to be unsubscribed
 110      * @param subscriptionId
 111      *            the identifier of the subscription to be removed for the given plant
 112      *
 113      * @return {@code true} if the plant is successfully unsubscribed, {@code false} otherwise
 114      *
 115      * @throws {@link SmartherGatewayException}
 116      *             in case of communication issues with the Smarther API
 117      */
 118     void unsubscribePlant(String plantId, String subscriptionId) throws SmartherGatewayException;
 119
 120     /**
 121      * Returns the chronothermostat modules registered at the given location.
 122      *
 123      * @param location
 124      *            the identifier of the location
 125      *
 126      * @return the list of registered modules, or an empty {@link List} if the location contains no module or in case of
 127      *         communication issues with the Smarther API
 128      */
 129     List<Module> getLocationModules(Location location);
 130
 131     /**
 132      * Returns the current status of a given chronothermostat module.
 133      *
 134      * @param plantId
 135      *            the identifier of the plant
 136      * @param moduleId
 137      *            the identifier of the chronothermostat module inside the plant
 138      *
 139      * @return the current status of the chronothermostat module
 140      *
 141      * @throws {@link SmartherGatewayException}
 142      *             in case of communication issues with the Smarther API
 143      */
 144     ModuleStatus getModuleStatus(String plantId, String moduleId) throws SmartherGatewayException;
 145
 146     /**
 147      * Sends new settings to be applied to a given chronothermostat module.
 148      *
 149      * @param settings
 150      *            the module settings to be applied
 151      *
 152      * @return {@code true} if the settings have been successfully applied, {@code false} otherwise
 153      *
 154      * @throws {@link SmartherGatewayException}
 155      *             in case of communication issues with the Smarther API
 156      */
 157     boolean setModuleStatus(ModuleSettings moduleSettings) throws SmartherGatewayException;
 158
 159     /**
 160      * Returns the automatic mode programs registered for the given chronothermostat module.
 161      *
 162      * @param plantId
 163      *            the identifier of the plant
 164      * @param moduleId
 165      *            the identifier of the chronothermostat module inside the plant
 166      *
 167      * @return the list of registered programs, or an empty {@link List} in case of no programs found
 168      *
 169      * @throws {@link SmartherGatewayException}
 170      *             in case of communication issues with the Smarther API
 171      */
 172     List<Program> getModulePrograms(String plantId, String moduleId) throws SmartherGatewayException;
 173
 174     /**
 175      * Checks whether the Smarther Bridge associated with this Smarther account handler is authorized by Smarther API.
 176      *
 177      * @return {@code true} if the Bridge is authorized, {@code false} otherwise
 178      */
 179     boolean isAuthorized();
 180
 181     /**
 182      * Checks whether the Smarther Bridge thing is online.
 183      *
 184      * @return {@code true} if the Bridge is online, {@code false} otherwise
 185      */
 186     boolean isOnline();
 187
 188     /**
 189      * Performs the authorization procedure with Legrand/Bticino portal.
 190      * In case of success, the returned refresh/access tokens and the notification url are stored in the Bridge.
 191      *
 192      * @param redirectUrl
 193      *            the redirect url BTicino/Legrand portal calls back to
 194      * @param reqCode
 195      *            the unique code passed by BTicino/Legrand portal to obtain the refresh and access tokens
 196      * @param notificationUrl
 197      *            the endpoint C2C Webhook service will send module status notifications to, once authorized
 198      *
 199      * @return a string containing the name of the BTicino/Legrand portal user that is authorized
 200      */
 201     String authorize(String redirectUrl, String reqCode, String notificationUrl) throws SmartherGatewayException;
 202
 203     /**
 204      * Compares this Smarther account handler instance to a given Thing UID.
 205      *
 206      * @param thingUID
 207      *            the Thing UID the account handler is compared to
 208      *
 209      * @return {@code true} if the two instances match, {@code false} otherwise
 210      */
 211     boolean equalsThingUID(String thingUID);
 212
 213     /**
 214      * Formats the url used to call the Smarther API in order to authorize the Smarther Bridge associated with this
 215      * Smarther account handler.
 216      *
 217      * @param redirectUri
 218      *            the uri BTicino/Legrand portal redirects back to
 219      *
 220      * @return a string containing the formatted url, or the empty string ("") in case of issue
 221      */
 222     String formatAuthorizationUrl(String redirectUri);
 223 }