Document OAuth 2 support class

Author: acogoluegnes

src/main/java/com/rabbitmq/client/amqp/impl/AmqpConnection.java

@@ -796,7 +796,7 @@ private void close(Throwable cause) {
     if (this.closed.compareAndSet(false, true)) {
       this.state(CLOSING, cause);
       LOGGER.debug("Closing connection {}", this);
-      this.credentialsRegistration.unregister();
+      this.credentialsRegistration.close();
       this.environment.removeConnection(this);
       BiConsumer<String, RunnableWithException> safeClose =
           (label, action) -> {

src/main/java/com/rabbitmq/client/amqp/impl/UsernamePasswordCredentialsManager.java

@@ -22,11 +22,9 @@
 
 final class UsernamePasswordCredentialsManager implements CredentialsManager {
 
-  private final UsernamePasswordCredentialsProvider provider;
   private final Registration registration;
 
   UsernamePasswordCredentialsManager(UsernamePasswordCredentialsProvider provider) {
-    this.provider = provider;
     this.registration = new RegistrationImpl(provider);
   }
 
@@ -49,6 +47,6 @@ public void connect(AuthenticationCallback callback) {
     }
 
     @Override
-    public void unregister() {}
+    public void close() {}
   }
 }

src/main/java/com/rabbitmq/client/amqp/oauth2/CredentialsManager.java

@@ -17,21 +17,57 @@
 // [email protected].
 package com.rabbitmq.client.amqp.oauth2;
 
+/**
+ * Contract to authenticate and possibly re-authenticate application components.
+ *
+ * <p>A typical "application component" is a connection.
+ */
 public interface CredentialsManager {
 
+  /** No-op credentials manager. */
   CredentialsManager NO_OP = new NoOpCredentialsManager();
 
+  /**
+   * Register a component for authentication.
+   *
+   * @param name component name (must be unique)
+   * @param updateCallback callback to update the component authentication
+   * @return the registration (must be closed when no longer necessary)
+   */
   Registration register(String name, AuthenticationCallback updateCallback);
 
-  interface Registration {
+  /** A component registration. */
+  interface Registration extends AutoCloseable {
 
+    /**
+     * Connection request from the component.
+     *
+     * <p>The component calls this method when it needs to authenticate. The underlying credentials
+     * manager implementation must take of providing the component with the appropriate credentials
+     * in the callback.
+     *
+     * @param callback client code to authenticate the component
+     */
     void connect(AuthenticationCallback callback);
 
-    void unregister();
+    /** Close the registration. */
+    void close();
   }
 
+  /**
+   * Component authentication callback.
+   *
+   * <p>The component provides the logic and the manager implementation calls it with the
+   * appropriate credentials.
+   */
   interface AuthenticationCallback {
 
+    /**
+     * Authentication logic.
+     *
+     * @param username username
+     * @param password password
+     */
     void authenticate(String username, String password);
   }
 
@@ -49,6 +85,6 @@ class NoOpRegistration implements Registration {
     public void connect(AuthenticationCallback callback) {}
 
     @Override
-    public void unregister() {}
+    public void close() {}
   }
 }

src/main/java/com/rabbitmq/client/amqp/oauth2/GsonTokenParser.java

@@ -23,6 +23,12 @@
 import java.time.Instant;
 import java.util.Map;
 
+/**
+ * Token parser for <a href="https://www.rfc-editor.org/rfc/rfc6749#section-5.1">JSON OAuth 2 Access
+ * tokens</a>.
+ *
+ * <p>Uses <a href="https://github.com/google/gson">GSON</a> for the JSON parsing.
+ */
 public class GsonTokenParser implements TokenParser {
 
   private static final Gson GSON = new Gson();

src/main/java/com/rabbitmq/client/amqp/oauth2/HttpTokenRequester.java

@@ -31,6 +31,11 @@
 import java.util.Map;
 import java.util.function.Consumer;
 
+/**
+ * Token requester using HTTP(S) to request an OAuth2 Access token.
+ *
+ * <p>Uses {@link HttpClient} for the HTTP operations.
+ */
 public final class HttpTokenRequester implements TokenRequester {
 
   private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(60);

src/main/java/com/rabbitmq/client/amqp/oauth2/OAuth2Exception.java

@@ -17,6 +17,7 @@
 // [email protected].
 package com.rabbitmq.client.amqp.oauth2;
 
+/** OAuth 2-related exception. */
 public class OAuth2Exception extends RuntimeException {
 
   public OAuth2Exception(String message) {

src/main/java/com/rabbitmq/client/amqp/oauth2/Token.java

@@ -19,9 +19,20 @@
 
 import java.time.Instant;
 
+/** A token. */
 public interface Token {
 
+  /**
+   * The value of the token.
+   *
+   * @return the token value
+   */
   String value();
 
+  /**
+   * The expiration time of the token.
+   *
+   * @return the expiration time
+   */
   Instant expirationTime();
 }

src/main/java/com/rabbitmq/client/amqp/oauth2/TokenCredentialsManager.java

@@ -237,7 +237,7 @@ public void connect(AuthenticationCallback callback) {
     }
 
     @Override
-    public void unregister() {
+    public void close() {
       if (this.closed.compareAndSet(false, true)) {
         registrations.remove(this.id);
         ScheduledFuture<?> task = refreshTask;

src/main/java/com/rabbitmq/client/amqp/oauth2/TokenParser.java

@@ -17,7 +17,14 @@
 // [email protected].
 package com.rabbitmq.client.amqp.oauth2;
 
+/** Contract to parse a token from a string. */
 public interface TokenParser {
 
+  /**
+   * Parse the token.
+   *
+   * @param tokenAsString token as a string
+   * @return the token
+   */
   Token parse(String tokenAsString);
 }

src/main/java/com/rabbitmq/client/amqp/oauth2/TokenRequester.java

@@ -17,7 +17,13 @@
 // [email protected].
 package com.rabbitmq.client.amqp.oauth2;
 
+/** Contract to request a token (usually on HTTP). */
 public interface TokenRequester {
 
+  /**
+   * Request a token.
+   *
+   * @return the token
+   */
   Token request();
 }