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

/**
 * Outbound-Port zum Lesen und Schreiben der Scheduler-Einstellungen
 * in der {@code .properties}-Konfigurationsdatei.
 * <p>
 * Schreiboperationen aktualisieren ausschließlich den Scheduler-Key
 * {@code scheduler.interval.seconds}. Alle übrigen Zeilen, Kommentare
 * und unbekannten Properties bleiben unverändert erhalten.
 * <p>
 * Schreibvorgänge sind atomar: Sie erfolgen über eine temporäre Datei,
 * die erst nach vollständigem Schreiben an den Zielort verschoben wird.
 * Bei einem Fehler bleibt die Originaldatei unverändert.
 * <p>
 * Die Implementierung teilt sich einen {@code FileChannel} mit dem
 * {@link ConfigurationFileLockPort}-Adapter, damit Settings auch
 * während eines aktiven OS-Locks geschrieben werden können.
 */
public interface SchedulerSettingsPort {

    /**
     * Liest die aktuellen Scheduler-Einstellungen aus der
     * Konfigurationsdatei.
     * <p>
     * Fehlt ein Key oder ist er leer, wird der jeweilige Standardwert
     * zurückgegeben (siehe {@link SchedulerSettings#defaults()}).
     * Ungültige Werte (z.B. nicht-numerisches Intervall) werden als
     * Fehler in {@code SchedulerSettings} signalisiert und führen nicht
     * zu einer Exception in diesem Port.
     *
     * @return gelesene Scheduler-Einstellungen; nie {@code null}
     */
    SchedulerSettings loadSettings();

    /**
     * Schreibt den Wert von {@code scheduler.interval.seconds} in die
     * Konfigurationsdatei.
     * <p>
     * Alle übrigen Inhalte der Datei bleiben unverändert.
     *
     * @param seconds neues Intervall in Sekunden; muss mindestens 30 betragen
     * @throws SchedulerSettingsWriteException wenn der Schreibvorgang fehlschlägt
     */
    void saveIntervalSeconds(int seconds) throws SchedulerSettingsWriteException;
}
