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

/**
 * Outbound-Port für den exklusiven OS-Lock auf die Konfigurationsdatei.
 * <p>
 * Solange der Scheduler läuft oder ein Verarbeitungslauf aktiv ist, hält
 * die Anwendung einen exklusiven Lock auf die {@code .properties}-Datei.
 * Dieser Lock schützt vor konkurrierenden Schreibzugriffen durch externe
 * Prozesse (z.B. Texteditoren).
 * <p>
 * Der Lock wird als bestmöglicher OS-Level-Schreibschutz betrachtet und
 * erhebt keinen Anspruch darauf, alle externen Schreibstrategien zu
 * verhindern (z.B. Delete-Rename durch manche Editoren).
 * <p>
 * Alle Operationen müssen im Worker-Thread ausgeführt werden,
 * niemals auf dem JavaFX Application Thread.
 */
public interface ConfigurationFileLockPort {

    /**
     * Erwirbt den exklusiven OS-Lock auf die Konfigurationsdatei.
     * <p>
     * Falls die Datei bereits durch einen anderen Prozess gesperrt ist,
     * wird der Erwerb mit einer konfigurierbaren Deadline-Schleife
     * versucht. Schlägt der Erwerb nach Ablauf der Deadline fehl,
     * wird eine {@link ConfigurationFileLockException} geworfen.
     * <p>
     * Ist der Lock bereits durch diese Instanz gehalten, hat dieser
     * Aufruf keine Wirkung.
     *
     * @throws ConfigurationFileLockException wenn der Lock nicht innerhalb
     *         der Deadline erworben werden kann
     */
    void acquireLock() throws ConfigurationFileLockException;

    /**
     * Gibt den exklusiven Lock frei.
     * <p>
     * Ist kein Lock aktiv, hat dieser Aufruf keine Wirkung (idempotent).
     * Implementierungen dürfen bei der Freigabe keine geprüfte Ausnahme
     * werfen; Fehler werden geloggt und still übergangen.
     */
    void releaseLock();

    /**
     * Prüft, ob der Lock aktuell von dieser Instanz gehalten wird.
     *
     * @return {@code true}, wenn der Lock aktiv ist
     */
    boolean isLocked();
}
