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.mielecloud.internal.auth;
  14
  15 import java.util.Optional;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18
  19 /**
  20  * An {@link OAuthTokenRefresher} offers convenient access to OAuth 2 authentication related functionality,
  21  * especially refreshing the access token.
  22  *
  23  * @author Roland Edelhoff - Initial contribution
  24  * @author Björn Lange - Allow removing tokens from the storage
  25  */
  26 @NonNullByDefault
  27 public interface OAuthTokenRefresher {
  28     /**
  29      * Sets the listener that is called when the access token was refreshed.
  30      *
  31      * @param listener The listener to register.
  32      * @param serviceHandle The service handle identifying the internal OAuth configuration.
  33      * @throws OAuthException if the listener needs to be registered at an underlying service which is not available
  34      *             because the account has not yet been authorized
  35      */
  36     public void setRefreshListener(OAuthTokenRefreshListener listener, String serviceHandle);
  37
  38     /**
  39      * Unsets a listener.
  40      *
  41      * @param serviceHandle The service handle identifying the internal OAuth configuration.
  42      */
  43     public void unsetRefreshListener(String serviceHandle);
  44
  45     /**
  46      * Refreshes the access and refresh tokens for the given service handle. If an {@link OAuthTokenRefreshListener} is
  47      * registered for the service handle then it is notified after the refresh has completed.
  48      *
  49      * This call will succeed if the access token is still valid or a valid refresh token exists, which can be used to
  50      * refresh the expired access token. If refreshing fails, an {@link OAuthException} is thrown.
  51      *
  52      * @param serviceHandle The service handle identifying the internal OAuth configuration.
  53      * @throws OAuthException if the token cannot be obtained or refreshed
  54      */
  55     public void refreshToken(String serviceHandle);
  56
  57     /**
  58      * Gets the currently stored access token from persistent storage.
  59      *
  60      * @param serviceHandle The service handle identifying the internal OAuth configuration.
  61      * @return The currently stored access token or an empty {@link Optional} if there is no stored token.
  62      */
  63     public Optional<String> getAccessTokenFromStorage(String serviceHandle);
  64
  65     /**
  66      * Removes the tokens from persistent storage.
  67      *
  68      * Note: Calling this method will force the user to run through the pairing process again in order to obtain a
  69      * working bridge.
  70      *
  71      * @param serviceHandle The service handle identifying the internal OAuth configuration.
  72      */
  73     public void removeTokensFromStorage(String serviceHandle);
  74 }