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

import java.nio.file.Path;

import de.gecheckt.pdf.umbenenner.adapter.in.gui.editor.GuiConfigurationValues;

/**
 * Writes a normalized {@code .properties} configuration file from the current editor values.
 * <p>
 * The interface allows Bootstrap to provide the concrete file-writing, backup and
 * normalization logic while the GUI only deals with editor values and target paths.
 * Implementations must follow the backup schema defined for this application:
 * {@code <filename>.bak}, and on collision {@code <filename>.bak.1}, {@code .bak.2}, ...
 * Existing backups are never overwritten.
 */
@FunctionalInterface
public interface GuiConfigurationFileWriter {

    /**
     * Writes the given configuration values to the specified target path as a normalized
     * {@code .properties} file.
     * <p>
     * When {@code targetPath} already exists on disk, the implementation must create a
     * {@code .bak} backup of the existing file before overwriting it. The caller is
     * responsible for obtaining user confirmation before invoking this method.
     *
     * @param values     the current editor values to serialize; must not be {@code null}
     * @param targetPath the target file path to write to; must not be {@code null}
     * @return the result of the write operation, including any API-key preservation note;
     *         never {@code null}
     * @throws GuiConfigurationWriteException if the file cannot be written
     */
    GuiConfigurationSaveResult write(GuiConfigurationValues values, Path targetPath);
}
