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 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 SmartherGatewayException in case of communication issues with the Smarther API
  86      */
  87     List<Subscription> getSubscriptions() throws SmartherGatewayException;
  88
  89     /**
  90      * Subscribes a plant to the C2C Webhook to start receiving modules status notifications.
  91      *
  92      * @param plantId
  93      *            the identifier of the plant to be subscribed
  94      * @param notificationUrl
  95      *            the url notifications will have to be sent to for the given plant
  96      *
  97      * @return the identifier this subscription has been registered under
  98      *
  99      * @throws SmartherGatewayException in case of communication issues with the Smarther API
 100      */
 101     String subscribePlant(String plantId, String notificationUrl) throws SmartherGatewayException;
 102
 103     /**
 104      * Unsubscribes a plant from the C2C Webhook to stop receiving modules status notifications.
 105      *
 106      * @param plantId
 107      *            the identifier of the plant to be unsubscribed
 108      * @param subscriptionId
 109      *            the identifier of the subscription to be removed for the given plant
 110      *
 111      * @throws SmartherGatewayException in case of communication issues with the Smarther API
 112      */
 113     void unsubscribePlant(String plantId, String subscriptionId) throws SmartherGatewayException;
 114
 115     /**
 116      * Returns the chronothermostat modules registered at the given location.
 117      *
 118      * @param location
 119      *            the identifier of the location
 120      *
 121      * @return the list of registered modules, or an empty {@link List} if the location contains no module or in case of
 122      *         communication issues with the Smarther API
 123      */
 124     List<Module> getLocationModules(Location location);
 125
 126     /**
 127      * Returns the current status of a given chronothermostat module.
 128      *
 129      * @param plantId
 130      *            the identifier of the plant
 131      * @param moduleId
 132      *            the identifier of the chronothermostat module inside the plant
 133      *
 134      * @return the current status of the chronothermostat module
 135      *
 136      * @throws SmartherGatewayException in case of communication issues with the Smarther API
 137      */
 138     ModuleStatus getModuleStatus(String plantId, String moduleId) throws SmartherGatewayException;
 139
 140     /**
 141      * Sends new settings to be applied to a given chronothermostat module.
 142      *
 143      * @param moduleSettings
 144      *            the module settings to be applied
 145      *
 146      * @return {@code true} if the settings have been successfully applied, {@code false} otherwise
 147      *
 148      * @throws SmartherGatewayException in case of communication issues with the Smarther API
 149      */
 150     boolean setModuleStatus(ModuleSettings moduleSettings) throws SmartherGatewayException;
 151
 152     /**
 153      * Returns the automatic mode programs registered for the given chronothermostat module.
 154      *
 155      * @param plantId
 156      *            the identifier of the plant
 157      * @param moduleId
 158      *            the identifier of the chronothermostat module inside the plant
 159      *
 160      * @return the list of registered programs, or an empty {@link List} in case of no programs found
 161      *
 162      * @throws SmartherGatewayException in case of communication issues with the Smarther API
 163      */
 164     List<Program> getModulePrograms(String plantId, String moduleId) throws SmartherGatewayException;
 165
 166     /**
 167      * Checks whether the Smarther Bridge associated with this Smarther account handler is authorized by Smarther API.
 168      *
 169      * @return {@code true} if the Bridge is authorized, {@code false} otherwise
 170      */
 171     boolean isAuthorized();
 172
 173     /**
 174      * Checks whether the Smarther Bridge thing is online.
 175      *
 176      * @return {@code true} if the Bridge is online, {@code false} otherwise
 177      */
 178     boolean isOnline();
 179
 180     /**
 181      * Performs the authorization procedure with Legrand/Bticino portal.
 182      * In case of success, the returned refresh/access tokens and the notification url are stored in the Bridge.
 183      *
 184      * @param redirectUrl
 185      *            the redirect url BTicino/Legrand portal calls back to
 186      * @param reqCode
 187      *            the unique code passed by BTicino/Legrand portal to obtain the refresh and access tokens
 188      * @param notificationUrl
 189      *            the endpoint C2C Webhook service will send module status notifications to, once authorized
 190      *
 191      * @return a string containing the name of the BTicino/Legrand portal user that is authorized
 192      */
 193     String authorize(String redirectUrl, String reqCode, String notificationUrl) throws SmartherGatewayException;
 194
 195     /**
 196      * Compares this Smarther account handler instance to a given Thing UID.
 197      *
 198      * @param thingUID
 199      *            the Thing UID the account handler is compared to
 200      *
 201      * @return {@code true} if the two instances match, {@code false} otherwise
 202      */
 203     boolean equalsThingUID(String thingUID);
 204
 205     /**
 206      * Formats the url used to call the Smarther API in order to authorize the Smarther Bridge associated with this
 207      * Smarther account handler.
 208      *
 209      * @param redirectUri
 210      *            the uri BTicino/Legrand portal redirects back to
 211      *
 212      * @return a string containing the formatted url, or the empty string ("") in case of issue
 213      */
 214     String formatAuthorizationUrl(String redirectUri);
 215 }