Provide complete public API documentation (#26)

This PR improves the Javadocs in the classes that are part of the public
API.

It aims to provide a complete walkthrough for users reading the
Javadocs, guiding them through using the library starting at the package
level. This will be visible outside the source code thanks to #24, which
provides a direct link to the rendered Javadocs from the `README.md`.

This is an attempt to move some of the information which is currently
only shown in [code
samples](https://github.com/aws-samples/aurora-dsql-samples/blob/c94e23cf6b59d98f444638e6ec1a5132533c76f3/java/pgjdbc_using_dsql_connector/src/main/java/com/amazon/dsql/samples/CustomCredentialsProviderExample.java)
into a more maintainable location which is directly tied to the library.

I recommend starting the review with the `package-info.java` file since
that is the top-level description that will show up in the Javadocs and
points to the others.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Author: danielfrankcom

README.md

@@ -91,13 +91,16 @@ Connection conn = DriverManager.getConnection(url);
 
 ## Properties
 
-| Parameter | Description                                                                                                               | Default                                                                                                              |
-|-----------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
-| `user` | Determines the user for the connection and the token generation method used. Example: `admin`                             | -                                                                                                                    |
-| `token-duration-secs` | Duration in seconds for token validity                                                                                    | [Same as dsql sdk limit](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) |
-| `profile` | Used for instantiating a `ProfileCredentialsProvider` for token generation with the provided profile name                 | -                                                                                                                    |
-| `region` | AWS region for Aurora DSQL connections. It is optional. When provided, it will override the region extracted from the URL | -                                                                                                                    |
-| `database` | The database name to connect to                                                                                           | postgres                                                                                                             |
+The connector supports the following connection properties:
+
+| Parameter | Description                                                                                                               | Default                                                                                                               |
+|-----------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `user` | Determines the user for the connection and the token generation method used. Example: `admin`                             | -                                                                                                                     |
+| `token-duration-secs` | Duration in seconds for token validity                                                                                    | [Same as AWS SDK default](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) |
+| `profile` | Used for instantiating a `ProfileCredentialsProvider` for token generation with the provided profile name                 | -                                                                                                                     |
+| `region` | AWS region for Aurora DSQL connections. It is optional. When provided, it will override the region extracted from the URL | -                                                                                                                     |
+
+**Note:** The database name is specified in the URL path (e.g., `/postgres`). If not specified in the URL, it defaults to `postgres`.
 
 ## Logging
 Enabling logging is a very useful mechanism for troubleshooting any issue one might potentially experience while using the Aurora DSQL JDBC Connector.

build.gradle.kts

@@ -167,6 +167,8 @@ tasks.register("generateVersionClass") {
             /**
              * Version information for Aurora DSQL JDBC Connector.
              * Generated automatically during build.
+             *
+             * @since 1.1.1
              */
             public final class Version {
                 public static final int MAJOR = $major;

src/main/java/software/amazon/dsql/jdbc/AuroraDsqlCredentialsManager.java

@@ -19,6 +19,72 @@
 import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
 import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
 
+/**
+ * Manages the global AWS credentials provider used for IAM authentication token generation.
+ *
+ * <p>This utility class provides a centralized mechanism for configuring the {@link
+ * AwsCredentialsProvider} used by {@link DSQLConnector} when establishing connections to Aurora
+ * DSQL. By default, the connector uses the AWS SDK's {@link DefaultCredentialsProvider}, which
+ * searches for credentials in standard locations. Applications can customize this behavior by
+ * providing a custom credentials provider through {@link #setProvider(AwsCredentialsProvider)}.
+ *
+ * <h3>Default Behavior</h3>
+ *
+ * <p>When no custom provider is configured, the connector uses {@link DefaultCredentialsProvider},
+ * which automatically searches for credentials in the AWS SDK's standard credential chain.
+ *
+ * <p>The {@link #resetProvider()} method can be used to restore the default behaviour.
+ *
+ * <h3>Custom Profile</h3>
+ *
+ * <p>For most use cases requiring a specific AWS profile, use the {@code profile} connection
+ * property instead of configuring a custom provider through this class. The {@code profile}
+ * property is simpler and takes precedence over the credentials provider configured here.
+ *
+ * <pre>{@code
+ * Properties props = new Properties();
+ * props.setProperty("user", "admin");
+ * props.setProperty("profile", "production");
+ * Connection conn = DriverManager.getConnection(url, props);
+ * }</pre>
+ *
+ * <h3>Custom Credentials Provider</h3>
+ *
+ * <p>For advanced scenarios requiring credential sources beyond named profiles, configure a custom
+ * provider:
+ *
+ * <pre>{@code
+ * StsClient stsClient = StsClient.builder()
+ *      .region(Region.US_EAST_1)
+ *      .build();
+ *
+ * AwsCredentialsProvider assumeRoleCredentials = StsAssumeRoleCredentialsProvider.builder()
+ *      .refreshRequest(
+ *          AssumeRoleRequest.builder()
+ *              .roleArn(ROLE_ARN)
+ *              .roleSessionName("aurora-dsql-session")
+ *              .durationSeconds(3600) // 1 hour
+ *              .build()
+ *      )
+ *      .stsClient(stsClient)
+ *      .build();
+ *
+ * AuroraDsqlCredentialsManager.setProvider(assumeRoleCredentials);
+ *
+ * Properties props = new Properties();
+ * props.setProperty("user", "admin");
+ * Connection conn = DriverManager.getConnection(url, props);
+ * }</pre>
+ *
+ * <h3>Thread Safety</h3>
+ *
+ * <p>All methods in this class are thread-safe. The credentials provider can be safely configured
+ * or retrieved from multiple threads concurrently.
+ *
+ * @see DSQLConnector#connect(String, java.util.Properties)
+ * @see PropertyDefinition#PROFILE
+ * @since 1.0.0
+ */
 public final class AuroraDsqlCredentialsManager {
 
     private AuroraDsqlCredentialsManager() {
@@ -30,21 +96,49 @@ private AuroraDsqlCredentialsManager() {
             DefaultCredentialsProvider.builder().build();
 
     /**
-     * Set the AwsCredentialsProvider to use for token generation.
+     * Configures a custom AWS credentials provider for IAM token generation.
+     *
+     * <p>This method sets the global credentials provider used by all subsequent connections that
+     * do not specify a {@code profile} property. The provider will be used to obtain AWS
+     * credentials for generating IAM authentication tokens.
      *
-     * @param customCredentialsProvider is an AwsCredentialsProvider (e.g.
-     *     'ProfileCredentialProvider').
+     * <p><b>Note:</b> This setting is global and affects all connections created after this method
+     * is called. Connections that specify a {@code profile} property will use that profile instead
+     * of this provider.
+     *
+     * @param customCredentialsProvider the credentials provider to use for token generation
+     * @throws NullPointerException if {@code customCredentialsProvider} is null
+     * @see #resetProvider()
+     * @see #getProvider()
      */
     public static void setProvider(final AwsCredentialsProvider customCredentialsProvider) {
         credentialsProvider = customCredentialsProvider;
     }
 
-    /** Resets AuroraDsqlCredentialsManager back to the DefaultCredentialsProvider. */
+    /**
+     * Resets the credentials provider to the default AWS SDK credential chain.
+     *
+     * <p>This method restores the credentials provider to {@link DefaultCredentialsProvider},
+     * reverting any custom provider configured through {@link
+     * #setProvider(AwsCredentialsProvider)}.
+     *
+     * @see #setProvider(AwsCredentialsProvider)
+     * @see #getProvider()
+     */
     public static void resetProvider() {
         credentialsProvider = DefaultCredentialsProvider.builder().build();
     }
 
-    /** Retrieves AuroraDsqlCredentialsManager's credentials provider. */
+    /**
+     * Retrieves the currently configured AWS credentials provider.
+     *
+     * <p>Returns the credentials provider that will be used for IAM token generation when no {@code
+     * profile} property is specified in the connection.
+     *
+     * @return the current credentials provider
+     * @see #setProvider(AwsCredentialsProvider)
+     * @see #resetProvider()
+     */
     public static AwsCredentialsProvider getProvider() {
         return credentialsProvider;
     }

src/main/java/software/amazon/dsql/jdbc/AuroraDsqlProperty.java

@@ -21,29 +21,63 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+/**
+ * Represents a connection property for the Aurora DSQL JDBC driver.
+ *
+ * <p>This class extends {@link DriverPropertyInfo} to provide additional functionality for managing
+ * connection properties.
+ *
+ * @see DriverPropertyInfo
+ * @since 1.0.0
+ */
 public class AuroraDsqlProperty extends DriverPropertyInfo {
 
+    /** The default value for this property, or {@code null} if no default is defined. */
     public final @Nullable String defaultValue;
 
+    /**
+     * Creates an optional property which accepts any value.
+     *
+     * @param name the property name
+     * @param defaultValue the default value, or {@code null} if no default
+     * @param description the property description, or {@code null} if no description
+     */
     public AuroraDsqlProperty(
             @Nonnull final String name,
             @Nullable final String defaultValue,
-            final String description) {
+            @Nullable final String description) {
         this(name, defaultValue, description, false);
     }
 
+    /**
+     * Creates a property which accepts any value.
+     *
+     * @param name the property name
+     * @param defaultValue the default value, or {@code null} if no default
+     * @param description the property description, or {@code null} if no description
+     * @param required whether this property is required for connections
+     */
     public AuroraDsqlProperty(
             @Nonnull final String name,
             @Nullable final String defaultValue,
-            final String description,
+            @Nullable final String description,
             final boolean required) {
         this(name, defaultValue, description, required, null);
     }
 
+    /**
+     * Creates a property.
+     *
+     * @param name the property name
+     * @param defaultValue the default value, or {@code null} if no default
+     * @param description the property description, or {@code null} if no description
+     * @param required whether this property is required for connections
+     * @param choices valid choices for this property, or {@code null} if any value is allowed
+     */
     public AuroraDsqlProperty(
             @Nonnull final String name,
             @Nullable final String defaultValue,
-            final String description,
+            @Nullable final String description,
             final boolean required,
             @Nullable final String[] choices) {
         super(name, null);
@@ -53,14 +87,36 @@ public AuroraDsqlProperty(
         this.choices = choices;
     }
 
+    /**
+     * Retrieves the property value from the given {@link Properties}, or the default value if not
+     * set.
+     *
+     * @param properties the {@link Properties} to query
+     * @return the property value, or the default value if not set, or {@code null} if neither
+     *     exists
+     */
     public @Nullable String getOrDefault(Properties properties) {
         return properties.getProperty(this.name, this.defaultValue);
     }
 
+    /**
+     * Retrieves the property value from the given {@link Properties}.
+     *
+     * @param properties the {@link Properties} to query
+     * @return the property value, or {@code null} if not set
+     */
     public @Nullable String get(Properties properties) {
         return properties.getProperty(this.name);
     }
 
+    /**
+     * Sets the property value in the given {@link Properties}.
+     *
+     * <p>If the value is {@code null}, the property is removed from the {@link Properties} object.
+     *
+     * @param properties the {@link Properties} to modify
+     * @param value the value to set, or {@code null} to remove the property
+     */
     public void set(Properties properties, @Nullable String value) {
         if (value == null) {
             properties.remove(name);
@@ -69,14 +125,35 @@ public void set(Properties properties, @Nullable String value) {
         }
     }
 
+    /**
+     * Retrieves the property value as an integer.
+     *
+     * <p>If the property is not set and no default value exists, returns {@code 0}.
+     *
+     * @param properties the {@link Properties} to query
+     * @return the property value as an integer, or {@code 0} if not set and no default exists
+     * @throws NumberFormatException if the property value cannot be parsed as an integer
+     */
     public int getInteger(final Properties properties) {
         final Object value = properties.get(name);
+        if (value == null && defaultValue == null) {
+            return 0;
+        }
         if (value instanceof Integer) {
             return (Integer) value;
         }
         return Integer.parseInt(properties.getProperty(name, defaultValue));
     }
 
+    /**
+     * Retrieves the property value as a long.
+     *
+     * <p>If the property is not set and no default value exists, returns {@code 0L}.
+     *
+     * @param properties the {@link Properties} to query
+     * @return the property value as a long, or {@code 0L} if not set and no default exists
+     * @throws NumberFormatException if the property value cannot be parsed as a long
+     */
     public long getLong(final Properties properties) {
         final Object value = properties.get(name);
         if (value == null && defaultValue == null) {
@@ -88,6 +165,17 @@ public long getLong(final Properties properties) {
         return Long.parseLong(properties.getProperty(name, defaultValue));
     }
 
+    /**
+     * Converts this property to a {@link DriverPropertyInfo} instance.
+     *
+     * <p>Creates a {@link DriverPropertyInfo} object containing this property's metadata (name,
+     * description, etc.) along with the current value from the provided {@link Properties} object.
+     * If the property is not set in the {@link Properties} object, the value will be {@code null}.
+     *
+     * @param properties the {@link Properties} to query for the current value
+     * @return a {@link DriverPropertyInfo} instance with property metadata and provided property
+     *     value
+     */
     public DriverPropertyInfo toDriverPropertyInfo(final Properties properties) {
         final DriverPropertyInfo propertyInfo = new DriverPropertyInfo(name, get(properties));
         propertyInfo.required = required;