javadocs, javadoc, javadoc...28 to go

datastax · clun · Apr 4, 2025 · Nov 21, 2024 · Nov 30, 2024 · Nov 30, 2024
commit 05af2bca3464593e5dd179269d7502ffdbda2cf8
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
@@ -183,6 +183,8 @@ public static DataAPIClient clientHCD() {
      * </ul>
      * This setup allows developers to focus on application logic rather than database configuration or connectivity.
      *
+     * @param username The username for authenticating with the Data API. This username should have the necessary
+     * @param password The password for authenticating with the Data API. This password should be kept secure and
      * @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.

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
@@ -278,6 +278,7 @@ public static SerdesOptions getSerdesOptions() {
     /**
      * Register an observer with its className.
      *
+     * @param name     observer name
      * @param observer command observer
      * @return instance of the command options
      */

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
@@ -615,6 +615,7 @@ public Collection<Document> getCollection(String collectionName) {
      *
      * @param collectionName The name of the collection to retrieve.
      * @param documentClass The class type of the documents stored in the collection.
+     * @param <T> The type of the documents stored in the collection.
      * @return A {@link Collection} object representing the specified collection, configured with the provided options.
      */
     public <T> Collection<T> getCollection(String collectionName, Class<T> documentClass) {

diff --git a/...rc/main/java/com/datastax/astra/client/tables/commands/options/DropTableIndexOptions.java b/...rc/main/java/com/datastax/astra/client/tables/commands/options/DropTableIndexOptions.java
@@ -28,6 +28,9 @@
 import static com.datastax.astra.client.core.commands.CommandType.TABLE_ADMIN;
 import static com.datastax.astra.client.tables.Table.DEFAULT_TABLE_SERIALIZER;
 
+/**
+ * Options for dropping an index on a table.
+ */
 @Setter
 @Accessors(fluent = true, chain = true)
 public class DropTableIndexOptions extends BaseOptions<DropTableIndexOptions> {

diff --git a/...ava/src/main/java/com/datastax/astra/client/tables/commands/options/DropTableOptions.java b/...ava/src/main/java/com/datastax/astra/client/tables/commands/options/DropTableOptions.java
@@ -28,6 +28,9 @@
 import static com.datastax.astra.client.core.commands.CommandType.TABLE_ADMIN;
 import static com.datastax.astra.client.tables.Table.DEFAULT_TABLE_SERIALIZER;
 
+/**
+ * Options for dropping a table.
+ */
 @Setter
 @Accessors(fluent = true, chain = true)
 public class DropTableOptions extends BaseOptions<DropTableOptions> {

diff --git a/...a/src/main/java/com/datastax/astra/client/tables/definition/columns/ColumnTypeMapper.java b/...a/src/main/java/com/datastax/astra/client/tables/definition/columns/ColumnTypeMapper.java
@@ -65,6 +65,9 @@ public class ColumnTypeMapper {
      */
     private static final Map<Class<?>, ColumnTypes> typeMapping = new HashMap<>();
 
+    /**
+     * Static initializer block that populates the type mapping.
+     */
     static {
         // Primitive and wrapper types
         typeMapping.put(Integer.class, ColumnTypes.INT);
@@ -104,6 +107,11 @@ public class ColumnTypeMapper {
         typeMapping.put(Object.class, ColumnTypes.UNSUPPORTED);
     }
 
+    /**
+     * Private constructor to prevent instantiation.
+     */
+    private ColumnTypeMapper() {}
+
     /**
      * Retrieves the Cassandra column type corresponding to the given Java class.
      * If the type is not explicitly mapped, {@code ColumnTypes.UNSUPPORTED} is returned.

diff --git a/astra-db-java/src/main/java/com/datastax/astra/client/tables/mapping/EntityTable.java b/astra-db-java/src/main/java/com/datastax/astra/client/tables/mapping/EntityTable.java
@@ -34,6 +34,7 @@
 
     /**
      * Table Name, if not provided the class name will be used
+     * @return the table name
      */
     String value() default "";
 }
diff --git a/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIDocumentResponse.java b/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIDocumentResponse.java
@@ -28,16 +28,46 @@
 import java.io.Serializable;
 import java.util.List;
 
-@Getter @Setter
+/**
+ * Represents the response of a Data API operation involving documents.
+ * <p>
+ * This class provides a structured representation of a document response,
+ * including its unique identifier(s) and status. The class is serializable
+ * and integrates with JSON serialization frameworks like Jackson.
+ * </p>
+ */
+@Getter
+@Setter
 public class DataAPIDocumentResponse implements Serializable {
 
+    /**
+     * A list of objects representing the unique identifier(s) of the document.
+     * <p>
+     * This field is annotated with {@link JsonProperty} to map it to the {@code "_id"}
+     * key in JSON.
+     * </p>
+     */
     @JsonProperty("_id")
     private List<Object> id;
 
+    /**
+     * The status of the document operation, such as "SUCCESS" or "FAILED".
+     */
     private String status;
 
+    /**
+     * Default constructor for serialization frameworks.
+     */
+    public DataAPIDocumentResponse() {}
+
+    /**
+     * Converts the {@code DataAPIDocumentResponse} object into a string representation.
+     * This implementation uses {@link RowSerializer#marshall(Object)} for serialization.
+     *
+     * @return a string representation of this object
+     */
     @Override
     public String toString() {
         return new RowSerializer().marshall(this);
     }
-}
+}
diff --git a/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIResponse.java b/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIResponse.java
@@ -43,8 +43,7 @@
  * such as status information, error details, and data returned by 'find' operations. It provides flexibility to handle
  * various types of responses within a unified framework.
  */
-@Getter
-@Setter
+@Getter @Setter
 public class DataAPIResponse implements Serializable {
 
     /**
@@ -129,6 +128,14 @@ public <T> Map<String, T> getStatusKeyAsMap(@NonNull String key, Class<T> target
                         .constructMapType(Map.class, String.class, targetClass));
     }
 
+    /**
+     * Retrieves a single object from the 'status' map based on the provided key, casting it to the specified class.
+     * This method is suitable for cases where the status information contains a single object under a specific key.
+     *
+     * @param targetClass The class to which the object should be cast.
+     * @param <T> The type of the object to be returned.
+     * @return The object associated with the specified key, cast to the specified class; {@code null} if the key does not exist.
+     */
     public <T> T getStatus(Class<T> targetClass) {
         return serializer.getMapper().convertValue(status, targetClass);
     }

diff --git a/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIStatus.java b/astra-db-java/src/main/java/com/datastax/astra/internal/api/DataAPIStatus.java
@@ -36,6 +36,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Status of the Data API.
+ */
 @Getter @Setter
 public class DataAPIStatus {
 
@@ -84,6 +87,12 @@ public class DataAPIStatus {
     @JsonIgnore
     private DataAPISerializer serializer;
 
+    /**
+     * Default constructor.
+     */
+    public DataAPIStatus() {
+    }
+
     /**
      * Access the insertedIds mapping.
      *

diff --git a/astra-db-java/src/main/java/com/datastax/astra/internal/reflection/EntityBeanDefinition.java b/astra-db-java/src/main/java/com/datastax/astra/internal/reflection/EntityBeanDefinition.java
@@ -206,6 +206,16 @@ public Map<String, Integer> getPartitionSort() {
         return cc;
     }
 
+    /**
+     * Create a table command based on the annotated fields.
+     *
+     * @param tableName
+     *      the table name
+     * @param clazz
+     *      the class
+     * @return
+     *      a document representing the table command
+     */
     public static Document createTableCommand(String tableName, Class<?> clazz) {
         EntityBeanDefinition<?> bean = new EntityBeanDefinition<>(clazz);
         if (Utils.hasLength(bean.getName()) && !bean.getName().equals(tableName)) {

diff --git a/...a-db-java/src/main/java/com/datastax/astra/internal/reflection/EntityFieldDefinition.java b/...a-db-java/src/main/java/com/datastax/astra/internal/reflection/EntityFieldDefinition.java
@@ -27,8 +27,10 @@
 import lombok.Data;
 
 import java.lang.reflect.Method;
-import java.lang.reflect.Type;
 
+/**
+ * Definition of a field in an entity.
+ */
 @Data
 public class EntityFieldDefinition {
 
@@ -55,4 +57,9 @@ public class EntityFieldDefinition {
     // @PartitionSort
     private Integer     partitionSortPosition;
     private SortOrder   partitionSortOrder;
+
+    /**
+     * Default constructor.
+     */
+    public EntityFieldDefinition() {}
 }
diff --git a/...db-java/src/main/java/com/datastax/astra/internal/serdes/tables/DurationDeserializer.java b/...db-java/src/main/java/com/datastax/astra/internal/serdes/tables/DurationDeserializer.java
@@ -64,6 +64,11 @@ public class DurationDeserializer extends JsonDeserializer<Duration> {
      */
     private static final Pattern NEGATIVE_PATTERN = Pattern.compile("^-(.*)");
 
+    /**
+     * Default constructor.
+     */
+    public DurationDeserializer() {}
+
     /**
      * Deserializes a JSON string into a {@link Duration} object.
      * <p>