diff --git a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/StartConfigurationValidator.java b/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/StartConfigurationValidator.java index cc08560..9d031f5 100644 --- a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/StartConfigurationValidator.java +++ b/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. + *

+ * Used for paths like source and target folders that must already exist before processing can begin. */ private void validateRequiredExistingDirectory(Path path, String fieldName, List 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. + *

+ * 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 errors) { if (filePath == null) { diff --git a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/package-info.java b/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/package-info.java index 882966a..80db16e 100644 --- a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/bootstrap/validation/package-info.java +++ b/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. *

- * 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. + *

+ * Validation concerns include: + *

+ *

+ * 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; diff --git a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapter.java b/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapter.java index 7d1faa6..ecc5a97 100644 --- a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/PropertiesConfigurationPortAdapter.java +++ b/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}. *

- * 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 { diff --git a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/package-info.java b/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/package-info.java index ed71573..5a69e6b 100644 --- a/pdf-umbenenner-adapter-out/src/main/java/de/gecheckt/pdf/umbenenner/adapter/out/configuration/package-info.java +++ b/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. *

* 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). *

+ * Responsibilities: + *

+ *

* 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; \ No newline at end of file diff --git a/pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunner.java b/pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunner.java index 7ae707c..20a339d 100644 --- a/pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunner.java +++ b/pdf-umbenenner-bootstrap/src/main/java/de/gecheckt/pdf/umbenenner/bootstrap/BootstrapRunner.java @@ -41,17 +41,19 @@ import de.gecheckt.pdf.umbenenner.domain.model.BatchRunContext; import de.gecheckt.pdf.umbenenner.domain.model.RunId; /** - * Manual bootstrap runner that constructs the object graph and drives the startup flow. + * Orchestrator for the complete startup sequence and object graph construction. *

- * Responsibilities: + * Separates startup concerns into two distinct phases: *

    - *
  1. Load and validate the startup configuration.
    2. - *
  2. Initialise the SQLite persistence schema.
    3. - *
  3. Resolve the run-lock file path (with default fallback).
    4. - *
  4. Create and wire all ports and adapters via configured factories.
    5. - *
  5. Start the CLI adapter and execute the batch use case.
    6. - *
  6. Map the batch outcome to a process exit code.
    7. + *
  7. Bootstrap Phase: Load and validate configuration, initialize persistence schema, + * establish run-lock, and prepare all adapters and ports.
    8. + *
  8. Execution Phase: Wire and execute the batch processing use case, then map outcome to exit code.
    9. *
+ *

+ * The startup configuration encompasses all technical infrastructure and runtime parameters + * needed for bootstrap and execution. Once validated and the schema is initialized, + * configuration is handed to the use case factory which extracts the minimal runtime + * configuration for the application layer. * *

Exit code semantics

*