Update doc

Author: clun

README.MD

@@ -3,5 +3,115 @@
 
 `astra-db-java` is the java libraries use to interact with Astra, the Data API with vector support.
 
-- `astra-db-ts` is the equivalent in typescript
-- `astrapy` is the equivalent in python
+- `astra-db-ts` is the equivalent for typescript
+- `astrapy` is the equivalent in python
+
+This library is under development and not yet available in Maven Central. You can build it locally and install it in your local repository.
+
+## 1. Local Installation
+
+### 1.1 Prerequisites
+
+#### 📦 Java Development Kit (JDK) 8
+- Use the [reference documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html) to install a **Java Development Kit**
+- Validate your installation with
+
+```bash
+java --version
+```
+
+#### 📦 Apache Maven
+- Use the [reference documentation](https://maven.apache.org/install.html) to install **Apache Maven**
+- Validate your installation with
+
+```bash
+mvn -version
+```
+
+#### 📦 Docker (local Installation)
+
+Docker is an open-source project that automates the deployment of software applications inside containers by providing an additional layer of abstraction and automation of OS-level virtualization on Linux.
+
+### 1.2 Packaging
+
+- Clone the repository
+
+```console
+git clone [email protected]:datastax/astra-db-java.git
+```
+
+- Build the project (java 11 and Maven is required)
+
+> Note: You should skip the tests if you want to speed up the build, to run the test you need to have a bit of setup:
+> - An environment variable `ASTRA_DB_APPLICATION_TOKEN` with your an Organization Administrator Astra token (PROD)
+> - An environment variable `ASTRA_DB_APPLICATION_TOKEN_DEV` with your an Organization Administrator Astra token (DEV)
+> - A running Data API locally with docker (see the `docker-compose.yml` in the root of the project)
+
+```console
+mvn clean install -DskipTests=true
+```
+
+### 1.3 Installation
+
+Add the following dependency to your `pom.xml` file:
+
+```xml
+
+<dependency>
+  <groupId>com.datastax.astra</groupId>
+  <artifactId>astra-db-java</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+</dependency>
+```
+
+## 2. QuickStart
+
+After creating a new java Project and adding the dependency to your `pom.xml` file, you can start using the library.
+
+Here is a sample class that demonstrates how to use the library:
+
+```java
+import com.datastax.astra.client.DataAPIClient;
+import com.datastax.astra.client.Collection;
+import com.datastax.astra.client.Database;
+import com.datastax.astra.client.model.Document;
+import com.datastax.astra.client.model.FindIterable;
+import java.util.List;
+import static com.datastax.astra.client.model.Filters.eq;
+import static com.datastax.astra.client.model.SimilarityMetric.cosine;
+
+public class GettingStarted {
+ public static void main(String[] args) {
+  // Initializing client with a token
+  DataAPIClient client = new DataAPIClient("my_token");
+
+  // Accessing the Database through the HTTP endpoint
+  Database db = client.getDatabase("http://db-region.apps.astra.datastax.com");
+
+  // Create collection with vector support
+  Collection<Document> col = db.createCollection("demo", 2, cosine);
+
+  // Insert records
+  col.insertMany(List.of(
+   new Document("doc1").vector(new float[]{.1f, 0.2f}).append("key", "value1"),
+   new Document().id("doc2").vector(new float[]{.2f, 0.4f}).append("hello", "world"),
+   new Document("doc3").vector(new float[]{.5f, 0.6f}).append("key", "value1"))
+  );
+
+  // Search
+  FindIterable<Document> docs = col.find(
+    eq("key", "value1"), // metadata filter
+    new float[] {.5f, .5f},              //vector
+    10);                                 // maxRecord
+
+  // Iterate and print your results
+  for (Document doc : docs) System.out.println(doc);
+ }
+}
+```
+
+### 3. What's Next
+
+- For more information use the [JAVADOC  documentation](https://datastaxdevs.github.io/astra-db-java/latest/)
+
+- The `examples` directory contains more examples on how to use the library.

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

@@ -45,9 +45,7 @@
 import com.datastax.astra.client.model.InsertManyResult;
 import com.datastax.astra.client.model.InsertOneResult;
 import com.datastax.astra.client.model.Page;
-import com.datastax.astra.client.model.Projection;
 import com.datastax.astra.client.model.ReplaceOneOptions;
-import com.datastax.astra.client.model.SortOrder;
 import com.datastax.astra.client.model.Update;
 import com.datastax.astra.client.model.UpdateOneOptions;
 import com.datastax.astra.client.model.UpdateResult;
@@ -58,10 +56,8 @@
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 
-import javax.print.Doc;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.Callable;
 import java.util.concurrent.CompletableFuture;
@@ -851,10 +847,10 @@ public Optional<DOC> findOne(Filter filter) {
      *  // Assuming a Document in the collection with an id field
      *  Document doc = new Document().id(1).append("name", "John Doe");
      *  // To find the document with the id 1
-     *  FindOneOptions options = FindOneOptions.builder()
-     *    .withIncludeSimilarity()                    // return similarity in vector search
-     *    .withProjection(Map.of("name", 1),  // return a subset of fields
-     *    .build());
+     *  FindOneOptions options2 = FindOneOptions.builder()
+     *    .withIncludeSimilarity()     // return similarity in vector search
+     *    .projections("_id", "name")  // return a subset of fields
+     *    .build();
      *  Optional<Document> foundDoc = collection.findOne(Filters.eq("_id", 1), );
      *  foundDoc.ifPresent(System.out::println);
      * }
@@ -902,6 +898,46 @@ public Optional<DOC> findOne(Filter filter, FindOneOptions options) {
     public CompletableFuture<Optional<DOC>> findOneASync(Filter filter) {
         return CompletableFuture.supplyAsync(() -> findOne(filter));
     }
+
+
+    /**
+     * Asynchronously attempts to find a single document within the collection that matches the given filter criteria,
+     * utilizing the specified {@link FindOneOptions} for the query. This method offers a non-blocking approach to
+     * querying the database, making it well-suited for applications requiring efficient I/O operations without
+     * compromising the responsiveness of the application.
+     *
+     * <p>By executing the search operation in an asynchronous manner, this method allows other tasks to proceed
+     * concurrently, effectively utilizing system resources and improving application throughput. The query leverages
+     * a {@link Filter} instance to define the search criteria, and {@link FindOneOptions} to specify query
+     * customizations, such as projection or sort parameters.</p>
+     *
+     * <p>In cases where no document matches the filter, the method returns a {@link CompletableFuture} completed with
+     * an empty {@link java.util.Optional}, thus avoiding exceptions for non-existent documents. This behavior ensures
+     * a more graceful handling of such scenarios, allowing for cleaner and more robust client code by leveraging
+     * the {@link java.util.Optional} pattern within asynchronous workflows.</p>
+     *
+     * @param filter  The {@link Filter} instance encapsulating the criteria used to identify the desired document.
+     *                It defines the conditions that a document must meet to be considered a match.
+     * @param options The {@link FindOneOptions} providing additional query configurations such as projection
+     *                and sort criteria to tailor the search operation.
+     * @return A {@link CompletableFuture<Optional<DOC>>} that, upon completion, contains an {@link Optional<DOC>}
+     *         with the found document if one exists matching the filter criteria. If no matching document is found,
+     *         a completed future with an empty {@link Optional} is returned, facilitating safe asynchronous retrieval.
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * Filter filter = Filters.eq("id", 1);
+     * FindOneOptions options = FindOneOptions.builder().projection("name");
+     * CompletableFuture<Optional<Document>> futureDoc = collection.findOneASync(filter, options);
+     * futureDoc.thenAccept(doc -> doc.ifPresent(System.out::println));
+     * }
+     * </pre>
+     */
+    public CompletableFuture<Optional<DOC>> findOneASync(Filter filter, FindOneOptions options) {
+        return CompletableFuture.supplyAsync(() -> findOne(filter, options));
+    }
+
     /**
      * Retrieves a document by its identifier from the collection.
      * <p>
@@ -918,6 +954,40 @@ public Optional<DOC> findById(Object id) {
         return findOne(Filters.eq(id));
     }
 
+    /**
+     * Asynchronously retrieves a document from the collection by its unique identifier. This method wraps
+     * the synchronous {@code findById} operation in a {@link CompletableFuture}, enabling non-blocking
+     * database queries that improve application responsiveness and efficiency. The method is ideal for
+     * applications that require the retrieval of specific documents without impacting the performance
+     * of the user interface or other concurrent operations.
+     *
+     * <p>The unique identifier used to locate the document is typically the primary key or a unique field
+     * within the collection. This method abstracts the complexity of asynchronous programming, providing
+     * a straightforward way to execute and handle database queries within a non-blocking model.</p>
+     *
+     * <p>If the document with the specified identifier exists, it is wrapped in an {@link Optional} and
+     * returned within the completed future. Otherwise, the future is completed with an empty {@link Optional},
+     * neatly handling cases where no matching document is found without throwing exceptions.</p>
+     *
+     * @param id The unique identifier of the document to retrieve. This can be of any type that the database
+     *           recognizes as a valid identifier format (e.g., String, Integer).
+     * @return A {@link CompletableFuture<Optional<DOC>>} that, upon completion, contains an {@link Optional<DOC>}
+     *         with the document if found. If no document matches the specified identifier, a completed future
+     *         with an empty {@link Optional} is returned.
+     *
+     * <p>Example usage:</p>
+     * <pre>
+     * {@code
+     * Object documentId = "uniqueDocumentId123";
+     * CompletableFuture<Optional<Document>> futureDocument = collection.findByIdASync(documentId);
+     * futureDocument.thenAccept(document -> document.ifPresent(System.out::println));
+     * }
+     * </pre>
+     */
+    public CompletableFuture<Optional<DOC>> findByIdASync(Object id) {
+        return CompletableFuture.supplyAsync(() -> findById(id));
+    }
+
     /**
      * Finds all documents in the collection.
      *
@@ -942,7 +1012,7 @@ public FindIterable<DOC> find(Filter filter, FindOptions options) {
      * @return A {@link FindIterable} for iterating over all documents in the collection.
      */
     public FindIterable<DOC> find() {
-        return find(null, new FindOptions());
+        return find(null, FindOptions.builder().build());
     }
 
     /**
@@ -956,7 +1026,7 @@ public FindIterable<DOC> find() {
      * @return A {@link FindIterable} for iterating over the documents that match the filter.
      */
     public FindIterable<DOC> find(Filter filter) {
-        return find(filter, new FindOptions());
+        return find(filter, FindOptions.builder().build());
     }
 
     /**
@@ -975,7 +1045,7 @@ public FindIterable<DOC> find(Filter filter) {
      */
     public FindIterable<DOC> find(Filter filter, float[] vector, int limit) {
         return find(filter, FindOptions.builder()
-                .withVector(vector)
+                .vector(vector)
                 .limit(limit)
                 .build());
     }
@@ -994,7 +1064,7 @@ public FindIterable<DOC> find(Filter filter, float[] vector, int limit) {
      */
     public FindIterable<DOC> find(Filter filter, String vectorize, int limit) {
         return find(filter, FindOptions.builder()
-                .withVectorize(vectorize)
+                .vectorize(vectorize)
                 .limit(limit)
                 .build());
     }

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

@@ -337,31 +337,16 @@ public Database getDatabase(UUID databaseId, String namespace) {
      * operations such as querying, updating, and managing data within the specified database and namespace.
      *
      * @param databaseId The unique identifier of the database to interact with.
-     * @param cloud The cloud provider on which the database is deployed, values are AWS, GCP, or AZURE.
+     * @param namespace The namespace associated to this database
      * @param region The cloud provider region where the database is deployed.
-     * @return
-     *      A {@link Database} client configured to interact with the specified database and namespace, allowing for
-     *      data manipulation and query operations.
-     */
-    public Database getDatabase(UUID databaseId, CloudProviderType cloud, String region) {
-        return getDatabase(databaseId, cloud, region, DEFAULT_NAMESPACE);
-    }
-
-    /**
-     * 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 namespace.
      *
-     * @param databaseId The unique identifier of the database to interact with.
-     * @param cloud The cloud provider on which the database is deployed, values are AWS, GCP, or AZURE.
-     * @param region The cloud provider region where the database is deployed.
-     * @param namespace The namespace associated to this database
      * @return
      *      A {@link Database} client configured to interact with the specified database and namespace, allowing for
      *      data manipulation and query operations.
      */
-    public Database getDatabase(UUID databaseId, CloudProviderType cloud, String region, String namespace) {
+    public Database getDatabase(UUID databaseId, String namespace, String region) {
         Assert.notNull(databaseId, "databaseId");
-        Assert.notNull(cloud, "cloud");
+        Assert.hasLength(namespace, "namespace");
         Assert.hasLength(region, "namespace");
         return new Database(new AstraApiEndpoint(databaseId, region,
                 getAstraEnvironment()).getApiEndPoint(),