package de.gecheckt.pdf.umbenenner.adapter.in.gui;

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.application.port.in.CreateNewDatabaseUseCase.CreateNewDatabaseResult;

/**
 * GUI-internes Bridge-Interface zwischen dem Workspace und dem
 * {@link de.gecheckt.pdf.umbenenner.application.port.in.CreateNewDatabaseUseCase}.
 * <p>
 * Dieses Interface ist <em>kein</em> hexagonaler Outbound-Port der Application-Schicht.
 * Es ist eine modul-interne Brücke, über die Bootstrap die DB-Anlage- und Wechsellogik
 * für die GUI bereitstellt, ohne dass der GUI-Adapter direkt auf den Use-Case oder die
 * darunterliegenden Outbound-Ports zugreift.
 * <p>
 * <strong>Threading:</strong> Implementierungen dürfen blockierende Operationen
 * ausführen (Flyway-Migration, Verbindungstest, atomares Verschieben einer Datei).
 * Sie müssen daher von einem Hintergrund-Worker-Thread aufgerufen werden. Der Aufruf
 * blockiert, bis das Ergebnis vollständig vorliegt.
 */
@FunctionalInterface
public interface GuiCreateNewDatabasePort {

    /**
     * Legt eine neue, leere SQLite-Datenbankdatei am übergebenen Zielpfad an und
     * stellt die aktive Datenbankreferenz auf diese Datei um.
     *
     * @param configFilePath Pfad zur aktuell geladenen {@code .properties}-Datei,
     *                       oder {@code null}, wenn (noch) keine Konfiguration
     *                       geladen ist. Die Bootstrap-Implementierung leitet
     *                       daraus den Pfad der aktuell aktiven SQLite-Datei ab,
     *                       sofern noch kein Override vom
     *                       {@link de.gecheckt.pdf.umbenenner.application.port.out.ActiveDatabaseContextPort}
     *                       gesetzt ist.
     * @param targetFile     der vom Benutzer ausgewählte Zielpfad; darf nicht
     *                       {@code null} sein
     * @return strukturiertes Ergebnis mit Erfolg oder klassifiziertem Fehler;
     *         nie {@code null}
     */
    CreateNewDatabaseResult createNewDatabase(Path configFilePath, Path targetFile);
}
