reducing to 1838474 warnings

Author: clun

astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java

@@ -30,33 +30,32 @@
 
 import java.util.UUID;
 
-import static com.datastax.astra.client.exception.InvalidEnvironmentException.throwErrorRestrictedAstra;
+import static com.datastax.astra.client.exceptions.InvalidEnvironmentException.throwErrorRestrictedAstra;
 
 /**
  * Serves as the primary entry point to the Data API client, providing an intuitive and streamlined interface
  * for interacting with the Data API. The client is compatible with both Astra environments and on-premise
  * DataStax Enterprise installations, offering flexibility across deployment scenarios.
  *
- * <p>The {@code DataAPIClient} is designed to simplify database interactions by providing:
+ * <p>The {@code DataAPIClient} is designed to simplify database interactions by providing:</p>
+ *
  * <ul>
  *   <li>A high-level, user-friendly API that adheres to fluent programming principles.</li>
  *   <li>Support for builder patterns to accommodate complex client configurations.</li>
  *   <li>Idiomatic method naming and design inspired by the MongoDB API, ensuring a familiar experience for developers.</li>
  * </ul>
- * This design philosophy facilitates quick onboarding and ease of use while enabling advanced customizations when needed.
- * </p>
  *
- * <p>Core Features:
+ * <p>This design philosophy facilitates quick onboarding and ease of use while enabling advanced customizations when needed.</p>
+ *
+ * <h2>Core Features:</h2>
  * <ul>
  *   <li>Data manipulation capabilities for databases, collections, and tables.</li>
  *   <li>Administrative operations, such as database and keyspace creation (requires appropriate privileges).</li>
  *   <li>Support for destination-specific options, including Astra and DSE environments.</li>
  * </ul>
- * </p>
  *
- * <p>Example usage:</p>
- * <pre>
- * {@code
+ * <h2>Example Usage:</h2>
+ * <pre>{@code
  * DataAPIClientOptions options = new DataAPIClientOptions()
  *         .destination(DataAPIDestination.DSE) // Set the destination
  *         .httpClientOptions(new HttpClientOptions()
@@ -68,8 +67,7 @@
  *         .enableFeatureFlagTables() // Enable feature flag for tables
  *         .addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true"); // Add custom headers
  * DataAPIClient client = new DataAPIClient("token", options);
- * }
- * </pre>
+ * }</pre>
  */
 public class DataAPIClient {
 
@@ -214,14 +212,13 @@ public DataAPIClient(DataAPIClientOptions options) {
      * performing administrative tasks such as database creation, user management, and configuration adjustments.
      * It provides a programmatic interface for managing Astra resources securely and efficiently.
      *
-     * <p>This method has three variants, allowing for flexibility in token usage:
+     * <p>This method has three variants, allowing for flexibility in token usage:</p>
      * <ul>
      *   <li>{@link #getAdmin()}: Uses the authentication token provided during the {@code DataAPIClient} initialization.</li>
      *   <li>{@link #getAdmin(String superToken)}: Uses a custom token with elevated privileges, overriding the default token.</li>
      *   <li>{@link #getAdmin(AdminOptions adminOptions)}: Allows fine-grained control by specifying both the token and
      *       additional options.</li>
      * </ul>
-     * </p>
      *
      * <p>To perform administrative tasks, the token must belong to a user with sufficient privileges (e.g., Database
      * Administrator or Organization Administrator). If these conditions are not met, a {@code SecurityException} is thrown.</p>
@@ -288,15 +285,14 @@ public AstraDBAdmin getAdmin(String superToken) {
      * with the specified Data API endpoint, supporting a wide range of data manipulation operations such as querying,
      * inserting, updating, and deleting data.
      *
-     * <p>The {@code getDatabase} method has multiple variants to cater to different usage scenarios:
+     * <p>The {@code getDatabase} method has multiple variants to cater to different usage scenarios:</p>
      * <ul>
      *   <li>{@link #getDatabase(String)}: Connects to the Data API using a specified API endpoint with default options.</li>
      *   <li>{@link #getDatabase(UUID)}: Connects to the Data API using a database identifier, automatically resolving the endpoint.</li>
      *   <li>{@link #getDatabase(String, DatabaseOptions)}: Allows customization of database options while connecting to a specific API endpoint.</li>
      *   <li>{@link #getDatabase(UUID, DatabaseOptions)}: Resolves the endpoint using a database identifier and applies custom database options.</li>
      *   <li>{@link #getDatabase(UUID, String, DatabaseOptions)}: Provides fine-grained control by specifying the database ID, region, and additional options.</li>
      * </ul>
-     * </p>
      *
      * <p>By providing flexibility in how connections are established and configured, these methods simplify the process
      * of interacting with Cassandra databases through the Data API. They are suitable for various deployment scenarios,

astra-db-java/src/main/java/com/datastax/astra/client/admin/AdminOptions.java

@@ -28,17 +28,52 @@
 import lombok.Setter;
 import lombok.experimental.Accessors;
 
+/**
+ * Represents the configuration options for administrative operations in the database API.
+ * This class extends {@link BaseOptions} to inherit common configuration options
+ * and provides additional functionality specific to administrative commands.
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * {@code
+ * AdminOptions options = new AdminOptions()
+ *     .token("your-token-here")
+ *     .options(new DataAPIClientOptions())
+ *     .serializer(new CustomSerializer());
+ * }
+ * </pre>
+ *
+ * <p>Key Features:</p>
+ * <ul>
+ *   <li>Provides default serialization through {@link DatabaseSerializer}.</li>
+ *   <li>Fluent and chainable setter methods for seamless configuration.</li>
+ *   <li>Supports administrative command types via {@link CommandType#DATABASE_ADMIN}.</li>
+ * </ul>
+ */
 @Setter
 @Accessors(fluent = true, chain = true)
 public class AdminOptions extends BaseOptions<AdminOptions> {
 
-    /** Serializer for the Collections. */
+    /**
+     * Serializer for the collections.
+     * Defaults to {@link DatabaseSerializer}.
+     */
     private static final DataAPISerializer DEFAULT_SERIALIZER = new DatabaseSerializer();
 
+    /**
+     * Serializer for the collections.
+     * Defaults to {@link DatabaseSerializer}.
+     */
     public AdminOptions() {
         this(null, null);
     }
 
+    /**
+     * Constructs an {@code AdminOptions} instance with the specified token and options.
+     *
+     * @param token the authentication token to use.
+     * @param options additional configuration options for the Data API client.
+     */
     public AdminOptions(String token, DataAPIClientOptions options) {
         super(token, CommandType.DATABASE_ADMIN, DEFAULT_SERIALIZER, options);
     }

astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBAdmin.java

@@ -21,7 +21,7 @@
  */
 
 import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.client.databases.DatabaseInfo;
+import com.datastax.astra.client.databases.definition.DatabaseInfo;
 import com.datastax.astra.client.databases.DatabaseOptions;
 import com.datastax.astra.internal.api.AstraApiEndpoint;
 import com.datastax.astra.internal.command.LoggingCommandObserver;
@@ -49,7 +49,7 @@
 import java.util.stream.Collectors;
 
 import static com.datastax.astra.client.core.options.DataAPIClientOptions.DEFAULT_KEYSPACE;
-import static com.datastax.astra.client.exception.InvalidEnvironmentException.throwErrorRestrictedAstra;
+import static com.datastax.astra.client.exceptions.InvalidEnvironmentException.throwErrorRestrictedAstra;
 import static com.datastax.astra.internal.utils.AnsiUtils.green;
 import static com.dtsx.astra.sdk.utils.Utils.readEnvVariable;
 
@@ -319,7 +319,7 @@ public DatabaseInfo getDatabaseInfo(@NonNull UUID id) {
      *
      * @param databaseId
      *      database identifier
-     * @param options
+     * @param dbOptions
      *      target keyspace name
      * @return
      *      database client

astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBDatabaseAdmin.java

@@ -22,7 +22,6 @@
 
 import com.datastax.astra.client.DataAPIDestination;
 import com.datastax.astra.client.core.commands.BaseOptions;
-import com.datastax.astra.client.core.commands.CommandType;
 import com.datastax.astra.client.core.options.DataAPIClientOptions;
 import com.datastax.astra.client.core.results.FindEmbeddingProvidersResult;
 import com.datastax.astra.client.databases.DatabaseOptions;

astra-db-java/src/main/java/com/datastax/astra/client/collections/Collection.java

@@ -20,29 +20,32 @@
  * #L%
  */
 
-import com.datastax.astra.client.collections.documents.Document;
-import com.datastax.astra.client.collections.documents.ReturnDocument;
-import com.datastax.astra.client.collections.documents.Update;
+import com.datastax.astra.client.collections.definition.CollectionDefaultIdTypes;
+import com.datastax.astra.client.collections.definition.CollectionDefinition;
+import com.datastax.astra.client.collections.definition.CollectionDescriptor;
+import com.datastax.astra.client.collections.definition.documents.Document;
+import com.datastax.astra.client.collections.commands.ReturnDocument;
+import com.datastax.astra.client.collections.commands.Update;
 import com.datastax.astra.client.collections.exceptions.TooManyDocumentsToCountException;
-import com.datastax.astra.client.collections.options.CollectionDeleteManyOptions;
-import com.datastax.astra.client.collections.options.CollectionDeleteOneOptions;
-import com.datastax.astra.client.collections.options.CollectionFindOneAndDeleteOptions;
-import com.datastax.astra.client.collections.options.CollectionFindOneAndReplaceOptions;
-import com.datastax.astra.client.collections.options.CollectionFindOneAndUpdateOptions;
-import com.datastax.astra.client.collections.options.CollectionFindOneOptions;
-import com.datastax.astra.client.collections.options.CollectionFindOptions;
-import com.datastax.astra.client.collections.options.CollectionInsertManyOptions;
-import com.datastax.astra.client.collections.options.CollectionInsertOneOptions;
-import com.datastax.astra.client.collections.options.CollectionReplaceOneOptions;
-import com.datastax.astra.client.collections.options.CollectionUpdateManyOptions;
-import com.datastax.astra.client.collections.options.CountDocumentsOptions;
-import com.datastax.astra.client.collections.options.EstimatedCountDocumentsOptions;
-import com.datastax.astra.client.collections.options.UpdateOneOptions;
-import com.datastax.astra.client.collections.results.CollectionDeleteResult;
-import com.datastax.astra.client.collections.results.CollectionInsertManyResult;
-import com.datastax.astra.client.collections.results.CollectionInsertOneResult;
-import com.datastax.astra.client.collections.results.CollectionUpdateResult;
-import com.datastax.astra.client.collections.results.FindOneAndReplaceResult;
+import com.datastax.astra.client.collections.commands.options.CollectionDeleteManyOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionDeleteOneOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionFindOneAndDeleteOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionFindOneAndReplaceOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionFindOneAndUpdateOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionFindOneOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionFindOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionInsertManyOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionInsertOneOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionReplaceOneOptions;
+import com.datastax.astra.client.collections.commands.options.CollectionUpdateManyOptions;
+import com.datastax.astra.client.collections.commands.options.CountDocumentsOptions;
+import com.datastax.astra.client.collections.commands.options.EstimatedCountDocumentsOptions;
+import com.datastax.astra.client.collections.commands.options.UpdateOneOptions;
+import com.datastax.astra.client.collections.commands.results.CollectionDeleteResult;
+import com.datastax.astra.client.collections.commands.results.CollectionInsertManyResult;
+import com.datastax.astra.client.collections.commands.results.CollectionInsertOneResult;
+import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
+import com.datastax.astra.client.collections.commands.results.FindOneAndReplaceResult;
 import com.datastax.astra.client.core.commands.BaseOptions;
 import com.datastax.astra.client.core.commands.Command;
 import com.datastax.astra.client.core.paging.CollectionCursor;
@@ -56,8 +59,8 @@
 import com.datastax.astra.client.core.types.UUIDv6;
 import com.datastax.astra.client.core.types.UUIDv7;
 import com.datastax.astra.client.databases.Database;
-import com.datastax.astra.client.exception.DataAPIException;
-import com.datastax.astra.client.exception.UnexpectedDataAPIResponseException;
+import com.datastax.astra.client.exceptions.DataAPIException;
+import com.datastax.astra.client.exceptions.UnexpectedDataAPIResponseException;
 import com.datastax.astra.internal.api.DataAPIResponse;
 import com.datastax.astra.internal.api.DataAPIStatus;
 import com.datastax.astra.internal.command.AbstractCommandRunner;
@@ -88,8 +91,8 @@
 import static com.datastax.astra.client.core.options.DataAPIClientOptions.MAX_CHUNK_SIZE;
 import static com.datastax.astra.client.core.options.DataAPIClientOptions.MAX_COUNT;
 import static com.datastax.astra.client.core.types.DataAPIKeywords.SORT_VECTOR;
-import static com.datastax.astra.client.exception.DataAPIException.ERROR_CODE_INTERRUPTED;
-import static com.datastax.astra.client.exception.DataAPIException.ERROR_CODE_TIMEOUT;
+import static com.datastax.astra.client.exceptions.DataAPIException.ERROR_CODE_INTERRUPTED;
+import static com.datastax.astra.client.exceptions.DataAPIException.ERROR_CODE_TIMEOUT;
 import static com.datastax.astra.internal.utils.AnsiUtils.cyan;
 import static com.datastax.astra.internal.utils.AnsiUtils.green;
 import static com.datastax.astra.internal.utils.AnsiUtils.magenta;

astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionOptions.java

@@ -21,11 +21,7 @@
  */
 
 import com.datastax.astra.client.core.commands.BaseOptions;
-import com.datastax.astra.client.core.commands.CommandType;
 import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
-import com.datastax.astra.internal.utils.Assert;
-import lombok.NoArgsConstructor;
 import lombok.Setter;
 import lombok.experimental.Accessors;
 

astra-db-java/src/main/java/com/datastax/astra/client/collections/documents/ReturnDocument.java renamed to astra-db-java/src/main/java/com/datastax/astra/client/collections/commands/ReturnDocument.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.client.collections.documents;
+package com.datastax.astra.client.collections.commands;
 
 /*-
  * #%L

astra-db-java/src/main/java/com/datastax/astra/client/collections/documents/Update.java renamed to astra-db-java/src/main/java/com/datastax/astra/client/collections/commands/Update.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.client.collections.documents;
+package com.datastax.astra.client.collections.commands;
 
 /*-
  * #%L
@@ -20,6 +20,8 @@
  * #L%
  */
 
+import com.datastax.astra.client.collections.definition.documents.Document;
+
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.LinkedHashMap;

astra-db-java/src/main/java/com/datastax/astra/client/collections/documents/Updates.java renamed to astra-db-java/src/main/java/com/datastax/astra/client/collections/commands/Updates.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.client.collections.documents;
+package com.datastax.astra.client.collections.commands;
 
 /*-
  * #%L

astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteManyOptions.java renamed to astra-db-java/src/main/java/com/datastax/astra/client/collections/commands/options/CollectionDeleteManyOptions.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.client.collections.options;
+package com.datastax.astra.client.collections.commands.options;
 
 /*-
  * #%L