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

import java.nio.file.Path;
import java.util.Set;

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

/**
 * Inbound bridge implemented by Bootstrap to let the GUI execute a targeted mini batch
 * run restricted to a specific set of document fingerprints.
 * <p>
 * A mini-run applies the full processing pipeline — legacy migration, configuration
 * loading, validation, SQLite schema initialisation, run-lock, use-case wiring, and
 * execution — but limits processing to the supplied fingerprint set. Documents not in
 * the set are silently skipped without any persistence side-effects.
 *
 * <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 GuiMiniRunLauncher {

    /**
     * Executes a targeted batch run restricted to the supplied fingerprint set.
     *
     * @param configFilePath    path of the {@code .properties} file to run against;
     *                          must not be {@code null}; must exist and be readable
     * @param fingerprintFilter the set of document fingerprints to process; must not be
     *                          {@code null}; an empty set results in a completed run
     *                          that processes nothing
     * @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,
            Set<DocumentFingerprint> fingerprintFilter,
            BatchRunProgressObserver observer,
            BatchRunCancellationToken cancellationToken);
}
