package com.atlassian.bitbucket.mesh.process;

import javax.annotation.Nonnull;

/**
 * Evaluates the {@link ProcessSummary summary} when a process completes to determine whether the process
 * succeeded or failed.
 * <p>
 * {@link #onComplete} is called after every other {@link ProcessStdioHandler} callback <i>except</i>
 * {@link ProcessStdioHandler#getResult()}. This means completion handlers can override, replace, suppress
 * or propagate any error (be it a non-zero exit code, fatal errors on {@code stderr} or exceptions thrown
 * by the {@link ProcessStdioHandler}. However, even if the completion handler does not throw an exception,
 * if {@link ProcessStdioHandler#getResult()} throws the process will still be considered failed.
 */
public interface ProcessCompletionHandler {

    /**
     * Implementations review the exit code, as well as {@code stderr} (if the {@link ProcessStdioHandler} didn't
     * consume it) and any previously-thrown exception, and decide whether the process succeeded or failed.
     * <p>
     * If the implementation throws, the process is considered a failure and {@link ProcessStdioHandler#getResult()}
     * is never invoked. If no exception is thrown, any previously-thrown exception is ignored and the process is
     * considered a success.
     *
     * @param summary a summary of the completed process
     */
    void onComplete(@Nonnull ProcessSummary summary);
}
