diff --git a/.github/workflows/ci-astra-dev-new.yml b/.github/workflows/ci-astra-dev-new.yml
index 19c065ae..53bafe18 100644
--- a/.github/workflows/ci-astra-dev-new.yml
+++ b/.github/workflows/ci-astra-dev-new.yml
@@ -68,7 +68,7 @@ jobs:
mvn test -Dtest=com.datastax.astra.test.integration.dev.*Test
run_vectorize_tests:
- needs: setup
+ needs: BUILD
runs-on: ubuntu-latest
strategy:
matrix:
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java b/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java
index 3fe8e536..fd31a61c 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java
@@ -21,67 +21,58 @@
*/
import com.datastax.astra.client.admin.AstraDBAdmin;
-import com.datastax.astra.client.admin.AstraDBDatabaseAdmin;
-import com.datastax.astra.client.admin.DatabaseAdmin;
+import com.datastax.astra.client.admin.AdminOptions;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.databases.Database;
+import com.datastax.astra.client.databases.DatabaseOptions;
import com.datastax.astra.internal.api.AstraApiEndpoint;
import com.datastax.astra.internal.utils.Assert;
import java.util.UUID;
-import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_KEYSPACE;
import static com.datastax.astra.client.exception.InvalidEnvironmentException.throwErrorRestrictedAstra;
/**
- * Serves as the primary entry point to the Data API client, offering streamlined access to the functionalities
- * provided by the Data API, whether deployed within Astra environments or on-premise DataStax Enterprise installations.
- *
- * This client aims to simplify interactions with the Data API through a user-friendly, high-level API design. It
- * supports fluent API patterns, builder mechanisms for complex configurations, and employs idiomatic method naming
- * conventions to enhance readability and ease of use. The design philosophy of this client closely mirrors that of
- * the established MongoDB API, providing a familiar experience to developers accustomed to MongoDB's client interface.
+ * 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.
+ *
+ *
The {@code DataAPIClient} is designed to simplify database interactions by providing:
+ *
+ * - A high-level, user-friendly API that adheres to fluent programming principles.
+ * - Support for builder patterns to accommodate complex client configurations.
+ * - Idiomatic method naming and design inspired by the MongoDB API, ensuring a familiar experience for developers.
+ *
+ * This design philosophy facilitates quick onboarding and ease of use while enabling advanced customizations when needed.
*
- *
- * Through this client, users can perform a wide range of operations, from basic data manipulation in databases and
- * collections to more advanced administrative tasks. Administrative capabilities, such as database creation and
- * keyspace management, are available to users with the appropriate administrative privileges.
+ *
+ *
Core Features:
+ *
+ * - Data manipulation capabilities for databases, collections, and tables.
+ * - Administrative operations, such as database and keyspace creation (requires appropriate privileges).
+ * - Support for destination-specific options, including Astra and DSE environments.
+ *
*
*
* Example usage:
*
* {@code
- * // Initialize the client with default settings
- * DataAPIClient client = new DataAPIClient("yourAuthTokenHere");
- *
- * // Initialize the client with custom HTTP configuration
- * DataAPIClient clientWithCustomConfig = new DataAPIClient("yourAuthTokenHere", DataAPIOptions.builder()
- * .withHttpRequestTimeout(1000) // Request timeout in milliseconds
- * .withHttpConnectTimeout(10) // Connection timeout in milliseconds
- * .withHttpVersion(HttpClient.Version.HTTP_2) // HTTP protocol version
- * .withDestination("ASTRA") // Target destination, e.g., Astra
- * .build());
+ * DataAPIClientOptions options = new DataAPIClientOptions()
+ * .destination(DataAPIDestination.DSE) // Set the destination
+ * .httpClientOptions(new HttpClientOptions()
+ * .httpRedirect(HttpClient.Redirect.NORMAL) // Configure HTTP redirects
+ * .httpProxy(new HttpProxy("localhost", 8080)) // Set up an HTTP proxy
+ * .httpRetries(1, Duration.ofSeconds(10))) // Configure retries
+ * .timeoutOptions(new TimeoutOptions()
+ * .requestTimeoutMillis(1000)) // Set request timeout
+ * .enableFeatureFlagTables() // Enable feature flag for tables
+ * .addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true"); // Add custom headers
+ * DataAPIClient client = new DataAPIClient("token", options);
* }
*
- *
- * This documentation highlights the ease of starting with the DataAPIClient, whether opting for a quick setup with
- * default configurations or a more tailored approach via detailed HTTP client settings. The examples demonstrate
- * both the straightforward initialization process and the method to apply fine-grained configurations for developers'
- * specific needs.
*/
public class DataAPIClient {
- /** parameters names. */
- private static final String ARG_KEYSPACE = "keyspace";
- /** parameters names. */
- private static final String ARG_OPTIONS = "options";
- /** parameters names. */
- private static final String ARG_TOKEN = "token";
- /** parameters names. */
- private static final String ARG_DATABASE_ID = "databaseId";
- /** parameters names. */
- private static final String ARG_REGION = "region";
-
/**
* The authentication token used as credentials in HTTP requests, specifically as the Authorization bearer token.
* This token is crucial for accessing and interacting with Astra environments, where it plays a role in determining
@@ -130,9 +121,7 @@ public class DataAPIClient {
* Example usage:
*
* {@code
- * String myAuthToken = "AstraCS:...";
- * DataAPIClient client = new DataAPIClient(myAuthToken);
- * // Now the client is ready to make authenticated requests with default settings
+ * DataAPIClient client = new DataAPIClient("token");
* }
*
*
@@ -140,7 +129,7 @@ public class DataAPIClient {
* by the server, typically starting with "AstraCS:.." for Astra environments.
*/
public DataAPIClient(String token) {
- this(token, DataAPIClientOptions.builder().build());
+ this(token, new DataAPIClientOptions());
}
/**
@@ -161,15 +150,17 @@ public DataAPIClient(String token) {
* Example usage:
*
* {@code
- * String myAuthToken = "AstraCS:...";
- * DataAPIOptions myOptions = DataAPIOptions.builder()
- * .withHttpRequestTimeout(1000)
- * .withHttpConnectTimeout(500)
- * .withHttpVersion(HttpClient.Version.HTTP_2)
- * .build();
- *
- * DataAPIClient myClient = new DataAPIClient(myAuthToken, myOptions);
- * // The client is now ready to perform actions with custom configurations.
+ * DataAPIClientOptions options = new DataAPIClientOptions()
+ * .destination(DataAPIDestination.DSE) // Set the destination
+ * .httpClientOptions(new HttpClientOptions()
+ * .httpRedirect(HttpClient.Redirect.NORMAL) // Configure HTTP redirects
+ * .httpProxy(new HttpProxy("localhost", 8080)) // Set up an HTTP proxy
+ * .httpRetries(1, Duration.ofSeconds(10))) // Configure retries
+ * .timeoutOptions(new TimeoutOptions()
+ * .requestTimeoutMillis(1000)) // Set request timeout
+ * .enableFeatureFlagTables() // Enable feature flag for tables
+ * .addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true"); // Add custom headers
+ * DataAPIClient client = new DataAPIClient("token", options);
* }
*
*
@@ -180,82 +171,112 @@ public DataAPIClient(String token) {
* @throws IllegalArgumentException if the token is empty or null, or if the options are null.
*/
public DataAPIClient(String token, DataAPIClientOptions options) {
- Assert.hasLength(token, ARG_TOKEN);
- Assert.notNull(options, ARG_OPTIONS);
+ Assert.hasLength(token, "token");
+ Assert.notNull(options, "options");
this.token = token;
this.options = options;
}
- // --------------------------------------------------
- // --- Access AstraDBAdmin ---
- // --------------------------------------------------
-
/**
- * Retrieves an administration client specific to Astra deployments. This client is intended for performing
- * administrative tasks such as creating databases. It requires the use of a token with sufficient privileges.
- *
- * To use this method effectively, the provided authentication token must be associated with a user having
- * elevated privileges, such as a Database Administrator or Organization Administrator. This ensures that
- * the client has the necessary permissions to execute administrative operations within the Astra environment.
- *
- *
- * The administration client provides a programmatic interface for managing various aspects of the Astra
- * deployment, enabling tasks such as database creation, user management, and configuration adjustments
- * without the need for direct interaction with the Astra UI.
- *
+ * Constructs a new instance of the {@link DataAPIClient} without a default token. The token will instead need to
+ * be specified when calling `.getDatabase()` or `.getAdmin()`. Prefer this method when using a db-scoped token
+ * instead of a more universal token.
*
* Example usage:
*
* {@code
- * DataAPIClient apiClient = new DataAPIClient("AstraCS:your_admin_token_here");
- * AstraDBAdmin adminClient = apiClient.getAdmin();
- * // Use adminClient to perform administrative operations, e.g., create a database
+ * DataAPIClientOptions options = new DataAPIClientOptions()
+ * .timeoutOptions(new TimeoutOptions()
+ * .connectTimeoutMillis(1000)
+ * .requestTimeoutMillis(1000))
+ * .httpClientOptions(new HttpClientOptions()
+ * .httpVersion(HttpClient.Version.HTTP_2)
+ * );
+ * DataAPIClient myClient = new DataAPIClient(myOptions);
+ * // The client is now ready to perform actions with custom configurations.
* }
*
*
- * @return An instance of {@link AstraDBAdmin} configured with the current authentication token, ready for
- * administrative operations.
- * @throws SecurityException if the current token does not have the necessary administrative privileges.
+ * @param options - The default options to use when spawning new instances of {@link Database} or {@link AstraDBAdmin}.
*/
- public AstraDBAdmin getAdmin() {
- return getAdmin(this.token);
+ public DataAPIClient(DataAPIClientOptions options) {
+ Assert.notNull(options, "options");
+ this.token = null;
+ this.options = options;
}
+ // --------------------------------------------------
+ // --- Access AstraDBAdmin ---
+ // --------------------------------------------------
+
/**
- * Retrieves an administration client capable of performing CRUD operations on databases, requiring a token with
- * advanced privileges. This method is designed for scenarios where administrative access is necessary beyond the
- * default token capabilities associated with the {@code DataAPIClient}.
- *
- * The provided {@code superUserToken} should be granted sufficient privileges to perform administrative operations,
- * such as creating, updating, and deleting databases. This typically involves tokens associated with roles like
- * Database Administrator or Organization Administrator within the Astra environment.
- *
- *
- * Utilizing this method allows for direct access to the Astra database's administrative functionalities, enabling
- * comprehensive management capabilities through the returned {@link AstraDBAdmin} client. This includes but is not
- * limited to database creation, modification, and deletion.
+ * Retrieves an administration client specifically designed for Astra deployments. This client is used for
+ * performing administrative tasks such as database creation, user management, and configuration adjustments.
+ * It provides a programmatic interface for managing Astra resources securely and efficiently.
+ *
+ *
This method has three variants, allowing for flexibility in token usage:
+ *
+ * - {@link #getAdmin()}: Uses the authentication token provided during the {@code DataAPIClient} initialization.
+ * - {@link #getAdmin(String superToken)}: Uses a custom token with elevated privileges, overriding the default token.
+ * - {@link #getAdmin(AdminOptions adminOptions)}: Allows fine-grained control by specifying both the token and
+ * additional options.
+ *
*
*
+ * 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.
+ *
* Example usage:
*
* {@code
- * String superUserToken = "AstraCS:super_user_token_here";
- * DataAPIClient apiClient = new DataAPIClient(superUserToken);
- * AstraDBAdmin adminClient = apiClient.getAdmin(superUserToken);
- * // Now you can use adminClient for administrative operations like creating a database
+ * // Example 1: Using the default token provided at client initialization
+ * DataAPIClient apiClient = new DataAPIClient("AstraCS:your_admin_token_here");
+ * AstraDBAdmin adminClient = apiClient.getAdmin();
+ * adminClient.createDatabase("new_database", "keyspace_name");
+ *
+ * // Example 2: Using a custom super token for administrative operations
+ * AstraDBAdmin adminClientWithSuperToken = apiClient.getAdmin("AstraCS:your_super_admin_token_here");
+ * adminClientWithSuperToken.createDatabase("another_database", "another_keyspace");
+ *
+ * // Example 3: Using advanced options for fine-grained control
+ * AdminOptions options = new AdminOptions("AstraCS:custom_token", new DataAPIClientOptions().logRequests());
+ * AstraDBAdmin advancedAdminClient = apiClient.getAdmin(options);
+ * advancedAdminClient.createDatabase("custom_database", "custom_keyspace");
* }
*
*
- * @param superUserToken A token with elevated privileges, enabling administrative actions within the Astra
- * environment. This token must be authorized to perform operations such as creating and managing databases.
- * @return An instance of {@link AstraDBAdmin}, configured for administrative tasks with the provided user token.
- * @throws SecurityException if the provided {@code superUserToken} lacks the necessary privileges for administrative operations.
+ * @return An instance of {@link AstraDBAdmin} configured with the appropriate authentication token and options,
+ * ready for administrative operations.
*/
- public AstraDBAdmin getAdmin(String superUserToken) {
+ public AstraDBAdmin getAdmin(AdminOptions adminOptions) {
if (!options.isAstra()) {
throwErrorRestrictedAstra("getAdmin()", options.getDestination());
}
- return new AstraDBAdmin(superUserToken, options);
+ return new AstraDBAdmin(adminOptions);
+ }
+
+ /**
+ * Retrieves an administration client using the default authentication token provided during
+ * {@code DataAPIClient} initialization.
+ *
+ * @return An instance of {@link AstraDBAdmin} configured with the default token.
+ * @throws SecurityException if the token does not have the necessary privileges or the operation is not in an Astra environment.
+ * @see #getAdmin(AdminOptions)
+ */
+ public AstraDBAdmin getAdmin() {
+ return getAdmin(new AdminOptions(token, options));
+ }
+
+ /**
+ * Retrieves an administration client using the default authentication token provided during
+ * {@code DataAPIClient} initialization.
+ *
+ * @param superToken The custom token to use for administrative operations.
+ * @return An instance of {@link AstraDBAdmin} configured with the default token.
+ * @see #getAdmin(AdminOptions)
+ */
+ public AstraDBAdmin getAdmin(String superToken) {
+ return getAdmin(new AdminOptions(superToken, options));
}
// --------------------------------------------------
@@ -263,188 +284,147 @@ public AstraDBAdmin getAdmin(String superUserToken) {
// --------------------------------------------------
/**
- * Retrieves a client for a specific database, enabling interactions with the Data API. This method allows for
- * operations such as querying, updating, and managing data within the specified database and keyspace.
- *
- * The {@code databaseId} parameter is a unique identifier for the target database. This ID ensures that operations
- * performed through the returned client are executed against the correct database instance within the Astra
- * environment or an on-premise DataStax Enterprise setup.
- *
- *
- * The {@code keyspace} parameter specifies the keyspace (often synonymous with "keyspace" in Cassandra terminology)
- * within the database to which the client will have access. Keyspaces are used to organize and isolate data within
- * the database, providing a layer of abstraction and security.
+ * Retrieves a database client configured to interact with the Data API. This client enables direct communication
+ * with the specified Data API endpoint, supporting a wide range of data manipulation operations such as querying,
+ * inserting, updating, and deleting data.
+ *
+ *
The {@code getDatabase} method has multiple variants to cater to different usage scenarios:
+ *
+ * - {@link #getDatabase(String)}: Connects to the Data API using a specified API endpoint with default options.
+ * - {@link #getDatabase(UUID)}: Connects to the Data API using a database identifier, automatically resolving the endpoint.
+ * - {@link #getDatabase(String, DatabaseOptions)}: Allows customization of database options while connecting to a specific API endpoint.
+ * - {@link #getDatabase(UUID, DatabaseOptions)}: Resolves the endpoint using a database identifier and applies custom database options.
+ * - {@link #getDatabase(UUID, String, DatabaseOptions)}: Provides fine-grained control by specifying the database ID, region, and additional options.
+ *
*
*
+ * 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,
+ * including Astra cloud services and on-premise installations.
+ *
* Example usage:
*
* {@code
- * UUID databaseId = UUID.fromString("your-database-uuid-here");
- * String keyspace = "your_keyspace_here";
+ * // Example 1: Connect using a direct API endpoint
+ * String apiEndpoint = "https://-.apps.astra.datastax.com";
* DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
- * Database databaseClient = apiClient.getDatabase(databaseId, keyspace);
- * // Use databaseClient to perform data operations within the specified keyspace
+ * Database databaseClient = apiClient.getDatabase(apiEndpoint);
+ *
+ * // Example 2: Connect using a database ID (with automatic endpoint resolution)
+ * UUID databaseId = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
+ * Database databaseClientById = apiClient.getDatabase(databaseId);
+ *
+ * // Example 3: Customize options while connecting
+ * DatabaseOptions options = new DatabaseOptions("yourAuthTokenHere", new DataAPIClientOptions().logRequests());
+ * Database customDatabaseClient = apiClient.getDatabase(apiEndpoint, options);
* }
*
*
- * @param databaseId The unique identifier of the database to interact with.
- * @param keyspace The keyspace within the specified database to which operations will be scoped.
- * @return A {@link Database} client configured to interact with the specified database and keyspace, allowing for
- * data manipulation and query operations.
+ * @return A {@link Database} client tailored for interaction with the Data API, configured according to the
+ * provided parameters.
+ *
+ * @throws IllegalArgumentException If the provided parameters are invalid or insufficient for resolving the endpoint.
*/
- public Database getDatabase(UUID databaseId, String keyspace) {
- Assert.notNull(databaseId, ARG_DATABASE_ID);
- Assert.hasLength(keyspace, ARG_KEYSPACE);
- if (!options.isAstra()) {
- throwErrorRestrictedAstra("getDatabase(id,keyspace)", options.getDestination());
- }
- return new Database(new AstraApiEndpoint(databaseId,
- getAdmin().getDatabaseInfo(databaseId).getRegion(),
- options.getAstraEnvironment()).getApiEndPoint(),
- this.token, keyspace, options);
+ public Database getDatabase(String apiEndpoint, DatabaseOptions dbOptions) {
+ return new Database(apiEndpoint, dbOptions);
}
/**
- * Retrieves a client for a specific database, enabling interactions with the Data API. This method allows for
- * operations such as querying, updating, and managing data within the specified database and keyspace.
- *
- * @param databaseId The unique identifier of the database to interact with.
- * @param keyspace The keyspace associated to this database
- * @param region The cloud provider region where the database is deployed.
+ * Retrieves a database client configured to connect to the Data API using the specified API endpoint.
+ *
+ * Uses default {@link DatabaseOptions} for configuration.
+ *
*
- * @return
- * A {@link Database} client configured to interact with the specified database and keyspace, allowing for
- * data manipulation and query operations.
+ * @param apiEndpoint The URL of the Data API endpoint to connect to.
+ * @return A {@link Database} client configured with default options for the specified endpoint.
+ * @see #getDatabase(String, DatabaseOptions)
*/
- public Database getDatabase(UUID databaseId, String keyspace, String region) {
- Assert.notNull(databaseId, ARG_DATABASE_ID);
- Assert.hasLength(keyspace, ARG_KEYSPACE);
- Assert.hasLength(region, ARG_REGION);
- if (!options.isAstra()) {
- throwErrorRestrictedAstra("getDatabase(dbId,keyspace,region)", options.getDestination());
- }
- return new Database(new AstraApiEndpoint(databaseId, region,
- options.getAstraEnvironment()).getApiEndPoint(),
- this.token, keyspace, options);
+ public Database getDatabase(String apiEndpoint) {
+ return getDatabase(apiEndpoint, new DatabaseOptions(token, options));
}
/**
- * Retrieves a client for interacting with a specified database using its unique identifier. This client facilitates
- * direct communication with the Data API, enabling a range of operations such as querying, inserting, updating, and
- * deleting data within the database. This streamlined method provides access to the default keyspace or keyspace.
+ * Retrieves a database client configured to connect to the Data API using a database identifier.
*
- * The {@code databaseId} serves as a unique identifier for the database within the Astra environment or an on-premise
- * DataStax Enterprise setup, ensuring that all operations through the client are correctly routed to the intended
- * database instance.
+ * Automatically resolves the API endpoint based on the database ID and uses default {@link DatabaseOptions}.
*
*
- * Example usage:
- *
- * {@code
- * UUID databaseId = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
- * DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
- * Database databaseClient = apiClient.getDatabase(databaseId);
- * // Perform data operations using the databaseClient
- * }
- *
- *
- * @param databaseId The unique identifier of the database for which to retrieve the client.
- * @return A {@link Database} client that provides the ability to perform operations on the specified database.
+ * @param databaseId The unique identifier of the database.
+ * @return A {@link Database} client configured with default options for the resolved endpoint.
+ * @see #getDatabase(UUID, DatabaseOptions)
*/
public Database getDatabase(UUID databaseId) {
- return getDatabase(databaseId, DEFAULT_KEYSPACE);
+ return getDatabase(lookupEndpoint(databaseId, null), new DatabaseOptions(token, options));
}
/**
- * Creates and returns a database client configured to interact with the Data API at the specified API endpoint
- * and within the given keyspace. This method facilitates operations such as querying, inserting, updating, and
- * deleting data by directly communicating with the Data API, allowing for a wide range of data manipulation
- * tasks in a specified keyspace.
+ * Retrieves a database client configured to connect to the Data API using a database identifier,
+ * with custom {@link DatabaseOptions}.
*
- * The {@code apiEndpoint} parameter should be the URL of the API endpoint where the Data API is hosted. This
- * is typically a fully qualified URL that points to the Astra service or an on-premise DataStax Enterprise
- * deployment hosting the Data API.
- *
- *
- * The {@code keyspace} parameter specifies the keyspace (or keyspace in Cassandra terms) within the database
- * that the client will interact with. Keyspaces help organize data within the database and provide a way to
- * isolate and manage access to data.
+ * Automatically resolves the API endpoint based on the database ID.
*
*
- * Example usage:
- *
- * {@code
- * String apiEndpoint = "https://example-astra-data-api.com";
- * String keyspace = "my_keyspace";
- * DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
- * Database databaseClient = apiClient.getDatabase(apiEndpoint, keyspace);
- * // Now you can use the databaseClient to perform operations within "my_keyspace"
- * }
- *
- *
- * @param apiEndpoint The URL of the Data API endpoint. This specifies the location of the API the client will connect to.
- * @param keyspace The keyspace within the database that the client will access and perform operations in.
- * @return A {@link Database} client configured for the specified API endpoint and keyspace, enabling data manipulation
- * and query operations within the targeted keyspace.
+ * @param databaseId The unique identifier of the database.
+ * @param dbOptions The options to configure the database client.
+ * @return A {@link Database} client configured for the resolved endpoint and custom options.
+ * @see #getDatabase(UUID)
*/
- public Database getDatabase(String apiEndpoint, String keyspace) {
- return new Database(apiEndpoint, token, keyspace, options);
+ public Database getDatabase(UUID databaseId, DatabaseOptions dbOptions) {
+ return getDatabase(databaseId, null, dbOptions);
}
/**
- * Retrieves a client for interacting with a specified database using its unique identifier.
+ * Retrieves a database client configured to connect to the Data API using a database identifier,
+ * a specified region, and custom {@link DatabaseOptions}.
*
- * @param apiEndpoint
- * apiEndpoint for the database.
- * @return
- * an instance of Database admin
+ * @param databaseId The unique identifier of the database.
+ * @param region The region where the database is deployed (optional).
+ * @param dbOptions The options to configure the database client.
+ * @return A {@link Database} client configured for the specified database ID, region, and options.
+ * @see #getDatabase(UUID, DatabaseOptions)
*/
- public DatabaseAdmin getDatabaseAdmin(String apiEndpoint) {
- return getDatabase(apiEndpoint).getDatabaseAdmin();
+ public Database getDatabase(UUID databaseId, String region, DatabaseOptions dbOptions) {
+ return getDatabase(lookupEndpoint(databaseId, region), dbOptions);
}
+ // --------------------------------------------------
+ // --- Getters ---
+ // --------------------------------------------------
+
/**
- * Retrieves a client for interacting with a specified database using its unique identifier.
+ * Gets token
*
- * @param databaseId
- * database identifier
- * @return
- * the database admin if exists
+ * @return value of token
*/
- public AstraDBDatabaseAdmin getDatabaseAdmin(UUID databaseId) {
- return (AstraDBDatabaseAdmin) getDatabase(databaseId).getDatabaseAdmin();
+ public String getToken() {
+ return token;
}
/**
- * Retrieves a database client configured to interact with the Data API at the specified API endpoint. This method
- * enables direct communication with the Data API, facilitating a range of data manipulation operations such as querying,
- * inserting, updating, and deleting data. The client accesses the default keyspace or keyspace for operations, unless
- * otherwise specified through additional configuration.
- *
- * The {@code apiEndpoint} parameter should be the URL of the Data API endpoint you wish to connect to. This URL
- * points to the location where the Data API is hosted, which could be an Astra cloud service or an on-premise DataStax
- * Enterprise instance.
- *
- *
- * Utilizing this method simplifies the process of connecting to the Data API by focusing on essential configuration,
- * making it particularly useful for scenarios where detailed keyspace management is handled separately or not required.
- *
+ * Gets options
*
- * Example usage:
- *
- * {@code
- * String apiEndpoint = "https://-.apps.astra.datastax.com";
- * DataAPIClient apiClient = new DataAPIClient("yourAuthTokenHere");
- * Database databaseClient = apiClient.getDatabase(apiEndpoint);
- * // The databaseClient is now ready to perform data operations at the specified API endpoint
- * }
- *
- *
- * @param apiEndpoint The URL of the Data API endpoint to connect to, specifying the API's location.
- * @return A {@link Database} client tailored for interaction with the Data API at the provided API endpoint,
- * ready for executing data manipulation tasks.
+ * @return value of options
*/
- public Database getDatabase(String apiEndpoint) {
- return getDatabase(apiEndpoint, DEFAULT_KEYSPACE);
+ public DataAPIClientOptions getOptions() {
+ return options;
}
+
+ /**
+ * Compute the endpoint for the database based on its ID and region.
+ * @param databaseId
+ * database ID (mandotory)
+ * @param region
+ * region (optional), if not provided the default region of the database is used.
+ * @return
+ * the endpoint for the database
+ */
+ private String lookupEndpoint(UUID databaseId, String region) {
+ Assert.notNull(databaseId, "databaseId");
+ String dbRegion = region;
+ if (dbRegion == null) {
+ dbRegion = getAdmin().getDatabaseInfo(databaseId).getRegion();
+ }
+ return new AstraApiEndpoint(databaseId, dbRegion, options.getAstraEnvironment()).getApiEndPoint();
+ }
+
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java b/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java
index 5765f0db..95d3e5ad 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java
@@ -20,13 +20,11 @@
* #L%
*/
-import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.databases.Database;
-import com.datastax.astra.internal.command.LoggingCommandObserver;
-import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_KEYSPACE;
+import static com.datastax.astra.client.core.options.DataAPIClientOptions.DEFAULT_KEYSPACE;
/**
* Provides utility methods for initializing and configuring clients to interact with the Data API. This class
@@ -42,10 +40,10 @@
*
* {@code
* // Get you the client for a local deployment of Data API
- * DataAPIClient devClient = DataAPIClients.localClient();
+ * DataAPIClient devClient = DataAPIClients.local();
*
* // Get you the database for a local deployment of Data API
- * DataAPIClient devClient = DataAPIClients.localDatabase();
+ * DataAPIClient devClient = DataAPIClients.astraDev("token");
*
* // Default target environment Astra Production
* DataAPIClient devClient = DataAPIClients.astra("token");
@@ -66,76 +64,122 @@ public class DataAPIClients {
private DataAPIClients() {}
/**
- * Creates and configures a {@link DataAPIClient} for interaction with a local instance of Stargate, a
- * data gateway for working with Apache Cassandra®. This method is specifically designed for scenarios
- * where the application is intended to communicate with a Stargate instance running locally, facilitating
- * development and testing workflows by providing easy access to local database resources.
+ * Creates and configures a {@link DataAPIClient} for interaction with a local instance of DataAPI,
+ * a data gateway that facilitates working with Apache Cassandra®. This method is tailored for
+ * development and testing workflows, enabling simplified and efficient access to local database
+ * resources without the need for extensive configuration.
*
- * @return A fully configured {@link DataAPIClient} ready for interacting with the local Stargate instance, equipped
- * with the necessary authentication token and targeting options for Cassandra. This client abstracts away
- * the complexities of direct database communication, providing a simplified interface for data operations.
+ * The returned {@link DataAPIClient} is preconfigured with:
+ *
+ * - An authentication token from {@link UsernamePasswordTokenProvider}.
+ * - A destination set to {@code DataAPIDestination.CASSANDRA}.
+ * - Feature flags for tables enabled.
+ * - Request logging enabled.
+ *
+ *
+ * @return A fully configured {@link DataAPIClient} ready for interacting with the local DataAPI instance.
+ * This client provides a streamlined interface for executing data operations, abstracting away
+ * the complexity of direct database interactions.
+ *
+ * Example usage:
+ *
+ * {@code
+ * DataAPIClient client = DataAPIClients.local();
+ * }
+ *
*/
- public static DataAPIClient createForLocal() {
+ public static DataAPIClient clientCassandra() {
+ return clientCassandra(
+ UsernamePasswordTokenProvider.DEFAULT_USERNAME,
+ UsernamePasswordTokenProvider.DEFAULT_CREDENTIALS);
+ }
+
+ public static DataAPIClient clientCassandra(String username, String password) {
+ return new DataAPIClient(
+ new UsernamePasswordTokenProvider(username, password).getToken(),
+ new DataAPIClientOptions()
+ .destination(DataAPIDestination.CASSANDRA)
+ .enableFeatureFlagTables()
+ .logRequests());
+ }
+
+ public static DataAPIClient clientHCD() {
+ return clientHCD(
+ UsernamePasswordTokenProvider.DEFAULT_USERNAME,
+ UsernamePasswordTokenProvider.DEFAULT_CREDENTIALS);
+ }
+
+ public static DataAPIClient clientHCD(String username, String password) {
return new DataAPIClient(
- new UsernamePasswordTokenProvider().getToken(),
- DataAPIClientOptions.builder()
- .withDestination(DataAPIDestination.CASSANDRA)
+ new UsernamePasswordTokenProvider(username, password).getToken(),
+ new DataAPIClientOptions()
+ .destination(DataAPIDestination.HCD)
.enableFeatureFlagTables()
- .logRequests()
- .withObserver(new LoggingCommandObserver(DataAPIClient.class))
- .build());
+ .logRequests());
}
/**
* Creates and configures a {@link Database} client specifically designed for interaction with a local instance
- * of Stargate. This method streamlines the process of setting up a client for local database interactions,
- * encapsulating both the creation of a {@link DataAPIClient} and its integration within a {@link Database}
- * abstraction. This setup is ideal for local development and testing, providing a straightforward path to
- * interact with Cassandra through Stargate with minimal setup.
+ * of the Data API and Cassandra. This method simplifies the setup process by combining the creation of a {@link DataAPIClient}
+ * with the integration of a {@link Database} abstraction. It is tailored for local development and testing,
+ * enabling seamless interaction with Apache Cassandra® through Stargate with minimal configuration.
*
- * @return A {@link Database} client ready for use with a local Stargate instance, fully configured for immediate
- * interaction with the database. This client enables developers to focus on their application logic rather
- * than the intricacies of database connectivity and command execution.
+ * Upon creation, this method ensures that a default keyspace is available in the local Stargate instance
+ * by automatically invoking {@link com.datastax.astra.client.admin.DatabaseAdmin#createKeyspace(String)}. This guarantees that developers
+ * have a ready-to-use environment for executing database operations during their development or testing workflows.
+ *
+ *
The returned {@link Database} client is preconfigured with:
+ *
+ * - A connection to the default local Stargate endpoint.
+ * - An automatically created keyspace, identified by {@code DEFAULT_KEYSPACE}.
+ *
+ * This setup allows developers to focus on application logic rather than database configuration or connectivity.
+ *
+ * @return A {@link Database} client configured for use with a local Stargate instance, including a default
+ * keyspace for immediate interaction. This client abstracts database connectivity and administrative tasks,
+ * streamlining development workflows.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Database db = localDbWithDefaultKeyspace();
+ * }
+ *
*/
- public static Database defaultLocalDatabase() {
- Database db = createForLocal().getDatabase(DEFAULT_ENDPOINT_LOCAL, DEFAULT_KEYSPACE);
- DataAPIDatabaseAdmin dbAdmin = (DataAPIDatabaseAdmin) db.getDatabaseAdmin();
- dbAdmin.createKeyspace(DEFAULT_KEYSPACE);
+ public static Database localDbWithDefaultKeyspace() {
+ Database db = clientCassandra().getDatabase(DEFAULT_ENDPOINT_LOCAL);
+ db.getDatabaseAdmin().createKeyspace(DEFAULT_KEYSPACE);
return db;
}
/**
- * Creates a {@link DataAPIClient} configured for interaction with Astra, DataStax's cloud-native database
- * as a service. This method streamlines the client setup by requiring only an authentication token, handling
- * the other configuration details internally to ensure compatibility with Astra's API and endpoints.
+ * Creates a {@link DataAPIClient} configured for interacting with Astra in a development environment. This
+ * method simplifies the setup of a client specifically tailored for development purposes, where you might
+ * need different configurations or less stringent security measures compared to a production environment.
+ * The client is configured to target Astra's development environment, ensuring that operations do not
+ * affect production data.
*
- * By specifying the destination as Astra in the {@link DataAPIClientOptions}, this method ensures that the
- * client is properly configured to communicate with Astra's infrastructure, leveraging the provided token
- * for authentication. This approach enables developers to quickly establish a connection to Astra for
- * database operations without manually setting up connection parameters and authentication details.
- **
- * @param token The authentication token required for accessing Astra. This token should be treated
- * securely and not exposed in public code repositories or unsecured locations.
- * @return A {@link DataAPIClient} instance ready for use with Astra, fully configured with the provided
- * authentication token and set to target Astra as its destination.
+ * @param token The authentication token required for accessing Astra's development environment. This token
+ * should have the necessary permissions for development activities and be protected accordingly.
+ * @return A {@link DataAPIClient} instance ready for development activities with Astra, configured with the
+ * provided authentication token and targeting Astra's development environment.
*
* Example usage:
*
* {@code
- * DataAPIClient astraClient = DataAPIClients.astra("my_astra_auth_token");
- * // Use astraClient for database operations
+ * DataAPIClient devClient = DataAPIClients.astraDev("your_astra_dev_token");
+ * // Utilize devClient for development database operations
* }
*
*/
- public static DataAPIClient create(String token) {
- return new DataAPIClient(token, DataAPIClientOptions
- .builder()
- .withDestination(DataAPIDestination.ASTRA)
- .build());
+ public static DataAPIClient astraDev(String token) {
+ return new DataAPIClient(token, new DataAPIClientOptions()
+ .destination(DataAPIDestination.ASTRA_DEV)
+ .logRequests());
}
/**
- * Creates a {@link DataAPIClient} configured for interacting with Astra in a development environment. This
+ * Creates a {@link DataAPIClient} configured for interacting with Astra in a production environment. This
* method simplifies the setup of a client specifically tailored for development purposes, where you might
* need different configurations or less stringent security measures compared to a production environment.
* The client is configured to target Astra's development environment, ensuring that operations do not
@@ -149,46 +193,52 @@ public static DataAPIClient create(String token) {
* Example usage:
*
* {@code
- * DataAPIClient devClient = DataAPIClients.astraDev("your_astra_dev_token");
+ * DataAPIClient devClient = DataAPIClients.astra("your_astra_dev_token");
* // Utilize devClient for development database operations
* }
*
*/
- public static DataAPIClient createForAstraDev(String token) {
- return new DataAPIClient(token, DataAPIClientOptions
- .builder()
- .withDestination(DataAPIDestination.ASTRA_DEV)
- .withObserver(new LoggingCommandObserver(DataAPIClient.class))
- .build());
+ public static DataAPIClient astra(String token) {
+ return new DataAPIClient(token, new DataAPIClientOptions()
+ .destination(DataAPIDestination.ASTRA)
+ .logRequests());
}
+
+
/**
* Creates a {@link DataAPIClient} specifically configured for interacting with Astra in a test environment.
- * This setup is ideal for testing scenarios, where isolation from development and production environments
- * is critical to ensure the integrity and stability of test results. By directing the client to Astra's
- * test environment, it facilitates safe, isolated testing of database interactions without risking the
- * alteration of development or production data.
+ * This method is designed for testing scenarios, providing an isolated environment to safely execute
+ * database operations without impacting development or production data.
+ *
+ * The returned {@link DataAPIClient} is preconfigured to:
+ *
+ * - Authenticate using the provided test-specific token.
+ * - Target the {@code DataAPIDestination.ASTRA_TEST} environment.
+ * - Enable request logging for better visibility during test operations.
+ *
+ *
+ * This setup ensures that all database interactions are restricted to Astra's test environment,
+ * preserving the integrity of other environments while facilitating thorough testing.
*
- * @param token The authentication token required for accessing Astra's test environment. Ensure that this
- * token is designated for testing purposes to prevent unintended access to or effects on
- * non-test data and resources.
- * @return A {@link DataAPIClient} instance specifically for use in testing scenarios with Astra, equipped
- * with the necessary authentication token and configured to target the test environment.
+ * @param token The authentication token required for accessing Astra's test environment. It is important
+ * to use a token that is explicitly designated for testing purposes to avoid unintended
+ * access to production or development resources.
+ * @return A {@link DataAPIClient} instance configured for testing with Astra, equipped with the provided
+ * authentication token and targeting the test environment.
*
* Example usage:
*
* {@code
* DataAPIClient testClient = DataAPIClients.astraTest("your_astra_test_token");
- * // Execute test database operations with testClient
+ * testClient.execute(query -> query.cql("SELECT * FROM test_table").execute());
* }
*
*/
- public static DataAPIClient createForAstraTest(String token) {
- return new DataAPIClient(token, DataAPIClientOptions
- .builder()
- .withDestination(DataAPIDestination.ASTRA_TEST)
- .withObserver(new LoggingCommandObserver(DataAPIClient.class))
- .build());
+ public static DataAPIClient astraTest(String token) {
+ return new DataAPIClient(token, new DataAPIClientOptions()
+ .destination(DataAPIDestination.ASTRA_TEST)
+ .logRequests());
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/admin/AdminOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/admin/AdminOptions.java
new file mode 100644
index 00000000..69a50f99
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/admin/AdminOptions.java
@@ -0,0 +1,46 @@
+package com.datastax.astra.client.admin;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+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.DataAPISerializer;
+import com.datastax.astra.internal.serdes.DatabaseSerializer;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+@Setter
+@Accessors(fluent = true, chain = true)
+public class AdminOptions extends BaseOptions {
+
+ /** Serializer for the Collections. */
+ private static final DataAPISerializer DEFAULT_SERIALIZER = new DatabaseSerializer();
+
+ public AdminOptions() {
+ this(null, null);
+ }
+
+ public AdminOptions(String token, DataAPIClientOptions options) {
+ super(token, CommandType.DATABASE_ADMIN, DEFAULT_SERIALIZER, options);
+ }
+
+}
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
index feb9b625..411a0a47 100644
--- 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
@@ -22,6 +22,7 @@
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.databases.DatabaseInfo;
+import com.datastax.astra.client.databases.DatabaseOptions;
import com.datastax.astra.internal.api.AstraApiEndpoint;
import com.datastax.astra.internal.command.LoggingCommandObserver;
import com.datastax.astra.internal.utils.Assert;
@@ -47,6 +48,7 @@
import java.util.UUID;
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.internal.utils.AnsiUtils.green;
import static com.dtsx.astra.sdk.utils.Utils.readEnvVariable;
@@ -66,20 +68,11 @@ public class AstraDBAdmin {
/** Default region. (free-tier) */
public static final String FREE_TIER_CLOUD_REGION = "us-east1";
- /** Header name used to hold the Astra Token. */
- public static final String TOKEN_HEADER_PARAM = "X-Token";
-
- /** Default keyspace (same created by the ui). */
- public static final String DEFAULT_KEYSPACE = "default_keyspace";
-
/** Client for Astra Devops Api. */
final AstraDBOpsClient devopsDbClient;
/** Options to personalized http client other client options. */
- final DataAPIClientOptions dataAPIClientOptions;
-
- /** Astra Token (credentials). */
- final String token;
+ final AdminOptions adminOptions;
/** Side Http Client (use only to resume a db). */
final HttpClient httpClient;
@@ -100,31 +93,30 @@ public class AstraDBAdmin {
/**
* Initialization with an authentication token and target environment, Use this constructor for testing purpose.
- *
- * @param token
- * authentication token
+
* @param options
* options for client
*/
- public AstraDBAdmin(String token, DataAPIClientOptions options) {
- Assert.hasLength(token, "token");
+ public AstraDBAdmin(AdminOptions options) {
Assert.notNull(options, "options");
- this.token = token;
- this.dataAPIClientOptions = options;
- if (options.getObservers() != null) {
+ this.adminOptions = options;
+ DataAPIClientOptions dataAPIClientOptions = options.getDataAPIClientOptions();
+ if (dataAPIClientOptions.getObservers() != null) {
Map devopsObservers = new HashMap<>();
- if (options.getObservers().containsKey(LoggingCommandObserver.class.getSimpleName())) {
+ if (dataAPIClientOptions.getObservers().containsKey(LoggingCommandObserver.class.getSimpleName())) {
devopsObservers.put("logging", new LoggingRequestObserver(AstraDBAdmin.class));
}
- this.devopsDbClient = new AstraDBOpsClient(token, options.getAstraEnvironment(), devopsObservers);
+ this.devopsDbClient = new AstraDBOpsClient(options.getToken(),
+ dataAPIClientOptions.getAstraEnvironment(), devopsObservers);
} else {
- this.devopsDbClient = new AstraDBOpsClient(token, options.getAstraEnvironment());
+ this.devopsDbClient = new AstraDBOpsClient(options.getToken(),
+ dataAPIClientOptions.getAstraEnvironment());
}
// Local Agent for Resume
HttpClient.Builder httpClientBuilder = HttpClient.newBuilder();
- httpClientBuilder.version(options.getHttpClientOptions().getHttpVersion());
- httpClientBuilder.connectTimeout(Duration.ofMillis(options.getTimeoutOptions().connectTimeoutMillis()));
+ httpClientBuilder.version(dataAPIClientOptions.getHttpClientOptions().getHttpVersion());
+ httpClientBuilder.connectTimeout(Duration.ofMillis(dataAPIClientOptions.getTimeoutOptions().getConnectTimeoutMillis()));
this.httpClient = httpClientBuilder.build();
}
@@ -327,25 +319,42 @@ public DatabaseInfo getDatabaseInfo(@NonNull UUID id) {
*
* @param databaseId
* database identifier
- * @param keyspace
+ * @param options
* target keyspace name
* @return
* database client
*/
- public com.datastax.astra.client.databases.Database getDatabase(UUID databaseId, String keyspace) {
+ public com.datastax.astra.client.databases.Database getDatabase(UUID databaseId, DatabaseOptions dbOptions) {
Assert.notNull(databaseId, "databaseId");
- Assert.hasLength(keyspace, "keyspace");
- if (!dataAPIClientOptions.isAstra()) {
- throwErrorRestrictedAstra("getDatabase(id, keyspace)", dataAPIClientOptions.getDestination());
+ if (!adminOptions.getDataAPIClientOptions().isAstra()) {
+ throwErrorRestrictedAstra("getDatabase(id, keyspace)", adminOptions.getDataAPIClientOptions().getDestination());
}
String databaseRegion = devopsDbClient
.findById(databaseId.toString())
.map(db -> db.getInfo().getRegion())
.orElseThrow(() -> new DatabaseNotFoundException(databaseId.toString()));
- return new com.datastax.astra.client.databases.Database(
- new AstraApiEndpoint(databaseId, databaseRegion, dataAPIClientOptions.getAstraEnvironment()).getApiEndPoint(),
- token, keyspace, dataAPIClientOptions) {
- };
+
+ AstraApiEndpoint astraApiEndpoint = new AstraApiEndpoint(databaseId,
+ databaseRegion, adminOptions.getDataAPIClientOptions().getAstraEnvironment());
+
+ return new com.datastax.astra.client.databases.Database(astraApiEndpoint.getApiEndPoint(), dbOptions);
+ }
+
+ /**
+ * Access the database functions.
+ *
+ * @param databaseId
+ * database identifier
+ * @param keyspace
+ * target keyspace name
+ * @return
+ * database client
+ */
+ public com.datastax.astra.client.databases.Database getDatabase(UUID databaseId, String keyspace) {
+ return getDatabase(databaseId, new DatabaseOptions(
+ this.adminOptions.getToken(),
+ this.adminOptions.getDataAPIClientOptions())
+ .keyspace(keyspace));
}
/**
@@ -370,7 +379,9 @@ public com.datastax.astra.client.databases.Database getDatabase(UUID databaseId)
*/
public AstraDBDatabaseAdmin getDatabaseAdmin(UUID databaseId) {
Assert.notNull(databaseId, "databaseId");
- return new AstraDBDatabaseAdmin(token, databaseId, dataAPIClientOptions);
+ return new AstraDBDatabaseAdmin(
+ adminOptions.getToken(), databaseId,
+ adminOptions.getDataAPIClientOptions());
}
/**
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
index c73dc68e..8178db86 100644
--- 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
@@ -21,10 +21,14 @@
*/
import com.datastax.astra.client.DataAPIDestination;
-import com.datastax.astra.client.core.commands.CommandOptions;
+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;
import com.datastax.astra.internal.api.AstraApiEndpoint;
+import com.datastax.astra.internal.command.AbstractCommandRunner;
+import com.datastax.astra.internal.utils.Assert;
import com.dtsx.astra.sdk.db.AstraDBOpsClient;
import com.dtsx.astra.sdk.db.domain.Database;
import com.dtsx.astra.sdk.db.exception.DatabaseNotFoundException;
@@ -34,29 +38,21 @@
import java.util.Set;
import java.util.UUID;
-import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_KEYSPACE;
-
/**
* Implementation of the DatabaseAdmin interface for Astra. To create the namespace the devops APi is leverage. To use this class a higher token permission is required.
*/
@Slf4j
-public class AstraDBDatabaseAdmin implements DatabaseAdmin {
-
- /** Token used for the credentials. */
- final String token;
+public class AstraDBDatabaseAdmin extends AbstractCommandRunner implements DatabaseAdmin {
/** Token used for the credentials. */
final UUID databaseId;
- /** Data Api Options. */
- final DataAPIClientOptions dataAPIClientOptions;
-
/** Client for Astra Devops Api. */
final AstraDBOpsClient devopsDbClient;
/** Database if initialized from the DB. */
- protected com.datastax.astra.client.databases.Database db;
+ final com.datastax.astra.client.databases.Database db;
/**
* Initialize a database admin from token and database id.
@@ -64,12 +60,24 @@ public class AstraDBDatabaseAdmin implements DatabaseAdmin {
* @param db
* target database
*/
- public AstraDBDatabaseAdmin(com.datastax.astra.client.databases.Database db) {
- this.databaseId = UUID.fromString(db.getDbApiEndpoint().substring(8, 44));
- this.dataAPIClientOptions = db.getOptions();
- this.token = db.getToken();
- this.db = db;
- this.devopsDbClient = new AstraDBOpsClient(token, dataAPIClientOptions.getAstraEnvironment());
+ public AstraDBDatabaseAdmin(com.datastax.astra.client.databases.Database db, AdminOptions adminOptions) {
+ Assert.notNull(db, "database");
+ this.db = db;
+ this.databaseId = db.getId(); // UUID.fromString(db.getApiEndpoint().substring(8, 44));
+ this.options = adminOptions;
+ if (adminOptions == null) {
+ this.options = new AdminOptions();
+ }
+ // Using database options if no extra parameters provided
+ if (this.options.getToken() == null) {
+ this.options.token(db.getOptions().getToken());
+ }
+ if (this.options.getDataAPIClientOptions() == null) {
+ this.options.dataAPIClientOptions(db.getOptions().getDataAPIClientOptions());
+ }
+ this.devopsDbClient = new AstraDBOpsClient(
+ options.getToken(),
+ options.getDataAPIClientOptions().getAstraEnvironment());
}
/**
@@ -79,15 +87,16 @@ public AstraDBDatabaseAdmin(com.datastax.astra.client.databases.Database db) {
* token value
* @param databaseId
* database identifier
- * @param options
+ * @param clientOptions
* options used to initialize the http client
*/
- public AstraDBDatabaseAdmin(String token, UUID databaseId, DataAPIClientOptions options) {
- this.token = token;
+ public AstraDBDatabaseAdmin(String token, UUID databaseId, DataAPIClientOptions clientOptions) {
this.databaseId = databaseId;
- this.dataAPIClientOptions = options;
- this.devopsDbClient = new AstraDBOpsClient(token, options.getAstraEnvironment());
- this.db = new com.datastax.astra.client.databases.Database(getApiEndpoint(), token, DEFAULT_KEYSPACE, options);
+ this.options = new AdminOptions(token, clientOptions);
+ this.devopsDbClient = new AstraDBOpsClient(token, options.getDataAPIClientOptions().getAstraEnvironment());
+
+ this.db = new com.datastax.astra.client.databases.Database(getApiEndpoint(),
+ new DatabaseOptions(token, options.getDataAPIClientOptions()));
}
/**
@@ -134,9 +143,9 @@ private static AstraEnvironment getEnvironment(DataAPIDestination destination) {
* @return
* the endpoint as an url.
*/
- private String getApiEndpoint() {
+ public String getApiEndpoint() {
return new AstraApiEndpoint(databaseId,
- getDatabaseInformations().getInfo().getRegion(), dataAPIClientOptions.getAstraEnvironment())
+ getDatabaseInformations().getInfo().getRegion(), options.getDataAPIClientOptions().getAstraEnvironment())
.getApiEndPoint();
}
@@ -162,7 +171,7 @@ public com.datastax.astra.client.databases.Database getDatabase(String keyspace)
* client to interact with database DML.
*/
public com.datastax.astra.client.databases.Database getDatabase(String keyspace, String tokenUser) {
- return new com.datastax.astra.client.databases.Database(getApiEndpoint(), tokenUser, keyspace, db.getOptions());
+ return new com.datastax.astra.client.databases.Database(getApiEndpoint(), db.getOptions());
}
@Override
@@ -177,8 +186,7 @@ public Set listKeyspaceNames() {
@Override
public FindEmbeddingProvidersResult findEmbeddingProviders() {
log.debug("findEmbeddingProviders");
- DataAPIDatabaseAdmin admin =
- new DataAPIDatabaseAdmin(getApiEndpoint() + "/" + db.getOptions().getApiVersion(), token, db.getOptions());
+ DataAPIDatabaseAdmin admin = new DataAPIDatabaseAdmin(db, this.options);
return new FindEmbeddingProvidersResult(admin.findEmbeddingProviders().getEmbeddingProviders());
}
@@ -199,9 +207,9 @@ public void dropKeyspace(String keyspace) {
}
@Override
- public void dropKeyspace(String namespace, CommandOptions options) {
+ public void dropKeyspace(String keyspace, BaseOptions options) {
log.warn("CommandOptions are not supported for dropKeyspace in Astra MODE");
- dropKeyspace(namespace);
+ dropKeyspace(keyspace);
}
/** {@inheritDoc} */
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/admin/DataAPIDatabaseAdmin.java b/astra-db-java/src/main/java/com/datastax/astra/client/admin/DataAPIDatabaseAdmin.java
index 822abbeb..c7b33c60 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/admin/DataAPIDatabaseAdmin.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/admin/DataAPIDatabaseAdmin.java
@@ -20,17 +20,15 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandType;
-import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.client.databases.Database;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.commands.Command;
-import com.datastax.astra.client.core.commands.CommandOptions;
-import com.datastax.astra.client.core.vectorize.EmbeddingProvider;
+import com.datastax.astra.client.core.commands.CommandType;
import com.datastax.astra.client.core.results.FindEmbeddingProvidersResult;
+import com.datastax.astra.client.core.vectorize.EmbeddingProvider;
+import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.keyspaces.KeyspaceOptions;
import com.datastax.astra.internal.api.DataAPIResponse;
import com.datastax.astra.internal.command.AbstractCommandRunner;
-import com.datastax.astra.internal.command.CommandObserver;
import com.datastax.astra.internal.serdes.DataAPISerializer;
import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
import com.datastax.astra.internal.utils.Assert;
@@ -40,7 +38,6 @@
import java.util.Set;
import java.util.stream.Collectors;
-import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_KEYSPACE;
import static com.datastax.astra.internal.utils.AnsiUtils.green;
import static com.datastax.astra.internal.utils.Assert.hasLength;
import static com.datastax.astra.internal.utils.Assert.notNull;
@@ -50,7 +47,7 @@
*/
@Slf4j
@Getter
-public class DataAPIDatabaseAdmin extends AbstractCommandRunner implements DatabaseAdmin {
+public class DataAPIDatabaseAdmin extends AbstractCommandRunner implements DatabaseAdmin {
/** parameters names. */
private static final String ARG_KEYSPACE = "keyspaceName";
@@ -64,28 +61,19 @@ public class DataAPIDatabaseAdmin extends AbstractCommandRunner implements Datab
/**
* Initialize a database admin from token and database id.
*
- * @param token
- * token value
- * @param apiEndpoint
- * api endpoint.
+ * @param db
+ * current database used to initialized the admin
* @param options
* list of options for the admin
*/
- public DataAPIDatabaseAdmin(String apiEndpoint, String token, DataAPIClientOptions options) {
- this(new Database(apiEndpoint, token, DEFAULT_KEYSPACE, options));
- }
-
- /**
- * Initialize a database admin from token and database id.
- *
- * @param db
- * current database instance
- */
- public DataAPIDatabaseAdmin(Database db) {
- this.db = db;
- this.commandOptions = new CommandOptions<>(db.getOptions());
- this.commandOptions.token(db.getToken());
- this.commandOptions.commandType(CommandType.KEYSPACE_ADMIN);
+ public DataAPIDatabaseAdmin(Database db, AdminOptions options) {
+ super(db.getRootEndpoint(), options);
+ this.db = db;
+ this.options.commandType(CommandType.KEYSPACE_ADMIN);
+ String apiVersion = options.getDataAPIClientOptions().getApiVersion();
+ if (!db.getRootEndpoint().endsWith(apiVersion)) {
+ this.apiEndpoint += "/" + apiVersion;
+ }
}
// ------------------------------------------
@@ -125,10 +113,9 @@ public Database getDatabase(String keyspace) {
/** {@inheritDoc} */
@Override
public Database getDatabase(String keyspace, String userToken) {
- Assert.hasLength(keyspace, ARG_KEYSPACE);
- Assert.hasLength(userToken, "userToken");
- db = new Database(db.getDbApiEndpoint(), userToken, keyspace, db.getOptions());
- return db;
+ return new Database(db.getRootEndpoint(), db.getOptions().clone()
+ .token(userToken)
+ .keyspace(keyspace));
}
/** {@inheritDoc} */
@@ -161,7 +148,7 @@ public void createKeyspace(String keyspace, KeyspaceOptions options) {
}
@Override
- public void dropKeyspace(String keyspace, CommandOptions options) {
+ public void dropKeyspace(String keyspace, BaseOptions options) {
hasLength(keyspace, ARG_KEYSPACE);
Command dropNamespace = Command
.create("dropKeyspace")
@@ -170,28 +157,4 @@ public void dropKeyspace(String keyspace, CommandOptions options) {
log.info("Keyspace '" + green("{}") + "' has been deleted", keyspace);
}
- /** {@inheritDoc} */
- @Override
- protected String getApiEndpoint() {
- return db.getDbApiEndpoint() + "/v1";
- }
-
- /** {@inheritDoc} */
- @Override
- protected DataAPISerializer getSerializer() {
- return SERIALIZER;
- }
-
- /**
- * Register a listener to execute commands on the collection. Please now use {@link CommandOptions}.
- *
- * @param logger
- * name for the logger
- * @param commandObserver
- * class for the logger
- */
- public void registerListener(String logger, CommandObserver commandObserver) {
- this.commandOptions.registerObserver(logger, commandObserver);
- }
-
}
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
index 78a358c5..b0affcc7 100644
--- 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
@@ -20,11 +20,12 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.core.commands.CommandRunner;
import com.datastax.astra.client.core.vectorize.EmbeddingProvider;
import com.datastax.astra.client.core.results.FindEmbeddingProvidersResult;
+import com.datastax.astra.internal.utils.Assert;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
@@ -188,10 +189,10 @@ default CompletableFuture> listKeyspacesNamesAsync() {
* // Assume 'client' is an instance of your data API client
* String keyspace = "targetKeyspace";
*
- * // Drop the namespace
+ * // Drop the keyspace
* client.dropKeyspace(keyspace);
*
- * // The namespace 'targetKeyspace' is now deleted, along with all its contained data
+ * // The keyspace 'targetKeyspace' is now deleted, along with all its contained data
* }
*
*
@@ -199,15 +200,16 @@ default CompletableFuture> listKeyspacesNamesAsync() {
* 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 namespace The name of the keyspace to be dropped. This parameter specifies the target keyspace
+ * @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.
*/
- default void dropKeyspace(String namespace) {
- dropKeyspace(namespace, null);
+ default void dropKeyspace(String keyspace) {
+ Assert.hasLength(keyspace, "keyspace");
+ dropKeyspace(keyspace, null);
}
- void dropKeyspace(String namespace, CommandOptions options);
+ void dropKeyspace(String keyspace, BaseOptions options);
/**
* Asynchronously drops (deletes) the specified keyspace from the database. This operation is idempotent, meaning
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/Collection.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/Collection.java
index ea747440..5f4d38d8 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/Collection.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/Collection.java
@@ -43,9 +43,8 @@
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.core.commands.BaseOptions;
import com.datastax.astra.client.core.commands.Command;
-import com.datastax.astra.client.core.commands.CommandOptions;
-import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.core.paging.CollectionCursor;
import com.datastax.astra.client.core.paging.CollectionDistinctIterable;
import com.datastax.astra.client.core.paging.FindIterable;
@@ -62,7 +61,6 @@
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;
import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
import com.datastax.astra.internal.utils.Assert;
@@ -87,7 +85,8 @@
import java.util.concurrent.atomic.AtomicInteger;
import java.util.stream.Collectors;
-import static com.datastax.astra.client.core.commands.CommandType.DATA;
+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;
@@ -130,56 +129,33 @@
* Java bean to unmarshall documents for collection.
*/
@Slf4j
-public class Collection extends AbstractCommandRunner {
+public class Collection extends AbstractCommandRunner {
/** parameters names. */
protected static final String ARG_OPTIONS = "options";
/** parameters names. */
- protected static final String ARG_FILTER = "filter";
- /** parameters names. */
- protected static final String ARG_DATABASE = "database";
- /** parameters names. */
- protected static final String ARG_CLAZZ = "working class 'clazz'";
- /** parameters names. */
- protected static final String ARG_COLLECTION_NAME = "collectionName";
- /** parameters names. */
protected static final String ARG_UPDATE = "update";
/** parameters names. */
protected static final String DOCUMENT = "document";
- // Json Outputs
-
- /** Serializer for the Collections. */
- private static final DocumentSerializer SERIALIZER = new DocumentSerializer();
+ /** Default collection serializer. */
+ public static final DataAPISerializer DEFAULT_COLLECTION_SERIALIZER = new DocumentSerializer();
/** Collection identifier. */
@Getter
private final String collectionName;
- /** Working class representing documents of the collection. The default value is {@link Document}. */
- @Getter
- protected final Class documentClass;
-
/** Parent Database reference. */
@Getter
private final Database database;
- /** Get global Settings for the client. */
@Getter
- private final DataAPIClientOptions dataAPIClientOptions;
-
- /** Api Endpoint for the Database, if using an astra environment it will contain the database id and the database region. */
- private final String apiEndpoint;
+ private final Class documentClass;
/**
* Keep Collection options in -memory to avoid multiple calls to the API.
*/
- private CollectionOptions options;
-
- /**
- * Check if options has been fetched
- */
- private boolean optionChecked = false;
+ private CollectionDefinition collectionDefinition;
/**
* Constructs an instance of a collection within the specified database. This constructor
@@ -194,11 +170,7 @@ public class Collection extends AbstractCommandRunner {
* @param collectionName A {@code String} that uniquely identifies the collection within the
* database. This name is used to route operations to the correct
* collection and should adhere to the database's naming conventions.
- * @param clazz The {@code Class} object that represents the model for documents within
- * this collection. This class is used for serialization and deserialization of
- * documents to and from the database. It ensures type safety and facilitates
- * the mapping of database documents to Java objects.
- * @param commandOptions the options to apply to the command operation. If left blank the default collection
+ * @param collectionOptions the options to apply to the command operation. If left blank the default collection
*
* Example usage:
*
@@ -212,18 +184,15 @@ public class Collection extends AbstractCommandRunner {
* }
*
*/
- public Collection(Database db, String collectionName, CommandOptions commandOptions, Class clazz) {
- notNull(db, ARG_DATABASE);
- notNull(clazz, ARG_CLAZZ);
- hasLength(collectionName, ARG_COLLECTION_NAME);
- this.collectionName = collectionName;
+ public Collection(Database db, String collectionName, CollectionOptions collectionOptions, Class documentClass) {
+ super(db.getApiEndpoint() + "/" + collectionName, collectionOptions);
+ hasLength(collectionName, "collection name");
+ notNull(documentClass, "documentClass");
+ notNull(collectionOptions, "collection options");
this.database = db;
- this.dataAPIClientOptions = db.getOptions();
- this.documentClass = clazz;
- this.commandOptions = commandOptions;
- // Defaulting to data in case of a Collection
- this.commandOptions.commandType(DATA);
- this.apiEndpoint = db.getApiEndpoint() + "/" + collectionName;
+ this.collectionName = collectionName;
+ this.documentClass = documentClass;
+ this.options.serializer(new DocumentSerializer());
}
// ----------------------------
@@ -251,7 +220,7 @@ public Collection(Database db, String collectionName, CommandOptions commandO
*
*/
public String getKeyspaceName() {
- return getDatabase().getKeyspaceName();
+ return getDatabase().getKeyspace();
}
/**
@@ -284,57 +253,16 @@ public String getKeyspaceName() {
* and identity within the database.
*/
public CollectionDefinition getDefinition() {
- return database
- .listCollections()
- .filter(col -> col.getName().equals(collectionName))
- .findFirst()
- .orElseThrow(() -> new DataAPIException("[COLLECTION_NOT_EXIST] - Collection does not exist, " +
- "collection name: '" + collectionName + "'", "COLLECTION_NOT_EXIST", null));
- }
-
- /**
- * Retrieves the configuration options for the collection, including vector and indexing settings.
- * These options specify how the collection should be created and managed, potentially affecting
- * performance, search capabilities, and data organization.
- * Example usage:
- *
- * {@code
- * // Given a collection
- * DataApiCollection collection;
- * // Access its Options
- * CollectionOptions options = collection.getOptions();
- * if (null != c.getVector()) {
- * System.out.println(c.getVector().getDimension());
- * System.out.println(c.getVector().getMetric());
- * }
- * if (null != c.getIndexing()) {
- * System.out.println(c.getIndexing().getAllow());
- * System.out.println(c.getIndexing().getDeny());
- * }
- * }
- *
- *
- * @return An instance of {@link CollectionOptions} containing the collection's configuration settings,
- * such as vector and indexing options. Returns {@code null} if no options are set or applicable.
- */
- public CollectionOptions getOptions() {
- if (!optionChecked) {
- options = Optional.ofNullable(getDefinition().getOptions()).orElse(new CollectionOptions());
- optionChecked = true;
+ if (collectionDefinition == null) {
+ collectionDefinition = database
+ .listCollections().stream()
+ .filter(col -> col.getName().equals(collectionName))
+ .findFirst()
+ .map(CollectionDescriptor::getOptions)
+ .orElseThrow(() -> new DataAPIException("[COLLECTION_NOT_EXIST] - Collection does not exist, " +
+ "collection name: '" + collectionName + "'", "COLLECTION_NOT_EXIST", null));
}
- return options;
- }
-
- /**
- * Retrieves the name of the collection. This name serves as a unique identifier within the database and is
- * used to reference the collection in database operations such as queries, updates, and deletions. The collection
- * name is defined at the time of collection creation and is immutable.
- *
- * @return A {@code String} representing the name of the collection. This is the same name that was specified
- * when the collection was created or initialized.
- */
- public String getName() {
- return collectionName;
+ return collectionDefinition;
}
// --------------------------
@@ -454,7 +382,11 @@ public final CollectionInsertOneResult insertOne(T document) {
*/
public final CollectionInsertOneResult insertOne(T document, CollectionInsertOneOptions collectionInsertOneOptions) {
Assert.notNull(document, DOCUMENT);
- return internalInsertOne(SERIALIZER.convertValue(document, Document.class), collectionInsertOneOptions);
+ DataAPISerializer serializer = getSerializer();
+ if (collectionInsertOneOptions != null && collectionInsertOneOptions.getSerializer() != null) {
+ serializer = collectionInsertOneOptions.getSerializer();
+ }
+ return internalInsertOne(serializer.convertValue(document, Document.class), collectionInsertOneOptions);
}
/**
@@ -545,16 +477,14 @@ private Object unmarshallDocumentId(Object id) {
if (mapId.containsKey(DataAPIKeywords.UUID.getKeyword())) {
// defaultId with UUID
UUID uid = UUID.fromString((String) mapId.get(DataAPIKeywords.UUID.getKeyword()));
- if (getOptions() != null && getOptions().getDefaultId() != null) {
- CollectionIdTypes defaultIdType = CollectionIdTypes.fromValue(getOptions().getDefaultId().getType());
- switch(defaultIdType) {
- case UUIDV6:
- return new UUIDv6(uid);
- case UUIDV7:
- return new UUIDv7(uid);
- default:
- return uid;
- }
+
+ if (getDefinition().getDefaultId() != null) {
+ CollectionDefaultIdTypes defaultIdType = getDefinition().getDefaultId().getType();
+ return switch (defaultIdType) {
+ case UUIDV6 -> new UUIDv6(uid);
+ case UUIDV7 -> new UUIDv7(uid);
+ default -> uid;
+ };
}
throw new IllegalStateException("Returned is is a UUID, but no defaultId is set in the collection definition.");
}
@@ -628,16 +558,16 @@ private Object unmarshallDocumentId(Object id) {
public CollectionInsertManyResult insertMany(List documents, CollectionInsertManyOptions options) {
Assert.isTrue(documents != null && !documents.isEmpty(), "documents list cannot be null or empty");
Assert.notNull(options, "insertMany options cannot be null");
- if (options.concurrency() > 1 && options.ordered()) {
+ if (options.getConcurrency() > 1 && options.isOrdered()) {
throw new IllegalArgumentException("Cannot run ordered insert_many concurrently.");
}
- if (options.chunkSize() > dataAPIClientOptions.getMaxRecordsInInsert()) {
- throw new IllegalArgumentException("Cannot insert more than " + dataAPIClientOptions.getMaxRecordsInInsert() + " at a time.");
+ if (options.getChunkSize() > MAX_CHUNK_SIZE) {
+ throw new IllegalArgumentException("Cannot insert more than " + MAX_CHUNK_SIZE + " at a time.");
}
long start = System.currentTimeMillis();
- ExecutorService executor = Executors.newFixedThreadPool(options.concurrency());
+ ExecutorService executor = Executors.newFixedThreadPool(options.getConcurrency());
List> futures = new ArrayList<>();
- for (int i = 0; i < documents.size(); i += options.chunkSize()) {
+ for (int i = 0; i < documents.size(); i += options.getChunkSize()) {
futures.add(executor.submit(getInsertManyResultCallable(documents, options, i)));
}
executor.shutdown();
@@ -651,11 +581,9 @@ public CollectionInsertManyResult insertMany(List documents, Collec
finalResult.getDocumentResponses().addAll(res.getDocumentResponses());
}
// Set a default timeouts for the overall operation
- long totalTimeout = this.commandOptions
- .getTimeoutOptions()
- .getDataOperationTimeoutMillis();
- if (options.getTimeoutOptions() != null) {
- totalTimeout = options.getTimeoutOptions().dataOperationTimeoutMillis();
+ long totalTimeout = this.options.getTimeout();
+ if (options.getDataAPIClientOptions() != null) {
+ totalTimeout = options.getTimeout();
}
if (executor.awaitTermination(totalTimeout, TimeUnit.MILLISECONDS)) {
log.debug(magenta(".[total insertMany.responseTime]") + "=" + yellow("{}") + " millis.",
@@ -840,15 +768,15 @@ public CompletableFuture insertManyAsync(List getInsertManyResultCallable(List documents, CollectionInsertManyOptions collectionInsertManyOptions, int start) {
- int end = Math.min(start + collectionInsertManyOptions.chunkSize(), documents.size());
+ int end = Math.min(start + collectionInsertManyOptions.getChunkSize(), documents.size());
return () -> {
log.debug("Insert block (" + cyan("size={}") + ") in collection {}", end - start, green(getCollectionName()));
Command insertMany = new Command("insertMany")
.withDocuments(documents.subList(start, end))
.withOptions(new Document()
- .append(INPUT_ORDERED, collectionInsertManyOptions.ordered())
- .append(INPUT_RETURN_DOCUMENT_RESPONSES, collectionInsertManyOptions.returnDocumentResponses()));
+ .append(INPUT_ORDERED, collectionInsertManyOptions.isOrdered())
+ .append(INPUT_RETURN_DOCUMENT_RESPONSES, collectionInsertManyOptions.isReturnDocumentResponses()));
DataAPIStatus status = runCommand(insertMany, collectionInsertManyOptions).getStatus();
CollectionInsertManyResult result = new CollectionInsertManyResult();
@@ -1308,8 +1236,8 @@ public long estimatedDocumentCount(EstimatedCountDocumentsOptions options) {
public int countDocuments(Filter filter, int upperBound, CountDocumentsOptions options)
throws TooManyDocumentsToCountException {
// Argument Validation
- if (upperBound<1 || upperBound> dataAPIClientOptions.getMaxCount()) {
- throw new IllegalArgumentException("UpperBound limit should be in between 1 and " + dataAPIClientOptions.getMaxCount());
+ if (upperBound < 1 || upperBound > MAX_COUNT) {
+ throw new IllegalArgumentException("UpperBound limit should be in between 1 and " + MAX_COUNT);
}
// Build command
Command command = new Command("countDocuments").withFilter(filter);
@@ -1354,7 +1282,6 @@ public int countDocuments(Filter filter, int upperBound)
* the query filter to apply the delete operation
* @return
* the result of the remove one operation
- *
*/
public CollectionDeleteResult deleteOne(Filter filter) {
return deleteOne(filter, new CollectionDeleteOneOptions());
@@ -1446,7 +1373,7 @@ public CollectionDeleteResult deleteAll() {
* @return {@code true} if the collection exists within the namespace, {@code false} otherwise.
*/
public boolean exists() {
- return getDatabase().collectionExists(getName());
+ return getDatabase().collectionExists(getCollectionName());
}
/**
@@ -1558,7 +1485,7 @@ public CollectionUpdateResult replaceOne(Filter filter, T replacement, Collectio
result.setMatchedCount(res.getMatchedCount());
result.setModifiedCount(res.getModifiedCount());
if (res.getDocument() != null) {
- Document doc = SERIALIZER.convertValue(res.getDocument(), Document.class);
+ Document doc = getSerializer().convertValue(res.getDocument(), Document.class);
if (doc.getId(Object.class) != null) {
result.setUpsertedId(doc.getId(Object.class));
}
@@ -1574,7 +1501,7 @@ public CollectionUpdateResult replaceOne(Filter filter, T replacement, Collectio
* @return
* command result
*/
- private FindOneAndReplaceResult executeFindOneAndReplace(Command cmd, CommandOptions options) {
+ private FindOneAndReplaceResult executeFindOneAndReplace(Command cmd, BaseOptions options) {
// Run Command
DataAPIResponse apiResponse = runCommand(cmd, options);
// Parse Command Result
@@ -1831,38 +1758,5 @@ public Optional findOneAndDelete(Filter filter, CollectionFindOneAndDeleteOpt
return Optional.empty();
}
- /**
- * Register a listener to execute commands on the collection. Please now use {@link CommandOptions}.
- *
- * @param logger
- * name for the logger
- * @param commandObserver
- * class for the logger
- */
- public void registerListener(String logger, CommandObserver commandObserver) {
- this.commandOptions.registerObserver(logger, commandObserver);
- }
-
- /**
- * Register a listener to execute commands on the collection. Please now use {@link CommandOptions}.
- *
- * @param name
- * name for the observer
- */
- public void deleteListener(String name) {
- this.commandOptions.unregisterObserver(name);
- }
-
- /** {@inheritDoc} */
- @Override
- protected DataAPISerializer getSerializer() {
- return SERIALIZER;
- }
-
- /** {@inheritDoc} */
- @Override
- protected String getApiEndpoint() {
- return apiEndpoint;
- }
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionIdTypes.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefaultIdTypes.java
similarity index 89%
rename from astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionIdTypes.java
rename to astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefaultIdTypes.java
index f04361a8..d880c074 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionIdTypes.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefaultIdTypes.java
@@ -26,7 +26,7 @@
* List of possible types for the collection 'defaultId'.
*/
@Getter
-public enum CollectionIdTypes {
+public enum CollectionDefaultIdTypes {
/**
* Represent a BSON ObjectId.
@@ -56,7 +56,7 @@ public enum CollectionIdTypes {
* @param value
* value to the types
*/
- CollectionIdTypes(String value) {
+ CollectionDefaultIdTypes(String value) {
this.value = value;
}
@@ -67,8 +67,8 @@ public enum CollectionIdTypes {
* @return The corresponding CollectionIdTypes enum constant.
* @throws IllegalArgumentException if the value does not correspond to any CollectionIdTypes.
*/
- public static CollectionIdTypes fromValue(String value) {
- for (CollectionIdTypes type : values()) {
+ public static CollectionDefaultIdTypes fromValue(String value) {
+ for (CollectionDefaultIdTypes type : values()) {
if (type.getValue().equals(value)) {
return type;
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefinition.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefinition.java
index 8140278c..af425063 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefinition.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDefinition.java
@@ -9,9 +9,9 @@
* Licensed under the Apache License, Version 2.0
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -20,36 +20,271 @@
* #L%
*/
-import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
+import com.datastax.astra.client.core.vector.SimilarityMetric;
+import com.datastax.astra.client.core.vector.VectorOptions;
+import com.datastax.astra.client.core.vectorize.VectorServiceOptions;
+import lombok.Data;
import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.NonNull;
import lombok.Setter;
+import lombok.experimental.Accessors;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
/**
- * Represents the Collection definition with its name and metadata.
+ * Set of options to define and initialize a collection.
*/
-@Getter @Setter
+@Setter
+@NoArgsConstructor
+@Accessors(fluent = true, chain = true)
public class CollectionDefinition {
/**
- * Name of the collection.
+ * The 'defaultId' to allow working with different types of identifiers.
+ */
+ private DefaultIdOptions defaultId;
+
+ /**
+ * Vector options.
+ */
+ private VectorOptions vector;
+
+ /**
+ * Indexing options
+ */
+ private IndexingOptions indexing;
+
+ /**
+ * Subclass representing the indexing options.
+ */
+ @Setter
+ public static class DefaultIdOptions {
+
+ /**
+ * Type for the default id.
+ */
+ private CollectionDefaultIdTypes type;
+
+ /**
+ * Default constructor.
+ */
+ public DefaultIdOptions() {
+ // marshalled by jackson
+ }
+
+ /**
+ * Default constructor.
+ *
+ * @param type type for the default id
+ */
+ public DefaultIdOptions(CollectionDefaultIdTypes type) {
+ this.type = type;
+ }
+
+ /**
+ * Gets type
+ *
+ * @return value of type
+ */
+ public CollectionDefaultIdTypes getType() {
+ return type;
+ }
+ }
+
+ /**
+ * Subclass representing the indexing options.
+ */
+ @Setter
+ @NoArgsConstructor
+ public static class IndexingOptions {
+
+ /**
+ * If not empty will index everything but those properties.
+ */
+ List deny;
+
+ /**
+ * If not empty will index just those properties.
+ */
+ List allow;
+
+ /**
+ * Gets deny
+ *
+ * @return value of deny
+ */
+ public List getDeny() {
+ return deny;
+ }
+
+ /**
+ * Gets allow
+ *
+ * @return value of allow
+ */
+ public List getAllow() {
+ return allow;
+ }
+ }
+
+ /*** Access the vector options.
+ *
+ * @return
+ * vector options
*/
- private String name;
+ public VectorOptions getVector() {
+ return vector;
+ }
/**
- * Options for the collection.
+ * Access the indexing options.
+ *
+ * @return indexing options
*/
- private CollectionOptions options;
+ public IndexingOptions getIndexing() {
+ return indexing;
+ }
/**
- * Default constructor.
+ * Gets defaultId
+ *
+ * @return value of defaultId
*/
- public CollectionDefinition() {
- // left blank, serialization with jackson
+ public DefaultIdOptions getDefaultId() {
+ return defaultId;
}
- /** {@inheritDoc} */
- @Override
- public String toString() {
- return new DocumentSerializer().marshall(this);
+ /**
+ * Builder pattern.
+ *
+ * @param type
+ * default id type
+ * @return self reference
+ */
+ public CollectionDefinition defaultId(CollectionDefaultIdTypes type) {
+ this.defaultId = new DefaultIdOptions(type);
+ return this;
}
+
+ /**
+ * Builder pattern.
+ *
+ * @param size size
+ * @return self reference
+ */
+ public CollectionDefinition vectorDimension(int size) {
+ getVector().dimension(size);
+ return this;
+ }
+
+ /**
+ * Builder pattern.
+ *
+ * @param metric similarity metric
+ * @return self reference
+ */
+ public CollectionDefinition vectorSimilarity(@NonNull SimilarityMetric metric) {
+ getVector().metric(metric.getValue());
+ return this;
+ }
+
+ /**
+ * Builder pattern.
+ *
+ * @param properties size
+ * @return self reference
+ */
+ public CollectionDefinition indexingDeny(@NonNull String... properties) {
+ if (getIndexing() == null) {
+ indexing = new IndexingOptions();
+ }
+ if (getIndexing().getAllow() != null) {
+ throw new IllegalStateException("'indexing.deny' and 'indexing.allow' are mutually exclusive");
+ }
+ getIndexing().deny(Arrays.asList(properties));
+ return this;
+ }
+
+ /**
+ * Builder pattern.
+ *
+ * @param properties size
+ * @return self reference
+ */
+ public CollectionDefinition indexingAllow(String... properties) {
+ if (getIndexing() == null) {
+ indexing = new IndexingOptions();
+ }
+ if (getIndexing().getDeny() != null) {
+ throw new IllegalStateException("'indexing.deny' and 'indexing.allow' are mutually exclusive");
+ }
+ getIndexing().allow(Arrays.asList(properties));
+ return this;
+ }
+
+ /**
+ * Builder pattern.
+ *
+ * @param dimension dimension
+ * @param function function
+ * @return self reference
+ */
+ public CollectionDefinition vector(int dimension, @NonNull SimilarityMetric function) {
+ if (getVector() == null) {
+ vector = new VectorOptions();
+ }
+ return vectorSimilarity(function).vectorDimension(dimension);
+ }
+
+ /**
+ * Enable Vectorization within the collection.
+ *
+ * @param provider provider Name (LLM)
+ * @param modeName mode name
+ * @return self reference
+ */
+ public CollectionDefinition vectorize(String provider, String modeName) {
+ return vectorize(provider, modeName, null);
+ }
+
+ /**
+ * Enable Vectorization within the collection.
+ *
+ * @param provider provider Name (LLM)
+ * @param modeName mode name
+ * @param sharedSecretKey name of the key in the system
+ * @return self reference
+ */
+ public CollectionDefinition vectorize(String provider, String modeName, String sharedSecretKey) {
+ VectorServiceOptions embeddingService = new VectorServiceOptions();
+ embeddingService.provider(provider).modelName(modeName);
+ if (sharedSecretKey != null) {
+ // --> Since 1.3.1 the suffix is not needed anymore
+ //embeddingService.setAuthentication(Map.of("providerKey", keyName + ".providerKey"));
+ embeddingService.authentication(Map.of("providerKey", sharedSecretKey));
+ // <--- Since 1.3.1 the suffix is not needed anymore
+ }
+ getVector().service(embeddingService);
+ return this;
+ }
+
+ /**
+ * Enable Vectorization within the collection.
+ *
+ * @param provider provider Name (LLM)
+ * @param modeName mode name
+ * @param parameters expected parameters for vectorize
+ * @param sharedSecretKey name of the key in the system
+ * @return self reference
+ */
+ public CollectionDefinition vectorize(String provider, String modeName, String sharedSecretKey, Map parameters) {
+ vectorize(provider, modeName, sharedSecretKey);
+ getVector().getService().parameters(parameters);
+ return this;
+ }
+
+
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDescriptor.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDescriptor.java
new file mode 100644
index 00000000..717d109c
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionDescriptor.java
@@ -0,0 +1,55 @@
+package com.datastax.astra.client.collections;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * Represents the Collection definition with its name and metadata.
+ */
+@Getter @Setter
+public class CollectionDescriptor {
+
+ /**
+ * Name of the collection.
+ */
+ private String name;
+
+ /**
+ * Options for the collection.
+ */
+ private CollectionDefinition options;
+
+ /**
+ * Default constructor.
+ */
+ public CollectionDescriptor() {
+ // left blank, serialization with jackson
+ }
+
+ /** {@inheritDoc} */
+ @Override
+ public String toString() {
+ return new DocumentSerializer().marshall(this);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionOptions.java
index bea0c67f..93f7d544 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/CollectionOptions.java
@@ -20,309 +20,44 @@
* #L%
*/
-import com.datastax.astra.client.core.vector.SimilarityMetric;
-import com.datastax.astra.client.core.vector.VectorOptions;
-import com.datastax.astra.client.core.vectorize.VectorServiceOptions;
-import lombok.Getter;
-import lombok.NonNull;
+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;
-import java.util.Arrays;
-import java.util.List;
-import java.util.Map;
+import static com.datastax.astra.client.collections.Collection.DEFAULT_COLLECTION_SERIALIZER;
+import static com.datastax.astra.client.core.commands.CommandType.COLLECTION_ADMIN;
/**
- * Set of options to define and initialize a collection.
+ * The options to use for the data API client.
*/
-@Getter
@Setter
-public class CollectionOptions {
+@Accessors(fluent = true, chain = true)
+public class CollectionOptions extends BaseOptions {
/**
- * The 'defaultId' to allow working with different types of identifiers.
- */
- private DefaultIdOptions defaultId;
-
- /**
- * Vector options.
- */
- private VectorOptions vector;
-
- /**
- * Indexing options
- */
- private IndexingOptions indexing;
-
- /**
- * Default constructor.
+ * Default constructor nor overriding token nor options
+ * but stilling setting the default timeouts and serializer
+ * for collection.
*/
public CollectionOptions() {
- // left blank on purpose, built with builder
- }
-
- /**
- * Subclass representing the indexing options.
- */
- @Getter @Setter
- public static class DefaultIdOptions {
-
- /** Type for the default id. */
- private String type;
-
- /**
- * Default constructor.
- */
- public DefaultIdOptions() {
- // marshalled by jackson
- }
-
- /**
- * Default constructor.
- *
- * @param type
- * type for the default id
- */
- public DefaultIdOptions(String type) {
- this.type = type;
- }
- }
-
- /**
- * Subclass representing the indexing options.
- */
- @Getter @Setter
- public static class IndexingOptions {
-
- /**
- * If not empty will index everything but those properties.
- */
- private List deny;
-
- /**
- * If not empty will index just those properties.
- */
- private List allow;
-
- /**
- * Default constructor.
- */
- public IndexingOptions() {
- // left blank, serialization with jackson
- }
+ this(null, null);
}
-
/**
- * Gets a builder.
+ * Constructor with options and not token override.
*
- * @return a builder
- */
- public static CollectionOptionsBuilder builder() {
- return new CollectionOptionsBuilder();
- }
-
- /**
- * Builder for {@link CollectionDefinition}.
+ * @param token
+ * the token to use for the database
+ * @param options
+ * data API client options
*/
- public static class CollectionOptionsBuilder {
-
- /**
- * Options for Vector
- */
- VectorOptions vector;
-
- /**
- * Options for Indexing
- */
- IndexingOptions indexing;
-
- /**
- * Options for Default Id
- */
- String defaultId;
-
- /**
- * Access the vector options.
- *
- * @return
- * vector options
- */
- private VectorOptions getVector() {
- if (vector == null) {
- vector = new VectorOptions();
- }
- return vector;
- }
-
- /**
- * Access the indexing options.
- *
- * @return
- * indexing options
- */
- private IndexingOptions getIndexing() {
- if (indexing == null) {
- indexing = new IndexingOptions();
- }
- return indexing;
- }
-
- /**
- * Default constructor.
- */
- public CollectionOptionsBuilder() {
- // left blank, builder pattern
- }
-
- /**
- * Builder Pattern with the Identifiers.
- *
- * @param idType
- * type of ids
- * @return
- * self reference
- */
- public CollectionOptionsBuilder defaultIdType(CollectionIdTypes idType) {
- this.defaultId = idType.getValue();
- return this;
- }
-
- /**
- * Builder pattern.
- *
- * @param size size
- * @return self reference
- */
- public CollectionOptionsBuilder vectorDimension(int size) {
- getVector().setDimension(size);
- return this;
- }
-
- /**
- * Builder pattern.
- *
- * @param function function
- * @return self reference
- */
- public CollectionOptionsBuilder vectorSimilarity(@NonNull SimilarityMetric function) {
- getVector().setMetric(function.getValue());
- return this;
- }
-
- /**
- * Builder pattern.
- *
- * @param properties size
- * @return self reference
- */
- public CollectionOptionsBuilder indexingDeny(@NonNull String... properties) {
- if (getIndexing().getAllow() != null) {
- throw new IllegalStateException("'indexing.deny' and 'indexing.allow' are mutually exclusive");
- }
- getIndexing().setDeny(Arrays.asList(properties));
- return this;
- }
-
- /**
- * Builder pattern.
- *
- * @param properties size
- * @return self reference
- */
- public CollectionOptionsBuilder indexingAllow(String... properties) {
- if (getIndexing().getDeny() != null) {
- throw new IllegalStateException("'indexing.deny' and 'indexing.allow' are mutually exclusive");
- }
- getIndexing().setAllow(Arrays.asList(properties));
- return this;
- }
-
- /**
- * Builder pattern.
- *
- * @param dimension dimension
- * @param function function
- * @return self reference
- */
- public CollectionOptionsBuilder vector(int dimension, @NonNull SimilarityMetric function) {
- vectorSimilarity(function);
- vectorDimension(dimension);
- return this;
- }
-
- /**
- * Enable Vectorization within the collection.
- *
- * @param provider
- * provider Name (LLM)
- * @param modeName
- * mode name
- * @return
- * self reference
- */
- public CollectionOptionsBuilder vectorize(String provider, String modeName) {
- return vectorize(provider, modeName, null);
- }
-
- /**
- * Enable Vectorization within the collection.
- *
- * @param provider
- * provider Name (LLM)
- * @param modeName
- * mode name
- * @param sharedSecretKey
- * name of the key in the system
- * @return
- * self reference
- */
- public CollectionOptionsBuilder vectorize(String provider, String modeName, String sharedSecretKey) {
- VectorServiceOptions embeddingService = new VectorServiceOptions();
- embeddingService.provider(provider).modelName(modeName);
- if (sharedSecretKey != null) {
- // --> Since 1.3.1 the suffix is not needed anymore
- //embeddingService.setAuthentication(Map.of("providerKey", keyName + ".providerKey"));
- embeddingService.authentication(Map.of("providerKey", sharedSecretKey));
- // <--- Since 1.3.1 the suffix is not needed anymore
- }
- getVector().setService(embeddingService);
- return this;
- }
-
- /**
- * Enable Vectorization within the collection.
- *
- * @param provider
- * provider Name (LLM)
- * @param modeName
- * mode name
- * @param parameters
- * expected parameters for vectorize
- * @param sharedSecretKey
- * name of the key in the system
- * @return
- * self reference
- */
- public CollectionOptionsBuilder vectorize(String provider, String modeName, String sharedSecretKey, Map parameters) {
- vectorize(provider, modeName, sharedSecretKey);
- getVector().getService().parameters(parameters);
- return this;
- }
-
- /**
- * Build the output.
- *
- * @return collection definition
- */
- public CollectionOptions build() {
- CollectionOptions req = new CollectionOptions();
- req.vector = this.vector;
- req.indexing = this.indexing;
- if (defaultId != null) {
- req.defaultId = new DefaultIdOptions(defaultId);
- }
- return req;
- }
+ public CollectionOptions(String token, DataAPIClientOptions options) {
+ super(token, COLLECTION_ADMIN, DEFAULT_COLLECTION_SERIALIZER, options);
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/exceptions/TooManyDocumentsToCountException.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/exceptions/TooManyDocumentsToCountException.java
index b65a04a8..6e3a3cda 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/exceptions/TooManyDocumentsToCountException.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/exceptions/TooManyDocumentsToCountException.java
@@ -33,7 +33,7 @@ public class TooManyDocumentsToCountException extends DataAPIException {
* Default constructor.
*/
public TooManyDocumentsToCountException() {
- super(ClientErrorCodes.HTTP, "Document count exceeds '" + DataAPIClientOptions.DEFAULT_MAX_COUNT + ", the maximum allowed by the server");
+ super(ClientErrorCodes.HTTP, "Document count exceeds '" + DataAPIClientOptions.MAX_COUNT + ", the maximum allowed by the server");
}
/**
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteManyOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteManyOptions.java
index 24666c2b..fe53d8bf 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteManyOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteManyOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
@@ -32,4 +32,4 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionDeleteManyOptions extends CommandOptions {}
+public class CollectionDeleteManyOptions extends BaseOptions {}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteOneOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteOneOptions.java
index 35aaf745..d687444d 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteOneOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionDeleteOneOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Sort;
import lombok.NoArgsConstructor;
@@ -28,7 +28,7 @@
* Options to delete One document.
*/
@NoArgsConstructor
-public class CollectionDeleteOneOptions extends CommandOptions {
+public class CollectionDeleteOneOptions extends BaseOptions {
/** Sort List. */
Sort[] sort;
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndDeleteOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndDeleteOptions.java
index fd50cd41..46d40b19 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndDeleteOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndDeleteOptions.java
@@ -20,19 +20,16 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.core.query.Sort;
-import lombok.Getter;
import lombok.NoArgsConstructor;
-import lombok.Setter;
-import lombok.experimental.Accessors;
/**
* Options to find one and delete.
*/
@NoArgsConstructor
-public class CollectionFindOneAndDeleteOptions extends CommandOptions {
+public class CollectionFindOneAndDeleteOptions extends BaseOptions {
/** Order by. */
Sort[] sort;
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndReplaceOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndReplaceOptions.java
index 4928b119..2043cf0f 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndReplaceOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndReplaceOptions.java
@@ -21,7 +21,7 @@
*/
import com.datastax.astra.client.collections.documents.ReturnDocument;
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.core.query.Sort;
import lombok.Getter;
@@ -35,7 +35,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionFindOneAndReplaceOptions extends CommandOptions {
+public class CollectionFindOneAndReplaceOptions extends BaseOptions {
/**
* Option to order the result.
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndUpdateOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndUpdateOptions.java
index 4170b25d..7c135bc1 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndUpdateOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneAndUpdateOptions.java
@@ -21,7 +21,7 @@
*/
import com.datastax.astra.client.collections.documents.ReturnDocument;
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.core.query.Sort;
import lombok.Getter;
@@ -36,7 +36,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionFindOneAndUpdateOptions extends CommandOptions {
+public class CollectionFindOneAndUpdateOptions extends BaseOptions {
/**
* Order by.
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneOptions.java
index 74567ca4..b16acc2c 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOneOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.core.query.Sort;
import lombok.Getter;
@@ -34,7 +34,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionFindOneOptions extends CommandOptions {
+public class CollectionFindOneOptions extends BaseOptions {
/**
* Order by.
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOptions.java
index e127f5a4..b0ce7a14 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionFindOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Projection;
import com.datastax.astra.client.core.query.Sort;
import lombok.Getter;
@@ -34,7 +34,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionFindOptions extends CommandOptions {
+public class CollectionFindOptions extends BaseOptions {
/**
* Order by.
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionInsertManyOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionInsertManyOptions.java
index 57e31d94..f7ad0041 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionInsertManyOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionInsertManyOptions.java
@@ -21,8 +21,8 @@
*/
import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.client.core.commands.CommandOptions;
-import lombok.Getter;
+import com.datastax.astra.client.core.commands.BaseOptions;
+import com.datastax.astra.client.core.options.TimeoutOptions;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.experimental.Accessors;
@@ -30,10 +30,10 @@
/**
* Options for InsertMany
*/
-@Getter @Setter
+@Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionInsertManyOptions extends CommandOptions {
+public class CollectionInsertManyOptions extends BaseOptions {
/**
* If the flag is set to true the command is failing on first error
@@ -58,6 +58,61 @@ public class CollectionInsertManyOptions extends CommandOptions {
+public class CollectionInsertOneOptions extends BaseOptions {
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionReplaceOneOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionReplaceOneOptions.java
index ee9a6aa5..6f3da7c8 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionReplaceOneOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionReplaceOneOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
@@ -32,7 +32,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionReplaceOneOptions extends CommandOptions {
+public class CollectionReplaceOneOptions extends BaseOptions {
/** If upsert is selected. */
Boolean upsert;
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionUpdateManyOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionUpdateManyOptions.java
index fc90f1b1..28ce030d 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionUpdateManyOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CollectionUpdateManyOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
@@ -32,7 +32,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CollectionUpdateManyOptions extends CommandOptions {
+public class CollectionUpdateManyOptions extends BaseOptions {
/**
* if upsert is selected
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CountDocumentsOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CountDocumentsOptions.java
index 16eebdfc..5df03e2b 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CountDocumentsOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/CountDocumentsOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
@@ -32,4 +32,4 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class CountDocumentsOptions extends CommandOptions {}
+public class CountDocumentsOptions extends BaseOptions {}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/EstimatedCountDocumentsOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/EstimatedCountDocumentsOptions.java
index 3d001895..a6a3953d 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/EstimatedCountDocumentsOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/EstimatedCountDocumentsOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
@@ -32,4 +32,4 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class EstimatedCountDocumentsOptions extends CommandOptions {}
+public class EstimatedCountDocumentsOptions extends BaseOptions {}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/UpdateOneOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/UpdateOneOptions.java
index 5ee47f48..db8b0718 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/UpdateOneOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/collections/options/UpdateOneOptions.java
@@ -20,7 +20,7 @@
* #L%
*/
-import com.datastax.astra.client.core.commands.CommandOptions;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.query.Sort;
import lombok.Getter;
import lombok.NoArgsConstructor;
@@ -34,7 +34,7 @@
@Getter @Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
-public class UpdateOneOptions extends CommandOptions {
+public class UpdateOneOptions extends BaseOptions {
/**
* if upsert is selected
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/BaseOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/BaseOptions.java
new file mode 100644
index 00000000..4edb9823
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/BaseOptions.java
@@ -0,0 +1,455 @@
+package com.datastax.astra.client.core.commands;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.auth.EmbeddingHeadersProvider;
+import com.datastax.astra.client.core.http.HttpClientOptions;
+import com.datastax.astra.client.core.options.DataAPIClientOptions;
+import com.datastax.astra.client.core.options.TimeoutOptions;
+import com.datastax.astra.internal.command.CommandObserver;
+import com.datastax.astra.internal.serdes.DataAPISerializer;
+import com.datastax.astra.internal.utils.Assert;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import lombok.NoArgsConstructor;
+
+import java.time.Duration;
+import java.util.Map;
+
+/**
+ * Options that will be provided to all commands for this collection.
+ *
+ * @param
+ * the sub-class implementing the command options
+ */
+@NoArgsConstructor
+public class BaseOptions> implements Cloneable {
+
+ /**
+ * Token used
+ */
+ protected DataAPIClientOptions dataAPIClientOptions;
+
+ /**
+ * Serializer for the command.
+ */
+ protected DataAPISerializer serializer;
+
+ /**
+ * Token to use for authentication.
+ */
+ protected String token;
+
+ /**
+ * The command type will drive the timeout in used.
+ */
+ protected CommandType commandType = CommandType.GENERAL_METHOD;
+
+ // --------------------------------------------
+ // ----- Setters (Fluent) -----
+ // --------------------------------------------
+
+ /**
+ * Provide the token.
+ *
+ * @param token
+ * authentication token
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T token(String token) {
+ this.token = token;
+ return (T) this;
+ }
+
+ /**
+ * Provide the token.
+ *
+ * @param serializer
+ * serializer
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T serializer(DataAPISerializer serializer) {
+ this.serializer = serializer;
+ return (T) this;
+ }
+
+ /**
+ * Provide the command type. The nature of the command will determine the timeout.
+ *
+ * @param commandType
+ * command Type
+ * @return
+ * service key
+ */
+ public T commandType(CommandType commandType) {
+ this.commandType = commandType;
+ return (T) this;
+ }
+
+ /**
+ * Provide a fluent setter for the data API Client.
+ *
+ * @param options
+ * command Type
+ * @return
+ * service key
+ */
+ public T dataAPIClientOptions(DataAPIClientOptions options) {
+ this.dataAPIClientOptions = options;
+ return (T) this;
+ }
+
+ /**
+ * Provide the command type. The nature of the command will determine the timeout.
+ *
+ * @param timeoutMillis
+ * timeout for the request
+ * @return
+ * service key
+ */
+ public T timeout(long timeoutMillis) {
+ return timeout(timeoutMillis, getCommandType());
+ }
+
+ /**
+ * Provide the command type. The nature of the command will determine the timeout.
+ *
+ * @param duration
+ * timeout for the request
+ * @return
+ * service key
+ */
+ public T timeout(Duration duration) {
+ Assert.notNull(duration, "duration");
+ return timeout(duration.toMillis(), getCommandType());
+ }
+
+ // --------------------------------------------
+ // ----- Setters -----
+ // --------------------------------------------
+
+ /**
+ * Provide the embedding service API key.
+ *
+ * @param embeddingAuthProvider
+ * authentication provider
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T embeddingAuthProvider(EmbeddingHeadersProvider embeddingAuthProvider) {
+ Assert.notNull(embeddingAuthProvider, "embeddingAuthProvider");
+ getDataAPIClientOptions().embeddingAuthProvider(embeddingAuthProvider);
+ return (T) this;
+ }
+
+ /**
+ * Provide the token.
+ *
+ * @param params
+ * additional headers
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T databaseAdditionalHeaders(Map params) {
+ if (params!=null && !params.isEmpty()) {
+ getDataAPIClientOptions().databaseAdditionalHeaders(params);
+ }
+ return (T) this;
+ }
+
+ /**
+ * Provide the token.
+ *
+ * @param params
+ * additional headers
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T adminAdditionalHeaders(Map params) {
+ if (params!=null && !params.isEmpty()) {
+ getDataAPIClientOptions().adminAdditionalHeaders(params);
+ }
+ return (T) this;
+ }
+
+ /**
+ * Provide the token.
+ *
+ * @param options
+ * options to initialize the http client
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T httpClientOptions(HttpClientOptions options) {
+ getDataAPIClientOptions().httpClientOptions(options);
+ return (T) this;
+ }
+
+ /**
+ * Provide the embedding service API key.
+ *
+ * @param timeoutOptions
+ * options of timeouts
+ * @return
+ * service key
+ */
+ @SuppressWarnings("unchecked")
+ public T timeoutOptions(TimeoutOptions timeoutOptions) {
+ Assert.notNull(timeoutOptions, "timeoutOptions");
+ getDataAPIClientOptions().timeoutOptions(timeoutOptions);
+ return (T) this;
+ }
+
+ /**
+ * Allow to register a listener for the command.
+ * @param name
+ * name of the observer
+ * @param observer
+ * observer to register
+ * @return
+ * instance of the command options
+ */
+ @SuppressWarnings("unchecked")
+ public T registerObserver(String name, CommandObserver observer) {
+ Assert.hasLength(name, "name");
+ Assert.notNull(observer, "observer");
+ getDataAPIClientOptions().addObserver(name, observer);
+ return (T) this;
+ }
+
+ /**
+ * Remove a listener from the command.
+ *
+ * @param name
+ * name of the observer
+ * @return
+ * instance of the command options
+ */
+ @SuppressWarnings("unchecked")
+ public T unregisterObserver(String name) {
+ getDataAPIClientOptions().getObservers().remove(name);
+ return (T) this;
+ }
+
+ /**
+ * Request timeout based on the command type.
+ *
+ * @param timeoutOptions
+ * options of timeouts
+ * @param type
+ * command type
+ * @return
+ * timeout
+ */
+ public long getTimeout(TimeoutOptions timeoutOptions, CommandType type) {
+ return switch (type) {
+ case DATABASE_ADMIN -> timeoutOptions.getDatabaseAdminTimeoutMillis();
+ case KEYSPACE_ADMIN -> timeoutOptions.getKeyspaceAdminTimeoutMillis();
+ case TABLE_ADMIN -> timeoutOptions.getTableAdminTimeoutMillis();
+ case COLLECTION_ADMIN -> timeoutOptions.getCollectionAdminTimeoutMillis();
+ default -> timeoutOptions.getGeneralMethodTimeoutMillis();
+ };
+ }
+
+ /**
+ * Request timeout based on the command type.
+ *
+ * @param timeoutOptions
+ * options of timeouts
+ * @param type
+ * command type
+ * @return
+ * timeout
+ */
+ public long getRequestTimeout(TimeoutOptions timeoutOptions, CommandType type) {
+ return switch (type) {
+ case DATABASE_ADMIN -> timeoutOptions.getDatabaseAdminTimeoutMillis();
+ case KEYSPACE_ADMIN -> timeoutOptions.getKeyspaceAdminTimeoutMillis();
+ case TABLE_ADMIN -> timeoutOptions.getTableAdminTimeoutMillis();
+ case COLLECTION_ADMIN -> timeoutOptions.getCollectionAdminTimeoutMillis();
+ default -> timeoutOptions.getRequestTimeoutMillis();
+ };
+ }
+
+ /**
+ * Provide the command type. The nature of the command will determine the timeout.
+ *
+ * @param timeoutMillis
+ * timeout for the request
+ * @return
+ * service key
+ */
+ public T timeout(long timeoutMillis, CommandType commandType) {
+ if (getDataAPIClientOptions().getTimeoutOptions() == null) {
+ getDataAPIClientOptions().timeoutOptions(new TimeoutOptions());
+ }
+ TimeoutOptions timeoutOptions = getDataAPIClientOptions().getTimeoutOptions();
+ switch (commandType) {
+ case DATABASE_ADMIN -> timeoutOptions.databaseAdminTimeoutMillis(timeoutMillis);
+ case KEYSPACE_ADMIN -> timeoutOptions.keyspaceAdminTimeoutMillis(timeoutMillis);
+ case TABLE_ADMIN -> timeoutOptions.tableAdminTimeoutMillis(timeoutMillis);
+ case COLLECTION_ADMIN -> timeoutOptions.collectionAdminTimeoutMillis(timeoutMillis);
+ default -> timeoutOptions.generalMethodTimeoutMillis(timeoutMillis);
+ };
+ return (T) this;
+ }
+
+ // --------------------------------------------
+ // ----- Getters -----
+ // --------------------------------------------
+
+ /**
+ * Gets dataAPIClientOptions
+ *
+ * @return value of dataAPIClientOptions
+ */
+ @JsonIgnore
+ public DataAPIClientOptions getDataAPIClientOptions() {
+ if (this.dataAPIClientOptions == null) {
+ this.dataAPIClientOptions = new DataAPIClientOptions();
+ }
+ return dataAPIClientOptions;
+ }
+
+ /**
+ * Return the HTTP Request Timeout based on the command type
+ *
+ * @return value of token
+ */
+ @JsonIgnore
+ public long getTimeout() {
+ if (getDataAPIClientOptions() != null && getDataAPIClientOptions().getTimeoutOptions() != null) {
+ return getTimeout(getDataAPIClientOptions().getTimeoutOptions(), getCommandType());
+ }
+ return -1;
+ }
+
+ /**
+ * Return the HTTP Request Timeout based on the command type
+ *
+ * @return value of token
+ */
+ @JsonIgnore
+ public long getRequestTimeout() {
+ if (getDataAPIClientOptions() != null && getDataAPIClientOptions().getTimeoutOptions() != null) {
+ return getRequestTimeout(getDataAPIClientOptions().getTimeoutOptions(), getCommandType());
+ }
+ return -1;
+ }
+
+ /**
+ * Gets token
+ *
+ * @return value of token
+ */
+ @JsonIgnore
+ public String getToken() {
+ return token;
+ }
+
+ /**
+ * Gets commandType
+ *
+ * @return value of commandType
+ */
+ @JsonIgnore
+ public CommandType getCommandType() {
+ return commandType;
+ }
+
+ /**
+ * Gets serializer
+ *
+ * @return value of serializer
+ */
+ @JsonIgnore
+ public DataAPISerializer getSerializer() {
+ return serializer;
+ }
+
+ // --------------------------------------------
+ // ----- Java Core -----
+ // --------------------------------------------
+
+ /**
+ * Return the HTTP Request Timeout based on the command type.
+ *
+ * @param token
+ * authentication token
+ * @param type
+ * command type
+ * @param options
+ * data api options
+ */
+ public BaseOptions(String token, CommandType type, DataAPIClientOptions options) {
+ this.token = token;
+ this.commandType = type;
+ if (options != null) {
+ this.dataAPIClientOptions = options.clone();
+ }
+ }
+
+ /**
+ * Return the HTTP Request Timeout based on the command type.
+ *
+ * @param token
+ * authentication token
+ * @param type
+ * command type
+ * @param options
+ * data api options
+ */
+ public BaseOptions(String token, CommandType type, DataAPISerializer serializer, DataAPIClientOptions options) {
+ this.token = token;
+ this.commandType = type;
+ this.serializer = serializer;
+ if (options != null) {
+ this.dataAPIClientOptions = options.clone();
+ }
+ }
+
+ @Override
+ public String toString() {
+ return getSerializer().marshall(this);
+ }
+
+ @Override
+ @SuppressWarnings("unchecked")
+ public T clone() {
+ try {
+ BaseOptions cloned = (BaseOptions) super.clone();
+ cloned.token = token;
+ cloned.commandType = commandType;
+ cloned.dataAPIClientOptions = dataAPIClientOptions.clone();
+ return (T) cloned;
+ } catch (CloneNotSupportedException e) {
+ throw new AssertionError("Cloning not supported", e);
+ }
+ }
+
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandOptions.java
deleted file mode 100644
index fae268d2..00000000
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandOptions.java
+++ /dev/null
@@ -1,343 +0,0 @@
-package com.datastax.astra.client.core.commands;
-
-/*-
- * #%L
- * Data API Java Client
- * --
- * Copyright (C) 2024 DataStax
- * --
- * Licensed under the Apache License, Version 2.0
- * You may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- * #L%
- */
-
-import com.datastax.astra.client.core.auth.EmbeddingHeadersProvider;
-import com.datastax.astra.client.core.http.HttpClientOptions;
-import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.client.core.options.TimeoutOptions;
-import com.datastax.astra.internal.command.CommandObserver;
-import lombok.Getter;
-
-import java.util.HashMap;
-import java.util.LinkedHashMap;
-import java.util.Map;
-
-import static com.datastax.astra.client.core.options.DataAPIClientOptions.HEADER_FEATURE_FLAG_TABLES;
-
-/**
- * Options that will be provided to all commands for this collection.
- *
- * @param
- * the sub-class implementing the command options
- */
-@Getter
-public class CommandOptions> implements Cloneable {
-
- /**
- * Default command type is DATA
- */
- protected CommandType commandType = CommandType.DATA;
-
- /**
- * List of observers to notify.
- */
- protected Map observers = new LinkedHashMap<>();
-
- /**
- * Token to use for authentication.
- */
- protected String token;
-
- /**
- * Will be used to create a client
- */
- protected HttpClientOptions httpClientOptions;
-
- /**
- * Will be used to create a client
- */
- protected TimeoutOptions timeoutOptions;
-
- /**
- * Embedding auth provider
- */
- protected EmbeddingHeadersProvider embeddingAuthProvider;
-
- /** Add headers to db calls. */
- protected Map databaseAdditionalHeaders = new HashMap<>();
-
- /** Add headers to admin calls. */
- protected Map adminAdditionalHeaders = new HashMap<>();
-
- /**
- * Provide the token.
- *
- * @param token
- * authentication token
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T token(String token) {
- this.token = token;
- return (T) this;
- }
-
- /**
- * Provide the token.
- *
- * @param params
- * additional headers
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T databaseAdditionalHeaders(Map params) {
- this.adminAdditionalHeaders = params;
- return (T) this;
- }
-
- /**
- * Provide the token.
- *
- * @param params
- * additional headers
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T adminAdditionalHeaders(Map params) {
- this.adminAdditionalHeaders = params;
- return (T) this;
- }
-
- /**
- * Provide the token.
- *
- * @param options
- * options to initialize the http client
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T httpClientOptions(HttpClientOptions options) {
- this.httpClientOptions = options;
- return (T) this;
- }
-
- /**
- * Provide the embedding service API key.
- *
- * @param embeddingAuthProvider
- * authentication provider
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T embeddingAuthProvider(EmbeddingHeadersProvider embeddingAuthProvider) {
- this.embeddingAuthProvider = embeddingAuthProvider;
- return (T) this;
- }
-
- /**
- * Provide the command type if default is not DATA.
- *
- * @param commandType
- * command Type
- * @return
- * service key
- */
- public T commandType(CommandType commandType) {
- this.commandType = commandType;
- return (T) this;
- }
-
- /**
- * Provide the embedding service API key.
- *
- * @param timeoutOptions
- * options of timeouts
- * @return
- * service key
- */
- @SuppressWarnings("unchecked")
- public T timeoutOptions(TimeoutOptions timeoutOptions) {
- this.timeoutOptions = timeoutOptions;
- return (T) this;
- }
-
- /**
- * Allow to register a listener for the command.
- * @param name
- * name of the observer
- * @param observer
- * observer to register
- * @return
- * instance of the command options
- */
- @SuppressWarnings("unchecked")
- public T registerObserver(String name, CommandObserver observer) {
- if (observer != null) {
- observers.put(name, observer);
- }
- return (T) this;
- }
-
- /**
- * Register an observer with its className.
- *
- * @param observer
- * command observer
- * @return
- * instance of the command options
- */
- public T registerObserver(CommandObserver observer) {
- return registerObserver(observer.getClass().getSimpleName(), observer);
- }
-
- /**
- * Remove a listener from the command.
- *
- * @param name
- * name of the observer
- * @return
- * instance of the command options
- */
- @SuppressWarnings("unchecked")
- public T unregisterObserver(String name) {
- observers.remove(name);
- return (T) this;
- }
-
- /**
- * Remove an observer by its class.
- *
- * @param observer
- * observer to remove
- * @return
- * instance of the command options
- */
- public T unregisterObserver(Class observer) {
- return unregisterObserver(observer.getSimpleName());
- }
-
- /**
- * Return the HTTP Request Timeout based on the command type
- *
- * @return value of token
- */
- public long selectRequestTimeout() {
- return selectRequestTimeout(commandType, timeoutOptions);
- }
-
- /**
- * Return the HTTP Request Timeout based on the command type
- *
- * @return value of token
- */
- public static long selectRequestTimeout(CommandType type, TimeoutOptions timeoutOptions) {
- return switch (type) {
- case DATABASE_ADMIN -> timeoutOptions.databaseAdminTimeoutMillis();
- case KEYSPACE_ADMIN -> timeoutOptions.keyspaceAdminTimeoutMillis();
- case SCHEMA -> timeoutOptions.schemaOperationTimeoutMillis();
- default -> timeoutOptions.requestTimeoutMillis();
- };
- }
-
- /**
- * Add a header to the db calls.
- *
- * @param key
- * key
- * @param value
- * value
- * @return
- * self reference
- */
- @SuppressWarnings("unchecked")
- public T addDatabaseAdditionalHeader(String key, String value) {
- databaseAdditionalHeaders.put(key, value);
- return (T) this;
- }
-
- public T enableFeatureFlagTables() {
- return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true");
- }
-
- public T disableFeatureFlagTables() {
- return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, null);
- }
-
- /**
- * Add a header to the admin calls.
- *
- * @param key
- * key
- * @param value
- * value
- * @return
- * self reference
- */
- @SuppressWarnings("unchecked")
- public T addAdminAdditionalHeader(String key, String value) {
- adminAdditionalHeaders.put(key, value);
- return (T) this;
- }
-
- /**
- * Default Constructor.
- */
- public CommandOptions() {
- // left blank, jackson serialization
- }
-
- /**
- * Default Constructor.
- */
- public CommandOptions(DataAPIClientOptions options) {
- if (options != null) {
- this.embeddingAuthProvider = options.getEmbeddingAuthProvider();
- this.adminAdditionalHeaders = options.getAdminAdditionalHeaders();
- this.databaseAdditionalHeaders = options.getDatabaseAdditionalHeaders();
- this.httpClientOptions = options.getHttpClientOptions();
- this.timeoutOptions = options.getTimeoutOptions();
- for(Map.Entry entry : options.getObservers().entrySet()) {
- // Avoid observers Duplication
- if (!getObservers().containsKey(entry.getKey())) {
- registerObserver(entry.getKey(), entry.getValue());
- }
- }
- }
- }
-
- @SuppressWarnings("unchecked")
- public T clone() {
- try {
- CommandOptions cloned = (CommandOptions) super.clone();
-
- // Deep copy of mutable fields
- cloned.observers = new LinkedHashMap<>(this.observers);
- cloned.databaseAdditionalHeaders = new HashMap<>(this.databaseAdditionalHeaders);
- cloned.adminAdditionalHeaders = new HashMap<>(this.adminAdditionalHeaders);
-
- // Copying other objects (assuming they have proper copy constructors or are immutable)
- cloned.httpClientOptions = this.httpClientOptions != null ? this.httpClientOptions.clone() : null;
- cloned.timeoutOptions = this.timeoutOptions != null ? this.timeoutOptions.clone() : null;
- cloned.embeddingAuthProvider = this.embeddingAuthProvider != null ? this.embeddingAuthProvider.copy() : null;
-
- return (T) cloned;
- } catch (CloneNotSupportedException e) {
- throw new AssertionError("Cloning not supported", e);
- }
- }
-
-}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandRunner.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandRunner.java
index f94bb816..b421c417 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandRunner.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandRunner.java
@@ -43,7 +43,7 @@ public interface CommandRunner {
* result as a document map
*/
default DataAPIResponse runCommand(Command command) {
- return runCommand(command, (CommandOptions) null);
+ return runCommand(command, (BaseOptions) null);
}
/**
@@ -58,7 +58,7 @@ default DataAPIResponse runCommand(Command command) {
* @return
* result as a document map
*/
- DataAPIResponse runCommand(Command command, CommandOptions options)
+ DataAPIResponse runCommand(Command command, BaseOptions options)
throws DataAPIResponseException;
/**
@@ -93,6 +93,6 @@ default T runCommand(Command command, Class documentClass) {
* @param
* document type to use
*/
- T runCommand(Command command, CommandOptions options, Class documentClass)
+ T runCommand(Command command, BaseOptions options, Class documentClass)
throws DataAPIResponseException;
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandType.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandType.java
index cdf46212..cfbc8854 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandType.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/commands/CommandType.java
@@ -29,12 +29,17 @@ public enum CommandType {
/**
* Data operation (find*, insert*, update*, delete*)
*/
- DATA,
+ GENERAL_METHOD,
/**
- * Schema operation (create*, drop*)
+ * Table schema operation (create*, drop*)
*/
- SCHEMA,
+ TABLE_ADMIN,
+
+ /**
+ * Collection Schema operation (create*, drop*)
+ */
+ COLLECTION_ADMIN,
/**
* Database admin operation (create, delete, list)
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
index dc064f97..0969f241 100644
--- 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
@@ -23,11 +23,16 @@
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
/**
* Caller information.
*/
-@Data @NoArgsConstructor @AllArgsConstructor
+@Setter
+@Accessors(fluent = true, chain = true)
+@NoArgsConstructor
+@AllArgsConstructor
public class Caller {
/** caller name. */
@@ -35,4 +40,22 @@ public class Caller {
/** caller version. */
String version;
+
+ /**
+ * Gets name
+ *
+ * @return value of name
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Gets version
+ *
+ * @return value of version
+ */
+ public String getVersion() {
+ return version;
+ }
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpClientOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpClientOptions.java
index 139afa63..38a5dcde 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpClientOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpClientOptions.java
@@ -22,7 +22,8 @@
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.internal.utils.Assert;
-import lombok.Getter;
+import lombok.Setter;
+import lombok.experimental.Accessors;
import java.net.http.HttpClient;
import java.time.Duration;
@@ -32,7 +33,8 @@
/**
* Options to set up http Client.
*/
-@Getter
+@Setter
+@Accessors(fluent = true, chain = true)
public class HttpClientOptions implements Cloneable {
// --------------------------------------------
@@ -59,6 +61,15 @@ public void addCaller(Caller caller) {
callers.add(caller);
}
+ /**
+ * Gets callers
+ *
+ * @return value of callers
+ */
+ public List getCallers() {
+ return callers;
+ }
+
// --------------------------------------------
// ----------------- RETRIES -----------------
// --------------------------------------------
@@ -79,18 +90,28 @@ public void addCaller(Caller caller) {
*/
Duration retryDelay = Duration.ofMillis(DEFAULT_RETRY_DELAY_MILLIS);
+ public HttpClientOptions httpRetries(int i, Duration duration) {
+ this.retryCount = i;
+ this.retryDelay = duration;
+ return this;
+ }
+
/**
- * Add a caller.
+ * Gets retryCount
*
- * @param count
- * retry count
- * @param delay
- * retry delay
+ * @return value of retryCount
*/
- public HttpClientOptions withRetries(int count, Duration delay) {
- this.retryCount = count;
- this.retryDelay = delay;
- return this;
+ public int getRetryCount() {
+ return retryCount;
+ }
+
+ /**
+ * Gets retryDelay
+ *
+ * @return value of retryDelay
+ */
+ public Duration getRetryDelay() {
+ return retryDelay;
}
// --------------------------------------------
@@ -110,48 +131,33 @@ public HttpClientOptions withRetries(int count, Duration delay) {
/**
* The http client could work through a proxy.
*/
- HttpProxy proxy;
-
+ HttpProxy httpProxy;
/**
- * Provide a custom redirect policy.
+ * Gets httpVersion
*
- * @param redirect
- * redirect policy
- * @return
- * self reference
+ * @return value of httpVersion
*/
- public HttpClientOptions withHttpRedirect(HttpClient.Redirect redirect) {
- Assert.notNull(redirect, "redirect");
- this.httpRedirect = redirect;
- return this;
+ public HttpClient.Version getHttpVersion() {
+ return httpVersion;
}
/**
- * Provide a custom http version.
+ * Gets httpRedirect
*
- * @param version
- * http version
- * @return
- * self reference
+ * @return value of httpRedirect
*/
- public HttpClientOptions withHttpVersion(HttpClient.Version version) {
- Assert.notNull(version, "version");
- this.httpVersion = version;
- return this;
+ public HttpClient.Redirect getHttpRedirect() {
+ return httpRedirect;
}
/**
- * Provide a proxy for HTTP connection.
+ * Gets proxy
*
- * @param proxy
- * http proxy
- * @return
- * self reference
+ * @return value of proxy
*/
- public HttpClientOptions withHttpProxy(HttpProxy proxy) {
- this.proxy = proxy;
- return this;
+ public HttpProxy getHttpProxy() {
+ return httpProxy;
}
// --------------------------------------------
@@ -172,7 +178,7 @@ public HttpClientOptions clone() {
// Deep copy of mutable fields
cloned.callers = new ArrayList<>(this.callers);
cloned.retryDelay = this.retryDelay != null ? Duration.ofMillis(this.retryDelay.toMillis()) : null;
- cloned.proxy = this.proxy != null ? this.proxy.clone() : null;
+ cloned.httpProxy = this.httpProxy != null ? this.httpProxy.clone() : null;
return cloned;
} catch (CloneNotSupportedException e) {
@@ -180,4 +186,5 @@ public HttpClientOptions clone() {
}
}
+
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpProxy.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpProxy.java
index e3f95962..de22c434 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpProxy.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/http/HttpProxy.java
@@ -20,14 +20,19 @@
* #L%
*/
+import lombok.AllArgsConstructor;
import lombok.Getter;
+import lombok.NoArgsConstructor;
import lombok.Setter;
+import lombok.experimental.Accessors;
/**
* Subclass to represent an http proxy.
*/
-@Getter
@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Accessors(fluent = true, chain = true)
public class HttpProxy implements Cloneable {
/** hostname of the proxy. */
@@ -36,21 +41,26 @@ public class HttpProxy implements Cloneable {
/** port of the proxy. */
int port;
+ @Override
+ public HttpProxy clone() {
+ return new HttpProxy(this.hostname, this.port);
+ }
+
/**
- * Default constructor.
+ * Gets hostname
*
- * @param hostname
- * host name
- * @param port
- * roxy port
+ * @return value of hostname
*/
- public HttpProxy(String hostname, int port) {
- this.hostname = hostname;
- this.port = port;
+ public String getHostname() {
+ return hostname;
}
- @Override
- public HttpProxy clone() {
- return new HttpProxy(this.hostname, this.port);
+ /**
+ * Gets port
+ *
+ * @return value of port
+ */
+ public int getPort() {
+ return port;
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/options/DataAPIClientOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/DataAPIClientOptions.java
index 1a606843..56461e2a 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/options/DataAPIClientOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/DataAPIClientOptions.java
@@ -9,9 +9,9 @@
* Licensed under the Apache License, Version 2.0
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -26,16 +26,16 @@
import com.datastax.astra.client.core.auth.EmbeddingHeadersProvider;
import com.datastax.astra.client.core.http.Caller;
import com.datastax.astra.client.core.http.HttpClientOptions;
-import com.datastax.astra.client.core.http.HttpProxy;
import com.datastax.astra.internal.command.CommandObserver;
import com.datastax.astra.internal.command.LoggingCommandObserver;
import com.datastax.astra.internal.serdes.DatabaseSerializer;
+import com.dtsx.astra.sdk.utils.Assert;
import com.dtsx.astra.sdk.utils.AstraEnvironment;
-import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
import lombok.extern.slf4j.Slf4j;
-import java.net.http.HttpClient;
-import java.time.Duration;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;
@@ -47,112 +47,138 @@
/**
* Options to set up the client for DataApiClient.
*/
-@Getter
@Slf4j
-public class DataAPIClientOptions {
+@Setter
+@Accessors(fluent = true, chain = true)
+public class DataAPIClientOptions implements Cloneable {
- /** Feature Flag Tables. */
- public static final String HEADER_FEATURE_FLAG_TABLES = "Feature-Flag-tables";
-
- /** path for json api. */
- public static final String DEFAULT_VERSION = "v1";
-
- /** Number of documents for a count. */
- public static final int DEFAULT_MAX_COUNT = 1000;
-
- /** Maximum number of documents in a page. */
- public static final int DEFAULT_MAX_PAGE_SIZE = 20;
+ // --------------------------------------------------
+ // --- Defaults ---
+ // --------------------------------------------------
- /** Maximum number of documents when you insert. */
- public static final int DEFAULT_MAX_CHUNK_SIZE = 100;
+ /**
+ * The default keyspace to use for working with your databases.
+ *
+ * This value is the default in Astra but you can create your own keyspaces in your database.
+ * Ensure the keyspace matches your database configuration to avoid runtime issues.
+ *
+ */
+ public static final String DEFAULT_KEYSPACE = "default_keyspace";
- /** Encode the vector as binary. */
- public static boolean encodeDurationAsISO8601 = true;
+ /**
+ * API version and path in the URL in the format '/api/${version}'.
+ *
+ * This constant can be used to construct endpoint URLs for making API calls.
+ * Modify this value if the backend version changes.
+ *
+ */
+ public static final String DEFAULT_VERSION = "v1";
- /** Encode the vector as binary. */
- public static boolean encodeDataApiVectorsAsBase64 = true;
+ /**
+ * The maximum number of documents allowed for processing before throwing an exception.
+ *
+ * This is a safeguard to prevent excessive memory or computational load when processing
+ * large batches of data. Applications should adhere to this limit for better stability.
+ *
+ */
+ public static final int MAX_COUNT = 1000;
- /** When operating a count operation, the maximum number of documents that can be returned. */
- final int maxCount;
+ /**
+ * The maximum number of documents to insert in a single batch operation.
+ *
+ * This is used to optimize bulk insertion performance while ensuring the operation
+ * doesn't exceed database constraints or memory limits.
+ *
+ */
+ public static final int MAX_CHUNK_SIZE = 50;
- /** The maximum number of documents that can be returned in a single page. */
- final int maxPageSize;
+ // --------------------------------------------------
+ // --- More Global Constants ---
+ // --------------------------------------------------
- /** The maximum number of documents that can be inserted in a single operation. */
- final int maxRecordsInInsert;
+ /**
+ * Feature Flag Tables.
+ */
+ public static final String HEADER_FEATURE_FLAG_TABLES = "Feature-Flag-tables";
- /** Set the API version like 'v1' */
- final String apiVersion;
+ // --------------------------------------------------
+ // --- Fields ---
+ // --------------------------------------------------
- /** Set Timeouts for the different operations */
- final TimeoutOptions timeoutOptions;
+ /**
+ * Set the API version like 'v1'
+ */
+ private String apiVersion = DEFAULT_VERSION;
- /** Group options and parameters for http client. */
- final HttpClientOptions httpClientOptions;
+ /**
+ * Encode the destination like Astra or local installation.
+ */
+ private DataAPIDestination destination = DataAPIDestination.ASTRA;
- /** Encode the destination like Astra or local installation. */
- final DataAPIDestination destination;
+ /**
+ * Http Client Options
+ */
+ private HttpClientOptions httpClientOptions = new HttpClientOptions();
- /** Embedding auth provider. */
- final EmbeddingHeadersProvider embeddingAuthProvider;
+ /**
+ * Timeout options.
+ */
+ private TimeoutOptions timeoutOptions = new TimeoutOptions();
- /** Add headers to db calls. */
- final Map databaseAdditionalHeaders;
+ /**
+ * Options for serialization and deserialization.
+ *
+ * This static field is shared across the application to ensure consistency in
+ * how objects are serialized and deserialized. The Jackson serializer, or any
+ * similar serialization framework, will leverage the options defined in this instance.
+ *
+ *
+ * Use this field to configure global serialization/deserialization behavior, such as
+ * custom serializers, choose vector and durations encodings.
+ *
+ */
+ private static SerdesOptions serdesOptions = new SerdesOptions();
- /** Add headers to admin calls. */
- final Map adminAdditionalHeaders;
+ /**
+ * The embedding service API key can be provided at top level.
+ */
+ private EmbeddingHeadersProvider embeddingAuthProvider;
- /** Observers for the commands. */
- final Map observers;
+ /**
+ * Add headers to admin calls.
+ */
+ private Map databaseAdditionalHeaders = new HashMap<>();
/**
- * Initializer for the builder.
- *
- * @return
- * a new instance of builder
+ * Add headers to admin calls.
*/
- public static DataAPIClientOptionsBuilder builder() {
- return new DataAPIClientOptionsBuilder();
- }
+ private Map adminAdditionalHeaders = new HashMap<>();
/**
- * Hidden constructor with the builder to build immutable class.
- *
- * @param builder
- * current builder
- */
- private DataAPIClientOptions(DataAPIClientOptionsBuilder builder) {
- this.apiVersion = builder.apiVersion;
- this.destination = builder.destination;
- this.maxCount = builder.maxCount;
- this.maxPageSize = builder.maxPageSize;
- this.maxRecordsInInsert = builder.maxDocumentsInInsert;
- this.embeddingAuthProvider = builder.embeddingAuthProvider;
- this.httpClientOptions = builder.httpClientOptions;
- this.observers = builder.observers;
- this.databaseAdditionalHeaders = builder.databaseAdditionalHeaders;
- this.adminAdditionalHeaders = builder.adminAdditionalHeaders;
- this.timeoutOptions = builder.timeoutOptions;
- }
+ * Observers for the commands (logging or metrics - emitter pattern).
+ */
+ private Map observers = new TreeMap<>();
+
+ // --------------------------------------------------
+ // --- Accessors ---
+ // --------------------------------------------------
/**
* Check if the deploying is Astra
*
- * @return
- * true if the destination is Astra
+ * @return true if the destination is Astra
*/
public boolean isAstra() {
return getDestination() == ASTRA ||
- getDestination() == ASTRA_DEV ||
- getDestination() == ASTRA_TEST;
+ getDestination() == ASTRA_DEV ||
+ getDestination() == ASTRA_TEST;
}
/**
* Find the Astra Environment from the destination provided in the initial Optional. It will help
* shaping the Api endpoint to spawn sub database objects.
*
- * @return
- * astra environment if found
+ * @return astra environment if found
*/
public AstraEnvironment getAstraEnvironment() {
if (getDestination() != null) {
@@ -169,384 +195,215 @@ public AstraEnvironment getAstraEnvironment() {
}
/**
- * Disabling the encoding of the vectors as base64.
+ * Gets apiVersion
+ *
+ * @return value of apiVersion
*/
- public static void disableEncodeDataApiVectorsAsBase64() {
- encodeDataApiVectorsAsBase64 = false;
+ public String getApiVersion() {
+ return apiVersion;
}
/**
- * Disabling the encoding of the vectors as base64.
+ * Gets destination
+ *
+ * @return value of destination
*/
- public static void disableEncodeDurationAsISO8601() {
- encodeDurationAsISO8601 = false;
+ public DataAPIDestination getDestination() {
+ return destination;
}
- @Override
- public String toString() {
- return new DatabaseSerializer().marshall(this);
+ /**
+ * Gets embeddingAuthProvider
+ *
+ * @return value of embeddingAuthProvider
+ */
+ public EmbeddingHeadersProvider getEmbeddingAuthProvider() {
+ return embeddingAuthProvider;
}
/**
- * Builder for the DataAPIClientOptions.
+ * Gets databaseAdditionalHeaders
+ *
+ * @return value of databaseAdditionalHeaders
*/
- public static class DataAPIClientOptionsBuilder {
-
- /** Caller name in User agent. */
- private String apiVersion = DEFAULT_VERSION;
-
- /** When operating a count operation, the maximum number of documents that can be returned. */
- private int maxCount = DEFAULT_MAX_COUNT;
-
- /** The maximum number of documents that can be returned in a single page. */
- private int maxPageSize = DEFAULT_MAX_PAGE_SIZE;
-
- /** The maximum number of documents that can be inserted in a single operation. */
- private int maxDocumentsInInsert = DEFAULT_MAX_CHUNK_SIZE;
-
- /** Encode the destination like Astra or local installation. */
- private DataAPIDestination destination = DataAPIDestination.ASTRA;
-
- /** The embedding service API key can be provided at top level. */
- private EmbeddingHeadersProvider embeddingAuthProvider;
-
- /** Add headers to admin calls. */
- final Map databaseAdditionalHeaders = new HashMap<>();
-
- /** Add headers to admin calls. */
- final Map adminAdditionalHeaders = new HashMap<>();
-
- /** Observers for the commands. */
- private final Map observers = new TreeMap<>();
-
- /** client options. */
- private HttpClientOptions httpClientOptions = new HttpClientOptions();
-
- /** timeout options. */
- public TimeoutOptions timeoutOptions = new TimeoutOptions();
-
- /**
- * Default constructor.
- */
- public DataAPIClientOptionsBuilder() {
- }
-
- /**
- * Builder pattern, update api version.
- *
- * @param apiVersion
- * api version
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withApiVersion(String apiVersion) {
- this.apiVersion = apiVersion;
- return this;
- }
-
- /**
- * Builder pattern, update api version.
- *
- * @param timeoutOptions
- * timeoutOptions
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withTimeoutOptions(TimeoutOptions timeoutOptions) {
- this.timeoutOptions = timeoutOptions;
- return this;
- }
+ public Map getDatabaseAdditionalHeaders() {
+ return databaseAdditionalHeaders;
+ }
- /**
- * Sets the maximum number of documents that can be returned by the count function.
- *
- *
- * If not explicitly set, the default value is defined by {@code MAX_DOCUMENTS_COUNT},
- * which is 1000 documents.
- *
- *
- * @param maxDocumentCount the maximum number of documents that can be returned by the count function.
- * Must be a positive number.
- * @return a reference to this builder, allowing for method chaining.
- *
- * Example usage:
- *
- * {@code
- * DataAPIClientOptions
- * .builder()
- * .withMaxDocumentCount(2000); // Sets the maximum number of documents to 2000.
- * }
- */
- public DataAPIClientOptionsBuilder withMaxCount(int maxDocumentCount) {
- if (maxDocumentCount <= 0) {
- throw new IllegalArgumentException("Max document count must be a positive number");
- }
- if (maxDocumentCount > DEFAULT_MAX_COUNT) {
- log.warn("Setting the maximum document count to a value greater than the default value of {} may impact performance.", DEFAULT_MAX_COUNT);
- }
- this.maxCount = maxDocumentCount;
- return this;
- }
+ /**
+ * Gets adminAdditionalHeaders
+ *
+ * @return value of adminAdditionalHeaders
+ */
+ public Map getAdminAdditionalHeaders() {
+ return adminAdditionalHeaders;
+ }
- /**
- * Sets the maximum number of documents that can be returned in a single page.
- *
- * If not explicitly set, the default value is defined by {@code MAX_PAGE_SIZE},
- * which is 20 documents.
- *
- *
- * @param maxPageSize the maximum number of documents that can be returned in a single page.
- * Must be a positive number.
- * @return a reference to this builder, allowing for method chaining.
- *
- * Example usage:
- *
- * {@code
- * DataAPIClientOptions
- * .builder()
- * .withMaxPageSize(50); // Sets the maximum page size to 50 documents.
- * }
- */
- public DataAPIClientOptionsBuilder withMaxPageSize(int maxPageSize) {
- if (maxPageSize <= 0) {
- throw new IllegalArgumentException("Max page size must be a positive number");
- }
- if (maxPageSize > DEFAULT_MAX_PAGE_SIZE) {
- log.warn("Setting the maximum page size to a value greater than the " +
- "default value of {} may impact performance or result in error at server level", DEFAULT_MAX_PAGE_SIZE);
- }
- this.maxPageSize = maxPageSize;
- return this;
- }
+ /**
+ * Gets observers
+ *
+ * @return value of observers
+ */
+ public Map getObservers() {
+ return observers;
+ }
- /**
- * Sets the maximum number of documents that can be inserted in a single operation.
- *
- * If not explicitly set, the default value is defined by {@code MAX_DOCUMENTS_IN_INSERT},
- * which is 20 documents.
- *
- *
- * @param maxDocumentsInInsert the maximum number of documents that can be inserted in a single operation.
- * Must be a positive number.
- * @return a reference to this builder, allowing for method chaining.
- *
- * Example usage:
- *
- * {@code
- * DataAPIClientOptions
- * .builder()
- * .withMaxDocumentsInInsert(50); // Sets the maximum number of documents to insert to 50.
- * }
- */
- public DataAPIClientOptionsBuilder withMaxDocumentsInInsert(int maxDocumentsInInsert) {
- if (maxDocumentsInInsert <= 0) {
- throw new IllegalArgumentException("Max documents in insert must be a positive number");
- }
- if (maxDocumentsInInsert > DEFAULT_MAX_CHUNK_SIZE) {
- log.warn("Setting the maximum number of documents in insert to a value greater than the " +
- "default value of {} may impact performance or result in error at server level", DEFAULT_MAX_CHUNK_SIZE);
- }
- this.maxDocumentsInInsert = maxDocumentsInInsert;
- return this;
- }
+ /**
+ * Gets httpClientOptions
+ *
+ * @return value of httpClientOptions
+ */
+ public HttpClientOptions getHttpClientOptions() {
+ return httpClientOptions;
+ }
- /**
- * Allow to register a listener for the command.
- * @param name
- * name of the observer
- * @param observer
- * observer to register
- * @return
- * instance of the command options
- */
- public DataAPIClientOptionsBuilder withObserver(String name, CommandObserver observer) {
- observers.put(name, observer);
- return this;
- }
+ /**
+ * Gets timeoutOptions
+ *
+ * @return value of timeoutOptions
+ */
+ public TimeoutOptions getTimeoutOptions() {
+ return timeoutOptions;
+ }
- /**
- * Register an observer with its className.
- *
- * @param observer
- * command observer
- * @return
- * instance of the command options
- */
- public DataAPIClientOptionsBuilder withObserver(CommandObserver observer) {
- return withObserver(observer.getClass().getSimpleName(), observer);
- }
+ /**
+ * Gets serdesOptions
+ *
+ * @return value of serdesOptions
+ */
+ public static SerdesOptions getSerdesOptions() {
+ return serdesOptions;
+ }
- /**
- * Help to enable loggin requests.
- *
- * @return current reference
- *
- */
- public DataAPIClientOptionsBuilder logRequests() {
- return withObserver(new LoggingCommandObserver(DataAPIClient.class));
- }
+ /**
+ * Register an observer with its className.
+ *
+ * @param observer command observer
+ * @return instance of the command options
+ */
+ public DataAPIClientOptions addObserver(String name, CommandObserver observer) {
+ this.observers.put(name, observer);
+ return this;
+ }
- /**
- * Builder pattern, update http connection Timeout
- *
- * @param destination
- * data api destination
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withDestination(DataAPIDestination destination) {
- this.destination = destination;
- return this;
- }
+ /**
+ * Register an observer with its className.
+ *
+ * @param observer command observer
+ * @return instance of the command options
+ */
+ public DataAPIClientOptions addObserver(CommandObserver observer) {
+ return addObserver(observer.getClass().getSimpleName(), observer);
+ }
- // --------------------------------------------
- // ----------------- HEADERS -----------------
- // --------------------------------------------
-
- /**
- * Builder pattern, update http connection Timeout
- *
- * @param embeddingAPIKey
- * embedding API Key
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withEmbeddingAPIKey(String embeddingAPIKey) {
- return withEmbeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider(embeddingAPIKey));
- }
+ /**
+ * Help to enable loggin requests.
+ *
+ * @return current reference
+ */
+ public DataAPIClientOptions logRequests() {
+ return addObserver(new LoggingCommandObserver(DataAPIClient.class));
+ }
- /**
- * Builder pattern, update authentication provider for vectorize.
- *
- * @param embeddingAuthProvider
- * embedding authentication provider
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withEmbeddingAuthProvider(EmbeddingHeadersProvider embeddingAuthProvider) {
- this.embeddingAuthProvider = embeddingAuthProvider;
- return this;
- }
+ // --------------------------------------------------
+ // --- Http Headers ---
+ // --------------------------------------------------
- /**
- * Builder pattern, update caller information.
- *o
- * @param name
- * caller name in the user agent
- * @param version
- * caller version in the user agent
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder addCaller(String name, String version) {
- httpClientOptions.addCaller(new Caller(name, version));
- return this;
- }
+ /**
+ * Builder pattern, update http connection Timeout
+ *
+ * @param embeddingAPIKey embedding API Key
+ * @return self reference
+ */
+ public DataAPIClientOptions embeddingAPIKey(String embeddingAPIKey) {
+ return embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider(embeddingAPIKey));
+ }
- /**
- * Add a header to the db calls.
- *
- * @param key
- * key
- * @param value
- * value
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder addDatabaseAdditionalHeader(String key, String value) {
- databaseAdditionalHeaders.put(key, value);
- return this;
- }
+ /**
+ * Builder pattern, update caller information.
+ * o
+ *
+ * @param name caller name in the user agent
+ * @param version caller version in the user agent
+ * @return self reference
+ */
+ public DataAPIClientOptions addCaller(String name, String version) {
+ this.httpClientOptions.addCaller(new Caller(name, version));
+ return this;
+ }
- public DataAPIClientOptionsBuilder enableFeatureFlagTables() {
- return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true");
- }
+ /**
+ * Add a header to the db calls.
+ *
+ * @param key key
+ * @param value value
+ * @return self reference
+ */
+ public DataAPIClientOptions addDatabaseAdditionalHeader(String key, String value) {
+ this.databaseAdditionalHeaders.put(key, value);
+ return this;
+ }
- public DataAPIClientOptionsBuilder disableFeatureFlagTables() {
- return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, null);
- }
+ /**
+ * Add a header to the admin calls.
+ *
+ * @param key key
+ * @param value value
+ * @return self reference
+ */
+ public DataAPIClientOptions addAdminAdditionalHeader(String key, String value) {
+ adminAdditionalHeaders.put(key, value);
+ return this;
+ }
- /**
- * Add a header to the admin calls.
- *
- * @param key
- * key
- * @param value
- * value
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder addAdminAdditionalHeader(String key, String value) {
- adminAdditionalHeaders.put(key, value);
- return this;
- }
+ public DataAPIClientOptions enableFeatureFlagTables() {
+ return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true");
+ }
- public DataAPIClientOptionsBuilder withHttpRetries(int count, Duration delay) {
- httpClientOptions.withRetries(count, delay);
- return this;
- }
+ public DataAPIClientOptions disableFeatureFlagTables() {
+ return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, null);
+ }
- /**
- * Builder pattern, update http redirect
- *
- * @param redirect
- * http redirect
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withHttpRedirect(HttpClient.Redirect redirect) {
- httpClientOptions.withHttpRedirect(redirect);
- return this;
- }
+ // --------------------------------------------
+ // ---------- JAVA DEFAULTS -----------------
+ // --------------------------------------------
- /**
- * Builder pattern, update http redirect
- *
- * @param httpClientOptions
- * all options for http client
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withHttpClientOptions(HttpClientOptions httpClientOptions) {
- this.httpClientOptions = httpClientOptions;
- return this;
- }
+ @Override
+ public String toString() {
+ return new DatabaseSerializer().marshall(this);
+ }
- /**
- * Builder pattern, update http version
- *
- * @param version
- * http version
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withHttpVersion(HttpClient.Version version) {
- httpClientOptions.withHttpVersion(version);
- return this;
- }
+ /**
+ * A default Client Options
+ */
+ public DataAPIClientOptions() {
+ // defaulting values
+ }
- /**
- * Builder pattern, update http httpProxy
- *
- * @param httpProxy
- * http proxy
- * @return
- * self reference
- */
- public DataAPIClientOptionsBuilder withHttpProxy(HttpProxy httpProxy) {
- httpClientOptions.withHttpProxy(httpProxy);
- return this;
- }
+ public DataAPIClientOptions(DataAPIClientOptions options) {
+ Assert.notNull(options, "Options");
+ this.apiVersion = options.apiVersion;
+ this.destination = options.destination;
+ this.embeddingAuthProvider = options.embeddingAuthProvider;
+ // Deep Copy
+ this.databaseAdditionalHeaders = options.databaseAdditionalHeaders != null ?
+ new HashMap<>(options.databaseAdditionalHeaders) : null;
+ this.adminAdditionalHeaders = options.adminAdditionalHeaders != null ?
+ new HashMap<>(options.adminAdditionalHeaders) : null;
+ this.observers = options.observers != null ?
+ new HashMap<>(options.observers) : null;
+ // Clones
+ this.httpClientOptions = options.httpClientOptions != null ?
+ options.httpClientOptions.clone() : null;
+ this.timeoutOptions = options.timeoutOptions != null ?
+ options.timeoutOptions.clone() : null;
+ this.serdesOptions = options.serdesOptions != null ?
+ options.serdesOptions.clone() : null;
+ }
- /**
- * Build the options.
- *
- * @return
- * options
- */
- public DataAPIClientOptions build() {
- return new DataAPIClientOptions(this);
- }
+ @Override
+ public DataAPIClientOptions clone() {
+ return new DataAPIClientOptions(this);
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/options/SerdesOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/SerdesOptions.java
new file mode 100644
index 00000000..3ec37c9a
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/SerdesOptions.java
@@ -0,0 +1,71 @@
+package com.datastax.astra.client.core.options;
+
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+@Setter
+@NoArgsConstructor
+@Accessors(fluent = true, chain = true)
+public class SerdesOptions implements Cloneable {
+
+ /** Encode the vector as binary. */
+ boolean encodeDurationAsISO8601 = true;
+
+ /** Encode the vector as binary. */
+ boolean encodeDataApiVectorsAsBase64 = true;
+
+ /**
+ * Gets encodeDurationAsISO8601
+ *
+ * @return value of encodeDurationAsISO8601
+ */
+ public boolean isEncodeDurationAsISO8601() {
+ return encodeDurationAsISO8601;
+ }
+
+ /**
+ * Gets encodeDataApiVectorsAsBase64
+ *
+ * @return value of encodeDataApiVectorsAsBase64
+ */
+ public boolean isEncodeDataApiVectorsAsBase64() {
+ return encodeDataApiVectorsAsBase64;
+ }
+
+ public SerdesOptions disableEncodeDataApiVectorsAsBase64() {
+ return encodeDataApiVectorsAsBase64(false);
+ }
+
+ public SerdesOptions disableEncodeDurationAsISO8601() {
+ return encodeDurationAsISO8601(false);
+ }
+
+ @Override
+ public SerdesOptions clone() {
+ try {
+ return (SerdesOptions) super.clone();
+ } catch (CloneNotSupportedException e) {
+ throw new AssertionError("Cloning not supported", e);
+ }
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/options/TimeoutOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/TimeoutOptions.java
index a92a5dd3..2986dbe3 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/options/TimeoutOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/options/TimeoutOptions.java
@@ -20,27 +20,28 @@
* #L%
*/
-import lombok.Builder;
-import lombok.Data;
-import lombok.Getter;
+import com.datastax.astra.internal.utils.Assert;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.experimental.Accessors;
+import java.time.Duration;
+
/**
* This class is used to define the timeout options for the client.
*/
-@Getter @Setter
+@Setter
@NoArgsConstructor
@Accessors(fluent = true, chain = true)
public class TimeoutOptions implements Cloneable {
public static final long DEFAULT_CONNECT_TIMEOUT_MILLIS = 10000L;
- public static final long DEFAULT_REQUEST_TIMEOUT_MILLIS = 30000L;
- public static final long DEFAULT_DATA_OPERATION_TIMEOUT_MILLIS = 30000L;
- public static final long DEFAULT_SCHEMA_OPERATION_TIMEOUT_MILLIS = 45000L;
+ public static final long DEFAULT_REQUEST_TIMEOUT_MILLIS = 10000L;
+ public static final long DEFAULT_GENERAL_METHOD_TIMEOUT_MILLIS = 30000L;
+ public static final long DEFAULT_COLLECTION_ADMIN_TIMEOUT_MILLIS = 60000L;
+ public static final long DEFAULT_TABLE_ADMIN_TIMEOUT_MILLIS = 30000L;
public static final long DEFAULT_DATABASE_ADMIN_TIMEOUT_MILLIS = 600000L;
- public static final long DEFAULT_KEYSPACE_ADMIN_TIMEOUT_MILLIS = 20000L;
+ public static final long DEFAULT_KEYSPACE_ADMIN_TIMEOUT_MILLIS = 30000L;
/**
* Lower level request timeout (http request)
@@ -55,12 +56,7 @@ public class TimeoutOptions implements Cloneable {
/**
* Data operation timeout (find*, insert*, update*, delete*)
*/
- long dataOperationTimeoutMillis = DEFAULT_DATA_OPERATION_TIMEOUT_MILLIS;
-
- /**
- * Schema operation timeout (create*, alter*, drop*)
- */
- long schemaOperationTimeoutMillis = DEFAULT_SCHEMA_OPERATION_TIMEOUT_MILLIS;
+ long generalMethodTimeoutMillis = DEFAULT_GENERAL_METHOD_TIMEOUT_MILLIS;
/**
* Database admin timeout (create, delete, list)
@@ -72,6 +68,16 @@ public class TimeoutOptions implements Cloneable {
*/
long keyspaceAdminTimeoutMillis = DEFAULT_KEYSPACE_ADMIN_TIMEOUT_MILLIS;
+ /**
+ * Schema operation timeout (create*, alter*, drop*)
+ */
+ long collectionAdminTimeoutMillis = DEFAULT_COLLECTION_ADMIN_TIMEOUT_MILLIS;
+
+ /**
+ * Schema operation timeout (create*, alter*, drop*)
+ */
+ long tableAdminTimeoutMillis = DEFAULT_TABLE_ADMIN_TIMEOUT_MILLIS;
+
@Override
public TimeoutOptions clone() {
try {
@@ -81,6 +87,48 @@ public TimeoutOptions clone() {
}
}
+ public TimeoutOptions connectTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.connectTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions requestTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.requestTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions generalMethodTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.generalMethodTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions databaseAdminTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.databaseAdminTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions keyspaceAdminTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.keyspaceAdminTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions collectionAdminTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.collectionAdminTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
+ public TimeoutOptions tableAdminTimeout(Duration timeout) {
+ Assert.notNull(timeout, "Timeout");
+ this.tableAdminTimeoutMillis = timeout.toMillis();
+ return this;
+ }
+
/**
* Gets connectTimeoutMillis
*
@@ -104,8 +152,8 @@ public long getRequestTimeoutMillis() {
*
* @return value of dataOperationTimeoutMillis
*/
- public long getDataOperationTimeoutMillis() {
- return dataOperationTimeoutMillis;
+ public long getGeneralMethodTimeoutMillis() {
+ return generalMethodTimeoutMillis;
}
/**
@@ -113,8 +161,8 @@ public long getDataOperationTimeoutMillis() {
*
* @return value of schemaOperationTimeoutMillis
*/
- public long getSchemaOperationTimeoutMillis() {
- return schemaOperationTimeoutMillis;
+ public long getTableAdminTimeoutMillis() {
+ return tableAdminTimeoutMillis;
}
/**
@@ -134,4 +182,13 @@ public long getDatabaseAdminTimeoutMillis() {
public long getKeyspaceAdminTimeoutMillis() {
return keyspaceAdminTimeoutMillis;
}
+
+ /**
+ * Gets collectionAdminTimeoutMillis
+ *
+ * @return value of collectionAdminTimeoutMillis
+ */
+ public long getCollectionAdminTimeoutMillis() {
+ return collectionAdminTimeoutMillis;
+ }
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/query/Sort.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/query/Sort.java
index 80196cda..1fd0b3b3 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/query/Sort.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/query/Sort.java
@@ -122,7 +122,7 @@ public static Sort vector(float[] embeddings) {
* sort instance.
*/
public static Sort vectorize(String vectorize) {
- return new Sort(DataAPIKeywords.VECTOR.getKeyword(), null, vectorize, null);
+ return new Sort(DataAPIKeywords.VECTORIZE.getKeyword(), null, vectorize, null);
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/core/vector/VectorOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/core/vector/VectorOptions.java
index 95144e34..100dc337 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/core/vector/VectorOptions.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/core/vector/VectorOptions.java
@@ -24,11 +24,15 @@
import com.fasterxml.jackson.annotation.JsonIgnore;
import lombok.Data;
import lombok.NoArgsConstructor;
+import lombok.Setter;
+import lombok.experimental.Accessors;
/**
* Subclass representing the vector options.
*/
-@Data @NoArgsConstructor
+@Setter
+@NoArgsConstructor
+@Accessors(fluent = true, chain = true)
public class VectorOptions {
/**
@@ -56,5 +60,32 @@ public class VectorOptions {
public SimilarityMetric getSimilarityMetric() {
return SimilarityMetric.fromValue(metric);
}
+
+ /**
+ * Gets dimension
+ *
+ * @return value of dimension
+ */
+ public Integer getDimension() {
+ return dimension;
+ }
+
+ /**
+ * Gets metric
+ *
+ * @return value of metric
+ */
+ public String getMetric() {
+ return metric;
+ }
+
+ /**
+ * Gets service
+ *
+ * @return value of service
+ */
+ public VectorServiceOptions getService() {
+ return service;
+ }
}
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
index 7e6d8895..c8833b79 100644
--- 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
@@ -20,524 +20,1109 @@
* #L%
*/
+import com.datastax.astra.client.admin.AdminOptions;
import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.admin.AstraDBDatabaseAdmin;
import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
import com.datastax.astra.client.admin.DatabaseAdmin;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.CollectionDefinition;
+import com.datastax.astra.client.collections.CollectionDescriptor;
import com.datastax.astra.client.collections.CollectionOptions;
import com.datastax.astra.client.collections.documents.Document;
+import com.datastax.astra.client.core.commands.BaseOptions;
import com.datastax.astra.client.core.commands.Command;
-import com.datastax.astra.client.core.commands.CommandOptions;
-import com.datastax.astra.client.core.options.DataAPIClientOptions;
-import com.datastax.astra.client.core.vector.SimilarityMetric;
+import com.datastax.astra.client.databases.options.CreateCollectionOptions;
+import com.datastax.astra.client.databases.options.DropCollectionOptions;
+import com.datastax.astra.client.databases.options.ListCollectionOptions;
+import com.datastax.astra.client.databases.options.ListIndexesOptions;
+import com.datastax.astra.client.databases.options.ListTablesOptions;
import com.datastax.astra.client.exception.InvalidConfigurationException;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.TableDefinition;
import com.datastax.astra.client.tables.TableDescriptor;
+import com.datastax.astra.client.tables.TableOptions;
import com.datastax.astra.client.tables.ddl.CreateTableOptions;
import com.datastax.astra.client.tables.ddl.DropTableIndexOptions;
import com.datastax.astra.client.tables.ddl.DropTableOptions;
-import com.datastax.astra.client.tables.index.IndexDescriptor;
+import com.datastax.astra.client.tables.index.TableIndexDefinition;
+import com.datastax.astra.client.tables.index.TableIndexDescriptor;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.row.Row;
import com.datastax.astra.internal.api.AstraApiEndpoint;
import com.datastax.astra.internal.command.AbstractCommandRunner;
import com.datastax.astra.internal.command.CommandObserver;
-import com.datastax.astra.internal.serdes.DataAPISerializer;
-import com.datastax.astra.internal.serdes.DatabaseSerializer;
+import com.datastax.astra.internal.utils.Assert;
import com.dtsx.astra.sdk.utils.Utils;
import lombok.Getter;
-import lombok.NonNull;
-import lombok.extern.slf4j.Slf4j;
-import java.util.stream.Stream;
+import java.util.List;
+import java.util.UUID;
-import static com.datastax.astra.client.core.commands.CommandType.SCHEMA;
-import static com.datastax.astra.client.exception.InvalidEnvironmentException.throwErrorRestrictedAstra;
import static com.datastax.astra.client.tables.mapping.EntityBeanDefinition.createTableCommand;
-import static com.datastax.astra.internal.utils.AnsiUtils.green;
import static com.datastax.astra.internal.utils.Assert.hasLength;
import static com.datastax.astra.internal.utils.Assert.notNull;
/**
- * A Data API database. This is the entry-point object for doing database-level
- * DML, such as creating/deleting collections, and for obtaining Collection
- * objects themselves. This class has a synchronous interface.
- *
- * A Database comes with an "API Endpoint", which implies a Database object
- * instance reaches a specific region (relevant point in case of multi-region
- * databases).
- *
+ * Represents a Data API database, providing the primary entry point for database-level operations
+ * and interactions. This class enables Data Manipulation Language (DML) operations such as
+ * creating and deleting collections, as well as obtaining {@link Collection} objects for further
+ * operations on specific collections. It also provides access to operations for managing tables.
+ *
+ * This class provides a synchronous interface, designed for straightforward and immediate
+ * execution of database commands. It is intended for use in scenarios where blocking calls are
+ * acceptable or desirable, such as in traditional server-side applications or command-line tools.
+ *
+ * Each {@code Database} instance is associated with an "API Endpoint," which defines the specific
+ * region it connects to. This is particularly important for multi-region databases, where each
+ * instance of {@code Database} ensures connectivity to a specific regional endpoint for optimal
+ * performance and consistency.
+ *
+ * Key Features:
+ *
+ * - Direct access to database-level operations, including collection management.
+ * - Region-specific connectivity for multi-region database configurations.
+ * - Built on {@link AbstractCommandRunner}, providing consistent command execution semantics.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * // Initialize the database object with endpoint and options
+ * DataAPIClient client = new DataAPIClient("token");
+ * client.getDatabase("https://-.apps.astra.datastax.com");
+ *
+ * // Perform database-level operations
+ * database.createCollection("myCollection");
+ * Collection collection = database.getCollection("myCollection");
+ * collection.insert(new Document("field1", "value1"));
+ * }
+ *
+ *
+ * @see Collection
+ * @see AbstractCommandRunner
*/
-@Slf4j
-public class Database extends AbstractCommandRunner {
+@Getter
+public class Database extends AbstractCommandRunner {
- /** Serializer for the Collections. */
- private static final DatabaseSerializer SERIALIZER = new DatabaseSerializer();
-
- /** Token to be used with the Database. */
- @Getter
- private final String token;
+ /**
+ * This core endpoint could be used for admin operations.
+ */
+ private final String rootEndpoint;
- /** Api Endpoint for the API. */
- @Getter
- private final String dbApiEndpoint;
+ /**
+ * Database information cached if (getInfo()) is called
+ */
+ private DatabaseInfo cachedDbInfo;
- /** Options to set up the client. */
- @Getter
- private final DataAPIClientOptions options;
+ /**
+ * Initializes a {@link Database} instance with the specified API endpoint and connection options.
+ * This constructor configures the database client to interact with the Data API at the provided
+ * root endpoint, setting up necessary parameters and constructing the API endpoint based on
+ * the deployment environment and options.
+ *
+ * The API endpoint is automatically adjusted for Astra deployments (e.g., {@code ASTRA},
+ * {@code ASTRA_TEST}, {@code ASTRA_DEV}), appending the required JSON API path if the root
+ * endpoint ends with {@code ".com"}. For local or on-premise deployments, no adjustments are made
+ * to the root endpoint.
+ *
+ * The constructed API endpoint includes:
+ *
+ * - The specified {@code apiVersion}, retrieved from {@link com.datastax.astra.client.core.options.DataAPIClientOptions}.
+ * - The {@code keyspace}, defined in the provided {@link DatabaseOptions}.
+ *
+ *
+ * @param rootEndpoint
+ * The root API endpoint for connecting to the database. This is the base URL that determines
+ * the target deployment environment (e.g., Astra or local).
+ * @param options
+ * The {@link DatabaseOptions} containing all attributes required to connect to the database,
+ * including authentication details, keyspace configuration, and client options.
+ */
+ public Database(String rootEndpoint, DatabaseOptions options) {
+ super(rootEndpoint, options);
+ this.rootEndpoint = rootEndpoint;
+ StringBuilder dbApiEndPointBuilder = new StringBuilder(rootEndpoint);
+ switch(options.getDataAPIClientOptions().getDestination()) {
+ case ASTRA:
+ case ASTRA_TEST:
+ case ASTRA_DEV:
+ if (rootEndpoint.endsWith(".com")) {
+ dbApiEndPointBuilder.append("/api/json");
+ }
+ break;
+ default:
+ // left blank as local deployments does not require any change
+ break;
+ }
+ this.apiEndpoint = dbApiEndPointBuilder
+ .append("/")
+ .append(options.getDataAPIClientOptions().getApiVersion())
+ .append("/")
+ .append(options.getKeyspace())
+ .toString();
+ }
- /** Current Keyspace information.*/
- @Getter
- private String keyspaceName;
+ // ------------------------------------------
+ // ---- Core Features ----
+ // ------------------------------------------
/**
- * This core endpoint could be used for admin operations.
+ * Retrieves the name of the currently selected keyspace.
+ *
+ * @return The name of the keyspace currently in use by this {@code Database} instance.
*/
- private final String databaseAdminEndpoint;
+ public String getKeyspace() {
+ return options.getKeyspace();
+ }
/**
- * Initialization with endpoint and apikey.
+ * Retrieves the region of the database if it is deployed in Astra. This method ensures that
+ * the database is an Astra deployment before returning the region. If the database is not deployed
+ * in Astra, an assertion error is raised.
*
- * @param token
- * api token
- * @param apiEndpoint
- * api endpoint
+ * @return The region where the Astra database is deployed.
+ * @throws IllegalStateException if the database is not deployed in Astra.
*/
- public Database(String apiEndpoint, String token) {
- this(apiEndpoint, token, AstraDBAdmin.DEFAULT_KEYSPACE, DataAPIClientOptions.builder().build());
+ public String getRegion() {
+ assertIsAstra();
+ return AstraApiEndpoint.parse(getApiEndpoint()).getDatabaseRegion();
}
/**
- * Initialization with endpoint and apikey.
+ * Retrieves the unique database identifier (UUID) of the database if it is deployed in Astra.
+ * This method ensures that the database is an Astra deployment before returning the identifier.
+ * If the database is not deployed in Astra, an assertion error is raised.
*
- * @param token
- * api token
- * @param apiEndpoint
- * api endpoint
- * @param keyspace
- * keyspace
+ * @return The unique identifier (UUID) of the Astra database.
+ * @throws IllegalStateException if the database is not deployed in Astra.
*/
- public Database(String apiEndpoint, String token, String keyspace) {
- this(apiEndpoint, token, keyspace, DataAPIClientOptions.builder().build());
+ public UUID getId() {
+ assertIsAstra();
+ return AstraApiEndpoint.parse(getApiEndpoint()).getDatabaseId();
}
/**
- * Initialization with endpoint and apikey.
+ * Retrieves information about the current database, including metadata and configuration details.
*
- * @param apiEndpoint
- * api endpoint
- * @param token
- * api token
- * @param keyspace
- * keyspace
- * @param options
- * setup of the clients with options
+ * This method interacts with the devops API to fetch database information. To optimize
+ * performance, the database information is cached after the first retrieval. Subsequent calls to this
+ * method return the cached {@link DatabaseInfo} object unless the cache is invalidated externally.
+ *
+ * Example usage:
+ *
+ * {@code
+ * DatabaseInfo info = database.getInfo();
+ * System.out.println("Database Name: " + info.getName());
+ * System.out.println("Database Version: " + info.getVersion());
+ * }
+ *
+ *
+ * @return A {@link DatabaseInfo} object containing details about the current database.
+ * @throws IllegalStateException if the database information cannot be retrieved or if the
+ * database is not properly configured for administration operations.
*/
- public Database(String apiEndpoint, String token, String keyspace, DataAPIClientOptions options) {
- hasLength(apiEndpoint, "endpoint");
- hasLength(token, "token");
- hasLength(keyspace, "keyspace");
- notNull(options, "options");
- this.keyspaceName = keyspace;
- this.token = token;
- this.options = options;
- this.dbApiEndpoint = apiEndpoint;
-
- // Command Options inherit from DataAPIOptions
- this.commandOptions = new CommandOptions<>(options);
- this.commandOptions.token(token);
- this.commandOptions.commandType(SCHEMA);
- this.databaseAdminEndpoint = apiEndpoint.endsWith(options.getApiVersion()) ?
- apiEndpoint :
- apiEndpoint + "/" + options.getApiVersion();
+ public DatabaseInfo getInfo() {
+ if (cachedDbInfo == null) {
+ cachedDbInfo = getAdmin().getDatabaseInfo(getId());
+ }
+ return cachedDbInfo;
}
- // ------------------------------------------
- // ---- Mutate Keyspace ----
- // ------------------------------------------
+ /**
+ * Retrieves the name of the current database.
+ *
+ * This method provides a convenient way to access the database name from the {@link DatabaseInfo}
+ * object returned by {@link #getInfo()}. It encapsulates the process of fetching and extracting
+ * the database name.
+ *
+ * Example usage:
+ *
+ * {@code
+ * String dbName = database.getName();
+ * System.out.println("Database Name: " + dbName);
+ * }
+ *
+ *
+ * @return The name of the current database as a {@link String}.
+ * @throws IllegalStateException if the database information cannot be retrieved or is unavailable.
+ */
+ public String getName() {
+ return getInfo().getName();
+ }
/**
- * This mutates the keyspace to be used.
+ * Sets the active keyspace for the database.
+ * This method allows switching the current keyspace context used for database operations.
*
* @param keyspace
- * current keyspace
+ * The name of the keyspace to set as the current keyspace.
+ * This must not be null or empty.
* @return
- * the database
+ * The database instance with the specified keyspace set as active,
+ * allowing for method chaining.
+ * @throws IllegalArgumentException
+ * If the provided keyspace is null or empty.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Database database = new Database();
+ * database.useKeyspace("my_keyspace");
+ * }
+ *
*/
public Database useKeyspace(String keyspace) {
- this.keyspaceName = keyspace;
+ Assert.hasLength(keyspace, "keyspace");
+ this.options.keyspace(keyspace);
return this;
}
// ------------------------------------------
- // ---- Access Region ----
+ // ---- Astra Admin ----
// ------------------------------------------
/**
- * Get the region of the database if deployed in Astra.
+ * Retrieves an administration client for Astra deployments using detailed administrative options.
+ *
+ * This method provides fine-grained control over the client configuration by allowing explicit
+ * specification of both the token and additional options.
+ *
*
- * @return
- * the region
+ * @param adminOptions The {@link AdminOptions} object containing authentication and configuration details.
+ * @return An {@link AstraDBAdmin} instance configured with the provided administrative options.
+ * @throws IllegalStateException if the database is not deployed in Astra.
*/
- public String getRegion() {
- if (!options.isAstra()) {
- throwErrorRestrictedAstra("getRegion", options.getDestination());
- }
- return AstraApiEndpoint.parse(getApiEndpoint()).getDatabaseRegion();
+ public AstraDBAdmin getAdmin(AdminOptions adminOptions) {
+ assertIsAstra();
+ return new AstraDBAdmin(adminOptions);
+ }
+
+ /**
+ * Retrieves an administration client specifically for Astra deployments using the default authentication token.
+ *
+ * This client allows execution of administrative tasks such as creating databases and managing Astra configurations.
+ *
+ *
+ * @return An {@link AstraDBAdmin} instance configured with the default token for administrative operations.
+ * @throws IllegalStateException if the database is not deployed in Astra.
+ */
+ public AstraDBAdmin getAdmin() {
+ return getAdmin(options.getToken());
+ }
+
+ /**
+ * Retrieves an administration client specifically for Astra deployments using a provided super-user token.
+ *
+ * This method allows overriding the default token with a custom super-user token for enhanced privileges.
+ *
+ *
+ * @param superUserToken A token with elevated privileges for administrative operations.
+ * @return An {@link AstraDBAdmin} instance configured with the provided token.
+ * @throws IllegalStateException if the database is not deployed in Astra.
+ */
+ public AstraDBAdmin getAdmin(String superUserToken) {
+ return getAdmin(new AdminOptions(superUserToken, options.getDataAPIClientOptions()));
}
// ------------------------------------------
- // ---- Access Database Admin ----
+ // ---- Database Admin ---
// ------------------------------------------
/**
- * Access a database Admin client from the database
- * @return
- * database admin
+ * Retrieves a database administration client using detailed administrative options.
+ *
+ * Depending on the deployment type (Astra or non-Astra), this method returns an appropriate implementation of
+ * {@link DatabaseAdmin}, either {@link AstraDBDatabaseAdmin} or {@link DataAPIDatabaseAdmin}. The provided
+ * {@link AdminOptions} object determines the authentication and configuration used for the client.
+ *
+ *
+ * Key behaviors:
+ *
+ * - If no {@code adminOptions} are provided, a default configuration is derived from the current options.
+ * - If the deployment is Astra, an {@link AstraDBDatabaseAdmin} instance is returned.
+ * - For non-Astra deployments, a {@link DataAPIDatabaseAdmin} instance is returned.
+ *
+ *
+ *
+ * @param adminOptions The {@link AdminOptions} object containing authentication and configuration details.
+ * @return A {@link DatabaseAdmin} instance tailored for the current deployment type and configured with the provided options.
+ */
+ public DatabaseAdmin getDatabaseAdmin(AdminOptions adminOptions) {
+ if (adminOptions == null) {
+ adminOptions = new AdminOptions(options.getToken(), options.getDataAPIClientOptions().clone());
+ } else if (adminOptions.getDataAPIClientOptions() == null) {
+ adminOptions.dataAPIClientOptions(options.getDataAPIClientOptions().clone());
+ }else if (adminOptions.getToken() == null) {
+ adminOptions.token(options.getToken());
+ }
+ // Pick the right admin client
+ if (options.getDataAPIClientOptions().isAstra()) {
+ return new AstraDBDatabaseAdmin(this, adminOptions);
+ }
+ return new DataAPIDatabaseAdmin(this, adminOptions);
+ }
+
+ /**
+ * Retrieves a database administration client using the default authentication token.
+ *
+ * The client enables management of database-level configurations, such as keyspaces, collections,
+ * and other database settings.
+ *
+ *
+ * @return A {@link DatabaseAdmin} instance configured with the default token for database-level operations.
*/
public DatabaseAdmin getDatabaseAdmin() {
- return new DataAPIDatabaseAdmin(this);
+ return getDatabaseAdmin(options.getToken());
}
/**
- * Gets the name of the database.
+ * Retrieves a database administration client using a provided super-user token.
+ *
+ * This method allows overriding the default token with a custom super-user token for privileged database
+ * management operations.
+ *
*
- * @param superUserToken
- * provide a token with a super-user role
- * @return the database name
+ * @param superUserToken A token with elevated privileges for database administration tasks.
+ * @return A {@link DatabaseAdmin} instance configured with the provided token.
*/
public DatabaseAdmin getDatabaseAdmin(String superUserToken) {
- if (options.isAstra()) {
- AstraApiEndpoint endpoint = AstraApiEndpoint.parse(getApiEndpoint());
- return new AstraDBDatabaseAdmin(superUserToken, endpoint.getDatabaseId(), options);
- }
- return new DataAPIDatabaseAdmin(databaseAdminEndpoint, token, options);
+ return getDatabaseAdmin(new AdminOptions(superUserToken, options.getDataAPIClientOptions()));
}
// ------------------------------------------
- // ---- Collection CRUD ----
+ // ---- List Collections ----
// ------------------------------------------
/**
- * Gets the names of all the collections in this database.
+ * Retrieves the names of all the collections present in this database.
+ *
+ * This method provides a list of collection names, allowing developers to explore or iterate over the
+ * available collections in the database. It is particularly useful for dynamic scenarios where the
+ * collections within a database might not be predetermined or when you need to inspect the database's
+ * current state programmatically.
+ *
*
- * @return
- * a stream containing all the names of all the collections in this database
+ * Example usage:
+ *
+ * {@code
+ * Database database = new DataAPIClient("token").getDatabase("endpoint);
+ * List collectionNames = database.listCollectionNames();
+ * collectionNames.forEach(System.out::println);
+ * }
+ *
+ *
+ * @return A {@link List} containing the names of all collections in this database.
+ * @throws com.datastax.astra.client.exception.DataAPIException if an error occurs while retrieving the collection names.
*/
- public Stream listCollectionNames() {
- Command findCollections = Command.create("findCollections");
- return runCommand(findCollections, this.commandOptions)
- .getStatusKeyAsList("collections", String.class)
- .stream();
+ public List listCollectionNames() {
+ return listCollectionNames(null);
}
/**
- * Finds all the collections in this database.
+ * Retrieves the names of all the collections present in this database, with the ability to customize
+ * the listing behavior using the specified {@link ListCollectionOptions}.
+ *
+ * This method provides a list of collection names, allowing developers to explore or iterate over
+ * the collections in the database. The behavior of this operation can be tailored by providing
+ * {@link ListCollectionOptions}, enabling filtering or additional configuration as needed.
+ *
*
- * @return
- * list of collection definitions
+ * Parameters:
+ *
+ * - {@code listCollectionOptions} - The options to customize the collection listing operation,
+ * such as filtering criteria or additional query parameters.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * // Create list collection options
+ * ListCollectionOptions options = new ListCollectionOptions()
+ * .timeout(Duration.ofMillis(1000));
+ *
+ * // Retrieve collection names based on options
+ * Database database = new DataAPIClient("token").getDatabase("endpoint);
+ * List collectionNames = database.listCollectionNames(options);
+ *
+ * // Print the collection names
+ * collectionNames.forEach(System.out::println);
+ * }
+ *
+ *
+ * @param listCollectionOptions The {@link ListCollectionOptions} to customize the collection listing behavior.
+ * @return A {@link List} containing the names of all collections in this database, filtered or modified
+ * according to the provided options.
+ */
+ public List listCollectionNames(ListCollectionOptions listCollectionOptions) {
+ return runCommand(Command.create("findCollections"), listCollectionOptions)
+ .getStatusKeyAsStringStream("collections")
+ .toList();
+ }
+
+ /**
+ * Retrieves all collections in this database along with their definitions.
+ *
+ * This method returns a list of {@link CollectionDescriptor} objects, providing detailed metadata
+ * about each collection, such as its name, schema, or other relevant attributes. It acts as a
+ * convenient entry point for obtaining all collection definitions without any filtering or additional options.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * Database database = new DataAPIClient("token").getDatabase("endpoint);
+ * List collections = database.listCollections();
+ * }
+ *
+ *
+ * @return A {@link List} of {@link CollectionDescriptor} objects representing all collections in this database.
+ */
+ public List listCollections() {
+ return listCollections(null);
+ }
+
+ /**
+ * Retrieves all collections in this database along with their definitions, customized by the
+ * specified {@link ListCollectionOptions}.
+ *
+ * This method allows for more fine-grained control over the collection retrieval process, enabling
+ * options such as filtering, limiting the number of results, or specifying additional query parameters.
+ * The returned list includes {@link CollectionDescriptor} objects, which provide detailed metadata
+ * for each collection that matches the provided options.
+ *
+ *
+ * Parameters:
+ *
+ * - {@code listCollectionOptions} - The {@link ListCollectionOptions} to customize the listing behavior,
+ * such as filtering criteria or additional query parameters. If {@code null}, all collections are returned.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * // Create options for listing collections with a specific prefix
+ * ListCollectionOptions options = new ListCollectionOptions()
+ * .timeout(Duration.ofMillis(1000));
+ *
+ * // Retrieve matching collections
+ * Database database = new DataAPIClient("token").getDatabase("endpoint);
+ * List collections = database.listCollections(options);
+ * }
+ *
+ *
+ * @param listCollectionOptions The {@link ListCollectionOptions} to customize the collection retrieval process.
+ * If {@code null}, no filtering or additional options are applied.
+ * @return A {@link List} of {@link CollectionDescriptor} objects representing the collections that match the criteria.
*/
- public Stream listCollections() {
- Command findCollections = Command
- .create("findCollections")
+ public List listCollections(ListCollectionOptions listCollectionOptions) {
+ Command findCollections = Command.create("findCollections")
.withOptions(new Document().append("explain", true));
- return runCommand(findCollections, this.commandOptions)
- .getStatusKeyAsList("collections", CollectionDefinition.class)
- .stream();
+ return runCommand(findCollections, listCollectionOptions)
+ .getStatusKeyAsList("collections", CollectionDescriptor.class);
}
/**
- * Evaluate if a collection exists.
+ * Checks if a specified collection exists in this database.
+ *
+ * This method evaluates whether a collection with the given name is present in the database.
+ * It is useful for verifying the existence of a collection before performing operations such
+ * as querying, inserting, or updating data.
+ *
*
- * @param collection
- * collections name.
- * @return
- * if collections exists
+ * Example usage:
+ *
+ * {@code
+ * Database database = new DataAPIClient("token").getDatabase("endpoint");
+ * boolean exists = database.collectionExists("my_collection");
+ * if (exists) {
+ * System.out.println("Collection exists!");
+ * } else {
+ * System.out.println("Collection does not exist.");
+ * }
+ * }
+ *
+ *
+ * @param collectionName The name of the collection to check.
+ * @return {@code true} if the collection exists, {@code false} otherwise.
+ * @throws IllegalArgumentException if the collection name is {@code null} or empty.
*/
- public boolean collectionExists(String collection) {
- return listCollectionNames().anyMatch(collection::equals);
+ public boolean collectionExists(String collectionName) {
+ Assert.hasLength(collectionName, "collectionName");
+ return listCollectionNames().contains(collectionName);
}
+ // ------------------------------------------
+ // ---- Get Collection ----
+ // ------------------------------------------
+
/**
- * Gets a collection.
+ * Retrieves a {@link Collection} object for the specified collection name.
+ *
+ * This method provides a convenient way to obtain a {@link Collection} instance for a specific
+ * collection in the database. The returned object allows for further operations on the collection,
+ * such as querying, inserting, or updating documents.
+ *
*
- * @param collectionName
- * the name of the collection to return
- * @return
- * the collection
- * @throws IllegalArgumentException
- * if collectionName is invalid
+ * Parameters:
+ *
+ * - {@code collectionName} - The name of the collection to retrieve. This must not be null or empty.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * Database database = new DataAPIClient("token").getDatabase("endpoint");
+ * Collection collection = database.getCollection("my_collection");
+ * }
+ *
+ *
+ * @param collectionName The name of the collection to retrieve.
+ * @return A {@link Collection} object representing the specified collection.
+ * @throws IllegalArgumentException if the collection name is {@code null} or empty.
*/
public Collection getCollection(String collectionName) {
return getCollection(collectionName, Document.class);
}
/**
- * Gets a collection, with a specific default document class.
+ * Retrieves a {@link Collection} object for the specified collection name, with the ability to
+ * customize the collection behavior using the specified {@link CollectionOptions}.
+ *
+ * This method provides a way to obtain a {@link Collection} instance for a specific collection in
+ * the database, with additional options for configuring the collection's behavior. The returned object
+ * allows for further operations on the collection, such as querying, inserting, or updating documents.
+ *
*
- * @param collectionName
- * the name of the collection to return
- * @param documentClass
- * the default class to cast any documents returned from the database into.
- * @param
- * the type of the class to use instead of {@code Document}.
- * @return
- * the collection
+ * Parameters:
+ *
+ * - {@code collectionName} - The name of the collection to retrieve. This must not be null or empty.
+ * - {@code collectionOptions} - The {@link CollectionOptions} to customize the collection behavior,
+ * such as setting a custom serializer or specifying additional options. If {@code null}, default options are used.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * // Create custom collection options
+ * CollectionOptions options = new CollectionOptions()
+ * .serializer(new MyCustomSerializer());
+ *
+ * // Retrieve the collection with custom options
+ * Database database = new DataAPIClient("token").getDatabase("endpoint");
+ * Collection collection = database.getCollection("my_collection", options);
+ * }
+ *
+ *
+ * @param collectionName The name of the collection to retrieve.
+ * @return A {@link Collection} object representing the specified collection, configured with the provided options.
+ * @throws IllegalArgumentException if the collection name is {@code null} or empty.
*/
- public Collection getCollection(String collectionName, @NonNull Class documentClass) {
- return getCollection(collectionName, this.commandOptions, documentClass);
+ public Collection getCollection(String collectionName, Class documentClass) {
+ return getCollection(collectionName, new CollectionOptions(
+ options.getToken(),
+ options.getDataAPIClientOptions()), documentClass);
}
/**
- * Gets a collection, with a specific default document class.
+ * Retrieves a {@link Collection} object for the specified collection name with the ability to specify custom options.
+ *
+ * This method provides a flexible way to obtain a {@link Collection} instance by allowing
+ * the caller to specify {@link CollectionOptions} to customize the behavior of the collection.
+ *
*
- * @param collectionName
- * the name of the collection to return
- * @param documentClass
- * the default class to cast any documents returned from the database into.
- * @param commandOptions
- * options to use when using this collection
- * @param
- * the type of the class to use instead of {@code Document}.
- * @return
- * the collection
+ * Parameters:
+ *
+ * - {@code collectionName} - The name of the collection to retrieve. This must not be null or empty.
+ * - {@code collectionOptions} - A {@link CollectionOptions} object that specifies custom
+ * behaviors for the collection. If {@code null}, default options will be used.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ *
+ * CollectionOptions options = new CollectionOptions()
+ * .timeout(Duration.ofMillis(1000))
+ * .dataAPIClientOptions(new DataAPIClientOptions())
+ * .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key"));
+ *
+ * Database database = new DataAPIClient("token").getDatabase("endpoint");
+ * Collection collection = database.getCollection("my_collection", options);
+ * }
+ *
+ *
+ * @param collectionName The name of the collection to retrieve.
+ * @param collectionOptions The {@link CollectionOptions} to customize the collection behavior.
+ * @return A {@link Collection} object representing the specified collection.
+ * @throws IllegalArgumentException if {@code collectionName} is {@code null} or empty.
*/
- public Collection getCollection(String collectionName, CommandOptions commandOptions, @NonNull Class documentClass) {
- hasLength(collectionName, "collectionName");
- notNull(documentClass, "documentClass");
- return new Collection<>(this, collectionName, commandOptions, documentClass);
+ public Collection getCollection(String collectionName, CollectionOptions collectionOptions) {
+ return getCollection(collectionName, collectionOptions, Document.class);
}
/**
- * Create a new collection with the given name.
+ * Retrieves a {@link Collection} object for the specified collection name with custom options and document type.
+ *
+ * This method provides the most flexible way to obtain a {@link Collection} instance, allowing
+ * clients to specify custom options and the type of documents in the collection.
+ *
*
- * @param collectionName
- * the name for the new collection to create
- * @return
- * the instance of collection
+ * Parameters:
+ *
+ * - {@code collectionName} - The name of the collection to retrieve. This must not be null or empty.
+ * - {@code options} - The {@link CollectionOptions} to customize the collection behavior. Must not be null.
+ * - {@code documentClass} - The {@link Class} type of the documents stored in the collection.
+ * This enables type safety when working with the collection's documents. Must not be null.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * CollectionOptions options = new CollectionOptions()
+ * .timeout(Duration.ofMillis(1000))
+ * .dataAPIClientOptions(new DataAPIClientOptions())
+ * .embeddingAuthProvider(new EmbeddingAPIKeyHeaderProvider("api-key"));
+ * Collection collection = database.getCollection("my_collection", options, MyDocument.class);
+ * }
+ *
+ *
+ * @param collectionName The name of the collection to retrieve.
+ * @param options The {@link CollectionOptions} for customizing the collection behavior.
+ * @param documentClass The class type of the documents in the collection.
+ * @return A {@link Collection} object representing the specified collection.
+ * @throws IllegalArgumentException if {@code collectionName}, {@code options}, or {@code documentClass} is {@code null}.
*/
- public Collection createCollection(String collectionName) {
- return createCollection(collectionName, null, commandOptions, Document.class);
+ public Collection getCollection(String collectionName, CollectionOptions options, Class documentClass) {
+ hasLength(collectionName, "collectionName");
+ notNull(options, "options");
+ notNull(documentClass, "documentClass");
+ return new Collection<>(this, collectionName, options, documentClass);
}
+ // ------------------------------------------
+ // ---- Create Collection ----
+ // ------------------------------------------
+
/**
- * Create a default new collection for vector.
- * @param collectionName
- * collection name
- * @param dimension
- * vector dimension
- * @param metric
- * vector metric
- * @return
- * the instance of collection
+ * Creates a new collection in the database.
+ *
+ * @param The type of the documents stored in the collection.
+ * @param collectionName The name of the collection to be created.
+ * @param collectionDefinition An optional {@link CollectionDefinition} object defining the schema and other properties of the collection.
+ * @param collectionOptions The {@link CollectionOptions} that include token, client configuration, and serializer for the collection.
+ * @param createCollectionOptions Additional options for creating the collection, such as timeouts or retry policies.
+ * @param documentClass The class of the documents stored in the collection.
+ * @return The created collection as a {@link Collection} of the specified document type.
+ *
+ * @throws IllegalArgumentException If any required argument is null or invalid.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = db.createCollection(
+ * "myCollection",
+ * new CollectionDefinition(),
+ * new CollectionOptions(token, dataAPIClientOptions),
+ * new CreateCollectionOptions(),
+ * MyDocument.class
+ * );
+ * }
+ *
*/
- public Collection createCollection(String collectionName, int dimension, SimilarityMetric metric) {
- return createCollection(collectionName, dimension, metric, Document.class);
+ public Collection createCollection(String collectionName,
+ CollectionDefinition collectionDefinition,
+ Class documentClass,
+ CreateCollectionOptions createCollectionOptions,
+ CollectionOptions collectionOptions) {
+
+ hasLength(collectionName, "collectionName");
+ notNull(collectionOptions, "collectionOptions");
+ notNull(documentClass, "documentClass");
+ notNull(collectionOptions.getSerializer(), "serializer");
+
+ Command createCollectionCommand = Command
+ .create("createCollection")
+ .append("name", collectionName);
+ if (collectionDefinition != null) {
+ createCollectionCommand.withOptions(collectionOptions
+ .getSerializer()
+ .convertValue(collectionDefinition, Document.class));
+ }
+ runCommand(createCollectionCommand, createCollectionOptions);
+ return getCollection(collectionName, collectionOptions, documentClass);
}
/**
- * Create a default new collection for vector.
- * @param collectionName
- * collection name
- * @param dimension
- * vector dimension
- * @param metric
- * vector metric
- * @param documentClass
- * class of document to return
- * @param
- * working class for the document
- * @return
- * the instance of collection
+ * Creates a new collection with the default document type {@link Document}.
+ *
+ * @param collectionName The name of the collection to be created.
+ * @return The created collection as a {@link Collection} of {@link Document}.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = db.createCollection("myDefaultCollection");
+ * }
+ *
*/
- public Collection createCollection(String collectionName, int dimension, SimilarityMetric metric, Class documentClass) {
- return createCollection(collectionName, CollectionOptions.builder()
- .vectorDimension(dimension)
- .vectorSimilarity(metric)
- .build(), this.commandOptions, documentClass);
+ public Collection createCollection(String collectionName) {
+ return createCollection(collectionName, Document.class);
}
/**
- * Create a new collection with the given name.
+ * Creates a new collection with the specified document class.
*
- * @param collectionName
- * the name for the new collection to create
- * @param documentClass
- * class of document to return
- * @param
- * working class for the document
- * @return the collection
+ * @param The type of the documents stored in the collection.
+ * @param collectionName The name of the collection to be created.
+ * @param documentClass The class of the documents stored in the collection.
+ * @return The created collection as a {@link Collection} of the specified document type.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = db.createCollection("myTypedCollection", MyDocument.class);
+ * }
+ *
*/
public Collection createCollection(String collectionName, Class documentClass) {
- return createCollection(collectionName, null, this.commandOptions, documentClass);
+ return createCollection(collectionName,
+ // no CollectionDefinition as simple
+ null,
+ documentClass,
+ // No create collection options
+ null,
+ new CollectionOptions(options.getToken(), options.getDataAPIClientOptions())
+ );
}
/**
- * Create a new collection with the given name.
+ * Creates a new collection with a specified definition and the default document type {@link Document}.
+ *
+ * @param name The name of the collection to be created.
+ * @param def The {@link CollectionDefinition} specifying the schema and other properties of the collection.
+ * @return The created collection as a {@link Collection} of {@link Document}.
*
- * @param collectionName
- * the name for the new collection to create
- * @param collectionOptions
- * various options for creating the collection
- * @return the collection
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = createCollection("myDefinedCollection", new CollectionDefinition());
+ * }
+ *
*/
- public Collection createCollection(String collectionName, CollectionOptions collectionOptions) {
- return createCollection(collectionName, collectionOptions, this.commandOptions, Document.class);
+ public Collection createCollection(String name, CollectionDefinition def) {
+ return createCollection(name, def, Document.class);
}
/**
- * Create a new collection with the given name.
+ * Creates a new collection with a specified definition and the specified document class.
*
- * @param collectionName
- * collection name
- * @param collectionOptions
- * collection options
- * @param documentClass
- * document class
- * @return
- * the collection created
- * @param
- * working object for the document
+ * @param The type of the documents stored in the collection.
+ * @param name The name of the collection to be created.
+ * @param def The {@link CollectionDefinition} specifying the schema and other properties of the collection.
+ * @param documentClass The class of the documents stored in the collection.
+ * @return The created collection as a {@link Collection} of the specified document type.
+ *
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = createCollection("myDefinedCollection",
+ * new CollectionDefinition(), MyDocument.class);
+ * }
+ *
*/
- public Collection createCollection(String collectionName, CollectionOptions collectionOptions, Class documentClass) {
- return createCollection(collectionName, collectionOptions, this.commandOptions, documentClass);
+ public Collection createCollection(String name, CollectionDefinition def, Class documentClass) {
+ return createCollection(name,
+ def,
+ documentClass,
+ null,
+ new CollectionOptions(options.getToken(), options.getDataAPIClientOptions()));
}
/**
- * Create a new collection with the given name.
+ * Creates a new collection with a specified definition, options, and the default document type {@link Document}.
+ *
+ * @param collectionName The name of the collection to be created.
+ * @param collectionDefinition The {@link CollectionDefinition} specifying the schema and other properties of the collection.
+ * @param collectionOptions The {@link CollectionOptions} that include token, client configuration, and serializer for the collection.
+ * @param createCollectionOptions Additional options for creating the collection, such as timeouts or retry policies.
+ * @return The created collection as a {@link Collection} of {@link Document}.
*
- * @param collectionName
- * the name for the new collection to create
- * @param collectionOptions
- * various options for creating the collection
- * @param pCommandOptions
- * options to use when using this collection
- * @return the collection
+ * Example usage:
+ *
+ * {@code
+ * Collection collection = createCollection(
+ * "myComplexCollection",
+ * new CollectionDefinition(),
+ * new CollectionOptions(token, dataAPIClientOptions),
+ * new CreateCollectionOptions()
+ * );
+ * }
+ *
*/
- public Collection createCollection(String collectionName, CollectionOptions collectionOptions, CommandOptions pCommandOptions) {
- return createCollection(collectionName, collectionOptions, pCommandOptions, Document.class);
+ public Collection createCollection(String collectionName,
+ CollectionDefinition collectionDefinition,
+ CreateCollectionOptions createCollectionOptions,
+ CollectionOptions collectionOptions
+ ) {
+ return createCollection(
+ collectionName,
+ collectionDefinition,
+ Document.class,
+ createCollectionOptions,
+ collectionOptions);
}
+ // ------------------------------------------
+ // ---- Drop Collection ----
+ // ------------------------------------------
+
/**
- * Create a new collection with the selected options
+ * Deletes a collection from the database.
+ *
+ * @param collectionName The name of the collection to be deleted. Must not be null or empty.
+ * @param dropCollectionOptions Additional options for dropping the collection, such as timeout or retry policies.
*
- * @param collectionName
- * the name for the new collection to create
- * @param collectionOptions
- * various options for creating the collection
- * @param documentClass
- * the default class to cast any documents returned from the database into.
- * @param pCommandOptions
- * options to use when using this collection
- * @param
- * working class for the document
- * @return the collection
+ * Example usage:
+ *
+ * {@code
+ * db.dropCollection("myCollection", new DropCollectionOptions().timeout(Duration.ofMillis(1000)));
+ * }
+ *
*/
- public Collection createCollection(String collectionName, CollectionOptions collectionOptions, CommandOptions pCommandOptions
- , Class documentClass) {
- hasLength(collectionName, "collectionName");
- notNull(documentClass, "documentClass");
- Command createCollection = Command
- .create("createCollection")
- .append("name", collectionName);
- if (collectionOptions != null) {
- createCollection.withOptions(SERIALIZER.convertValue(collectionOptions, Document.class));
- }
- runCommand(createCollection, pCommandOptions);
- log.info("Collection '" + green("{}") + "' has been created", collectionName);
- return getCollection(collectionName, commandOptions, documentClass);
+ public void dropCollection(String collectionName, DropCollectionOptions dropCollectionOptions) {
+ runCommand(Command
+ .create("deleteCollection")
+ .append("name", collectionName), dropCollectionOptions);
}
/**
- * Delete a collection.
+ * Deletes a collection from the database with default options.
+ *
+ * @param collectionName The name of the collection to be deleted. Must not be null or empty.
*
- * @param collectionName
- * collection name
+ * Example usage:
+ *
+ * {@code
+ * dropCollection("myCollection");
+ * }
+ *
*/
public void dropCollection(String collectionName) {
- runCommand(Command
- .create("deleteCollection")
- .append("name", collectionName), this.commandOptions);
- log.info("Collection '" + green("{}") + "' has been deleted", collectionName);
+ dropCollection(collectionName, null);
}
// ------------------------------------------
- // ------- TABLES CRUD -----
+ // ------- List tables -----
// ------------------------------------------
/**
- * Gets the names of all the tables in this database.
+ * Retrieves the names of all tables in the database with default options.
*
- * @return
- * a stream containing all the names of all the collections in this database
+ * @return A list of all table names in the database.
+ *
+ * Example usage:
+ *
+ * {@code
+ * List tableNames = listTableNames();
+ * }
+ *
*/
- public Stream listTableNames() {
- return runCommand(Command.create("listTables"))
- .getStatusKeyAsList("tables", String.class)
- .stream();
+ public List listTableNames() {
+ return listTableNames(null);
}
/**
- * Finds all the tables in this database.
+ * Retrieves the names of all tables in the database.
*
- * @return
- * list of table definitions
+ * @param listTablesOptions Options for filtering or configuring the table listing operation.
+ * @return A list of all table names in the database.
+ *
+ * Example usage:
+ *
+ * {@code
+ * ListTablesOptions options = new ListTablesOptions();
+ * List tableNames = listTableNames(options);
+ * }
+ *
+ */
+ public List listTableNames(ListTablesOptions listTablesOptions) {
+ return runCommand(Command.create("listTables"), listTablesOptions)
+ .getStatusKeyAsStringStream("tables")
+ .toList();
+ }
+
+ /**
+ * Retrieves the details of all tables in the database with default options.
+ *
+ * @return A list of {@link TableDescriptor} objects representing all tables in the database.
+ *
+ * Example usage:
+ *
+ * {@code
+ * List tables = listTables();
+ * }
+ *
+ */
+ public List listTables() {
+ return listTables(null);
+ }
+
+ /**
+ * Retrieves the details of all tables in the database.
+ *
+ * @param listTableOptions Options for filtering or configuring the table listing operation.
+ * @return A list of {@link TableDescriptor} objects representing all tables in the database.
+ *
+ * Example usage:
+ *
+ * {@code
+ * ListTablesOptions options = new ListTablesOptions();
+ * List tables = listTables(options);
+ * }
+ *
*/
- public Stream listTables() {
+ public List listTables(ListTablesOptions listTableOptions) {
Command findTables = Command
.create("listTables")
.withOptions(new Document().append("explain", true));
- return runCommand(findTables)
- .getStatusKeyAsList("tables", TableDescriptor.class)
- .stream();
+ return runCommand(findTables, listTableOptions)
+ .getStatusKeyAsList("tables", TableDescriptor.class);
}
/**
- * Evaluate if a collection exists.
+ * Checks if a table exists in the database by its name.
*
- * @param tableName
- * table name.
- * @return
- * if collections exists
+ * @param tableName The name of the table to check. Must not be null or empty.
+ * @return {@code true} if the table exists, {@code false} otherwise.
+ *
+ * @throws IllegalArgumentException if {@code tableName} is null or empty.
+ *
+ * Example usage:
+ *
+ * {@code
+ * boolean exists = tableExists("myTable");
+ * if (exists) {
+ * System.out.println("The table exists.");
+ * } else {
+ * System.out.println("The table does not exist.");
+ * }
+ * }
+ *
*/
public boolean tableExists(String tableName) {
- return listTableNames().anyMatch(tableName::equals);
+ Assert.hasLength(tableName, "tableName");
+ return listTableNames().contains(tableName);
}
+ // ------------------------------------------
+ // ---- Get Table ----
+ // ------------------------------------------
+
/**
- * Gets a collection.
+ * Retrieves a table representation for the specified table name, table options, and row class type.
+ * This is the primary method to obtain a typed table instance.
*
- * @param tableName
- * the name of the table to return
- * @return
- * the collection
- * @throws IllegalArgumentException
- * if collectionName is invalid
+ * @param the type of the row objects
+ * @param tableName the name of the table (must not be null or empty)
+ * @param tableOptions options used to configure the table (e.g., connection options)
+ * @param rowClass the class representing the type of rows in the table (must not be null)
+ * @return a {@code Table} instance for the specified configuration
+ *
+ * Example usage:
+ *
+ * {@code
+ * Table table = db.getTable("my_table", new TableOptions(...), MyRowType.class);
+ * }
+ *
+ */
+ public Table getTable(String tableName, TableOptions tableOptions, Class rowClass) {
+ hasLength(tableName, "tableName");
+ notNull(rowClass, "rowClass");
+ return new Table<>(this, tableName, tableOptions, rowClass);
+ }
+
+ /**
+ * Retrieves a table representation for the specified table name with default {@code TableOptions}.
+ *
+ * @param tableName the name of the table (must not be null or empty)
+ * @return a {@code Table} instance representing a generic table with {@code Row} type rows
+ * @throws IllegalArgumentException if {@code tableName} is null or empty
+ *
+ * Example usage:
+ *
+ * {@code
+ * Table table = db.getTable("my_table");
+ * }
+ *
*/
public Table getTable(String tableName) {
- return getTable(tableName, this.commandOptions, Row.class);
+ return getTable(tableName, Row.class);
}
/**
- * Gets a table, with a specific default document class.
+ * Retrieves a table representation for the specified table name and row class type with default {@code TableOptions}.
*
- * @param tableName
- * the name of the collection to return
- * @param rowClass
- * the default class to cast any row returned from the database into.
- * @param
- * the type of the class to use instead of {@code Document}.
- * @return
- * the collection
+ * @param the type of the row objects
+ * @param tableName the name of the table (must not be null or empty)
+ * @param rowClass the class representing the type of rows in the table (must not be null)
+ * @return a {@code Table} instance for the specified configuration
+ * @throws IllegalArgumentException if {@code tableName} is null or empty
+ * @throws NullPointerException if {@code rowClass} is null
+ *
+ * Example usage:
+ *
+ * {@code
+ * Table table = myFramework.getTable("my_table", MyRowType.class);
+ * }
+ *
*/
- public Table getTable(String tableName, @NonNull Class rowClass) {
- return getTable(tableName, this.commandOptions, rowClass);
+ public Table getTable(String tableName, Class rowClass) {
+ return getTable(tableName, new TableOptions(
+ options.getToken(),
+ options.getDataAPIClientOptions()), rowClass);
}
- public Table getTable(@NonNull Class rowClass) {
+ /**
+ * Retrieves a table representation for the specified table name and {@code TableOptions}, defaulting to {@code Row} type rows.
+ *
+ * @param tableName the name of the table (must not be null or empty)
+ * @param tableOptions options used to configure the table (e.g., connection options)
+ * @return a {@code Table} instance representing a generic table with {@code Row} type rows
+ * @throws IllegalArgumentException if {@code tableName} is null or empty
+ * @throws NullPointerException if {@code tableOptions} is null
+ *
+ * Example usage:
+ *
+ * {@code
+ * Table table = myFramework.getTable("my_table", new TableOptions(...));
+ * }
+ *
+ */
+ public Table getTable(String tableName, TableOptions tableOptions) {
+ return getTable(tableName, tableOptions, Row.class);
+ }
+
+ /**
+ * Retrieves a table representation for a row class annotated with {@link EntityTable}.
+ * The table name is inferred from the {@code value} attribute of the {@code EntityTable} annotation.
+ *
+ * @param the type of the row objects
+ * @param rowClass the class representing the type of rows in the table (must be annotated with {@link EntityTable})
+ * @return a {@code Table} instance for the inferred table name and row type
+ * @throws InvalidConfigurationException if the provided class is not annotated with {@link EntityTable}
+ *
+ * Example usage:
+ *
+ * {@code
+ * @EntityTable("my_table")
+ * public class MyRowType { ... }
+ *
+ * Table table = myFramework.getTable(MyRowType.class);
+ * }
+ *
+ */
+ public Table getTable(Class rowClass) {
EntityTable ann = rowClass.getAnnotation(EntityTable.class);
if (ann == null) {
InvalidConfigurationException.throwErrorMissingAnnotation(
@@ -545,150 +1130,179 @@ public Table getTable(@NonNull Class rowClass) {
rowClass.getName(),
"getTable(rowClass)");
}
- return getTable(ann.value(), this.commandOptions, rowClass);
+ return getTable(ann.value(), rowClass);
}
+ // -------------------------------------
+ // ---- Create Table ----
+ // -------------------------------------
+
/**
- * Gets a table with a specific default document class.
+ * Creates a table in the system with the specified parameters.
*
- * @param tableName
- * the name of the table to
- * @param rowClass
- * the default class to cast any row returned from the database into.
- * @param commandOptions
- * options to use when using this table
- * @param
- * the type of the class to use instead of {@code Row}.
- * @return
- * the table
+ * @param the type of the row objects that the table will hold
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param tableDefinition the schema definition of the table; must not be null
+ * @param creatTableOptions additional options for creating the table; optional, can be null
+ * @param rowClass the class representing the row type; must not be null
+ * @param tableOptions runtime options for interacting with the table; must not be null
+ * @return the created table object
+ * @throws IllegalArgumentException if any mandatory argument is null or invalid
+ *
+ * Example usage:
+ *
+ * {@code
+ * TableDefinition tableDefinition = new TableDefinition()
+ * .addColumnText("match_id")
+ * .addColumnInt("round")
+ * .addColumnVector("m_vector", new ColumnDefinitionVector().dimension(3).metric(COSINE))
+ * .addColumn("score", ColumnTypes.INT)
+ * .addColumn("when", ColumnTypes.TIMESTAMP)
+ * .addColumn("winner", ColumnTypes.TEXT)
+ * .addColumnSet("fighters", ColumnTypes.UUID)
+ * .addPartitionBy("match_id")
+ * .addPartitionSort(Sort.ascending("round"));
+ *
+ * // Optional
+ * CreateTableOptions createTableOptions =
+ * new CreateTableOptions().timeout(Duration.ofMillis(1000));
+ *
+ * // Optional to override spawn options
+ * TableOptions tableOptions =
+ * new TableOptions().timeout(Duration.ofMillis(1000));
+ *
+ * Table tableSimple2 = db.createTable("TABLE_SIMPLE", tableDefinition,
+ * Row.class, createTableOptions, tableOptions);
+ * }
+ *
*/
- public Table getTable(String tableName, CommandOptions commandOptions, @NonNull Class rowClass) {
+ public Table createTable(String tableName,
+ TableDefinition tableDefinition,
+ Class rowClass,
+ CreateTableOptions creatTableOptions,
+ TableOptions tableOptions) {
hasLength(tableName, "tableName");
+ notNull(tableDefinition, "tableDefinition");
notNull(rowClass, "rowClass");
- return new Table<>(this, tableName, commandOptions, rowClass);
+ Command createTable = Command
+ .create("createTable")
+ .append("name", tableName)
+ .append("definition", tableDefinition);
+ if (creatTableOptions != null) {
+ createTable.append("options", creatTableOptions);
+ }
+ runCommand(createTable, tableOptions);
+ return getTable(tableName, tableOptions, rowClass);
}
/**
- * Create a new table with the given description.
+ * Creates a table using default options and runtime configurations.
*
- * @param tableName
- * the name of the table to create
- * @param tableDefinition
- * table definition
+ * @param the type of the row objects that the table will hold
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param tableDefinition the schema definition of the table; must not be null
+ * @param rowClass the class representing the row type; must not be null
+ * @return the created table object
*/
- public Table createTable(String tableName, TableDefinition tableDefinition) {
- return createTable(tableName, tableDefinition, null, this.commandOptions, Row.class);
+ public Table createTable(String tableName, TableDefinition tableDefinition, Class rowClass) {
+ return createTable(tableName, tableDefinition, rowClass, new CreateTableOptions(),
+ new TableOptions(this.options.getToken(), this.options.getDataAPIClientOptions()));
}
/**
- * Create a new table with the given description.
+ * Creates a table with a default row type of {@code Row}.
*
- * @param tableName
- * the name for the new table to create
- * @param tableDefinition
- * table definition
- * @param options
- * collection options
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param tableDefinition the schema definition of the table; must not be null
+ * @return the created table object with rows of type {@code Row}
*/
- public Table createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions options) {
- return createTable(tableName, tableDefinition, options, commandOptions, Row.class);
+ public Table createTable(String tableName, TableDefinition tableDefinition) {
+ return createTable(tableName, tableDefinition, Row.class);
}
/**
- * Create a new table with the given description.
+ * Creates a table using the specified row class and runtime configurations.
*
- * @param tableName
- * the table name
- * @param tableDefinition
- * table definition
- * @param options
- * collection options
- * @param documentClass
- * document class
- * @return
- * the collection created
- * @param
- * working object for the document
+ * @param the type of the row objects that the table will hold
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param rowClass the class representing the row type; must not be null
+ * @param tableDefinition the schema definition of the table; must not be null
+ * @param createTableOptions additional options for creating the table; optional, can be null
+ * @return the created table object
*/
- public Table createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions options, Class documentClass) {
- return createTable(tableName, tableDefinition, options, commandOptions, documentClass);
+ public Table createTable(String tableName, TableDefinition tableDefinition, Class rowClass, CreateTableOptions createTableOptions) {
+ return createTable(tableName, tableDefinition, rowClass, createTableOptions,
+ new TableOptions(this.options.getToken(), this.options.getDataAPIClientOptions()));
}
/**
- * Create a new collection with the given name.
+ * Creates a table using the specified row class and runtime configurations.
*
- * @param tableName
- * the definition for the new table to create
- * @param tableDefinition
- * the definition for the new table to create
- * @param tableOptions
- * various options for creating the table
- * @param commandOptions
- * options to use when using this collection
- * @return the collection
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param createTableOptions additional options for creating the table; optional, can be null
+ * @param tableDefinition the schema definition of the table; must not be null
+ * @return the created table object
*/
- public Table createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions tableOptions, CommandOptions commandOptions) {
- return createTable(tableName, tableDefinition, tableOptions, commandOptions, Row.class);
+ public Table createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions createTableOptions) {
+ return createTable(tableName, tableDefinition, Row.class, createTableOptions);
}
+ /**
+ * Creates a table using default options and the inferred table name from the row class.
+ *
+ * @param the type of the row objects that the table will hold
+ * @param rowClass the class representing the row type; must not be null
+ * @return the created table object
+ */
public Table createTable(Class rowClass) {
- return createTable(getTableName(rowClass), rowClass);
- }
-
- public Table createTable(@NonNull Class rowClass, CreateTableOptions tableOptions) {
- return createTable(getTableName(rowClass), rowClass, tableOptions);
+ return createTable(rowClass, new CreateTableOptions());
}
- public Table createTable(String tableName, @NonNull Class rowClass) {
- return createTable(tableName, rowClass, null);
+ /**
+ * Creates a table using default options and the inferred table name from the row class.
+ *
+ * @param the type of the row objects that the table will hold
+ * @param rowClass the class representing the row type; must not be null
+ * @param createTableOptions additional options for creating the table; optional, can be null
+ * @return the created table object
+ */
+ public Table createTable(Class rowClass, CreateTableOptions createTableOptions) {
+ return createTable(getTableName(rowClass), rowClass, createTableOptions, new TableOptions());
}
- public Table createTable(String tableName, @NonNull Class rowClass, CreateTableOptions tableOptions) {
+ /**
+ * Creates a table using default options and runtime configurations.
+ *
+ * @param the type of the row objects that the table will hold
+ * @param rowClass the class representing the row type; must not be null
+ * @param tableName the name of the table to be created; must not be null or empty
+ * @param tableOptions runtime options for interacting with the table; must not be null
+ * @param createTableOptions additional options for creating the table; optional, can be null
+ * @return the created table object
+ */
+ public Table createTable(String tableName,
+ Class rowClass,
+ CreateTableOptions createTableOptions,
+ TableOptions tableOptions) {
hasLength(tableName, "tableName");
notNull(rowClass, "rowClass");
+ // FIX ME INVESTIGATING TO CREATE A TABLE DEFINITION OBJECT
Command createTable = new Command("createTable", createTableCommand(tableName, rowClass));
- if (tableOptions != null) {
- createTable.append("options", tableOptions);
+ if (createTableOptions != null) {
+ createTable.append("options", createTableOptions);
}
- runCommand(createTable, commandOptions);
- log.info("Table '" + green("{}") + "' has been created", tableName);
- return getTable(tableName, commandOptions, rowClass);
+ runCommand(createTable, createTableOptions);
+ return getTable(tableName, tableOptions, rowClass);
}
/**
- * Create a new table with the selected options
+ * Creates a table using default options and runtime configurations.
*
- * @param tableName
- * the definition for the new table to create
- * @param tableDefinition
- * the definition for the new table to create
- * @param tableOptions
- * various options for creating the table
- * @param rowClass
- * the default class to cast any row returned from the database into.
- * @param commandOptions
- * options to use when using this collection
- * @param
- * working class for the document
- * @return the collection
- */
- public Table createTable(String tableName, TableDefinition tableDefinition, CreateTableOptions tableOptions, CommandOptions commandOptions, Class rowClass) {
- hasLength(tableName, "tableName");
- notNull(tableDefinition, "tableDefinition");
- notNull(rowClass, "rowClass");
- Command createTable = Command
- .create("createTable")
- .append("name", tableName)
- .append("definition", tableDefinition);
- if (tableOptions != null) {
- createTable.append("options", tableOptions);
- }
- runCommand(createTable, commandOptions);
- log.info("Table '" + green("{}") + "' has been created", tableName);
- return getTable(tableName, commandOptions, rowClass);
- }
-
- private String getTableName(Class rowClass) {
+ * @param the type of the row objects that the table will hold
+ * @param rowClass the class representing the row type; must not be null
+ * @return the created table object
+ */
+ public String getTableName(Class rowClass) {
notNull(rowClass, "rowClass");
EntityTable ann = rowClass.getAnnotation(EntityTable.class);
if (ann == null) {
@@ -700,21 +1314,48 @@ private String getTableName(Class rowClass) {
return ann.value();
}
+ // -------------------------------------
+ // ---- Drop Table ----
+ // -------------------------------------
+
/**
- * Delete a collection.
+ * Deletes a collection (table) from the database.
+ * This method delegates to {@link #dropTable(String, DropTableOptions)}
+ * with default options.
*
* @param tableName
- * table name
+ * the name of the table to be deleted; must not be null or empty.
+ * @throws IllegalArgumentException
+ * if {@code tableName} is null or empty.
+ *
+ * Example usage:
+ *
+ * {@code
+ * database.dropTable("exampleTable");
+ * }
+ *
*/
public void dropTable(String tableName) {
dropTable(tableName, null);
}
/**
- * Delete a collection.
+ * Deletes a collection (table) from the database with specific options.
*
* @param tableName
- * table name
+ * the name of the table to be deleted; must not be null or empty.
+ * @param dropTableOptions
+ * the options to configure the table deletion operation; can be null.
+ * @throws IllegalArgumentException
+ * if {@code tableName} is null or empty.
+ *
+ * Example usage:
+ *
+ * {@code
+ * DropTableOptions options = new DropTableOptions();
+ * database.dropTable("exampleTable", options);
+ * }
+ *
*/
public void dropTable(String tableName, DropTableOptions dropTableOptions) {
hasLength(tableName, "tableName");
@@ -724,41 +1365,12 @@ public void dropTable(String tableName, DropTableOptions dropTableOptions) {
if (dropTableOptions != null) {
dropTableCmd.withOptions(dropTableOptions);
}
- runCommand(dropTableCmd, commandOptions);
- log.info("Table '" + green("{}") + "' has been deleted", tableName);
+ runCommand(dropTableCmd, dropTableOptions);
}
-
// ------------------------------------------
- // ---- Indexes CRUD ---
+ // ---- Drop Indexes ---
// ------------------------------------------
- /**
- * Gets the names of indices in the selected keyspace.
- *
- * @return
- * a stream containing all the names of all the collections in this database
- */
- public Stream listIndexesNames() {
- return runCommand(Command.create("listIndexes"))
- .getStatusKeyAsList("indexes", String.class)
- .stream();
- }
-
- /**
- * Finds all the indices in the selected keyspace.
- *
- * @return
- * list of table definitions
- */
- public Stream listIndexes() {
- Command findTables = Command
- .create("listIndexes")
- .withOptions(new Document().append("explain", true));
- return runCommand(findTables)
- .getStatusKeyAsList("indexes", IndexDescriptor.class)
- .stream();
- }
-
/**
* Delete an index by name.
*
@@ -778,69 +1390,23 @@ public void dropTableIndex(String indexName) {
* flag to drop index
*/
public void dropTableIndex(String indexName, DropTableIndexOptions dropIndexOptions) {
- Command dropIndexCommand = Command.create("dropIndex").append("name", indexName);
+ Command dropIndexCommand = Command
+ .create("dropIndex")
+ .append("name", indexName);
if (dropIndexOptions != null) {
dropIndexCommand.withOptions(dropIndexOptions);
}
- runCommand(dropIndexCommand, commandOptions);
- log.info("Index '" + green("{}") + "' has been dropped", indexName);
+ runCommand(dropIndexCommand, dropIndexOptions);
}
// ------------------------------------------
// ---- Generation Information ----
// ------------------------------------------
- /** {@inheritDoc} */
- @Override
- protected DataAPISerializer getSerializer() {
- return SERIALIZER;
- }
-
/** {@inheritDoc} */
@Override
public String getApiEndpoint() {
- StringBuilder dbApiEndPointBuilder = new StringBuilder(dbApiEndpoint);
- // Adding /api/json if needed for Astra.
- switch(options.getDestination()) {
- case ASTRA:
- case ASTRA_TEST:
- case ASTRA_DEV:
- if (dbApiEndpoint.endsWith(".com")) {
- dbApiEndPointBuilder.append("/api/json");
- }
- break;
- default:
- // left blank as local deployments does not require any change
- break;
- }
- return dbApiEndPointBuilder
- .append("/")
- .append(options.getApiVersion())
- .append("/")
- .append(keyspaceName)
- .toString();
- }
-
- /**
- * Register a listener to execute commands on the collection. Please now use {@link CommandOptions}.
- *
- * @param logger
- * name for the logger
- * @param commandObserver
- * class for the logger
- */
- public void registerListener(String logger, CommandObserver commandObserver) {
- this.commandOptions.registerObserver(logger, commandObserver);
- }
-
- /**
- * Register a listener to execute commands on the collection. Please now use {@link CommandOptions}.
- *
- * @param name
- * name for the observer
- */
- public void deleteListener(String name) {
- this.commandOptions.unregisterObserver(name);
+ return this.apiEndpoint;
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseInfo.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseInfo.java
index 636e45b6..60b813b5 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseInfo.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseInfo.java
@@ -24,6 +24,7 @@
import com.dtsx.astra.sdk.db.domain.CloudProviderType;
import com.dtsx.astra.sdk.db.domain.Database;
import com.dtsx.astra.sdk.db.domain.Datacenter;
+import com.dtsx.astra.sdk.utils.AstraEnvironment;
import lombok.Getter;
import lombok.Setter;
@@ -44,25 +45,19 @@ public class DatabaseInfo {
private String name;
/** cloud provider. */
- private CloudProviderType cloud;
+ private CloudProviderType cloudProvider;
- /** Main Region for the database. */
- private String region;
-
- /** Default namespace for the database. */
- @Deprecated
- private String namespace;
+ /** Astra Environment. */
+ private AstraEnvironment environment;
/** Default keyspace for the database. */
- @Deprecated
private String keyspace;
- /** List of Namespace for the db. */
- @Deprecated
- private String namespaceList;
-
private String keyspaceList;
+ /** Main Region for the database. */
+ private String region;
+
/** List of regions where the database is deployed. */
private Set regionList;
@@ -82,18 +77,20 @@ public class DatabaseInfo {
public DatabaseInfo(Database db) {
Assert.notNull(db, "Database");
this.rawDevopsResponse = db;
- this.id = UUID.fromString(db.getId());
- this.name = db.getInfo().getName();
- this.keyspace = db.getInfo().getKeyspace();
- this.region = db.getInfo().getRegion();
- this.cloud = db.getInfo().getCloudProvider();
+ this.id = UUID.fromString(db.getId());
+ this.name = db.getInfo().getName();
+ this.keyspace = db.getInfo().getKeyspace();
+ this.region = db.getInfo().getRegion();
+ this.cloudProvider = db.getInfo().getCloudProvider();
+
+ // FIX ME
+ //this.status;
+ //this.environment = db.getInfo().g
+
this.creationTime = db.getCreationTime();
- this.regionList = db.getInfo().getDatacenters().stream()
+ this.regionList = db.getInfo().getDatacenters().stream()
.map(Datacenter::getRegion).collect(Collectors.toSet());
this.keyspaceList = String.join(",", db.getInfo().getKeyspaces());
-
- this.namespace = keyspace;
- this.namespaceList = keyspaceList;
}
}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseOptions.java
new file mode 100644
index 00000000..d89707fe
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/DatabaseOptions.java
@@ -0,0 +1,110 @@
+package com.datastax.astra.client.databases;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+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.DataAPISerializer;
+import com.datastax.astra.internal.serdes.DatabaseSerializer;
+import com.datastax.astra.internal.utils.Assert;
+import lombok.Setter;
+import lombok.experimental.Accessors;
+
+/**
+ * Represents the configuration options required to connect to a database. This class encapsulates
+ * various settings, such as authentication details, API version, and keyspace configuration,
+ * enabling flexible and customized database connections.
+ *
+ * If not explicitly provided, default options will be used. This ensures ease of use for
+ * developers while still allowing fine-grained control over the connection configuration when needed.
+ *
+ * This class is annotated with {@code @Setter} and {@code @Accessors(fluent = true, chain = true)},
+ * enabling a fluent, chainable API for setting properties.
+ *
+ * Key Features:
+ *
+ * - Fluent setters for convenient configuration of options.
+ * - Support for default configurations when options are not specified.
+ * - Encapsulation of essential parameters such as keyspace, API version, and authentication token.
+ *
+ *
+ * Example usage:
+ *
+ * {@code
+ * // Create a DatabaseOptions object with custom settings
+ * DatabaseOptions options = new DatabaseOptions()
+ * .keyspace("my_keyspace")
+ * .authToken("my_auth_token")
+ * .apiVersion("v2")
+ * .logRequests(true);
+ *
+ * // Use the options when initializing a Database instance
+ * Database database = new Database("https://my-endpoint.com", options);
+ * }
+ *
+ */
+@Setter
+@Accessors(fluent = true, chain = true)
+public class DatabaseOptions extends BaseOptions implements Cloneable {
+
+ /** Serializer for the Collections. */
+ private static final DataAPISerializer DEFAULT_SERIALIZER = new DatabaseSerializer();
+
+ /**
+ * The keyspace to use for the database.
+ */
+ String keyspace = DataAPIClientOptions.DEFAULT_KEYSPACE;
+
+ /**
+ * Default constructor.
+ */
+ public DatabaseOptions() {
+ this(null, null);
+ }
+
+ /**
+ * Constructor with options and not token override.
+ *
+ * @param options
+ * data API client options
+ */
+ public DatabaseOptions(String token, DataAPIClientOptions options) {
+ super(token, CommandType.KEYSPACE_ADMIN, DEFAULT_SERIALIZER, options);
+ }
+
+ /**
+ * Gets keyspace
+ *
+ * @return value of keyspace
+ */
+ public String getKeyspace() {
+ return keyspace;
+ }
+
+ @Override
+ public DatabaseOptions clone() {
+ // Cloning options, token, and serializer
+ DatabaseOptions cloned = (DatabaseOptions) super.clone();
+ cloned.keyspace = keyspace;
+ return cloned;
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/CreateCollectionOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/CreateCollectionOptions.java
new file mode 100644
index 00000000..9582ece9
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/CreateCollectionOptions.java
@@ -0,0 +1,32 @@
+package com.datastax.astra.client.databases.options;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.commands.BaseOptions;
+
+import static com.datastax.astra.client.core.commands.CommandType.COLLECTION_ADMIN;
+
+public class CreateCollectionOptions extends BaseOptions {
+
+ public CreateCollectionOptions() {
+ super(null, COLLECTION_ADMIN, null);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/DropCollectionOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/DropCollectionOptions.java
new file mode 100644
index 00000000..1f0cd7e2
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/DropCollectionOptions.java
@@ -0,0 +1,33 @@
+package com.datastax.astra.client.databases.options;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.commands.BaseOptions;
+
+import static com.datastax.astra.client.collections.Collection.DEFAULT_COLLECTION_SERIALIZER;
+import static com.datastax.astra.client.core.commands.CommandType.COLLECTION_ADMIN;
+
+public class DropCollectionOptions extends BaseOptions {
+
+ public DropCollectionOptions() {
+ super(null, COLLECTION_ADMIN, DEFAULT_COLLECTION_SERIALIZER, null);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListCollectionOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListCollectionOptions.java
new file mode 100644
index 00000000..8bdf26b8
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListCollectionOptions.java
@@ -0,0 +1,34 @@
+package com.datastax.astra.client.databases.options;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.commands.BaseOptions;
+import com.datastax.astra.internal.serdes.collections.DocumentSerializer;
+import com.datastax.astra.internal.serdes.tables.RowSerializer;
+
+import static com.datastax.astra.client.core.commands.CommandType.COLLECTION_ADMIN;
+
+public class ListCollectionOptions extends BaseOptions {
+
+ public ListCollectionOptions() {
+ super(null, COLLECTION_ADMIN, new DocumentSerializer(), null);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListIndexesOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListIndexesOptions.java
new file mode 100644
index 00000000..fc0edd93
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListIndexesOptions.java
@@ -0,0 +1,33 @@
+package com.datastax.astra.client.databases.options;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.commands.BaseOptions;
+import com.datastax.astra.internal.serdes.tables.RowSerializer;
+
+import static com.datastax.astra.client.core.commands.CommandType.TABLE_ADMIN;
+
+public class ListIndexesOptions extends BaseOptions {
+
+ public ListIndexesOptions() {
+ super(null, TABLE_ADMIN, new RowSerializer(), null);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListTablesOptions.java b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListTablesOptions.java
new file mode 100644
index 00000000..ba4b0d76
--- /dev/null
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/databases/options/ListTablesOptions.java
@@ -0,0 +1,34 @@
+package com.datastax.astra.client.databases.options;
+
+/*-
+ * #%L
+ * Data API Java Client
+ * --
+ * Copyright (C) 2024 DataStax
+ * --
+ * Licensed under the Apache License, Version 2.0
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.datastax.astra.client.core.commands.BaseOptions;
+import com.datastax.astra.internal.serdes.tables.RowSerializer;
+
+import static com.datastax.astra.client.core.commands.CommandType.COLLECTION_ADMIN;
+import static com.datastax.astra.client.core.commands.CommandType.TABLE_ADMIN;
+
+public class ListTablesOptions extends BaseOptions {
+
+ public ListTablesOptions() {
+ super(null, TABLE_ADMIN, new RowSerializer(), null);
+ }
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/exception/DataAPIErrorDescriptor.java b/astra-db-java/src/main/java/com/datastax/astra/client/exception/DataAPIErrorDescriptor.java
index 7e832d30..d22c8b59 100644
--- a/astra-db-java/src/main/java/com/datastax/astra/client/exception/DataAPIErrorDescriptor.java
+++ b/astra-db-java/src/main/java/com/datastax/astra/client/exception/DataAPIErrorDescriptor.java
@@ -20,6 +20,8 @@
* #L%
*/
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import lombok.Getter;
import lombok.Setter;
@@ -30,6 +32,7 @@
*/
@Getter
@Setter
+@JsonIgnoreProperties({"stackTrace", "suppressed", "cause", "localizedMessage"})
public class DataAPIErrorDescriptor extends RuntimeException {
/**
@@ -77,6 +80,7 @@ public DataAPIErrorDescriptor() {
* @return A concatenated string representing the full error message, which may include the exception class name,
* the error code in parentheses, and the detailed error message. Each element is included only if it is not {@code null}.
*/
+ @JsonIgnore
public String getErrorMessage() {
StringBuilder sb = new StringBuilder();
if (exceptionClass != null) {
@@ -90,4 +94,11 @@ public String getErrorMessage() {
}
return sb.toString().trim();
}
+
+ @Override
+ @JsonIgnore
+ public String getLocalizedMessage() {
+ return super.getLocalizedMessage();
+ }
+
}
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
index 0bec2789..03b46b6c 100644
--- 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
@@ -20,17 +20,20 @@
* #L%
*/
+import com.datastax.astra.client.collections.CollectionDefinition;
import com.datastax.astra.client.collections.options.CollectionFindOptions;
import com.datastax.astra.client.collections.documents.Document;
import com.datastax.astra.client.core.commands.Command;
-import com.datastax.astra.client.core.commands.CommandOptions;
+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.paging.TableCursor;
import com.datastax.astra.client.core.paging.Page;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.databases.Database;
+import com.datastax.astra.client.databases.options.ListIndexesOptions;
import com.datastax.astra.client.exception.DataAPIException;
+import com.datastax.astra.client.tables.index.TableIndexDescriptor;
import com.datastax.astra.client.tables.options.CountRowsOptions;
import com.datastax.astra.client.tables.options.EstimatedCountRowsOptions;
import com.datastax.astra.client.tables.options.TableDeleteManyOptions;
@@ -47,8 +50,8 @@
import com.datastax.astra.client.tables.ddl.CreateIndexOptions;
import com.datastax.astra.client.tables.ddl.CreateVectorIndexOptions;
import com.datastax.astra.client.tables.exceptions.TooManyRowsToCountException;
-import com.datastax.astra.client.tables.index.IndexDefinition;
-import com.datastax.astra.client.tables.index.VectorIndexDefinition;
+import com.datastax.astra.client.tables.index.TableIndexDefinition;
+import com.datastax.astra.client.tables.index.TableVectorIndexDefinition;
import com.datastax.astra.client.tables.mapping.EntityBeanDefinition;
import com.datastax.astra.client.tables.mapping.EntityTable;
import com.datastax.astra.client.tables.results.TableUpdateResult;
@@ -80,6 +83,8 @@
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;
+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;
@@ -94,18 +99,10 @@
* Execute commands against tables
*/
@Slf4j
-public class Table extends AbstractCommandRunner {
+public class Table