Completed Javadocs

client-api/src/main/java/io/oxia/client/api/AsyncOxiaClient.java

@@ -199,10 +199,10 @@ void rangeScan(
      * will report the current latest sequence for a given key. Multiple updates can be collapsed into
      * one single event with the highest sequence.
      *
-     * @param key
-     * @param listener
-     * @param options
-     * @return
+     * @param key The key to subscribe to.
+     * @param listener The listener to receive the updates.
+     * @param options The options to use for the subscription.
+     * @return A handle to close the subscription.
      */
     Closeable getSequenceUpdates(
             String key, Consumer<String> listener, Set<GetSequenceUpdatesOption> options);

client-api/src/main/java/io/oxia/client/api/Authentication.java

@@ -17,7 +17,18 @@
 
 import java.util.Map;
 
+/**
+ * Represents an interface for implementing authentication mechanisms. The implementations of this
+ * interface are expected to provide a way to generate credentials in the form of key-value pairs.
+ */
 public interface Authentication {
 
+    /**
+     * Generates a set of credentials represented as key-value pairs.
+     *
+     * @return a map containing the generated credentials, where the keys represent the credential
+     *     type (e.g., username, password) and the values represent the corresponding credential
+     *     values.
+     */
     Map<String, String> generateCredentials();
 }

client-api/src/main/java/io/oxia/client/api/AuthenticationType.java

@@ -15,6 +15,19 @@
  */
 package io.oxia.client.api;
 
+/**
+ * Enum representing the type of authentication used for accessing resources.
+ *
+ * <p>This enum defines the supported authentication methods that can be used to authorize and
+ * authenticate a client or request against a service.
+ */
 public enum AuthenticationType {
+    /**
+     * Represents the Bearer authentication method.
+     *
+     * <p>Bearer is an authentication mechanism that uses a token-based approach where the client
+     * includes an access token in each request to provide proof of authorization. This method is
+     * commonly used in OAuth 2.0 authentication frameworks.
+     */
     Bearer;
 }

client-api/src/main/java/io/oxia/client/api/DeleteOption.java

@@ -15,8 +15,15 @@
  */
 package io.oxia.client.api;
 
+/** Options for deleting a record. */
 public sealed interface DeleteOption permits OptionPartitionKey, OptionVersionId {
 
+    /**
+     * Conditional delete will only succeed if the record's version matches the supplied versionId.
+     *
+     * @param versionId the versionId to compare with the record's version.
+     * @return the delete option.
+     */
     static DeleteOption IfVersionIdEquals(long versionId) {
         return new OptionVersionId.OptionVersionIdEqual(versionId);
     }
@@ -29,6 +36,7 @@ static DeleteOption IfVersionIdEquals(long versionId) {
      * Oxia shard.
      *
      * @param partitionKey the partition key to use
+     * @return the delete option.
      */
     static DeleteOption PartitionKey(String partitionKey) {
         return new OptionPartitionKey(partitionKey);

client-api/src/main/java/io/oxia/client/api/DeleteRangeOption.java

@@ -15,6 +15,7 @@
  */
 package io.oxia.client.api;
 
+/** Options for deleting a range of records. */
 public sealed interface DeleteRangeOption permits OptionPartitionKey {
 
     /**
@@ -25,6 +26,7 @@ public sealed interface DeleteRangeOption permits OptionPartitionKey {
      * Oxia shard.
      *
      * @param partitionKey the partition key to use
+     * @return the delete range option.
      */
     static DeleteRangeOption PartitionKey(String partitionKey) {
         return new OptionPartitionKey(partitionKey);

client-api/src/main/java/io/oxia/client/api/GetOption.java

@@ -15,6 +15,7 @@
  */
 package io.oxia.client.api;
 
+/** Options for getting a record. */
 public sealed interface GetOption
         permits OptionComparisonType, OptionIncludeValue, OptionPartitionKey, OptionSecondaryIndexName {
 
@@ -60,6 +61,7 @@ public sealed interface GetOption
      * Oxia shard.
      *
      * @param partitionKey the partition key to use
+     * @return the GetOption.
      */
     static GetOption PartitionKey(String partitionKey) {
         return new OptionPartitionKey(partitionKey);
@@ -83,6 +85,7 @@ static GetOption IncludeValue(boolean includeValue) {
      * <p>Note: if the secondary index is not unique, which primary record is returned is undefined.
      *
      * @param secondaryIndexName the name of the secondary index to use for the list operation
+     * @return the GetOption.
      */
     static GetOption UseIndex(String secondaryIndexName) {
         return new OptionSecondaryIndexName(secondaryIndexName);

client-api/src/main/java/io/oxia/client/api/GetSequenceUpdatesOption.java

@@ -15,6 +15,7 @@
  */
 package io.oxia.client.api;
 
+/** Options for getting sequence updates. */
 public sealed interface GetSequenceUpdatesOption permits OptionPartitionKey {
 
     /**
@@ -25,6 +26,7 @@ public sealed interface GetSequenceUpdatesOption permits OptionPartitionKey {
      * Oxia shard.
      *
      * @param partitionKey the partition key to use
+     * @return the GetSequenceUpdatesOption.
      */
     static GetSequenceUpdatesOption PartitionKey(String partitionKey) {
         return new OptionPartitionKey(partitionKey);

client-api/src/main/java/io/oxia/client/api/ListOption.java

@@ -15,6 +15,7 @@
  */
 package io.oxia.client.api;
 
+/** Options for listing records. */
 public sealed interface ListOption permits OptionPartitionKey, OptionSecondaryIndexName {
 
     /**
@@ -25,6 +26,7 @@ public sealed interface ListOption permits OptionPartitionKey, OptionSecondaryIn
      * Oxia shard.
      *
      * @param partitionKey the partition key to use
+     * @return the ListOption.
      */
     static ListOption PartitionKey(String partitionKey) {
         return new OptionPartitionKey(partitionKey);
@@ -36,6 +38,7 @@ static ListOption PartitionKey(String partitionKey) {
      * <p>Note: The returned list will contain they primary keys of the records
      *
      * @param secondaryIndexName the name of the secondary index to use for the list operation
+     * @return the ListOption.
      */
     static ListOption UseIndex(String secondaryIndexName) {
         return new OptionSecondaryIndexName(secondaryIndexName);

client-api/src/main/java/io/oxia/client/api/OptionEphemeral.java

@@ -15,4 +15,7 @@
  */
 package io.oxia.client.api;
 
+/**
+ * @hidden
+ */
 public record OptionEphemeral() implements PutOption {}

client-api/src/main/java/io/oxia/client/api/OxiaClientBuilder.java

@@ -25,40 +25,175 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Supplier;
 
+/** Builder for {@link SyncOxiaClient} and {@link AsyncOxiaClient}. */
 public interface OxiaClientBuilder {
 
+    /**
+     * Create a new client builder.
+     *
+     * @param serviceAddress the address of the Oxia server
+     * @return the client builder instance
+     */
     static OxiaClientBuilder create(String serviceAddress) {
         return DefaultImplementation.getDefaultImplementation(serviceAddress);
     }
 
+    /**
+     * Create a synchronous client.
+     *
+     * <p>This method is blocking while the client initializes and talks to the server.
+     *
+     * @return the synchronous client instance
+     * @throws OxiaException if failed to create the client
+     */
     SyncOxiaClient syncClient() throws OxiaException;
 
+    /**
+     * Create an asynchronous client.
+     *
+     * @return a future to retrieve the client instance, when ready
+     */
     CompletableFuture<AsyncOxiaClient> asyncClient();
 
+    /**
+     * Specify a custom timeout for all requests.
+     *
+     * <p>Default is <code>30 secs</code>.
+     *
+     * @param requestTimeout the timeout duration
+     * @return the builder instance
+     */
     OxiaClientBuilder requestTimeout(Duration requestTimeout);
 
+    /**
+     * Specify the maximum time to wait for a batch to be sent.
+     *
+     * <p>Default is <code>5 millis</code>
+     *
+     * <p>A larger linger time might help in creating batches with more ops in them and thus might
+     * improve the overall throughput.
+     *
+     * <p>A shorter linger time might help in minimizing the latency.
+     *
+     * @param batchLinger the batch linger duration
+     * @return the builder instance
+     */
     OxiaClientBuilder batchLinger(Duration batchLinger);
 
+    /**
+     * Specify the maximum number of requests to include in a batch.
+     *
+     * <p>Default is <code>1000</code>.
+     *
+     * @param maxRequestsPerBatch the maximum number of requests per batch
+     * @return the builder instance
+     */
     OxiaClientBuilder maxRequestsPerBatch(int maxRequestsPerBatch);
 
+    /**
+     * Specify the Oxia namesace to use for this client instance.
+     *
+     * <p>Default is <code>"default"</code>.
+     *
+     * @param namespace the namespace to use
+     * @return the builder instance
+     */
     OxiaClientBuilder namespace(String namespace);
 
+    /**
+     * Specify the session timeout for this client instance.
+     *
+     * <p>Default is <code>30 secs</code>.
+     *
+     * @see <a href="https://oxia-db.github.io/docs/features/ephemerals">Oxia Ephemeral Records</a>
+     * @param sessionTimeout the session timeout duration
+     * @return the builder instance
+     */
     OxiaClientBuilder sessionTimeout(Duration sessionTimeout);
 
+    /**
+     * Specify the client identifier for this client instance.
+     *
+     * <p>Default is a random UUID.
+     *
+     * @param clientIdentifier the client identifier
+     * @return the builder instance
+     * @see <a
+     *     href="https://oxia-db.github.io/docs/features/ephemerals#session-id-and-client-identity">Oxia
+     *     Client Identity</a>
+     */
     OxiaClientBuilder clientIdentifier(String clientIdentifier);
 
+    /**
+     * Specify the client identifier for this client instance.
+     *
+     * <p>Default is a random UUID.
+     *
+     * @param clientIdentifier the client identifier supplier
+     * @return the builder instance
+     * @see <a
+     *     href="https://oxia-db.github.io/docs/features/ephemerals#session-id-and-client-identity">Oxia
+     *     Client Identity</a>
+     */
     OxiaClientBuilder clientIdentifier(Supplier<String> clientIdentifier);
 
+    /**
+     * Specify the OpenTelemetry instance to use for this client instance.
+     *
+     * <p>By default, the client will use the global OpenTelemetry instance if available.
+     *
+     * @param openTelemetry an OpenTelemetry instance
+     * @return the builder instance
+     */
     OxiaClientBuilder openTelemetry(OpenTelemetry openTelemetry);
 
+    /**
+     * Configure the authentication plugin and its parameters.
+     *
+     * @param authentication the authentication instance
+     * @return the builder instance
+     */
     OxiaClientBuilder authentication(Authentication authentication);
 
+    /**
+     * Configure the connection backoff policy.
+     *
+     * <p>Defaults are <code>min=100millis, max=30sec</code>.
+     *
+     * @param minDelay the minimum delay between retries
+     * @param maxDelay the maximum delay between retries
+     * @return the builder instance
+     */
     OxiaClientBuilder connectionBackoff(Duration minDelay, Duration maxDelay);
 
+    /**
+     * Configure the maximum number of connections to each Oxia server node.
+     *
+     * <p>Default is <code>1</code>.
+     *
+     * @param connections the maximum number of connections
+     * @return the builder instance
+     */
     OxiaClientBuilder maxConnectionPerNode(int connections);
 
+    /**
+     * Configure the keep alive timeout for the connection.
+     *
+     * <p>Default is <code>5 sec</code>.
+     *
+     * @param connectionKeepAliveTimeout the keep alive timeout duration
+     * @return the builder instance
+     */
     OxiaClientBuilder connectionKeepAliveTimeout(Duration connectionKeepAliveTimeout);
 
+    /**
+     * Configure the keep alive interval for the connection.
+     *
+     * <p>Default is <code>10 sec</code>.
+     *
+     * @param connectionKeepAlive the keep alive interval duration
+     * @return the builder instance
+     */
     OxiaClientBuilder connectionKeepAliveTime(Duration connectionKeepAlive);
 
     /**
@@ -72,6 +207,12 @@ static OxiaClientBuilder create(String serviceAddress) {
     OxiaClientBuilder authentication(String authPluginClassName, String authParamsString)
             throws UnsupportedAuthenticationException;
 
+    /**
+     * Configures whether to enable TLS (Transport Layer Security) for the client connection.
+     *
+     * @param enableTls true to enable TLS, false to disable it
+     * @return the builder instance for method chaining
+     */
     OxiaClientBuilder enableTls(boolean enableTls);
 
     /**