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

/**
 * Outbound-Port zur Steuerung des technischen Scheduler-Mechanismus.
 * <p>
 * Kapselt die Infrastruktur für das periodische Polling (z.B. einen
 * {@code ScheduledExecutorService}). Die fachliche Scheduler-Steuerung
 * liegt im Use Case {@code SchedulerControlUseCase}; dieser Port
 * delegiert ausschließlich den technischen Lifecycle-Start und -Stop.
 * <p>
 * Abhängigkeitsrichtung: Application → Adapter (hexagonal outbound).
 */
public interface SchedulerPort {

    /**
     * Startet den periodischen Scheduler-Mechanismus.
     * <p>
     * Der erste Tick startet sofort (Initial Delay 0). Nachfolgende Ticks
     * starten jeweils {@link SchedulerConfig#intervalSeconds()} Sekunden
     * nach dem Ende des vorigen Ticks ({@code scheduleWithFixedDelay}).
     * <p>
     * Der bereitgestellte {@link BatchRunTrigger} wird bei jedem Tick
     * synchron aufgerufen. Der Scheduler-Adapter darf keine weiteren
     * Entscheidungen treffen – er ruft {@code trigger.triggerRun()} auf
     * und aktualisiert den Zustand anhand des Ergebnisses.
     *
     * @param config  Betriebskonfiguration mit Intervall in Sekunden
     * @param trigger Auslöser für den Verarbeitungslauf pro Tick
     * @throws RuntimeException wenn der Scheduler-Mechanismus nicht
     *                          gestartet werden kann
     */
    void startScheduler(SchedulerConfig config, BatchRunTrigger trigger);

    /**
     * Stoppt den periodischen Scheduler-Mechanismus.
     * <p>
     * Laufende Ticks werden nicht abgebrochen; es werden lediglich keine
     * weiteren Ticks geplant. Ist der Scheduler bereits gestoppt, hat
     * dieser Aufruf keine Wirkung (idempotent).
     */
    void stopScheduler();
}
