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.config.Config;
  16 import org.openhab.binding.digitalstrom.internal.lib.listener.ConnectionListener;
  17 import org.openhab.binding.digitalstrom.internal.lib.serverconnection.DsAPI;
  18 import org.openhab.binding.digitalstrom.internal.lib.serverconnection.HttpTransport;
  19
  20 /**
  21  * The {@link ConnectionManager} manages the connection to a digitalSTROM-Server.
  22  *
  23  * @author Michael Ochel - Initial contribution
  24  * @author Matthias Siegele - Initial contribution
  25  */
  26 public interface ConnectionManager {
  27
  28     public static final int GENERAL_EXCEPTION = -1;
  29     public static final int MALFORMED_URL_EXCEPTION = -2;
  30     public static final int CONNECTION_EXCEPTION = -3;
  31     public static final int SOCKET_TIMEOUT_EXCEPTION = -4;
  32     public static final int UNKNOWN_HOST_EXCEPTION = -5;
  33     public static final int AUTHENTIFICATION_PROBLEM = -6;
  34     public static final int SSL_HANDSHAKE_EXCEPTION = -7;
  35
  36     /**
  37      * Returns the {@link HttpTransport} to execute queries or special commands on the digitalSTROM-Server.
  38      *
  39      * @return the HttpTransport
  40      */
  41     HttpTransport getHttpTransport();
  42
  43     /**
  44      * Returns the {@link DsAPI} to execute commands on the digitalSTROM-Server.
  45      *
  46      * @return the DsAPI
  47      */
  48     DsAPI getDigitalSTROMAPI();
  49
  50     /**
  51      * This method has to be called before each command to check the connection to the digitalSTROM-Server.
  52      * It examines the connection to the server, sets a new Session-Token, if it is expired and sets a new
  53      * Application-Token, if none it set at the digitalSTROM-Server. It also outputs the specific connection failure.
  54      *
  55      * @return true if the connection is established and false if not
  56      */
  57     boolean checkConnection();
  58
  59     /**
  60      * Returns the current Session-Token.
  61      *
  62      * @return Session-Token
  63      */
  64     String getSessionToken();
  65
  66     /**
  67      * Returns the auto-generated or user defined Application-Token.
  68      *
  69      * @return Application-Token
  70      */
  71     String getApplicationToken();
  72
  73     /**
  74      * Registers a {@link ConnectionListener} to this {@link ConnectionManager}.
  75      *
  76      * @param connectionListener to register
  77      */
  78     void registerConnectionListener(ConnectionListener connectionListener);
  79
  80     /**
  81      * Unregisters the {@link ConnectionListener} from this {@link ConnectionManager}.
  82      */
  83     void unregisterConnectionListener();
  84
  85     /**
  86      * Revokes the saved Application-Token from the digitalSTROM-Server and returns true if the Application-Token was
  87      * revoke successful, otherwise false.
  88      *
  89      * @return successful = true, otherwise false
  90      */
  91     boolean removeApplicationToken();
  92
  93     /**
  94      * Updates the login configuration.
  95      *
  96      * @param hostAddress of the digitalSTROM-Server
  97      * @param username to login
  98      * @param password to login
  99      * @param applicationToken to login
 100      */
 101     void updateConfig(String hostAddress, String username, String password, String applicationToken);
 102
 103     /**
 104      * Updates the {@link Config} with the given config.
 105      *
 106      * @param config to update
 107      */
 108     void updateConfig(Config config);
 109
 110     /**
 111      * Returns the {@link Config}.
 112      *
 113      * @return the config
 114      */
 115     Config getConfig();
 116
 117     /**
 118      * Informs this {@link ConnectionManager} that the {@link Config} has been updated.
 119      */
 120     void configHasBeenUpdated();
 121
 122     /**
 123      * Generates and returns a new session token.
 124      *
 125      * @return new session token
 126      */
 127     String getNewSessionToken();
 128
 129     /**
 130      * Checks the connection through the given HTTP-Response-Code or exception code. If a {@link ConnectionListener} is
 131      * registered this method also informs the registered {@link ConnectionListener} if the connection state has
 132      * changed. <br>
 133      * <br>
 134      * <b>Exception-Codes:</b><br>
 135      * <b>{@link #GENERAL_EXCEPTION}</b> general exception<br>
 136      * <b>{@link #MALFORMED_URL_EXCEPTION}</b> MalformedURLException<br>
 137      * <b>{@link #CONNECTION_EXCEPTION}</b> java.net.ConnectException<br>
 138      * <b>{@link #SOCKET_TIMEOUT_EXCEPTION}</b> SocketTimeoutException<br>
 139      * <b>{@link #UNKNOWN_HOST_EXCEPTION}</b> java.net.UnknownHostException<br>
 140      * <br>
 141      * <b>Code for authentication problems:</b> {@link #AUTHENTIFICATION_PROBLEM}<br>
 142      *
 143      *
 144      * @param code exception or HTTP-Response-Code
 145      * @return true, if connection is valid
 146      */
 147     boolean checkConnection(int code);
 148
 149     /**
 150      * Returns true, if connection is established, otherwise false.
 151      *
 152      * @return true, if connection is established, otherwise false
 153      */
 154     boolean connectionEstablished();
 155 }