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

/**
 * Funktionales Interface zum Auslösen eines Verarbeitungslaufs.
 * <p>
 * Dieses Interface entkoppelt den Scheduler-Adapter von konkreten
 * Bootstrap- oder GUI-Klassen. Das Bootstrap-Modul erzeugt beim Start
 * eine Implementierung als Lambda und übergibt sie beim Starten des
 * Schedulers an {@link SchedulerPort#startScheduler(SchedulerConfig, BatchRunTrigger)}.
 * <p>
 * <strong>Ausführungsmodell:</strong>
 * <ul>
 *   <li>Der Aufruf ist synchron und blockiert bis zum Laufende.</li>
 *   <li>Ist der Run-Lock nicht verfügbar (anderer Lauf aktiv), kehrt die
 *       Methode sofort mit {@link BatchRunTriggerResult.SkippedBusy} zurück.</li>
 *   <li>Tritt ein technischer Fehler auf, liefert die Methode
 *       {@link BatchRunTriggerResult.Failed} mit deutschen Meldungen.
 *       Exceptions werden nicht propagiert; Stacktraces werden im Adapter
 *       geloggt und nicht im Result-Objekt transportiert.</li>
 * </ul>
 */
@FunctionalInterface
public interface BatchRunTrigger {

    /**
     * Löst synchron einen Verarbeitungslauf aus.
     * <p>
     * Ist der RunLock nicht verfügbar, kehrt diese Methode sofort mit
     * {@link BatchRunTriggerResult.SkippedBusy} zurück, ohne einen Lauf
     * zu starten. Wird der Lauf gestartet, kehrt die Methode erst nach
     * vollständigem Abschluss zurück.
     *
     * @return Ergebnis des Laufs; nie {@code null}
     */
    BatchRunTriggerResult triggerRun();
}
