package de.gecheckt.pdf.umbenenner.application.port.out;

import java.nio.file.Path;
import java.util.Optional;

/**
 * Outbound-Port, der die zur Laufzeit aktive SQLite-Datenbankdatei der Anwendung kapselt.
 * <p>
 * Eigentümer der „aktiven DB-Referenz" zur Laufzeit. Der Port erlaubt es, die aktive
 * Datenbank über einen In-Memory-Override umzustellen, ohne die Konfigurationsdatei
 * (`.properties`) zu verändern. Die GUI nutzt diesen Mechanismus, damit nach dem Anlegen
 * einer neuen Datenbank sofort sämtliche DB-Operationen (Verlauf, Reset, Löschen,
 * Verarbeitungsläufe) gegen die neue Datei laufen, bevor der Benutzer die Konfiguration
 * speichert.
 * <p>
 * <strong>Architekturgrenze:</strong> Der Port arbeitet ausschließlich mit
 * {@link java.nio.file.Path} und kennt keine JDBC- oder SQLite-spezifischen Typen.
 * Wie die Implementierung den Override technisch wirksam macht (z. B. durch Ersetzen
 * der JDBC-URL beim Verdrahten neuer SQLite-Adapter), ist Adapter-Detail.
 */
public interface ActiveDatabaseContextPort {

    /**
     * Stellt die aktive SQLite-Datenbankdatei der Anwendung um.
     * <p>
     * Nach dem Aufruf verwenden alle nachfolgenden DB-Operationen die übergebene Datei
     * als aktive Datenbank, sofern keine andere Datei explizit übergeben wird.
     *
     * @param newDbFile absoluter Pfad der neuen aktiven Datenbankdatei; darf nicht
     *                  {@code null} sein. Die Datei muss zum Zeitpunkt des Aufrufs
     *                  existieren, ein gültiges SQLite-Schema enthalten und lesbar sein
     *                  (Verbindung muss bereits durch den Aufrufer verifiziert worden sein).
     * @throws NullPointerException wenn {@code newDbFile} {@code null} ist
     */
    void switchActiveDatabase(Path newDbFile);

    /**
     * Liefert den aktuell aktiven DB-Pfad als Override, sofern einer gesetzt wurde.
     * <p>
     * Solange kein Override gesetzt wurde, gilt die in der jeweiligen
     * {@link de.gecheckt.pdf.umbenenner.application.config.startup.StartConfiguration}
     * konfigurierte Datenbankdatei. Erst nach dem ersten Aufruf von
     * {@link #switchActiveDatabase(Path)} liefert diese Methode einen nicht-leeren Wert.
     *
     * @return das gesetzte Override (nicht-leer) oder {@link Optional#empty()}, wenn die
     *         konfigurierte Datenbank weiterhin verwendet werden soll; nie {@code null}
     */
    Optional<Path> activeDatabaseOverride();
}
