Update JavaDocs

Author: clun

pom.xml

@@ -89,7 +89,7 @@
             <groupId>com.fasterxml.jackson</groupId>
             <artifactId>jackson-bom</artifactId>
             <version>${jackson.version}</version>
-            <scope>import</scope>
+            <scope>runtime</scope>
             <type>pom</type>
         </dependency>
         <dependency>

src/main/java/com/datastax/astra/client/Collection.java

@@ -20,12 +20,13 @@
  * #L%
  */
 
+import com.datastax.astra.client.DataAPIOptions;
 import com.datastax.astra.client.exception.DataApiException;
 import com.datastax.astra.client.exception.DataApiFaultyResponseException;
 import com.datastax.astra.client.exception.TooManyDocumentsToCountException;
 import com.datastax.astra.client.model.Command;
 import com.datastax.astra.client.model.Document;
-import com.datastax.astra.client.model.api.ApiResponse;
+import com.datastax.astra.client.internal.ApiResponse;
 import com.datastax.astra.client.model.collections.CollectionDefinition;
 import com.datastax.astra.client.model.collections.CollectionOptions;
 import com.datastax.astra.client.model.delete.DeleteOneOptions;
@@ -50,10 +51,10 @@
 import com.datastax.astra.client.model.update.Update;
 import com.datastax.astra.client.model.update.UpdateOneOptions;
 import com.datastax.astra.client.model.update.UpdateResult;
-import com.datastax.astra.internal.AbstractCommandRunner;
-import com.datastax.astra.internal.http.HttpClientOptions;
-import com.datastax.astra.internal.utils.Assert;
-import com.datastax.astra.internal.utils.JsonUtils;
+import com.datastax.astra.client.internal.AbstractCommandRunner;
+import com.datastax.astra.client.internal.http.HttpClientOptions;
+import com.datastax.astra.client.internal.utils.Assert;
+import com.datastax.astra.client.internal.utils.JsonUtils;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 
@@ -70,12 +71,12 @@
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.stream.Collectors;
 
