Optimierung: Bootstrap- und Konfigurationsdokumentation punktuell

geschärft

pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/StartConfigurationValidator.java

@@ -212,7 +212,9 @@ public class StartConfigurationValidator {
     // === Helper methods for common validation patterns ===
 
     /**
-     * Validates that a required path is not null, exists, and is a directory.
+     * Validates that a required directory path is not null, exists, and is a directory.
+     * <p>
+     * Used for paths like source and target folders that must already exist before processing can begin.
      */
     private void validateRequiredExistingDirectory(Path path, String fieldName, List<String> errors) {
         if (path == null) {
@@ -228,6 +230,10 @@ public class StartConfigurationValidator {
 
     /**
      * Validates that a required file path is not null and its parent directory exists and is a directory.
+     * <p>
+     * The file itself may not exist yet (e.g., SQLite will create it on first use), but the parent
+     * directory must be present and writable. Used for files like sqlite.file where the application
+     * will create the file if needed.
      */
     private void validateRequiredFileParentDirectory(Path filePath, String fieldName, List<String> errors) {
         if (filePath == null) {

pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/package-info.java

@@ -1,8 +1,21 @@
 /**
  * Bootstrap-phase technical configuration validation.
  * <p>
- * Handles startup configuration validation before the batch application begins.
- * Validates mandatory fields, numeric ranges, URI schemes, and path existence.
- * Technical responsibility that does not belong to the application layer.
+ * Handles startup configuration validation as a separate step after configuration loading.
+ * Validates mandatory fields, numeric ranges, URI schemes, and path existence before
+ * the batch application begins. If validation fails, the application exits with code 1.
+ * <p>
+ * Validation concerns include:
+ * <ul>
+ *   <li>Mandatory field presence and non-nullness</li>
+ *   <li>Numeric constraints (timeout, retry limits, page counts, character limits)</li>
+ *   <li>URI validity (API base URL must be absolute with http or https scheme)</li>
+ *   <li>Path existence and type (source/target folders exist and are readable, etc.)</li>
+ *   <li>Path relationships (source and target folders are not the same)</li>
+ * </ul>
+ * <p>
+ * This validation is a technical responsibility that does not belong to the application layer
+ * and is distinct from configuration loading. The validator is created and invoked by the
+ * bootstrap phase after configuration is loaded.
  */
 package de.gecheckt.pdf.umbenenner.adapter.out.bootstrap.validation;

pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapter.java

@@ -20,8 +20,10 @@ import de.gecheckt.pdf.umbenenner.application.port.out.ConfigurationPort;
 /**
  * Properties-based implementation of {@link ConfigurationPort}.
  * <p>
- * Loads configuration from config/application.properties with environment variable
- * precedence for sensitive values like the API key.
+ * Loads configuration from config/application.properties as the primary source.
+ * For sensitive values, environment variables take precedence: if the environment variable
+ * {@code PDF_UMBENENNER_API_KEY} is set, it overrides the {@code api.key} property from the file.
+ * This allows credentials to be managed securely without storing them in the configuration file.
  */
 public class PropertiesConfigurationPortAdapter implements ConfigurationPort {
 

pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/package-info.java

@@ -1,12 +1,21 @@
 /**
- * Configuration loading adapters.
+ * Configuration loading adapters for the bootstrap phase.
  * <p>
  * Contains implementations of the {@link de.gecheckt.pdf.umbenenner.application.port.out.ConfigurationPort}
- * that load the {@link de.gecheckt.pdf.umbenenner.application.config.startup.StartConfiguration}
+ * that load the complete {@link de.gecheckt.pdf.umbenenner.application.config.startup.StartConfiguration}
  * from external sources (e.g., properties files, environment variables).
  * <p>
+ * Responsibilities:
+ * <ul>
+ *   <li>Load configuration from the properties file (default: config/application.properties)</li>
+ *   <li>Apply environment variable precedence for sensitive values (e.g., API key)</li>
+ *   <li>Construct the typed StartConfiguration object with all technical infrastructure parameters</li>
+ * </ul>
+ * <p>
  * These adapters bridge the outbound port contract with concrete infrastructure
- * (property file parsing, environment variable lookup) without leaking infrastructure
- * details into the application or bootstrap layers.
+ * (property file parsing, environment variable lookup) without leaking infrastructure details
+ * into the application or bootstrap layers. Validation of the loaded configuration is performed
+ * separately by the {@link de.gecheckt.pdf.umbenenner.adapter.out.bootstrap.validation.StartConfigurationValidator}
+ * in the bootstrap phase.
  */
 package de.gecheckt.pdf.umbenenner.adapter.out.configuration;