📝 Add comprehensive JavaDoc to org.restheart.utils package

Author: ujibang

commons/src/main/java/org/restheart/utils/BsonUtils.java

@@ -75,32 +75,56 @@
 import org.slf4j.LoggerFactory;
 
 /**
+ * Utility class providing comprehensive BSON document manipulation operations.
+ * This class contains methods for parsing, converting, escaping, and manipulating
+ * BSON documents and values. It supports operations like key escaping/unescaping,
+ * path-based property access, document flattening/unflattening, and JSON conversion.
+ *
+ * <p>Key features include:</p>
+ * <ul>
+ * <li>Key escaping for MongoDB compatibility (handles $ and . characters)</li>
+ * <li>XPath-style property access using dot notation</li>
+ * <li>Document flattening and unflattening operations</li>
+ * <li>JSON parsing and serialization</li>
+ * <li>Update operator detection and validation</li>
+ * <li>Builder patterns for document and array construction</li>
+ * </ul>
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class BsonUtils {
 
+    /** Logger instance for this class. */
     static final Logger LOGGER = LoggerFactory.getLogger(BsonUtils.class);
 
+    /** Codec for encoding/decoding BSON arrays. */
     private static final BsonArrayCodec BSON_ARRAY_CODEC = new BsonArrayCodec(CodecRegistries.fromProviders(new BsonValueCodecProvider()));
+    
+    /** Codec registry for document encoding/decoding operations. */
     private static final CodecRegistry REGISTRY = CodecRegistries.fromCodecs(new DocumentCodec());
 
+    /** Escaped representation of the dollar sign character. */
     private static final String ESCAPED_DOLLAR = "_$";
+    
+    /** Escaped representation of the dot character. */
     private static final String ESCAPED_DOT = "::";
