Add comprehensive Javadoc documentation to org.restheart.exchange package

   - Enhanced all 37 classes in org.restheart.exchange package with detailed Javadoc
   - Added class-level documentation explaining purpose, features, and usage patterns
   - Documented all public/protected methods with parameters, return values, and exceptions
   - Included comprehensive examples and cross-references
   - Improved documentation for Version.java
   - Follows standard Javadoc conventions for better API documentation

Author: ujibang

commons/src/main/java/org/restheart/exchange/BadRequestException.java

@@ -23,21 +23,39 @@
 import org.restheart.utils.HttpStatus;
 
 /**
+ * Exception thrown when a client request is malformed or contains invalid data.
+ * <p>
+ * This exception is used throughout the RESTHeart framework to signal various
+ * types of client errors, typically resulting in HTTP 4xx status codes. It provides
+ * flexibility in specifying custom status codes, message formats, and content types
+ * for error responses.
+ * </p>
+ * <p>
+ * The exception supports both plain text and JSON error messages, allowing services
+ * to return structured error information when appropriate.
+ * </p>
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class BadRequestException extends RuntimeException {
-    /**
-     *
-     */
+    /** Serial version UID for serialization compatibility. */
     private static final long serialVersionUID = -8466126772297299751L;
 
+    /** The HTTP status code to be returned with this exception. */
     int statusCode = HttpStatus.SC_BAD_REQUEST;
+    
+    /** Flag indicating whether the exception message is valid JSON. */
     private final boolean jsonMessage;
