javadocs, javadoc, javadoc

datastax · clun · Apr 4, 2025 · Nov 21, 2024 · Nov 30, 2024 · Nov 30, 2024
commit 49557dba0049b5fcd288e8a3983fc690d729ee53
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBAdmin.java b/astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBAdmin.java
@@ -92,8 +92,8 @@ public class AstraDBAdmin {
     }
 
     /**
-     * Initialization with an authentication token and target environment, Use this constructor for testing purpose.
-
+     * Initialization with an authentication token and target environment,
+     * Use this constructor for testing purpose.
      * @param options
      *      options for client
      */

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBDatabaseAdmin.java b/astra-db-java/src/main/java/com/datastax/astra/client/admin/AstraDBDatabaseAdmin.java
@@ -58,6 +58,8 @@ public class AstraDBDatabaseAdmin extends AbstractCommandRunner<AdminOptions> im
      *
      * @param db
      *      target database
+     * @param adminOptions
+     *     options to use for the admin operations like timeouts
      */
     public AstraDBDatabaseAdmin(com.datastax.astra.client.databases.Database db, AdminOptions adminOptions) {
         Assert.notNull(db, "database");
@@ -173,6 +175,7 @@ public com.datastax.astra.client.databases.Database getDatabase(String keyspace,
         return new com.datastax.astra.client.databases.Database(getApiEndpoint(), db.getOptions());
     }
 
+    /** {@inheritDoc} */
     @Override
     public Set<String> listKeyspaceNames() {
         log.debug("listKeyspaceNames");
@@ -189,12 +192,14 @@ public FindEmbeddingProvidersResult findEmbeddingProviders() {
         return new FindEmbeddingProvidersResult(admin.findEmbeddingProviders().getEmbeddingProviders());
     }
 
+    /** {@inheritDoc} */
     @Override
     public void createKeyspace(String keyspace, boolean updateDBKeyspace) {
         log.debug("createKeyspace");
         devopsDbClient.database(databaseId.toString()).keyspaces().create(keyspace);
     }
 
+    /** {@inheritDoc} */
     @Override
     public void dropKeyspace(String keyspace) {
         log.debug("dropKeyspace");

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/admin/DatabaseAdmin.java b/astra-db-java/src/main/java/com/datastax/astra/client/admin/DatabaseAdmin.java
@@ -39,24 +39,6 @@
  * creation, retrieval, updating, and deletion of namespaces. By leveraging the extended command runner capabilities,
  * it facilitates a streamlined and efficient approach to data management within the specified context.
  * </p>
- * <p>&nbsp;</p>
- * <p>Example usage:</p>
- * <pre>
- * {@code
- *
- * // Initialization of the client
- * DataApiClient client1 = DataApiClients.create("http://<>endpoint>", "<token>", new HttpClientOptions());
- *
- * // Example operation: Create a new namespace
- * DataApiNamespace newNamespace = client.createNamespace("exampleNamespace");
- *
- * // Example operation: Fetch a namespace
- * DataApiNamespace fetchedNamespace = client.getNamespace("exampleNamespace");
- *
- * // Example operation: Delete a namespace
- * client.deleteNamespace("exampleNamespace");
- * }
- * </pre>
  */
 public interface DatabaseAdmin {
 
@@ -209,29 +191,45 @@ default void dropKeyspace(String keyspace) {
         dropKeyspace(keyspace, null);
     }
 
-    void dropKeyspace(String keyspace, BaseOptions<?> options);
-
     /**
-     * Asynchronously drops (deletes) the specified keyspace from the database. This operation is idempotent, meaning
-     * it will not produce an error if the keyspace does not exist. Performing this operation asynchronously ensures
-     * that the calling thread remains responsive, and can be particularly useful for applications that require high
-     * availability and cannot afford to block on potentially long-running operations. Just like its synchronous counterpart,
-     * this method should be used with caution as dropping a keyspace will remove all associated data, collections,
-     * or tables, and this action is irreversible.
+     * Drops (deletes) the specified keyspace from the database. This operation is idempotent; it will not
+     * produce an error if the keyspace does not exist. This method is useful for cleaning up data or removing
+     * entire keyspaces as part of database maintenance or restructuring. Caution should be exercised when using
+     * this method, as dropping a keyspace will remove all the data, collections, or tables contained within it,
+     * and this action cannot be undone.
      *
      * <p>Example usage:</p>
      * <pre>
      * {@code
      * // Assume 'client' is an instance of your data API client
-     * String keyspace = "asyncTargetKeyspace";
+     * String keyspace = "targetKeyspace";
      *
-     * // Asynchronously drop the namespace
-     * client.dropKeyspaceAsync(keyspace);
+     * // Drop the keyspace
+     * client.dropKeyspace(keyspace);
      *
-     * // The keyspace 'asyncTargetKeyspace' is now being deleted in the background, along with all its contained data
+     * // The keyspace 'targetKeyspace' is now deleted, along with all its contained data
      * }
      * </pre>
      *
+     * This example demonstrates how to safely drop a keyspace by name. The operation ensures that even if the
+     * keyspace does not exist, the method call will not interrupt the flow of the application, thereby allowing
+     * for flexible and error-tolerant code design.
+     *
+     * @param keyspace The name of the keyspace to be dropped. This parameter specifies the target keyspace
+     *                  that should be deleted. The operation will proceed silently and without error even if the
+     *                  keyspace does not exist, ensuring consistent behavior.
+     * @param options The options to use for the operation.
+     */
+    void dropKeyspace(String keyspace, BaseOptions<?> options);
+
+    /**
+     * Asynchronously drops (deletes) the specified keyspace from the database. This operation is idempotent, meaning
+     * it will not produce an error if the keyspace does not exist. Performing this operation asynchronously ensures
+     * that the calling thread remains responsive, and can be particularly useful for applications that require high
+     * availability and cannot afford to block on potentially long-running operations. Just like its synchronous counterpart,
+     * this method should be used with caution as dropping a keyspace will remove all associated data, collections,
+     * or tables, and this action is irreversible.
+     *
      * This example illustrates the non-blocking nature of dropping a keyspace. It demonstrates the method's utility in
      * maintaining application responsiveness, even when performing potentially long-running database operations.
      *

diff --git a/.../src/main/java/com/datastax/astra/client/collections/definition/CollectionDefinition.java b/.../src/main/java/com/datastax/astra/client/collections/definition/CollectionDefinition.java
@@ -174,6 +174,9 @@ public CollectionDefinition defaultId(CollectionDefaultIdTypes type) {
      * @return self reference
      */
     public CollectionDefinition vectorDimension(int size) {
+        if (getVector() == null) {
+            vector = new VectorOptions();
+        }
         getVector().dimension(size);
         return this;
     }
@@ -185,6 +188,9 @@ public CollectionDefinition vectorDimension(int size) {
      * @return self reference
      */
     public CollectionDefinition vectorSimilarity(@NonNull SimilarityMetric metric) {
+        if (getVector() == null) {
+            vector = new VectorOptions();
+        }
         getVector().metric(metric.getValue());
         return this;
     }
@@ -265,6 +271,9 @@ public CollectionDefinition vectorize(String provider, String modeName, String s
             embeddingService.authentication(Map.of("providerKey", sharedSecretKey));
             // <--- Since 1.3.1 the suffix is not needed anymore
         }
+        if (getVector() == null) {
+            vector = new VectorOptions();
+        }
         getVector().service(embeddingService);
         return this;
     }

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/http/Caller.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/http/Caller.java
@@ -31,7 +31,6 @@
  */
 @Setter
 @Accessors(fluent = true, chain = true)
-@NoArgsConstructor
 @AllArgsConstructor
 public class Caller {
 
@@ -41,6 +40,12 @@ public class Caller {
     /** caller version. */
     String version;
 
+    /**
+     * Default constructor.
+     */
+    public Caller() {
+    }
+
     /**
      * Gets name
      *

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/Database.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/Database.java
@@ -759,6 +759,24 @@ public <T> Collection<T> createCollection(String collectionName,
         if (createCollectionOptions != null) {
             if (createCollectionOptions.getDataAPIClientOptions() != null) {
                 collectionOptions.dataAPIClientOptions(createCollectionOptions.getDataAPIClientOptions());
+                DataAPIClientOptions options = createCollectionOptions.getDataAPIClientOptions();
+                // Merging db Headers
+                Map<String, String> dbHeaders = new HashMap<>();
+                dbHeaders.putAll(this.options.getDataAPIClientOptions().getDatabaseAdditionalHeaders());
+                dbHeaders.putAll(options.getDatabaseAdditionalHeaders());
+                options.databaseAdditionalHeaders(dbHeaders);
+                // Merging admin Headers
+                Map<String, String> adminHeaders = new HashMap<>();
+                adminHeaders.putAll(this.options.getDataAPIClientOptions().getAdminAdditionalHeaders());
+                adminHeaders.putAll(options.getAdminAdditionalHeaders());
+                options.adminAdditionalHeaders(adminHeaders);
+                collectionOptions.dataAPIClientOptions(createCollectionOptions.getDataAPIClientOptions());
+                // Merging listeners
+                Map<String, CommandObserver> listeners = new HashMap<>();
+                listeners.putAll(this.options.getDataAPIClientOptions().getObservers());
+                listeners.putAll(options.getObservers());
+                options.observers(listeners);
+
             }
             if (createCollectionOptions.getToken() != null) {
                 collectionOptions.token(createCollectionOptions.getToken());

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/tables/Table.java b/astra-db-java/src/main/java/com/datastax/astra/client/tables/Table.java
@@ -48,7 +48,6 @@
 import com.datastax.astra.client.tables.commands.options.TableUpdateOneOptions;
 import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
 import com.datastax.astra.client.tables.commands.results.TableInsertOneResult;
-import com.datastax.astra.client.tables.commands.results.TableUpdateResult;
 import com.datastax.astra.client.tables.cursor.TableCursor;
 import com.datastax.astra.client.tables.definition.TableDefinition;
 import com.datastax.astra.client.tables.definition.TableDescriptor;
@@ -59,7 +58,6 @@
 import com.datastax.astra.client.tables.exceptions.TooManyRowsToCountException;
 import com.datastax.astra.internal.api.DataAPIData;
 import com.datastax.astra.internal.api.DataAPIResponse;
-import com.datastax.astra.internal.api.DataAPIStatus;
 import com.datastax.astra.internal.command.AbstractCommandRunner;
 import com.datastax.astra.internal.command.CommandObserver;
 import com.datastax.astra.internal.serdes.DataAPISerializer;
@@ -68,7 +66,6 @@
 import com.datastax.astra.internal.utils.Assert;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
-import org.apache.hc.core5.http.NotImplementedException;
 
 import java.util.ArrayList;
 import java.util.Arrays;

diff --git a/...java/src/main/java/com/datastax/astra/client/tables/commands/AlterTableRenameColumns.java b/...java/src/main/java/com/datastax/astra/client/tables/commands/AlterTableRenameColumns.java
@@ -20,8 +20,27 @@
  * #L%
  */
 
-public class AlterTableRenameColumns implements AlterTableOperation{
+/**
+ * Represents an operation to rename columns in a database table.
+ * This class implements the {@link AlterTableOperation} interface,
+ * providing the functionality to return the operation name as "rename".
+ *
+ * <p>This operation is typically used to rename one or more columns in a table
+ * during schema alterations.</p>
+ */
+public class AlterTableRenameColumns implements AlterTableOperation {
+
+    /**
+     * Default constructor.
+     */
+    public AlterTableRenameColumns() {
+    }
 
+    /**
+     * Returns the name of the operation, which is "rename".
+     *
+     * @return a {@link String} representing the name of this operation.
+     */
     @Override
     public String getOperationName() {
         return "rename";

diff --git a/...ava/src/main/java/com/datastax/astra/client/tables/commands/options/TableFindOptions.java b/...ava/src/main/java/com/datastax/astra/client/tables/commands/options/TableFindOptions.java
@@ -32,7 +32,6 @@
  * List Options for a FindOne command.
  */
 @Getter @Setter
-@NoArgsConstructor
 @Accessors(fluent = true, chain = true)
 public class TableFindOptions extends BaseOptions<TableFindOptions> {
 
@@ -71,6 +70,11 @@ public class TableFindOptions extends BaseOptions<TableFindOptions> {
      */
     String pageState;
 
+    /**
+     * Default constructor.
+     */
+    public TableFindOptions() {}
+
     /**
      * Add a skip clause in the find block
      *