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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunCancellationToken;
import de.gecheckt.pdf.umbenenner.application.port.in.BatchRunProgressObserver;

/**
 * Inbound bridge implemented by Bootstrap to let the GUI execute a batch run against a
 * stored configuration file.
 * <p>
 * The launcher performs the complete headless startup sequence (legacy migration, config
 * loading, validation, SQLite schema initialisation, run-lock, use-case wiring, execution)
 * for the supplied configuration path while forwarding progress callbacks and honouring
 * the supplied cancellation token. It reuses the very same application ports and
 * persistence pipeline as a Task-Scheduler-triggered headless run; only the presentation
 * side (the GUI) differs.
 *
 * <h2>Threading</h2>
 * <p>
 * Implementations must be safe to call from a non-UI worker thread. They must not touch
 * the JavaFX Application Thread themselves; all JavaFX-specific scheduling is the
 * caller's concern. The call blocks until the run terminates (normally, after a
 * cancellation, or after a hard failure).
 *
 * <h2>Exception contract</h2>
 * <p>
 * Implementations must not propagate checked exceptions. Unexpected runtime exceptions
 * should be caught, logged, and returned as a
 * {@link GuiBatchRunLaunchOutcome#failedAfterStart(String)} outcome to keep the GUI in a
 * well-defined terminal state.
 */
@FunctionalInterface
public interface GuiBatchRunLauncher {

    /**
     * Executes exactly one batch run against the supplied configuration file.
     *
     * @param configFilePath    path of the {@code .properties} file to run against;
     *                          must not be {@code null}; must exist and be readable
     * @param observer          observer receiving start/completion/end callbacks; must
     *                          not be {@code null}
     * @param cancellationToken cancellation token the run polls between candidates; must
     *                          not be {@code null}
     * @return a description of how the run terminated; never {@code null}
     */
    GuiBatchRunLaunchOutcome launch(
            Path configFilePath,
            BatchRunProgressObserver observer,
            BatchRunCancellationToken cancellationToken);
}
