auth javadoc

README.md

@@ -10,18 +10,18 @@ Currently only thermostat and valves are supported.
 For authentication there is `net.suteren.netatmo.auth.AuthClient`.
 It is required by API classes.
 If you try to connect to the API, it opens Netatmo web page in the web browser,
-let you log in
-and approve the application, and then it stores auth token and refresh token into the `~/.netatmoauth.json` file,
+let you log in and approve the application, and then it stores auth token and refresh token into the `~/.netatmoauth.json` file,
 so you don't have to log in every request.
 
+See [Netatmo Authentication](https://dev.netatmo.com/apidocumentation/oauth) for details.
+
 There is also a simple commandline client and timeline visualizer. See the sections below.
 
 ## Basic usage
 
 ```java
 
-AuthClient authClient =
-	new AuthClient(clientId, clientSecret, List.of("read_thermostat", "write_thermostat"), "Netatmo tool", authconfig);
+AuthClient authClient =	new AuthClient(clientId, clientSecret, List.of("read_thermostat", "write_thermostat"), "Netatmo tool", authconfig);
 
 HomeClient homeClient = new HomeClient(authClient).getHomesData();
 HomesData homesData = homeClient.getHomesData();

src/main/java/net/suteren/netatmo/auth/AuthClient.java

@@ -37,6 +37,18 @@ public final class AuthClient extends AbstractNetatmoClient {
 	private final OAuth2 oauth;
 	private final File authFile;
 
+	/**
+	 * Retrieves OAUTH2 token.
+	 * It is required by {@link net.suteren.netatmo.client.AbstractApiClient} to provide valid `Authentication` token.
+	 * See <a href="https://dev.netatmo.com/apidocumentation/oauth">Netatmo Authentication</a> for more details.
+	 *
+	 * @param clientId `client_id` used to retrieve the authentication token.
+	 * @param clientSecret `client_secret` used to retrieve the authentication token.
+	 * @param scope scopes to authorize to.
+	 * @param state to prevent Cross-site Request Forgery.
+	 * @param authFile local file to store tokens to. This file should be protected from unauthorized reading.
+	 * @throws IOException in case of connection problems of problems accessing the `authFile`.
+	 */
 	public AuthClient(String clientId, String clientSecret, Object scope, String state, File authFile) throws IOException {
 		this.authFile = authFile;
 		if (this.authFile.exists()) {
@@ -61,6 +73,12 @@ public AuthClient(String clientId, String clientSecret, Object scope, String sta
 
 	}
 
+	/**
+	 * Entrance URL to log in and approve the client.
+	 *
+	 * @param redirectUri url of this application to pass the auth code to.
+	 * @return URL to open in the browser.
+	 */
 	public String authorizeUrl(String redirectUri) {
 		LinkedHashMap<String, String> map = new LinkedHashMap<String, String>(4);
 		map.put("client_id", clientId);
@@ -70,6 +88,15 @@ public String authorizeUrl(String redirectUri) {
 		return constructUrl("oauth2/authorize", map);
 	}
 
+	/**
+	 * Retrieves the authorization token from cache, and try to refresh it in case it is going to expire.
+	 * If there is no authorization token in the cache, start OAuth2 process to log in and retrieve the token.
+	 *
+	 * @return authorization token
+	 * @throws URISyntaxException if {@link #authorizeUrl(String)} return wrong URL.
+	 * @throws IOException in the case of local callback server issues.
+	 * @throws ConnectionException in case of error from Netatmo API server during retrieving the token.
+	 */
 	public String getToken() throws URISyntaxException, IOException, InterruptedException, ConnectionException {
 		if (accessToken == null) {
 			oauth.authorize(this::authorizeUrl);

src/main/java/net/suteren/netatmo/auth/OAuth2.java

@@ -23,19 +23,22 @@
 import lombok.Setter;
 import lombok.extern.slf4j.Slf4j;
 
+/**
+ * This class is responsible for Oauth2 callback server handling and opening of the URL in the browser.
+ * It is intended just for internal use.
+ */
 @Slf4j final class OAuth2 {
 	private final CountDownLatch latch = new CountDownLatch(1);
 	@Setter @Getter private String code;
 	@Setter @Getter private String redirectUri;
 
-	public String authorize(Function<String, String> getUrl) throws URISyntaxException, IOException, InterruptedException {
+	void authorize(Function<String, String> getUrl) throws URISyntaxException, IOException, InterruptedException {
 		final HttpServer server = startServer();
 		redirectUri = "http://localhost:%d/".formatted(server.getAddress().getPort());
 		String authUrl = getUrl.apply(redirectUri);
 		log.info("Authorize the app in the browser...\nIf it did not happen automatically, open following URL in your browser: {}", authUrl);
 		Desktop.getDesktop().browse(new URI(authUrl));
 		latch.await();
-		return code;
 	}
 
 	private HttpServer startServer() throws IOException {