Merge pull request #4 from fauna/BT-4349-Java-docs-for-configurations

BT-4349 Java docs for configurations

common/src/main/java/com/fauna/common/configuration/Endpoint.java

@@ -1,16 +1,37 @@
 package com.fauna.common.configuration;
 
+/**
+ * Endpoint enumerates the various endpoints available for connecting to Fauna.
+ * It includes the default cloud endpoint and a local endpoint for development purposes.
+ */
 public enum Endpoint {
 
+    /**
+     * The default cloud endpoint for connecting to Fauna.
+     */
     DEFAULT("https://db.fauna.com"),
+
+    /**
+     * A local endpoint for connecting to a Fauna instance running on localhost.
+     */
     LOCAL("http://localhost:8443");
 
     private final String stringValue;
 
+    /**
+     * Constructs a new Endpoint enum instance.
+     *
+     * @param stringValue The string representation of the endpoint URL.
+     */
     Endpoint(String stringValue) {
         this.stringValue = stringValue;
     }
 
+    /**
+     * Returns the string representation of the endpoint URL.
+     *
+     * @return A string representing the endpoint URL.
+     */
     @Override
     public String toString() {
         return this.stringValue;

common/src/main/java/com/fauna/common/configuration/FaunaConfig.java

@@ -3,6 +3,10 @@
 import java.time.Duration;
 import java.util.Map;
 
+/**
+ * FaunaConfig is a configuration class used to set up and configure a connection to Fauna.
+ * It encapsulates various settings such as the endpoint URL, secret key, query timeout, and others.
+ */
 public class FaunaConfig {
 
     private final String endpoint;
@@ -19,6 +23,11 @@ public class FaunaConfig {
 
     private static final Duration DEFAULT_QUERY_TIMEOUT = Duration.ofSeconds(5);
 
+    /**
+     * Private constructor for FaunaConfig.
+     *
+     * @param builder The builder used to create the FaunaConfig instance.
+     */
     private FaunaConfig(Builder builder) {
         this.endpoint = builder.endpoint;
         this.secret = builder.secret;
@@ -29,38 +38,83 @@ private FaunaConfig(Builder builder) {
         this.traceParent = builder.traceParent;
     }
 
+    /**
+     * Gets the Fauna endpoint URL.
+     *
+     * @return A String representing the endpoint URL.
+     * The default is https://db.fauna.com
+     */
     public String getEndpoint() {
         return endpoint;
     }
 
+    /**
+     * Gets the secret key used for authentication.
+     *
+     * @return A String representing the secret key.
+     */
     public String getSecret() {
         return secret;
     }
 
+    /**
+     * Gets the query timeout setting.
+     *
+     * @return A Duration representing the maximum amount of time Fauna will execute the query before marking it failed.
+     * The default is 5 sec
+     */
     public Duration getQueryTimeout() {
         return queryTimeout;
     }
 
+    /**
+     * Gets the linearized setting.
+     *
+     * @return A Boolean indicating whether to unconditionally run the query as strictly serialized.
+     */
     public Boolean getLinearized() {
         return linearized;
     }
 
+    /**
+     * Gets the type check setting.
+     *
+     * @return A Boolean indicating whether to enable or disable type checking of the query before evaluation.
+     */
     public Boolean getTypeCheck() {
         return typeCheck;
     }
 
+    /**
+     * Gets the query tags.
+     *
+     * @return A Map of Strings representing tags associated with the query.
+     */
     public Map<String, String> getQueryTags() {
         return queryTags;
     }
 
+    /**
+     * Gets the trace parent setting.
+     *
+     * @return A String representing a traceparent associated with the query.
+     */
     public String getTraceParent() {
         return traceParent;
     }
 
+    /**
+     * Creates a new builder for FaunaConfig.
+     *
+     * @return A new instance of Builder.
+     */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Builder class for FaunaConfig. Follows the Builder Design Pattern.
+     */
     public static class Builder {
         private String endpoint = Endpoint.DEFAULT.toString();
         private String secret;
@@ -70,45 +124,98 @@ public static class Builder {
         private Map<String, String> queryTags;
         private String traceParent;
 
+        /**
+         * Sets the endpoint URL.
+         *
+         * @param endpoint A String representing the endpoint URL.
+         * @return The current Builder instance.
+         */
         public Builder endpoint(String endpoint) {
             this.endpoint = endpoint;
             return this;
         }
 
+        /**
+         * Sets the secret key.
+         *
+         * @param secret A String representing the secret key.
+         * @return The current Builder instance.
+         */
         public Builder secret(String secret) {
             this.secret = secret;
             return this;
         }
 
+        /**
+         * Sets the query timeout.
+         *
+         * @param queryTimeout A Duration representing the query timeout.
+         *                     Controls the maximum amount of time Fauna will execute your query before marking it failed.
+         * @return The current Builder instance.
+         */
         public Builder queryTimeout(Duration queryTimeout) {
             this.queryTimeout = queryTimeout;
             return this;
         }
 
+        /**
+         * Sets the linearized setting.
+         *
+         * @param linearized A Boolean indicating whether to run the query as strictly serialized.
+         *                   This affects read-only transactions.
+         *                   Transactions which write will always be strictly serialized.
+         * @return The current Builder instance.
+         */
         public Builder linearized(Boolean linearized) {
             this.linearized = linearized;
             return this;
         }
 
+        /**
+         * Sets the type check setting.
+         *
+         * @param typeCheck A Boolean indicating whether to enable or disable type checking of the query.
+         *                  If not set, the value configured on the Client will be used.
+         *                  If neither is set, Fauna will use the value of the "typechecked" flag on the database configuration.
+         * @return The current Builder instance.
+         */
         public Builder typeCheck(Boolean typeCheck) {
             this.typeCheck = typeCheck;
             return this;
         }
 
+        /**
+         * Sets the query tags.
+         *
+         * @param queryTags A Map of Strings representing the query tags.
+         *                  Tags to associate with the query. See `logging <<a href="https://docs.fauna.com/fauna/current/build/logs/query_log/">...</a>>`_
+         * @return The current Builder instance.
+         */
         public Builder queryTags(Map<String, String> queryTags) {
             this.queryTags = queryTags;
             return this;
         }
 
+        /**
+         * Sets the trace parent.
+         *
+         * @param traceParent A String representing the traceparent associated with the query.
+         *                    See `logging <<a href="https://docs.fauna.com/fauna/current/build/logs/query_log/">...</a>>`_ Must match format: <a href="https://www.w3.org/TR/trace-context/#traceparent-header">...</a>
+         * @return The current Builder instance.
+         */
         public Builder traceParent(String traceParent) {
             this.traceParent = traceParent;
             return this;
         }
 
+        /**
+         * Builds and returns a new FaunaConfig instance.
+         *
+         * @return A new instance of FaunaConfig.
+         */
         public FaunaConfig build() {
             return new FaunaConfig(this);
         }
     }
 
-
 }

common/src/main/java/com/fauna/common/configuration/HttpClientConfig.java

@@ -2,6 +2,10 @@
 
 import java.time.Duration;
 
+/**
+ * HttpClientConfig encapsulates configuration settings for an HTTP client.
+ * It includes settings such as connection timeout and maximum number of connections.
+ */
 public class HttpClientConfig {
 
     private final Duration connectTimeout;
@@ -11,38 +15,82 @@ public class HttpClientConfig {
     private static final int DEFAULT_MAX_CONNECTIONS = 20;
 
 
+    /**
+     * Private constructor for HttpClientConfig.
+     *
+     * @param builder The builder used to create the HttpClientConfig instance.
+     */
     private HttpClientConfig(Builder builder) {
         this.connectTimeout = builder.connectTimeout;
         this.maxConnections = builder.maxConnections;
     }
 
+    /**
+     * Gets the connection timeout setting.
+     *
+     * @return A Duration representing the maximum time to wait for a connection to be established.
+     * The default is 5 seconds.
+     */
     public Duration getConnectTimeout() {
         return connectTimeout;
     }
 
+    /**
+     * Gets the maximum number of connections setting.
+     *
+     * @return An integer representing the maximum number of simultaneous connections.
+     * The default is 20.
+     */
     public int getMaxConnections() {
         return maxConnections;
     }
 
+    /**
+     * Creates a new builder for HttpClientConfig.
+     *
+     * @return A new instance of Builder.
+     */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Builder class for HttpClientConfig. Follows the Builder Design Pattern.
+     */
     public static class Builder {
 
         private Duration connectTimeout = DEFAULT_CONNECT_TIMEOUT;
         private int maxConnections = DEFAULT_MAX_CONNECTIONS;
 
+        /**
+         * Sets the connection timeout.
+         *
+         * @param connectTimeout A Duration representing the connection timeout.
+         *                       The default is 5 seconds.
+         * @return The current Builder instance.
+         */
         public Builder connectTimeout(Duration connectTimeout) {
             this.connectTimeout = connectTimeout;
             return this;
         }
 
+        /**
+         * Sets the maximum number of connections.
+         *
+         * @param maxConnections An integer representing the maximum number of connections.
+         *                       The default is 20.
+         * @return The current Builder instance.
+         */
         public Builder maxConnections(int maxConnections) {
             this.maxConnections = maxConnections;
             return this;
         }
 
+        /**
+         * Builds and returns a new HttpClientConfig instance.
+         *
+         * @return A new instance of HttpClientConfig.
+         */
         public HttpClientConfig build() {
             return new HttpClientConfig(this);
         }

common/src/main/java/com/fauna/common/configuration/Version.java

@@ -4,11 +4,24 @@
 import java.io.InputStream;
 import java.util.Properties;
 
+/**
+ * The Version class is a utility class that provides functionality to retrieve the software version.
+ * It reads the version information from a properties file.
+ */
 public final class Version {
 
+    /**
+     * Private constructor to prevent instantiation of this utility class.
+     */
     private Version() {
     }
 
+    /**
+     * Retrieves the software version from the "version.properties" file.
+     *
+     * @return A String representing the software version.
+     * @throws RuntimeException If the "version.properties" file is not found or if there is an issue reading the file.
+     */
     public static String getVersion() {
         Properties properties = new Properties();
         try (InputStream input = Version.class.getClassLoader().getResourceAsStream("version.properties")) {

common/src/main/java/com/fauna/common/connection/Auth.java

@@ -1,13 +1,29 @@
 package com.fauna.common.connection;
 
+/**
+ * The Auth class is responsible for handling authentication, providing functionality to generate bearer tokens.
+ */
 class Auth {
 
     private final String secret;
 
+    /**
+     * Constructs a new Auth instance with the provided secret.
+     *
+     * @param secret The secret key used for authentication.
+     */
     public Auth(String secret) {
+        if (secret == null || secret.trim().isEmpty()) {
+            throw new IllegalArgumentException("Secret cannot be null or empty");
+        }
         this.secret = secret;
     }
 
+    /**
+     * Generates a bearer token using the secret provided during construction.
+     *
+     * @return A string representing the bearer token.
+     */
     public String bearer() {
         return "Bearer " + secret;
     }