+    
+    /** The content type to be used in the error response. */
     private final String contentType;
 
     /**
-     *
+     * Creates a new BadRequestException with default settings.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code, plain text message format,
+     * and JSON content type.
+     * </p>
      */
     public BadRequestException() {
         super();
@@ -46,8 +64,12 @@ public BadRequestException() {
     }
 
     /**
+     * Creates a new BadRequestException with a custom HTTP status code.
+     * <p>
+     * Uses plain text message format and JSON content type.
+     * </p>
      *
-     * @param statusCode
+     * @param statusCode the HTTP status code to return with this exception
      */
     public BadRequestException(int statusCode) {
         super();
@@ -57,8 +79,13 @@ public BadRequestException(int statusCode) {
     }
 
     /**
+     * Creates a new BadRequestException with a custom error message.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code, plain text message format,
+     * and JSON content type.
+     * </p>
      *
-     * @param message
+     * @param message the error message to include in the exception
      */
     public BadRequestException(String message) {
         super(message);
@@ -67,9 +94,13 @@ public BadRequestException(String message) {
     }
 
     /**
+     * Creates a new BadRequestException with a custom error message and message format.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code and JSON content type.
+     * </p>
      *
-     * @param message
-     * @param jsonMessage mark message as json, i.e. the string is valid json
+     * @param message the error message to include in the exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
      */
     public BadRequestException(String message, boolean jsonMessage) {
         super(message);
@@ -78,10 +109,14 @@ public BadRequestException(String message, boolean jsonMessage) {
     }
 
     /**
+     * Creates a new BadRequestException with custom message, format, and content type.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code.
+     * </p>
      *
-     * @param message
-     * @param jsonMessage mark message as json, i.e. the string is valid json
-     * @param contentType error response content type
+     * @param message the error message to include in the exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param contentType the content type to use in the error response
      */
     public BadRequestException(String message, boolean jsonMessage, String contentType) {
         super(message);
@@ -90,9 +125,13 @@ public BadRequestException(String message, boolean jsonMessage, String contentTy
     }
 
     /**
+     * Creates a new BadRequestException with custom message and status code.
+     * <p>
+     * Uses plain text message format and JSON content type.
+     * </p>
      *
-     * @param message
-     * @param statusCode
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
      */
     public BadRequestException(String message, int statusCode) {
         super(message);
@@ -102,10 +141,14 @@ public BadRequestException(String message, int statusCode) {
     }
 
     /**
+     * Creates a new BadRequestException with custom message, status code, and message format.
+     * <p>
+     * Uses JSON content type.
+     * </p>
      *
-     * @param message
-     * @param statusCode
-     * @param jsonMessage mark message as json, i.e. the string is valid json
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
      */
     public BadRequestException(String message, int statusCode, boolean jsonMessage) {
         super(message);
@@ -115,11 +158,15 @@ public BadRequestException(String message, int statusCode, boolean jsonMessage)
     }
 
     /**
+     * Creates a new BadRequestException with full customization options.
+     * <p>
+     * This constructor provides complete control over all exception properties.
+     * </p>
      *
-     * @param message
-     * @param statusCode
-     * @param jsonMessage mark message as json, i.e. the string is valid json
-     * @param contentType error response content type
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param contentType the content type to use in the error response
      */
     public BadRequestException(String message, int statusCode, boolean jsonMessage, String contentType) {
         super(message);
@@ -129,9 +176,14 @@ public BadRequestException(String message, int statusCode, boolean jsonMessage,
     }
 
     /**
+     * Creates a new BadRequestException with a message and underlying cause.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code, plain text message format,
+     * and plain text content type.
+     * </p>
      *
-     * @param message
-     * @param cause
+     * @param message the error message to include in the exception
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, Throwable cause) {
         super(message, cause);
@@ -140,10 +192,14 @@ public BadRequestException(String message, Throwable cause) {
     }
 
     /**
+     * Creates a new BadRequestException with message, cause, and message format.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code and JSON content type.
+     * </p>
      *
-     * @param message
-     * @param cause
-     * @param jsonMessage mark message as json, i.e. the string is valid json
+     * @param message the error message to include in the exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, boolean jsonMessage, Throwable cause) {
         super(message, cause);
@@ -152,11 +208,15 @@ public BadRequestException(String message, boolean jsonMessage, Throwable cause)
     }
 
     /**
+     * Creates a new BadRequestException with message, cause, format, and content type.
+     * <p>
+     * Uses HTTP 400 (Bad Request) status code.
+     * </p>
      *
-     * @param message
-     * @param cause
-     * @param jsonMessage mark message as json, i.e. the string is valid json
-     * @param contentType error response content type
+     * @param message the error message to include in the exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param contentType the content type to use in the error response
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, boolean jsonMessage, String contentType, Throwable cause) {
         super(message, cause);
@@ -165,10 +225,14 @@ public BadRequestException(String message, boolean jsonMessage, String contentTy
     }
 
     /**
+     * Creates a new BadRequestException with message, status code, and cause.
+     * <p>
+     * Uses plain text message format and JSON content type.
+     * </p>
      *
-     * @param message
-     * @param statusCode
-     * @param cause
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, int statusCode, Throwable cause) {
         super(message, cause);
@@ -178,11 +242,15 @@ public BadRequestException(String message, int statusCode, Throwable cause) {
     }
 
     /**
+     * Creates a new BadRequestException with message, status code, format, and cause.
+     * <p>
+     * Uses JSON content type.
+     * </p>
      *
-     * @param message
-     * @param statusCode
-     * @param jsonMessage mark message as json, i.e. the string is valid json
-     * @param cause
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, int statusCode, boolean jsonMessage, Throwable cause) {
         super(message, cause);
@@ -192,12 +260,17 @@ public BadRequestException(String message, int statusCode, boolean jsonMessage,
     }
 
     /**
+     * Creates a new BadRequestException with full customization and a cause.
+     * <p>
+     * This constructor provides complete control over all exception properties
+     * while also capturing the underlying cause of the error.
+     * </p>
      *
-     * @param message
-     * @param statusCode
-     * @param jsonMessage mark message as json, i.e. the string is valid json
-     * @param contentType error response content type
-     * @param cause
+     * @param message the error message to include in the exception
+     * @param statusCode the HTTP status code to return with this exception
+     * @param jsonMessage true if the message is valid JSON, false for plain text
+     * @param contentType the content type to use in the error response
+     * @param cause the underlying cause of this exception
      */
     public BadRequestException(String message, int statusCode, boolean jsonMessage, String contentType, Throwable cause) {
         super(message, cause);
@@ -207,16 +280,36 @@ public BadRequestException(String message, int statusCode, boolean jsonMessage,
     }
 
     /**
-     * @return the statusCode
+     * Returns the HTTP status code associated with this exception.
+     *
+     * @return the HTTP status code to be returned in the error response
      */
     public int getStatusCode() {
         return statusCode;
     }
 
+    /**
+     * Indicates whether the exception message is formatted as valid JSON.
+     * <p>
+     * When true, the message can be directly used as JSON content in the response.
+     * When false, the message should be treated as plain text.
+     * </p>
+     *
+     * @return true if the message is valid JSON, false otherwise
+     */
     public boolean isJsonMessage() {
         return jsonMessage;
     }
 
+    /**
+     * Returns the content type to be used in the error response.
+     * <p>
+     * This determines how the client should interpret the error message content.
+     * Common values include "application/json" and "text/plain".
+     * </p>
+     *
+     * @return the content type for the error response
+     */
     public String contentType() {
         return this.contentType;
     }