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

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

import de.gecheckt.pdf.umbenenner.application.port.in.SchedulerControlUseCase;

/**
 * Callback invoked by the workspace on a background thread after a configuration file
 * has been successfully loaded from disk.
 * <p>
 * Bootstrap supplies an implementation that builds the application run context
 * (migrate → load → validate → schema-init sequence) and, on success, also initialises
 * the automatic scheduler. The workspace calls this initializer inside the same
 * background submit that loads the editor state, so the JavaFX Application Thread is
 * never blocked.
 * <p>
 * In isolated GUI tests a {@link #noOp() no-op} implementation can be used so that no
 * Bootstrap wiring is required.
 */
@FunctionalInterface
public interface GuiApplicationContextInitializer {

    /**
     * Attempts to initialise the application run context for the supplied configuration file.
     * <p>
     * If context initialisation succeeds and the configuration enables the scheduler, the
     * scheduler is also wired and its use case is returned in the result. The caller is
     * responsible for handing the scheduler use case to the scheduler tab on the JavaFX
     * Application Thread via {@code Platform.runLater}.
     * <p>
     * This method must be called on a background worker thread, not on the JavaFX Application
     * Thread.
     *
     * @param configFilePath path to the {@code .properties} configuration file; must exist on disk
     * @return the result of the initialisation attempt; never {@code null}
     */
    InitResult initialize(Path configFilePath);

    /**
     * Returns a no-op initializer that always reports success and no scheduler.
     * <p>
     * Suitable for GUI tests and startup paths where no Bootstrap wiring is available.
     *
     * @return no-op initializer; never {@code null}
     */
    static GuiApplicationContextInitializer noOp() {
        return configFilePath -> new InitResult(Optional.empty(), Optional.empty());
    }

    /**
     * Result of a context initialisation attempt.
     *
     * @param contextError            empty on success; a human-readable German error message
     *                                when initialisation failed — the GUI remains functional
     *                                but falls back to per-run initialisation for batch runs;
     *                                must not be {@code null}
     * @param schedulerControlUseCase the scheduler use case when the configuration enables the
     *                                scheduler and initialisation succeeded; empty otherwise;
     *                                must not be {@code null}
     */
    record InitResult(
            Optional<String> contextError,
            Optional<SchedulerControlUseCase> schedulerControlUseCase) {
    }
}
