📝 Add comprehensive JavaDoc to org.restheart.configuration package of module commons

Author: ujibang

commons/src/main/java/org/restheart/configuration/Configuration.java

@@ -20,33 +20,91 @@
 package org.restheart.configuration;
 
 /**
- *
+ * Exception thrown when configuration loading or validation fails.
+ * 
+ * <p>This exception is thrown in various scenarios:</p>
+ * <ul>
+ *   <li>Configuration file is not found or cannot be read</li>
+ *   <li>Configuration file has invalid syntax (YAML/JSON parse errors)</li>
+ *   <li>Required configuration properties are missing</li>
+ *   <li>Configuration values are invalid or out of acceptable range</li>
+ *   <li>Override files have unsupported extensions or invalid format</li>
+ * </ul>
+ * 
+ * <p>The exception includes a flag {@code shouldPrintStackTrace} that indicates
+ * whether the full stack trace should be printed. This is typically set to false
+ * for user-friendly errors (like missing files) and true for unexpected errors
+ * (like parse exceptions).</p>
+ * 
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
+ * @since 1.0
  */
 public class ConfigurationException extends IllegalArgumentException {
     private static final long serialVersionUID = 1685800316196830205L;
     private final boolean shoudlPrintStackTrace;
 
+    /**
+     * Constructs a new ConfigurationException with no message.
+     * 
+     * <p>Stack trace printing is disabled by default for this constructor.</p>
+     */
     public ConfigurationException() {
         super();
         this.shoudlPrintStackTrace = false;
     }
 
+    /**
+     * Constructs a new ConfigurationException with the specified message.
+     * 
+     * <p>Stack trace printing is disabled by default for this constructor.
+     * This is typically used for user-friendly error messages.</p>
+     * 
+     * @param message the detail message explaining the configuration error
+     */
     public ConfigurationException(String message) {
         super(message);
         this.shoudlPrintStackTrace = false;
     }
 
+    /**
+     * Constructs a new ConfigurationException with message and cause.
+     * 
+     * <p>Stack trace printing is enabled by default for this constructor.
+     * This is typically used for unexpected errors that require debugging.</p>
+     * 
+     * @param message the detail message explaining the configuration error
+     * @param cause the underlying cause of the configuration error
+     */
     public ConfigurationException(String message, Throwable cause) {
         super(message, cause);
         this.shoudlPrintStackTrace = true;
     }
 
+    /**
+     * Constructs a new ConfigurationException with full control over stack trace printing.
+     * 
+     * <p>This constructor allows explicit control over whether the stack trace
+     * should be printed when the exception is logged. Use this when you want
+     * to provide a cause but control the verbosity of error output.</p>
+     * 
+     * @param message the detail message explaining the configuration error
+     * @param cause the underlying cause of the configuration error
+     * @param shoudlPrintStackTrace true if stack trace should be printed when logged
+     */
     public ConfigurationException(String message, Throwable cause, boolean shoudlPrintStackTrace) {
         super(message, cause);
         this.shoudlPrintStackTrace = shoudlPrintStackTrace;
     }
 
+    /**
+     * Indicates whether the stack trace should be printed when this exception is logged.
+     * 
+     * <p>This is used by error handlers to determine the appropriate level of
+     * detail to show to users. User-friendly errors (like missing files) typically
+     * return false, while unexpected errors return true.</p>
+     * 
+     * @return true if the stack trace should be printed, false otherwise
+     */
     public boolean shoudlPrintStackTrace() {
         return shoudlPrintStackTrace;
     }

commons/src/main/java/org/restheart/configuration/ConfigurationException.java

@@ -26,6 +26,45 @@
 import static org.restheart.configuration.Utils.asMap;
 import static org.restheart.configuration.Utils.getOrDefault;
 
+/**
+ * Core configuration module containing essential RESTHeart settings.
+ * 
+ * <p>This record encapsulates the core configuration parameters that control
+ * RESTHeart's fundamental behavior including plugin management, threading,
+ * buffering, and URL handling.</p>
+ * 
+ * <h2>Configuration Structure</h2>
+ * <p>In the configuration file, these settings are under the {@code core} section:</p>
+ * <pre>{@code
+ * core:
+ *   name: "my-restheart"
+ *   plugins-directory: "./plugins"
+ *   plugins-packages:
+ *     - "org.restheart.plugins"
+ *     - "com.example.myplugins"
+ *   io-threads: 4
+ *   workers-scheduler-parallelism: 8
+ *   buffer-size: 16384
+ *   direct-buffers: true
+ * }</pre>
+ * 
+ * @param name the instance name for this RESTHeart server
+ * @param pluginsDirectory path to the directory containing plugin JARs
+ * @param pluginsPackages list of Java packages to scan for plugins
+ * @param pluginsScanningVerbose if true, enables verbose logging during plugin scanning
+ * @param baseUrl the base URL for this instance (optional, for URL construction)
+ * @param ioThreads number of I/O threads (0 for automatic based on CPU cores)
+ * @param workersSchedulerParallelism parallelism level for the workers thread pool
+ * @param workersSchedulerMaxPoolSize maximum size of the workers thread pool
+ * @param buffersPooling if true, enables buffer pooling for better performance
+ * @param bufferSize size of I/O buffers in bytes
+ * @param directBuffers if true, uses direct (off-heap) buffers
+ * @param forceGzipEncoding if true, forces GZIP encoding for all responses
+ * @param allowUnescapedCharsInUrl if true, allows unescaped characters in URLs
+ * 
+ * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
+ * @since 1.0
+ */
 public record CoreModule(String name,
         String pluginsDirectory,
         List<String> pluginsPackages,
@@ -40,23 +79,104 @@ public record CoreModule(String name,
         boolean forceGzipEncoding,
         boolean allowUnescapedCharsInUrl) {
 
+    /**
+     * Configuration key for the core section in the configuration file.
+     */
     public static final String CORE_KEY = "core";
+    
+    /**
+     * Configuration key for the instance name.
+     */
     public static final String INSTANCE_NAME_KEY = "name";
+    
+    /**
+     * Configuration key for the plugins directory path.
+     */
     public static final String PLUGINS_DIRECTORY_PATH_KEY = "plugins-directory";
+    
+    /**
+     * Configuration key for the list of packages to scan for plugins.
+     */
     public static final String PLUGINS_PACKAGES_KEY = "plugins-packages";
+    
+    /**
+     * Configuration key for enabling verbose plugin scanning output.
+     */
     public static final String PLUGINS_SCANNING_VERBOSE_KEY = "plugins-scanning-verbose";
+    
+    /**
+     * Configuration key for the base URL of this instance.
+     */
     public static final String BASE_URL_KEY = "base-url";
+    
+    /**
+     * Configuration key for the number of I/O threads.
+     */
     public static final String IO_THREADS_KEY = "io-threads";
+    
+    /**
+     * Configuration key for workers scheduler parallelism level.
+     */
     public static final String WORKERS_SCHEDULER_PARALLELISM_KEY ="workers-scheduler-parallelism";
+    
+    /**
+     * Configuration key for workers scheduler maximum pool size.
+     */
     public static final String WORKERS_SCHEDULER_MAX_POOL_SIZE_KEY = "workers-scheduler-max-pool-size";
+    
+    /**
+     * Configuration key for enabling buffer pooling.
+     */
     public static final String BUFFERS_POOLING_KEY = "buffers-pooling";
+    
+    /**
+     * Configuration key for the I/O buffer size in bytes.
+     */
     public static final String BUFFER_SIZE_KEY = "buffer-size";
+    
+    /**
+     * Configuration key for enabling direct (off-heap) buffers.
+     */
     public static final String DIRECT_BUFFERS_KEY = "direct-buffers";
+    
+    /**
+     * Configuration key for forcing GZIP encoding on responses.
+     */
     public static final String FORCE_GZIP_ENCODING_KEY = "force-gzip-encoding";
+    
+    /**
+     * Configuration key for allowing unescaped characters in URLs.
+     */
     public static final String ALLOW_UNESCAPED_CHARS_IN_ULR_KEY = "allow-unescaped-characters-in-url";
 
+    /**
+     * Default CoreModule configuration used when no configuration is provided.
+     * 
+     * <p>Default values:</p>
+     * <ul>
+     *   <li>name: "default"</li>
+     *   <li>plugins-directory: "plugins"</li>
+     *   <li>plugins-packages: empty list</li>
+     *   <li>io-threads: 0 (auto-detect based on CPU cores)</li>
+     *   <li>workers-scheduler-parallelism: 0 (uses default)</li>
+     *   <li>workers-scheduler-max-pool-size: 256</li>
+     *   <li>buffer-size: 16384 bytes</li>
+     *   <li>direct-buffers: true</li>
+     *   <li>force-gzip-encoding: false</li>
+     *   <li>allow-unescaped-characters-in-url: true</li>
+     * </ul>
+     */
     private static final CoreModule DEFAULT_CORE_MODULE = new CoreModule("default", "plugins", new ArrayList<>(), false, null, 0, 0, 256, true, 16364, true, false, true);
 
+    /**
+     * Creates a CoreModule from a configuration map.
+     * 
+     * <p>This constructor extracts core configuration values from the provided map,
+     * using default values for any missing properties.</p>
+     * 
+     * @param conf the configuration map containing core settings
+     * @param silent if true, suppresses warning messages for missing optional properties
+     */
     public CoreModule(Map<String, Object> conf, boolean silent) {
         this(getOrDefault(conf, INSTANCE_NAME_KEY, DEFAULT_CORE_MODULE.name(), silent),
             getOrDefault(conf, PLUGINS_DIRECTORY_PATH_KEY, DEFAULT_CORE_MODULE.pluginsDirectory(), silent),
@@ -76,6 +196,17 @@ public CoreModule(Map<String, Object> conf, boolean silent) {
             getOrDefault(conf, ALLOW_UNESCAPED_CHARS_IN_ULR_KEY, DEFAULT_CORE_MODULE.allowUnescapedCharsInUrl(), true));
     }
 
+    /**
+     * Builds a CoreModule from the main configuration map.
+     * 
+     * <p>This method looks for the {@code core} section in the configuration map.
+     * If found, it creates a CoreModule from that section. If not found, returns
+     * the default CoreModule configuration.</p>
+     * 
+     * @param conf the main configuration map
+     * @param silent if true, suppresses warning messages for missing optional properties
+     * @return a CoreModule instance with configuration values or defaults
+     */
     public static CoreModule build(Map<String, Object> conf, boolean silent) {
         var core = asMap(conf, CORE_KEY, null, silent);
 

commons/src/main/java/org/restheart/configuration/CoreModule.java

@@ -22,13 +22,82 @@
 import static org.restheart.configuration.Utils.findOrDefault;
 import java.util.Map;
 
+/**
+ * Configuration for HTTP and AJP protocol listeners.
+ * 
+ * <p>This record represents the configuration for network listeners that handle
+ * incoming HTTP or AJP (Apache JServ Protocol) connections. Each listener can be
+ * independently enabled or disabled and configured with specific host and port
+ * bindings.</p>
+ * 
+ * <h2>Configuration Structure</h2>
+ * <p>In the configuration file, listeners are configured as:</p>
+ * <pre>{@code
+ * http-listener:
+ *   enabled: true
+ *   host: "0.0.0.0"
+ *   port: 8080
+ * 
+ * ajp-listener:
+ *   enabled: false
+ *   host: "localhost"
+ *   port: 8009
+ * }</pre>
+ * 
+ * <h2>Host Binding</h2>
+ * <p>The host parameter controls which network interfaces the listener binds to:</p>
+ * <ul>
+ *   <li>{@code "localhost"} or {@code "127.0.0.1"} - only local connections</li>
+ *   <li>{@code "0.0.0.0"} - all available interfaces (use with caution)</li>
+ *   <li>Specific IP address - binds to that interface only</li>
+ * </ul>
+ * 
+ * @param enabled whether this listener should be activated
+ * @param host the hostname or IP address to bind to
+ * @param port the port number to listen on
+ * 
+ * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
+ * @since 1.0
+ */
 public record Listener(boolean enabled, String host, int port) {
+    /**
+     * Configuration key for the HTTP listener section.
+     */
     public static final String HTTP_LISTENER_KEY = "http-listener";
+    
+    /**
+     * Configuration key for the AJP listener section.
+     */
     public static final String AJP_LISTENER_KEY = "ajp-listener";
+    
+    /**
+     * Configuration key for enabling/disabling the listener.
+     */
     public static final String ENABLED_KEY = "enabled";
+    
+    /**
+     * Configuration key for the host/IP binding.
+     */
     public static final String HOST_KEY = "host";
+    
+    /**
+     * Configuration key for the port number.
+     */
     public static final String PORT_KEY = "port";
 
+    /**
+     * Creates a Listener from a configuration map.
+     * 
+     * <p>This constructor extracts listener configuration values from the provided map
+     * under the specified listener key (e.g., "http-listener" or "ajp-listener").
+     * If any values are missing, the corresponding values from the defaultValue
+     * parameter are used.</p>
+     * 
+     * @param conf the main configuration map
+     * @param listenerKey the key for this listener section (e.g., "http-listener")
+     * @param defaultValue default values to use for missing configuration
+     * @param silent if true, suppresses warning messages for missing properties
+     */
     public Listener(Map<String, Object> conf, String listenerKey, Listener defaultValue, boolean silent) {
         this(findOrDefault(conf, "/" + listenerKey + "/" + ENABLED_KEY, defaultValue.enabled(), silent),
             findOrDefault(conf, "/" + listenerKey + "/" + HOST_KEY, defaultValue.host(), silent),