+    
+    /** The dollar sign character. */
     private static final String DOLLAR = "$";
 
     /**
-     * replaces the underscore prefixed keys (eg _$exists) with the
-     * corresponding key (eg $exists) and the dot (.) in property names. This is
-     * needed because MongoDB does not allow to store keys that starts with $
-     * and with dots in it
+     * Replaces the underscore prefixed keys (e.g., _$exists) with the
+     * corresponding key (e.g., $exists) and replaces escaped dots (::) with 
+     * actual dots (.) in property names. This operation reverses the escaping
+     * applied by {@link #escapeKeys(BsonValue)} method.
      *
-     * See
-     * https://docs.mongodb.org/manual/reference/limits/#Restrictions-on-Field-Names
+     * <p>This is needed because MongoDB does not allow storing keys that start with $
+     * and contain dots in them.</p>
      *
-     * @param json
-     * @return the json object where the underscore prefixed keys are replaced
-     * with the corresponding keys
+     * @param json the BSON value to process (can be document, array, or primitive)
+     * @return the BSON value where the underscore prefixed keys are replaced
+     *         with the corresponding unescaped keys, or null if input is null
+     * @see <a href="https://docs.mongodb.org/manual/reference/limits/#Restrictions-on-Field-Names">MongoDB Field Name Restrictions</a>
      */
     public static BsonValue unescapeKeys(BsonValue json) {
         if (json == null) {
@@ -156,14 +180,15 @@ public static BsonValue unescapeKeys(BsonValue json) {
     }
 
     /**
-     * replaces the dollar prefixed keys (eg $exists) with the corresponding
-     * underscore prefixed key (eg _$exists). Also replaces dots if escapeDots
-     * is true. This is needed because MongoDB does not allow to store keys that
-     * starts with $ and that contains dots.
+     * Replaces the dollar prefixed keys (e.g., $exists) with the corresponding
+     * underscore prefixed key (e.g., _$exists). Also replaces dots with escaped
+     * dots (::) if escapeDots is true. This is needed because MongoDB does not 
+     * allow storing keys that start with $ and contain dots.
      *
-     * @param json
-     * @param escapeDots
-     * @return the json object where the keys are escaped
+     * @param json the BSON value to process (can be document, array, or primitive)
+     * @param escapeDots if true, dots in keys will be replaced with "::"
+     * @return the BSON value where the keys are escaped for MongoDB compatibility,
+     *         or null if input is null
      */
     public static BsonValue escapeKeys(BsonValue json, boolean escapeDots) {
         return escapeKeys(json, escapeDots, false);
@@ -738,10 +763,12 @@ public static String toJson(BsonValue bson, JsonMode mode) {
     }
 
     /**
+     * Converts a BSON value representing an ID to its string representation.
+     * Handles different BSON types appropriately and can optionally quote string values.
      *
-     * @param id
-     * @param quote
-     * @return the String representation of the id
+     * @param id the BSON value to convert to string
+     * @param quote if true, string values will be wrapped in single quotes
+     * @return the string representation of the ID, or null if id is null
      */
     public static String getIdAsString(BsonValue id, boolean quote) {
         if (id == null) {
@@ -757,12 +784,14 @@ public static String getIdAsString(BsonValue id, boolean quote) {
         }
     }
 
+    /** Default codec registry from MongoDB client settings for BSON encoding/decoding operations. */
     public static final CodecRegistry DEFAULT_CODEC_REGISTRY = MongoClientSettings.getDefaultCodecRegistry();
 
     /**
+     * Converts a Map to a BsonDocument using the default codec registry.
      *
-     * @param map
-     * @return
+     * @param map the map to convert to BSON document
+     * @return the BsonDocument representation of the map, or null if map is null
      */
     public static BsonDocument toBsonDocument(Map<String, ? super Object> map) {
         if (map == null) {

commons/src/main/java/org/restheart/utils/BuffersUtils.java

@@ -32,17 +32,25 @@
 import io.undertow.server.HttpServerExchange;
 
 /**
+ * Utility class for handling buffer operations and conversions.
+ * Provides methods for converting between different buffer types, managing
+ * pooled byte buffers, and performing buffer operations safely with size limits.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class BuffersUtils {
 
+    /** Logger instance for this class. */
     private static final Logger LOGGER = LoggerFactory.getLogger(BuffersUtils.class);
 
     /**
-     * @param srcs
-     * @return
-     * @throws java.io.IOException
+     * Converts an array of pooled byte buffers to a single ByteBuffer.
+     * This method consolidates multiple pooled buffers into one continuous buffer,
+     * respecting the maximum content size limit.
+     *
+     * @param srcs array of pooled byte buffers to convert
+     * @return a ByteBuffer containing all the data from the source buffers, or null if srcs is null
+     * @throws IOException if the total content exceeds the maximum allowed size
      */
     public static ByteBuffer toByteBuffer(final PooledByteBuffer[] srcs) throws IOException {
         if (srcs == null) {
@@ -72,6 +80,15 @@ public static ByteBuffer toByteBuffer(final PooledByteBuffer[] srcs) throws IOEx
         return dst.flip();
     }
 
+    /**
+     * Converts an array of pooled byte buffers to a byte array.
+     * This method first converts the pooled buffers to a ByteBuffer and then
+     * extracts the data as a byte array.
+     *
+     * @param srcs array of pooled byte buffers to convert
+     * @return a byte array containing all the data from the source buffers
+     * @throws IOException if the conversion fails or content exceeds size limits
+     */
     public static byte[] toByteArray(final PooledByteBuffer[] srcs) throws IOException {
         var content = toByteBuffer(srcs);
 
@@ -82,21 +99,38 @@ public static byte[] toByteArray(final PooledByteBuffer[] srcs) throws IOExcepti
         return ret;
     }
 
+    /**
+     * Converts an array of pooled byte buffers to a string using the specified charset.
+     *
+     * @param srcs array of pooled byte buffers to convert
+     * @param cs the charset to use for string conversion
+     * @return a string representation of the buffer content
+     * @throws IOException if the conversion fails or content exceeds size limits
+     */
     public static String toString(final PooledByteBuffer[] srcs, Charset cs) throws IOException {
         return new String(toByteArray(srcs), cs);
     }
 
+    /**
+     * Converts a byte array to a string using the specified charset.
+     *
+     * @param src the byte array to convert
+     * @param cs the charset to use for string conversion
+     * @return a string representation of the byte array content
+     * @throws IOException if the conversion fails
+     */
     public static String toString(final byte[] src, Charset cs) throws IOException {
         return new String(src, cs);
     }
 
     /**
-     * transfer the src data to the pooled buffers overwriting the exising data
+     * Transfers data from a source ByteBuffer to pooled byte buffers, overwriting existing data.
+     * This method allocates new pooled buffers as needed and clears existing ones before copying.
      *
-     * @param src
-     * @param dest
-     * @param exchange
-     * @return
+     * @param src the source ByteBuffer containing data to transfer
+     * @param dest array of pooled byte buffers to receive the data
+     * @param exchange the HTTP server exchange for accessing the byte buffer pool
+     * @return the number of bytes copied
      */
     public static int transfer(final ByteBuffer src, final PooledByteBuffer[] dest, HttpServerExchange exchange) {
         var byteBufferPool = exchange.getConnection().getByteBufferPool();
@@ -132,6 +166,13 @@ public static int transfer(final ByteBuffer src, final PooledByteBuffer[] dest,
         return copied;
     }
 
+    /**
+     * Dumps the content of pooled byte buffers to the debug log for debugging purposes.
+     * This method logs the hexadecimal representation of each buffer's content.
+     *
+     * @param msg a message to include in the log output
+     * @param data array of pooled byte buffers to dump
+     */
     public static void dump(String msg, PooledByteBuffer[] data) {
         int nbuf = 0;
         for (PooledByteBuffer dest : data) {
@@ -151,12 +192,13 @@ public static void dump(String msg, PooledByteBuffer[] data) {
     }
 
     /**
-     * append the src data to the pooled buffers
+     * Appends data from a source ByteBuffer to pooled byte buffers.
+     * Unlike transfer(), this method appends to existing buffer content rather than overwriting it.
      *
-     * @param src
-     * @param dest
-     * @param exchange
-     * @return
+     * @param src the source ByteBuffer containing data to append
+     * @param dest array of pooled byte buffers to append data to
+     * @param exchange the HTTP server exchange for accessing the byte buffer pool
+     * @return the number of bytes copied
      */
     public static int append(final ByteBuffer src, final PooledByteBuffer[] dest, HttpServerExchange exchange) {
         var byteBufferPool = exchange.getConnection().getByteBufferPool();
@@ -192,6 +234,16 @@ public static int append(final ByteBuffer src, final PooledByteBuffer[] dest, Ht
         return copied;
     }
 
+    /**
+     * Transfers data from source pooled byte buffers to destination pooled byte buffers.
+     * This method copies data between two arrays of pooled buffers, allocating destination
+     * buffers as needed.
+     *
+     * @param src array of source pooled byte buffers
+     * @param dest array of destination pooled byte buffers
+     * @param exchange the HTTP server exchange for accessing the byte buffer pool
+     * @return the number of bytes copied
+     */
     public static int transfer(final PooledByteBuffer[] src, final PooledByteBuffer[] dest, final HttpServerExchange exchange) {
         var byteBufferPool = exchange.getConnection().getByteBufferPool();
         int copied = 0;

commons/src/main/java/org/restheart/utils/ChannelReader.java

@@ -26,15 +26,21 @@
 import io.undertow.server.HttpServerExchange;
 
 /**
+ * Utility class for reading data from HTTP server exchange channels.
+ * Provides convenient methods to read request body content as strings or byte arrays
+ * using Undertow's asynchronous receiver API.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class ChannelReader {
     /**
+     * Reads the complete request body as a string using UTF-8 encoding.
+     * This method uses Undertow's asynchronous receiver to read the full request
+     * content and convert it to a string.
      *
-     * @param exchange
-     * @return
-     * @throws java.io.IOException
+     * @param exchange the HTTP server exchange containing the request body
+     * @return the complete request body as a UTF-8 encoded string
+     * @throws IOException if an I/O error occurs during reading
      */
     public static String readString(HttpServerExchange exchange) throws IOException {
         final var receiver = exchange.getRequestReceiver();
@@ -49,10 +55,13 @@ public static String readString(HttpServerExchange exchange) throws IOException
     }
 
     /**
+     * Reads the complete request body as a byte array.
+     * This method uses Undertow's asynchronous receiver to read the full request
+     * content as raw bytes.
      *
-     * @param exchange
-     * @return
-     * @throws java.io.IOException
+     * @param exchange the HTTP server exchange containing the request body
+     * @return the complete request body as a byte array
+     * @throws IOException if an I/O error occurs during reading
      */
     public static byte[] readBytes(HttpServerExchange exchange) throws IOException {
         final var receiver = exchange.getRequestReceiver();

commons/src/main/java/org/restheart/utils/CheckersUtils.java

@@ -26,23 +26,33 @@
 import org.restheart.exchange.MongoRequest;
 
 /**
+ * Utility class providing validation and checking methods for MongoDB requests.
+ * This class contains methods to analyze request content and determine characteristics
+ * such as whether a request is a bulk operation, uses update operators, or employs
+ * dot notation in field names.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class CheckersUtils {
     /**
+     * Determines if the given MongoDB request is a bulk request.
+     * A request is considered bulk if it either explicitly declares bulk documents
+     * or if its content is an array of documents.
      *
-     * @param request
-     * @return if the request is a bulk request
+     * @param request the MongoDB request to check
+     * @return true if the request is a bulk request, false otherwise
      */
     public static boolean isBulkRequest(MongoRequest request) {
         return request.isBulkDocuments() || request.getContent().isArray();
     }
 
     /**
+     * Determines if the request content includes MongoDB update operators.
+     * This method checks both single documents and arrays of documents for
+     * the presence of update operators like $set, $unset, $inc, etc.
      *
-     * @param content
-     * @return true if the request content includes update operators
+     * @param content the BSON content to analyze (document or array)
+     * @return true if the content includes update operators, false otherwise
      */
     public static boolean doesRequestUseUpdateOperators(BsonValue content) {
         if (content.isDocument()) {
@@ -63,10 +73,13 @@ public static boolean doesRequestUseUpdateOperators(BsonValue content) {
     }
 
     /**
+     * Determines if the request content includes properties identified with dot notation.
+     * Dot notation is used in MongoDB to reference nested fields (e.g., "address.street").
+     * This method checks both single documents and arrays of documents for field names
+     * containing dots.
      *
-     * @param content
-     * @return true if the request content includes properties identified with
-     * the dot notation
+     * @param content the BSON content to analyze (document or array)
+     * @return true if the content includes properties with dot notation, false otherwise
      */
     public static boolean doesRequestUseDotNotation(BsonValue content) {
         if (content.isDocument()) {