package de.gecheckt.pdf.umbenenner.domain.model;

import java.util.Objects;

/**
 * Represents a technical (infrastructure) failure during candidate access or PDF extraction.
 * <p>
 * This outcome indicates that a document could not be processed due to technical infrastructure failures,
 * such as I/O errors, file access problems, or extraction engine failures.
 * <p>
 * These are typically retryable conditions, as they may be transient issues that could succeed
 * in a later batch run.
 * <p>
 * Examples:
 * <ul>
 *   <li>File not readable due to permissions</li>
 *   <li>File disappeared between discovery and extraction</li>
 *   <li>I/O error during file read</li>
 *   <li>Extraction engine (PDFBox) internal failure</li>
 *   <li>Out of memory during extraction</li>
 * </ul>
 * <p>
 * This is distinct from content errors, which represent problems with the document
 * content itself rather than infrastructure failures.
 *
 * @param candidate the source document metadata
 * @param errorMessage a description of the technical failure
 * @param cause the underlying exception, if any (may be null)
 */
public record TechnicalDocumentError(
    SourceDocumentCandidate candidate,
    String errorMessage,
    Throwable cause
) implements DocumentProcessingOutcome {
    /**
     * Constructor with validation.
     *
     * @param candidate must be non-null
     * @param errorMessage must be non-null and non-empty
     * @param cause may be null
     * @throws NullPointerException if candidate or errorMessage is null
     * @throws IllegalArgumentException if errorMessage is empty
     */
    public TechnicalDocumentError {
        Objects.requireNonNull(candidate, "candidate must not be null");
        Objects.requireNonNull(errorMessage, "errorMessage must not be null");
        if (errorMessage.isEmpty()) {
            throw new IllegalArgumentException("errorMessage must not be empty");
        }
    }
}