Adding javadoc

Author: aschenzle

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/DynamoDbAttributeValueHelper.java

@@ -33,9 +33,18 @@ public final class DynamoDbAttributeValueHelper {
     private static final String SCIENTIFIC_NOTATION_E_LOWER = "e";
     private static final String SCIENTIFIC_NOTATION_E_UPPER = "E";
 
+    /**
+     * Utility class, no instances.
+     */
     private DynamoDbAttributeValueHelper() {
     }
 
+    /**
+     * Converts a map of DynamoDB attribute values into plain Java values.
+     *
+     * @param source input object expected to be a map
+     * @return normalized map or empty map when input is not a map
+     */
     public static Map<String, Object> toPlainMap(Object source) {
         if (!(source instanceof Map<?, ?>)) {
             return Collections.emptyMap();
@@ -50,6 +59,12 @@ public static Map<String, Object> toPlainMap(Object source) {
         return result;
     }
 
+    /**
+     * Converts one DynamoDB attribute value object into a plain Java value.
+     *
+     * @param value attribute value object
+     * @return normalized Java value
+     */
     @SuppressWarnings("unchecked")
     public static Object toPlainValue(Object value) {
         if (value == null) {
@@ -119,6 +134,12 @@ public static Object toPlainValue(Object value) {
         return value;
     }
 
+    /**
+     * Converts binary payloads into plain byte arrays when backed by ByteBuffer.
+     *
+     * @param value binary payload object
+     * @return byte array or original value when conversion is not needed
+     */
     private static Object toPlainBinary(Object value) {
         if (value instanceof ByteBuffer) {
             ByteBuffer bb = ((ByteBuffer) value).asReadOnlyBuffer();
@@ -130,13 +151,27 @@ private static Object toPlainBinary(Object value) {
         return value;
     }
 
+    /**
+     * Reads a reflected value only when its corresponding {@code hasX} accessor is true.
+     *
+     * @param target target object
+     * @param hasMethod presence-check method name
+     * @param valueMethod value accessor method name
+     * @return reflected value or {@code null}
+     */
     private static Object readIfPresent(Object target, String hasMethod, String valueMethod) {
         if (Boolean.TRUE.equals(DynamoDbReflectionHelper.invokeBooleanNoArg(target, hasMethod))) {
             return DynamoDbReflectionHelper.invokeNoArg(target, valueMethod);
         }
         return null;
     }
 
+    /**
+     * Converts a collection of attribute values into plain Java values.
+     *
+     * @param source source collection
+     * @return normalized list
+     */
     private static List<Object> toPlainList(Collection<Object> source) {
         List<Object> converted = new ArrayList<>(source.size());
         for (Object element : source) {
@@ -145,6 +180,12 @@ private static List<Object> toPlainList(Collection<Object> source) {
         return converted;
     }
 
+    /**
+     * Converts a collection of numeric tokens into parsed numeric values.
+     *
+     * @param source source numeric collection
+     * @return normalized number set
+     */
     private static Set<Object> toNumberSet(Collection<?> source) {
         LinkedHashSet<Object> numbers = new LinkedHashSet<>();
         for (Object number : source) {
@@ -155,6 +196,12 @@ private static Set<Object> toNumberSet(Collection<?> source) {
         return numbers;
     }
 
+    /**
+     * Converts a collection of binary payloads into plain binary values.
+     *
+     * @param source source binary collection
+     * @return normalized binary set
+     */
     private static Set<Object> toBinarySet(Collection<?> source) {
         LinkedHashSet<Object> binaries = new LinkedHashSet<>();
         for (Object binary : source) {
@@ -163,6 +210,12 @@ private static Set<Object> toBinarySet(Collection<?> source) {
         return binaries;
     }
 
+    /**
+     * Parses a numeric token into {@link Long} or {@link Double}.
+     *
+     * @param text numeric token
+     * @return parsed number or {@link Double#NaN} when parsing fails
+     */
     private static Object parseNumber(String text) {
         try {
             if (text.contains(DECIMAL_SEPARATOR)

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/DynamoDbComparisonType.java

@@ -13,6 +13,12 @@ public enum DynamoDbComparisonType {
     LESS_THAN,
     LESS_THAN_EQUALS;
 
+    /**
+     * Maps a DynamoDB comparator token to a normalized comparison type.
+     *
+     * @param token comparator token from parsed expression
+     * @return normalized comparison type
+     */
     public static DynamoDbComparisonType fromToken(String token) {
         if ("=".equals(token)) {
             return EQUALS;
@@ -35,6 +41,13 @@ public static DynamoDbComparisonType fromToken(String token) {
         throw new IllegalArgumentException("Unsupported comparator token: " + token);
     }
 
+    /**
+     * Creates a comparison operation instance for this comparison type.
+     *
+     * @param fieldName compared field name/path
+     * @param value comparison value
+     * @return concrete comparison operation
+     */
     public ComparisonOperation<?> toOperation(String fieldName, Object value) {
         switch (this) {
             case EQUALS:

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/DynamoDbExpressionParser.java

@@ -171,6 +171,9 @@ private QueryOperation mergeOr(QueryOperation left, QueryOperation right) {
         return new OrOperation(Arrays.asList(left, right));
     }
 
+    /**
+     * Visitor that converts grammar value nodes into Java values.
+     */
     private class ValueVisitor extends DynamoDbConditionExpressionBaseVisitor<Object> {
 
         /** {@inheritDoc} */
@@ -211,6 +214,9 @@ public Object visitIdentifierValue(DynamoDbConditionExpressionParser.IdentifierV
         }
     }
 
+    /**
+     * Visitor that converts grammar predicate nodes into query operations.
+     */
     private class OperationVisitor extends DynamoDbConditionExpressionBaseVisitor<QueryOperation> {
 
         /** {@inheritDoc} */

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/DynamoDbReflectionHelper.java

@@ -7,9 +7,19 @@
  */
 public final class DynamoDbReflectionHelper {
 
+    /**
+     * Utility class, no instances.
+     */
     private DynamoDbReflectionHelper() {
     }
 
+    /**
+     * Invokes a no-argument method on the target object.
+     *
+     * @param target target object
+     * @param methodName method name to invoke
+     * @return invocation result or {@code null} on errors
+     */
     public static Object invokeNoArg(Object target, String methodName) {
         if (target == null) {
             return null;
@@ -22,6 +32,13 @@ public static Object invokeNoArg(Object target, String methodName) {
         }
     }
 
+    /**
+     * Invokes a no-argument method and returns it only when boolean.
+     *
+     * @param target target object
+     * @param methodName method name to invoke
+     * @return boolean result or {@code null}
+     */
     public static Boolean invokeBooleanNoArg(Object target, String methodName) {
         Object value = invokeNoArg(target, methodName);
         return value instanceof Boolean ? (Boolean) value : null;

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/DynamoDbRequestParser.java

@@ -15,6 +15,9 @@ public class DynamoDbRequestParser {
 
     private final Map<DynamoDbOperationNames, DynamoDbApiMethodParser> parsersByApiMethod;
 
+    /**
+     * Creates a request parser and registers supported DynamoDB API method parsers.
+     */
     public DynamoDbRequestParser() {
         Map<DynamoDbOperationNames, DynamoDbApiMethodParser> map = new LinkedHashMap<>();
         registerParser(map, new QueryApiMethodParser());
@@ -28,7 +31,7 @@ public DynamoDbRequestParser() {
     }
 
     /**
-     * Entry-point parser used by the handler.
+     * Entry-point parser used by a future handler.
      * It routes a DynamoDB SDK request to the API-method parser and returns
      * one parsed condition tree per table name.
      * Unsupported operations intentionally yield an empty map.
@@ -47,6 +50,12 @@ public Map<String, QueryOperation> parseByTable(Object request, DynamoDbOperatio
         return parsed == null ? Collections.emptyMap() : parsed;
     }
 
+    /**
+     * Registers one API-method parser and rejects duplicates.
+     *
+     * @param parsersByApiMethod parser registry by API method name
+     * @param parser parser instance to register
+     */
     private static void registerParser(Map<DynamoDbOperationNames, DynamoDbApiMethodParser> parsersByApiMethod,
                                        DynamoDbApiMethodParser parser) {
         DynamoDbOperationNames apiMethodName = parser.apiMethodName();

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/operations/AndOperation.java

@@ -2,14 +2,27 @@
 
 import java.util.List;
 
+/**
+ * Logical AND operation over multiple DynamoDB query conditions.
+ */
 public class AndOperation extends QueryOperation {
 
     private final List<QueryOperation> conditions;
 
+    /**
+     * Creates an AND operation.
+     *
+     * @param conditions conditions to combine
+     */
     public AndOperation(List<QueryOperation> conditions) {
         this.conditions = conditions;
     }
 
+    /**
+     * Returns the conditions combined by this AND operation.
+     *
+     * @return combined conditions
+     */
     public List<QueryOperation> getConditions() {
         return conditions;
     }

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/operations/BeginsWithOperation.java

@@ -1,10 +1,19 @@
 package org.evomaster.client.java.controller.dynamodb.operations;
 
+/**
+ * DynamoDB {@code begins_with(path, value)} predicate operation.
+ */
 public class BeginsWithOperation extends QueryOperation {
 
     private final String fieldName;
     private final Object prefix;
 
+    /**
+     * Creates a begins-with operation.
+     *
+     * @param fieldName attribute path
+     * @param prefix expected prefix
+     */
     public BeginsWithOperation(String fieldName, Object prefix) {
         this.fieldName = fieldName;
         this.prefix = prefix;

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/operations/BetweenOperation.java

@@ -1,11 +1,21 @@
 package org.evomaster.client.java.controller.dynamodb.operations;
 
+/**
+ * DynamoDB {@code path BETWEEN lower AND upper} predicate operation.
+ */
 public class BetweenOperation extends QueryOperation {
 
     private final String fieldName;
     private final Object lowerBound;
     private final Object upperBound;
 
+    /**
+     * Creates a BETWEEN operation.
+     *
+     * @param fieldName attribute path
+     * @param lowerBound lower bound value
+     * @param upperBound upper bound value
+     */
     public BetweenOperation(String fieldName, Object lowerBound, Object upperBound) {
         this.fieldName = fieldName;
         this.lowerBound = lowerBound;

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/operations/ContainsOperation.java

@@ -1,10 +1,19 @@
 package org.evomaster.client.java.controller.dynamodb.operations;
 
+/**
+ * DynamoDB {@code contains(path, value)} predicate operation.
+ */
 public class ContainsOperation extends QueryOperation {
 
     private final String fieldName;
     private final Object expectedValue;
 
+    /**
+     * Creates a contains operation.
+     *
+     * @param fieldName attribute path
+     * @param expectedValue expected contained value
+     */
     public ContainsOperation(String fieldName, Object expectedValue) {
         this.fieldName = fieldName;
         this.expectedValue = expectedValue;

client-java/controller/src/main/java/org/evomaster/client/java/controller/dynamodb/operations/ExistsOperation.java

@@ -1,11 +1,21 @@
 package org.evomaster.client.java.controller.dynamodb.operations;
 
+/**
+ * DynamoDB existence predicate operation for {@code attribute_exists} and
+ * {@code attribute_not_exists}.
+ */
 public class ExistsOperation extends QueryOperation {
 
     private final String fieldName;
     //true = exists, false = not exists
     private final boolean exists;
 
+    /**
+     * Creates an existence operation.
+     *
+     * @param fieldName attribute path
+     * @param exists {@code true} for exists, {@code false} for not-exists
+     */
     public ExistsOperation(String fieldName, boolean exists) {
         this.fieldName = fieldName;
         this.exists = exists;