Add docs

Thanks, Claude!

Author: yuriyostapenko

src/main/java/com/scalepoint/oauth_token_client/CertificateWithPrivateKey.java

@@ -28,13 +28,17 @@ public CertificateWithPrivateKey(PrivateKey privateKey, X509Certificate certific
     }
 
     /**
+     * Gets the X.509 certificate.
+     *
      * @return Certificate
      */
     public X509Certificate getCertificate() {
         return certificate;
     }
 
     /**
+     * Gets the private key associated with the certificate.
+     *
      * @return Private key
      */
     public PrivateKey getPrivateKey() {

src/main/java/com/scalepoint/oauth_token_client/ClientCredentialsGrantTokenClient.java

@@ -38,6 +38,7 @@ public ClientCredentialsGrantTokenClient(String tokenEndpointUri, ClientCredenti
      * @param scopes OAuth2 scopes to request
      * @return Access token
      * @throws IOException Exception during token endpoint communication
+     * @throws InterruptedException if the thread is interrupted during token retrieval
      */
     @SuppressWarnings("UnusedReturnValue")
     public String getToken(final String... scopes) throws IOException, InterruptedException {

src/main/java/com/scalepoint/oauth_token_client/CustomGrantTokenClient.java

@@ -4,12 +4,23 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Abstract base class for OAuth2 custom grant token clients.
+ * Provides common functionality for obtaining access tokens using custom grant types.
+ */
 public abstract class CustomGrantTokenClient {
     private final ClientCredentials clientCredentials;
     private final TokenEndpointHttpClient tokenEndpointHttpClient;
     private final String partialCacheKey;
     private final TokenCache cache;
 
+    /**
+     * Constructs a custom grant token client.
+     *
+     * @param tokenEndpointUri URI of the OAuth2 token endpoint
+     * @param clientCredentials client credentials for authentication
+     * @param cache token cache for storing and retrieving tokens
+     */
     public CustomGrantTokenClient(String tokenEndpointUri, ClientCredentials clientCredentials, TokenCache cache) {
         this.tokenEndpointHttpClient = new TokenEndpointHttpClient(tokenEndpointUri);
         this.clientCredentials = clientCredentials;
@@ -24,6 +35,7 @@ public CustomGrantTokenClient(String tokenEndpointUri, ClientCredentials clientC
      * @param scopes     OAuth2 scopes to request
      * @return Access token
      * @throws IOException Exception during token endpoint communication
+     * @throws InterruptedException if the thread is interrupted during token retrieval
      */
     protected String getTokenInternal(final List<NameValuePair> parameters, final String... scopes) throws IOException, InterruptedException {
 
@@ -55,6 +67,8 @@ public ExpiringToken get() throws IOException, InterruptedException {
     }
 
     /**
+     * Gets the OAuth2 grant type for this client.
+     *
      * @return Grant type (i.e. "client_credentials")
      */
     protected abstract String getGrantType();

src/main/java/com/scalepoint/oauth_token_client/ExpiringToken.java

@@ -19,13 +19,17 @@ public class ExpiringToken {
     }
 
     /**
+     * Gets the access token string.
+     *
      * @return Token
      */
     public String getToken() {
         return token;
     }
 
     /**
+     * Gets the token expiration time in seconds.
+     *
      * @return Expiration in seconds
      */
     public int getExpiresInSeconds() {

src/main/java/com/scalepoint/oauth_token_client/InMemoryTokenCache.java

@@ -11,6 +11,13 @@
 public class InMemoryTokenCache implements TokenCache {
     private final ConcurrentMap<String, CachedToken> cache = new ConcurrentHashMap<>();
 
+    /**
+     * Constructs a new in-memory token cache.
+     */
+    public InMemoryTokenCache() {
+        // Default constructor
+    }
+
     /**
      * Wrapper class to store token with its expiration time
      */

src/main/java/com/scalepoint/oauth_token_client/NameValuePair.java

@@ -9,6 +9,8 @@ public class NameValuePair {
     final String value;
 
     /**
+     * Constructs a name-value pair.
+     *
      * @param name Name
      * @param value Value
      */

src/main/java/com/scalepoint/oauth_token_client/NoCache.java

@@ -7,6 +7,14 @@
  */
 @SuppressWarnings("unused")
 public class NoCache implements TokenCache {
+    
+    /**
+     * Constructs a new no-cache implementation.
+     */
+    public NoCache() {
+        // Default constructor
+    }
+
     /**
      * @param cacheKey         Cache key
      * @param underlyingSource Underlying token source to invoke

src/main/java/com/scalepoint/oauth_token_client/ResourceScopedAccessGrantParameters.java

@@ -35,34 +35,47 @@ public ResourceScopedAccessGrantParameters(String scope, String resource, String
     }
 
     /**
+     * Gets the OAuth2 scope for the access request.
+     *
      * @return OAuth2 scope
      */
     public String getScope() {
         return scope;
     }
 
     /**
+     * Gets the specific resource identifier for the access request.
+     *
      * @return Specific resource identifier
      */
     public String getResource() {
         return resource;
     }
 
     /**
+     * Gets the resource tenant identifier.
+     *
      * @return Resource tenant identifier
      */
     public String getTenantId() {
         return tenantId;
     }
 
     /**
+     * Gets the original authentication method references.
+     *
      * @return Original authentication method references
      */
     @SuppressWarnings("unused")
     public String[] getAmr() {
         return amr;
     }
 
+    /**
+     * Gets the authentication method references as a space-separated string.
+     *
+     * @return AMR values as a space-separated string, or null if no AMR values are set
+     */
     protected String getAmrString() {
         return (amr == null || amr.length < 1)
                 ? null

src/main/java/com/scalepoint/oauth_token_client/ResourceScopedAccessGrantTokenClient.java

@@ -10,6 +10,12 @@
 @SuppressWarnings("WeakerAccess")
 public class ResourceScopedAccessGrantTokenClient extends CustomGrantTokenClient {
 
+    /**
+     * Constructs a resource-scoped access grant token client.
+     *
+     * @param tokenEndpointUri URI of the OAuth2 token endpoint
+     * @param clientCredentials client credentials for authentication
+     */
     @SuppressWarnings("SameParameterValue")
     public ResourceScopedAccessGrantTokenClient(String tokenEndpointUri, ClientCredentials clientCredentials) {
         super(tokenEndpointUri, clientCredentials, new NoCache());
@@ -21,6 +27,7 @@ public ResourceScopedAccessGrantTokenClient(String tokenEndpointUri, ClientCrede
      * @param parameters Custom grant parameters
      * @return Access token
      * @throws IOException Exception during token endpoint communication
+     * @throws InterruptedException if the thread is interrupted during token retrieval
      */
     @SuppressWarnings("UnusedReturnValue")
     public String getToken(ResourceScopedAccessGrantParameters parameters) throws IOException, InterruptedException {

src/main/java/com/scalepoint/oauth_token_client/TokenCache.java

@@ -7,10 +7,13 @@
  */
 public interface TokenCache {
     /**
+     * Gets a token from the cache or retrieves it from the underlying source if not cached.
+     *
      * @param cacheKey         Cache key
      * @param underlyingSource Underlying token source to invoke on cache miss
      * @return Token from either cache or underlying source
      * @throws IOException Exception from underlying cache
+     * @throws InterruptedException if the thread is interrupted during token retrieval
      */
     String get(String cacheKey, TokenSource underlyingSource) throws IOException, InterruptedException;
 }