update javadoc and serialization

stargate-sdk-data/pom.xml

@@ -2,7 +2,7 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <artifactId>stargate-sdk-data</artifactId>
-    <name>+ stargate-sdk-data</name>
+    <name>Client for Stargate DataAPI</name>
 
     <parent>
         <groupId>com.datastax.stargate</groupId>

stargate-sdk-data/src/main/java/io/stargate/sdk/data/CollectionClient.java

@@ -4,7 +4,10 @@
 import io.stargate.sdk.data.domain.ApiData;
 import io.stargate.sdk.data.domain.ApiError;
 import io.stargate.sdk.data.domain.ApiResponse;
+import io.stargate.sdk.data.domain.DocumentMutationResult;
+import io.stargate.sdk.data.domain.DocumentMutationStatus;
 import io.stargate.sdk.data.domain.JsonDocument;
+import io.stargate.sdk.data.domain.JsonDocumentMutationResult;
 import io.stargate.sdk.data.domain.JsonDocumentResult;
 import io.stargate.sdk.data.domain.JsonResultUpdate;
 import io.stargate.sdk.data.domain.UpdateStatus;
@@ -50,7 +53,7 @@
 import static io.stargate.sdk.utils.AnsiUtils.green;
 
 /**
- * Wrapper for collection operations.
+ * Client for a collection (crud for documents).
  */
 @Slf4j
 public class CollectionClient {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/CollectionRepository.java

@@ -1,6 +1,7 @@
 package io.stargate.sdk.data;
 
 import io.stargate.sdk.core.domain.Page;
+import io.stargate.sdk.data.domain.DocumentMutationResult;
 import io.stargate.sdk.data.domain.odm.Document;
 import io.stargate.sdk.data.domain.odm.DocumentResult;
 import io.stargate.sdk.data.domain.query.DeleteQuery;
@@ -16,10 +17,10 @@
 import java.util.stream.Stream;
 
 /**
- * Crud repository with Json Api
+ * Client implementing repository pattern for a collection.
  *
  * @param <DOC>
- *     current bean
+ *    java bean representing a document
  */
 @Getter
 public class CollectionRepository<DOC> {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/DataApiClient.java

@@ -22,7 +22,7 @@
 import static io.stargate.sdk.utils.AnsiUtils.green;
 
 /**
- * Client for the JSON Document API.
+ * Client core for Data API (crud for namespaces).
  */
 @Slf4j
 @Getter

stargate-sdk-data/src/main/java/io/stargate/sdk/data/NamespaceClient.java

@@ -19,7 +19,7 @@
 import static io.stargate.sdk.utils.AnsiUtils.green;
 
 /**
- * Work with namespace and collections.
+ * Client for a namespace (crud for collections).
  */
 @Getter  @Slf4j
 public class NamespaceClient {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/ApiData.java

@@ -5,7 +5,7 @@
 import java.util.List;
 
 /**
- * Payload for json api response.
+ * Subpart of the payload for json api response holding returned data.
  */
 @Data
 public class ApiData {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/ApiError.java

@@ -3,7 +3,7 @@
 import lombok.Data;
 
 /**
- * Payload for json Api error.
+ * Subpart of the payload for json api response holding error information.
  */
 @Data
 public class ApiError {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/ApiResponse.java

@@ -8,29 +8,28 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 /**
- * Payload for json api response.
+ * Represents the Api response.
  */
 @Data
 public class ApiResponse {
 
     /**
-     * Return by everything except find*()
+     * Return by all operations except find*()
      */
     @JsonInclude(JsonInclude.Include.NON_NULL)
     private Map<String, Object> status;
 
     /**
-     * If an error ocured
+     * List of errors, could be one per inserted items with reason.
      */
     @JsonInclude(JsonInclude.Include.NON_NULL)
     private List<ApiError> errors;
 
     /**
-     * Data retrieved by find*()
+     * Data retrieve with operations find
      */
     private ApiData data;
 
@@ -41,7 +40,7 @@ public ApiResponse() {
     }
 
     /**
-     * Syntax sugar.
+     * Read a value as a stream from the key/value 'status' map.
      *
      * @param key
      *      key to be retrieved
@@ -57,7 +56,7 @@ public Stream<String> getStatusKeyAsStringStream(@NonNull String key) {
     }
 
     /**
-     * Use when attribute in status is an object.
+     * Read a value as a List from the key/value 'status' map.
      *
      * @param key
      *      target get
@@ -68,15 +67,15 @@ public Stream<String> getStatusKeyAsStringStream(@NonNull String key) {
      * @param <T>
      *      type in used
      */
-    public <T> T getStatusKeyAsObject(@NonNull String key, Class<T> targetClass) {
+    public <T> T getStatusKeyAsObject(@NonNull String key, @NonNull Class<T> targetClass) {
         if (status.containsKey(key)) {
             return JsonUtils.convertValue(status.get(key), targetClass);
         }
         return null;
     }
 
     /**
-     * Use when attribute in status is a list.
+     * Read a value as a Specialized class from the key/value 'status' map.
      *
      * @param key
      *      target get
@@ -97,19 +96,7 @@ public <T> List<T> getStatusKeyAsList(@NonNull String key, Class<T> targetClass)
     }
 
     /**
-     * Syntax sugar.
-     *
-     * @param key
-     *      key to be retrieved
-     * @return
-     *      list of values
-     */
-    public List<String> getStatusKeyAsList(@NonNull String key) {
-        return getStatusKeyAsStringStream(key).collect(Collectors.toList());
-    }
-
-    /**
-     * Syntax sugar.
+     * Read a value as an Integer from the key/value 'status' map.
      *
      * @param key
      *      key to be retrieved

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/CollectionDefinition.java

@@ -3,7 +3,7 @@
 import lombok.Data;
 
 /**
- * Request to create a collection.
+ * Represents the Collection definition with its name and metadata.
  */
 @Data
 public class CollectionDefinition {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/DocumentMutationResult.java → stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/DocumentMutationResult.java

@@ -1,6 +1,5 @@
-package io.stargate.sdk.data;
+package io.stargate.sdk.data.domain;
 
-import io.stargate.sdk.data.domain.JsonDocument;
 import io.stargate.sdk.data.domain.odm.Document;
 import io.stargate.sdk.utils.JsonUtils;
 import lombok.Getter;
@@ -9,7 +8,7 @@
 import java.util.Map;
 
 /**
- * Wrapper to get result from API with schemaless document.
+ * Result per document mutation working a generic Document<T>
  *
  * @param <T>
  *     represents the pojo for returned document

stargate-sdk-data/src/main/java/io/stargate/sdk/data/DocumentMutationStatus.java → stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/DocumentMutationStatus.java

@@ -1,7 +1,7 @@
-package io.stargate.sdk.data;
+package io.stargate.sdk.data.domain;
 
 /**
- * Each document will have a STATUS.
+ * Status and document mutation like <code>CREATED</code>, <code>UPDATED</code> or <code>UNCHANGED</code>...
  */
 public enum DocumentMutationStatus {
     /** Document Created. */

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/JsonDocument.java

@@ -40,7 +40,7 @@
 
 
 /**
- * Json Api Payload.
+ * Represents a document without schema contraints as a Map<String, Object>.(key/value)
  */
 public class JsonDocument extends Document<Map<String, Object>> {
 
@@ -426,5 +426,4 @@ public boolean isAttributeExist(String key) {
         return data.containsKey(key);
     }
 
-
 }

stargate-sdk-data/src/main/java/io/stargate/sdk/data/JsonDocumentMutationResult.java → stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/JsonDocumentMutationResult.java

@@ -1,11 +1,9 @@
-package io.stargate.sdk.data;
-
-import io.stargate.sdk.data.domain.JsonDocument;
+package io.stargate.sdk.data.domain;
 
 import java.util.Map;
 
 /**
- * Wrapper to get result from API with schemaless document
+ * Result per document working with a schemaless document (JsonDocument or Json String).
  */
 public class JsonDocumentMutationResult extends DocumentMutationResult<Map<String, Object>> {
 

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/JsonDocumentResult.java

@@ -17,7 +17,7 @@
 import java.util.UUID;
 
 /**
- * Json Results.
+ * Represents entity returns for find() queries working with shemaless documents.
  */
 @Getter @Setter
 public class JsonDocumentResult extends DocumentResult<Map<String, Object>> {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/JsonResultUpdate.java

@@ -3,7 +3,7 @@
 import lombok.Data;
 
 /**
- * Payload for json Api update.
+ * Represents the payload returned for a specialized update function.
  */
 @Data
 public class JsonResultUpdate {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/NamespaceDefinition.java

@@ -8,7 +8,7 @@
 import java.util.Map;
 
 /**
- * Pogo to create a namspace.
+ * Represents the Namespace (keyspac) definition with its name and metadata.
  */
 @Data
 public class NamespaceDefinition {

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/odm/Document.java

@@ -14,7 +14,7 @@
 import javax.print.Doc;
 
 /**
- * Working with entities.
+ * Unitary entity for a document. Adding `id` and `vector`.
  *
  * @param <T>
  *     type of bean in use
@@ -120,4 +120,15 @@ public Document<T> data(T data) {
     public static <R> Document<R> of(String id, float[] vector, R data) {
         return new Document<R>().id(id).vector(vector).data(data);
     }
+
+    /**
+     * Print the document as a Json String.
+     *
+     * @return
+     *      json string
+     */
+    @Override
+    public String toString() {
+        return JsonUtils.marshallForDataApi(this);
+    }
 }

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/odm/DocumentResult.java

@@ -10,7 +10,7 @@
 
 
 /**
- * Result class with ODM.
+ * Unitary entity for a return document. It is a document amended with `similarity`.
  *
  * @param <DOC>
  *     pojo in use for ODM
@@ -83,5 +83,4 @@ public DocumentResult(JsonDocumentResult result, Class<DOC> clazz) {
     public static <R> DocumentResult<R> of(JsonDocumentResult result, Class<R> clazz) {
         return new DocumentResult<>(result, clazz);
     }
-
 }

stargate-sdk-data/src/main/java/io/stargate/sdk/data/domain/package-info.java

@@ -1,4 +1,4 @@
 /**
- * Specialized entities for this Api
+ * Specialized domain objects for data operations.
  */
 package io.stargate.sdk.data.domain;

stargate-sdk-data/src/main/java/io/stargate/sdk/data/exception/package-info.java

@@ -1,4 +1,4 @@
 /**
- * Specialized exceptions for this API.
+ * Specialized runtime exceptions for Data API.
  */
 package io.stargate.sdk.data.exception;

stargate-sdk-data/src/main/java/io/stargate/sdk/data/package-info.java

@@ -1,4 +1,4 @@
 /**
- * Main package for client to works with Stargate Data API (collection,vector)
+ * Core Data API Client Classes.
  */
 package io.stargate.sdk.data;

stargate-sdk-data/src/main/java/io/stargate/sdk/data/utils/DataApiUtils.java

@@ -1,20 +1,19 @@
 package io.stargate.sdk.data.utils;
 
 import io.stargate.sdk.data.domain.ApiData;
-import io.stargate.sdk.http.LoadBalancedHttpClient;
-import io.stargate.sdk.http.ServiceHttp;
-import io.stargate.sdk.http.domain.ApiResponseHttp;
 import io.stargate.sdk.data.domain.ApiError;
 import io.stargate.sdk.data.domain.ApiResponse;
+import io.stargate.sdk.data.exception.DataApiDocumentAlreadyExistException;
 import io.stargate.sdk.data.exception.DataApiErrorCode;
 import io.stargate.sdk.data.exception.DataApiException;
-import io.stargate.sdk.data.exception.DataApiDocumentAlreadyExistException;
 import io.stargate.sdk.data.exception.DataApiInvalidArgumentException;
+import io.stargate.sdk.http.LoadBalancedHttpClient;
+import io.stargate.sdk.http.ServiceHttp;
+import io.stargate.sdk.http.domain.ApiResponseHttp;
 import io.stargate.sdk.utils.JsonUtils;
 import lombok.NonNull;
 import lombok.extern.slf4j.Slf4j;
 
-import java.util.List;
 import java.util.function.Function;
 
 import static io.stargate.sdk.utils.AnsiUtils.magenta;
@@ -32,12 +31,12 @@ public class DataApiUtils {
     private DataApiUtils() {}
 
     /**
-     * Accessing api.
+     * Wrapper to execute Http POST request.
      *
      * @param stargateHttpClient
      *      http client
      * @param operation
-     *      name of the operation
+     *      operation name
      * @param rootResource
      *      rest resource
      * @param body

stargate-sdk-data/src/main/java/io/stargate/sdk/data/utils/package-info.java

@@ -1,4 +1,4 @@
 /**
- * Utilities to work with Json Structures
+ * Utilities to build and parse http requests
  */
 package io.stargate.sdk.data.utils;

stargate-sdk-test/src/test/java/io/stargate/test/data/VectorClientProductTest.java

@@ -5,7 +5,7 @@
 import io.stargate.sdk.data.DataApiClient;
 import io.stargate.sdk.data.CollectionClient;
 import io.stargate.sdk.data.CollectionRepository;
-import io.stargate.sdk.data.DocumentMutationResult;
+import io.stargate.sdk.data.domain.DocumentMutationResult;
 import io.stargate.sdk.data.domain.CollectionDefinition;
 import io.stargate.sdk.data.domain.query.Filter;
 import io.stargate.sdk.data.domain.JsonDocument;