-import static com.datastax.astra.internal.utils.AnsiUtils.cyan;
-import static com.datastax.astra.internal.utils.AnsiUtils.green;
-import static com.datastax.astra.internal.utils.AnsiUtils.magenta;
-import static com.datastax.astra.internal.utils.AnsiUtils.yellow;
-import static com.datastax.astra.internal.utils.Assert.hasLength;
-import static com.datastax.astra.internal.utils.Assert.notNull;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.cyan;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.green;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.magenta;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.yellow;
+import static com.datastax.astra.client.internal.utils.Assert.hasLength;
+import static com.datastax.astra.client.internal.utils.Assert.notNull;
 
 /**
  * A Data API collection, the main object to interact with the Data API, especially for DDL operations.
@@ -86,7 +87,7 @@
  * options to specialize the usage as vector collections or advanced indexing parameters.
  * </p>
  * <p>
- * A Collection is typed object designed to work both with default @{@link com.datastax.astra.client.model.Document} (wrapper for a Map) and application
+ * A Collection is typed object designed to work both with default @{@link Document} (wrapper for a Map) and application
  * plain old java objects (pojo). The serialization is performed with Jackson and application beans can be annotated.
  * </p>
  * <p>Example usage:</p>
@@ -220,7 +221,7 @@ public CollectionOptions getOptions() {
      * Retrieves the class type of the POJO (Plain Old Java Object) used for unmarshalling documents
      * within the collection. This class type is crucial for converting the raw data from the collection
      * into more manageable, object-oriented representations. By default, this method returns the
-     * {@link com.datastax.astra.client.model.Document} class, which serves as the standard container
+     * {@link Document} class, which serves as the standard container
      * for document data. Custom implementations can override this default to utilize a different POJO
      * that better suits their data structure and requirements.
      *
@@ -664,8 +665,8 @@ public <FIELD> DistinctIterable<DOC, FIELD> distinct(String fieldName, Filter fi
      *
      * <p>
      * Takes in a `upperBound` option which dictates the maximum number of documents that may be present before a
-     * {@link com.datastax.astra.client.exception.TooManyDocumentsToCountException} is thrown. If the limit is higher than the highest limit accepted by the
-     * Data API, a {@link com.datastax.astra.client.exception.TooManyDocumentsToCountException} will be thrown anyway (i.e. `1000`).
+     * {@link TooManyDocumentsToCountException} is thrown. If the limit is higher than the highest limit accepted by the
+     * Data API, a {@link TooManyDocumentsToCountException} will be thrown anyway (i.e. `1000`).
      * </p>
      * <p>
      * Count operations are expensive: for this reason, the best practice is to provide a reasonable `upperBound`
@@ -679,7 +680,7 @@ public <FIELD> DistinctIterable<DOC, FIELD> distinct(String fieldName, Filter fi
      *      The maximum number of documents to count.
      * @return
      *      The number of documents in the collection.
-     * @throws com.datastax.astra.client.exception.TooManyDocumentsToCountException
+     * @throws TooManyDocumentsToCountException
      *      If the number of documents counted exceeds the provided limit.
      */
     public int countDocuments(int upperBound) throws TooManyDocumentsToCountException {

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

@@ -20,14 +20,15 @@
  * #L%
  */
 
-import com.datastax.astra.internal.astra.AstraApiEndpoint;
-import com.datastax.astra.internal.utils.Assert;
+import com.datastax.astra.client.admin.AstraDBAdmin;
+import com.datastax.astra.client.internal.AstraApiEndpoint;
+import com.datastax.astra.client.internal.utils.Assert;
 import com.dtsx.astra.sdk.utils.AstraEnvironment;
 
 import java.util.Optional;
 import java.util.UUID;
 
-import static com.datastax.astra.client.AstraDBAdmin.DEFAULT_NAMESPACE;
+import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_NAMESPACE;
 
 /**
  * Entry point to access the Data API.

src/main/java/com/datastax/astra/client/DataAPIClients.java

@@ -20,11 +20,11 @@
  * #L%
  */
 
-import com.datastax.astra.client.observer.LoggingCommandObserver;
-import com.datastax.astra.internal.DataAPIDatabaseAdmin;
-import com.datastax.astra.internal.auth.StargateAuthenticationService;
+import com.datastax.astra.client.internal.observer.LoggingCommandObserver;
+import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
+import com.datastax.astra.client.internal.auth.StargateAuthenticationService;
 
-import static com.datastax.astra.client.AstraDBAdmin.DEFAULT_NAMESPACE;
+import static com.datastax.astra.client.admin.AstraDBAdmin.DEFAULT_NAMESPACE;
 
 /**
  * Initialization of the client in a Static way.
@@ -48,7 +48,7 @@ private DataAPIClients() {}
     public static DataAPIClient localClient() {
         return new DataAPIClient(
                 new StargateAuthenticationService().getToken(),
-                DataAPIOptions.builder().withDestination(DataAPIDestination.CASSANDRA).build());
+                DataAPIOptions.builder().withDestination(DataAPIOptions.DataAPIDestination.CASSANDRA).build());
     }
 
     /**
@@ -78,7 +78,7 @@ public static Database localDatabase() {
     public static DataAPIClient astra(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
-                .withDestination(DataAPIDestination.ASTRA)
+                .withDestination(DataAPIOptions.DataAPIDestination.ASTRA)
                 .build());
     }
 
@@ -93,7 +93,7 @@ public static DataAPIClient astra(String token) {
     public static DataAPIClient astraDev(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
-                .withDestination(DataAPIDestination.ASTRA_DEV)
+                .withDestination(DataAPIOptions.DataAPIDestination.ASTRA_DEV)
                 .build());
     }
 
@@ -108,7 +108,7 @@ public static DataAPIClient astraDev(String token) {
     public static DataAPIClient astraTest(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
-                .withDestination(DataAPIDestination.ASTRA_TEST)
+                .withDestination(DataAPIOptions.DataAPIDestination.ASTRA_TEST)
                 .build());
     }
 

src/main/java/com/datastax/astra/client/DataAPIDestination.java

@@ -20,8 +20,8 @@
  * #L%
  */
 
-import com.datastax.astra.internal.http.HttpClientOptions;
-import com.datastax.astra.internal.utils.Assert;
+import com.datastax.astra.client.internal.http.HttpClientOptions;
+import com.datastax.astra.client.internal.utils.Assert;
 import lombok.Getter;
 
 import java.net.http.HttpClient;
@@ -106,6 +106,42 @@ private DataAPIOptions(DataAPIClientOptionsBuilder builder) {
         this.httpClientOptions = httpClientOptions;
     }
 
+    /**
+     * Represent the destination of the data API.
+     */
+    public enum DataAPIDestination {
+
+        /**
+         * Astra Production environment
+         */
+        ASTRA,
+
+        /**
+         * Astra Development environment
+         */
+        ASTRA_DEV,
+
+        /**
+         * Astra Test environment
+         */
+        ASTRA_TEST,
+
+        /**
+         * Local installation of Datastax Enterprise
+         */
+        DSE,
+
+        /**
+         * Local installation of Apache Cassandra
+         */
+        CASSANDRA,
+
+        /**
+         * Extra local installation .
+         */
+        OTHERS
+    }
+
     /**
      * Builder for the DataAPIClientOptions.
      */

src/main/java/com/datastax/astra/client/DataAPIOptions.java

@@ -20,27 +20,30 @@
  * #L%
  */
 
+import com.datastax.astra.client.DataAPIOptions.DataAPIDestination;
+import com.datastax.astra.client.admin.AstraDBAdmin;
+import com.datastax.astra.client.admin.DatabaseAdmin;
 import com.datastax.astra.client.model.Command;
 import com.datastax.astra.client.model.Document;
 import com.datastax.astra.client.model.collections.CollectionDefinition;
 import com.datastax.astra.client.model.collections.CollectionOptions;
 import com.datastax.astra.client.model.find.SimilarityMetric;
-import com.datastax.astra.internal.AbstractCommandRunner;
-import com.datastax.astra.internal.DataAPIDatabaseAdmin;
-import com.datastax.astra.internal.astra.AstraApiEndpoint;
-import com.datastax.astra.internal.AstraDBDatabaseAdmin;
-import com.datastax.astra.internal.http.HttpClientOptions;
-import com.datastax.astra.internal.utils.JsonUtils;
+import com.datastax.astra.client.internal.AbstractCommandRunner;
+import com.datastax.astra.client.admin.DataAPIDatabaseAdmin;
+import com.datastax.astra.client.internal.AstraApiEndpoint;
+import com.datastax.astra.client.admin.AstraDBDatabaseAdmin;
+import com.datastax.astra.client.internal.http.HttpClientOptions;
+import com.datastax.astra.client.internal.utils.JsonUtils;
 import lombok.Getter;
 import lombok.NonNull;
 import lombok.extern.slf4j.Slf4j;
 
 import java.util.Objects;
 import java.util.stream.Stream;
 
-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;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.green;
+import static com.datastax.astra.client.internal.utils.Assert.hasLength;
+import static com.datastax.astra.client.internal.utils.Assert.notNull;
 
 /**
  * Class to interact with a Namespace.

src/main/java/com/datastax/astra/client/Database.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.client;
+package com.datastax.astra.client.admin;
 
 /*-
  * #%L
@@ -19,10 +19,9 @@
  * limitations under the License.
  * #L%
  */
-
-import com.datastax.astra.internal.astra.AstraApiEndpoint;
-import com.datastax.astra.internal.AstraDBDatabaseAdmin;
-import com.datastax.astra.internal.utils.Assert;
+import com.datastax.astra.client.DataAPIOptions;
+import com.datastax.astra.client.internal.AstraApiEndpoint;
+import com.datastax.astra.client.internal.utils.Assert;
 import com.dtsx.astra.sdk.db.AstraDBOpsClient;
 import com.dtsx.astra.sdk.db.DbOpsClient;
 import com.dtsx.astra.sdk.db.domain.CloudProviderType;
@@ -48,7 +47,7 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-import static com.datastax.astra.internal.utils.AnsiUtils.green;
+import static com.datastax.astra.client.internal.utils.AnsiUtils.green;
 import static com.dtsx.astra.sdk.utils.Utils.readEnvVariable;
 
 /**
@@ -108,7 +107,7 @@ public class AstraDBAdmin {
      * @param env
      *      astra environment
      */
-    AstraDBAdmin(String token, AstraEnvironment env, DataAPIOptions options) {
+    public AstraDBAdmin(String token, AstraEnvironment env, DataAPIOptions options) {
         Assert.hasLength(token, "token");
         Assert.notNull(env, "environment");
         Assert.notNull(options, "options");
@@ -294,7 +293,7 @@ public boolean dropDatabase(@NonNull UUID databaseId) {
      */
     public boolean dropDatabase(@NonNull String databaseName) {
         Assert.hasLength(databaseName, "database");
-        com.datastax.astra.internal.utils.Assert.hasLength(databaseName, "Database ");
+        Assert.hasLength(databaseName, "Database ");
         Optional<Database> db = listDatabases().filter(d -> d.getInfo().getName().equals(databaseName)).findFirst();
         if (db.isPresent()) {
             devopsDbClient.database(db.get().getId()).delete();

src/main/java/com/datastax/astra/client/AstraDBAdmin.java renamed to src/main/java/com/datastax/astra/client/admin/AstraDBAdmin.java

@@ -1,4 +1,4 @@
-package com.datastax.astra.internal;
+package com.datastax.astra.client.admin;
 
 /*-
  * #%L
@@ -21,8 +21,7 @@
  */
 
 import com.datastax.astra.client.DataAPIOptions;
-import com.datastax.astra.client.DatabaseAdmin;
-import com.datastax.astra.internal.astra.AstraApiEndpoint;
+import com.datastax.astra.client.internal.AstraApiEndpoint;
 import com.dtsx.astra.sdk.db.AstraDBOpsClient;
 import com.dtsx.astra.sdk.db.domain.Database;
 import com.dtsx.astra.sdk.db.exception.DatabaseNotFoundException;