/*
 * $Id$
 *
 * This file is part of the Cloud Services Integration Platform (CSIP),
 * a Model-as-a-Service framework, API and application suite.
 *
 * 2012-2017, Olaf David and others, OMSLab, Colorado State University.
 *
 * OMSLab licenses this file to you under the MIT license.
 * See the LICENSE file in the project root for more information.
 */
package csip;

import java.io.File;
import java.io.IOException;
import java.io.StringWriter;
import java.util.Map;

/**
 * Interface to manage an executable.
 *
 * @author od
 */
public interface Executable {

    /**
     * Receives output for stderr or stdout. Allows to parse the process output
     * during execution as it becomes available.
     */
    interface StdHandler {

        /**
         * The output string. This is not a single line! Could be multiple
         * lines. Be careful what you are doing here. Do not spend too much time
         * in this method.
         *
         * @param out the current multi-line output string. Output lines are
         * always complete.
         */
        void handle(String out);
    }


    /**
     * Get the name of the executable.
     * @return the name of the executable
     */
    String getName();


    /**
     * Set the executable arguments.
     *
     * @param args the executable arguments
     */
    void setArguments(Object... args);


    /**
     * Add additional arguments.
     * @param args the command line arguments.
     */
    void addArguments(Object... args);


    /**
     * Get the executables arguments
     * @return the arguments
     */
    Object[] getArguments();


    /**
     * Get the current environment map
     *
     * @return the environment.
     */
    Map<String, String> environment();


    /**
     * Redirect stdout to a file in the workspace.
     *
     * @param filename the filename to use relative to the workspace.
     * @throws IOException if redirection fails.
     */
    void redirectOutput(String filename) throws IOException;


    /**
     * Redirect the output to a string writer
     * @param w the StringWriter
     * @throws IOException if redirection fails.
     */
    void redirectOutput(StringWriter w) throws IOException;


    /**
     * Redirect stderr to a file in the workspace.
     *
     * @param filename the filename to use relative to the workspace.
     * @throws java.io.IOException if redirection fails.
     */
    void redirectError(String filename) throws IOException;


    /**
     * Redirect the error stream to a string writer
     * @param w the StringWriter
     * @throws IOException if redirection fails
     */
    void redirectError(StringWriter w) throws IOException;


    /**
     * redirect to default files and append. Call this before repeated
     * execution.
     *
     * @throws IOException if redirection fails
     */
    void redirectDefaults() throws IOException;


    /**
     * run the executable.
     *
     * @return 0 if successful, !=0 otherwise
     * @throws java.io.IOException if an IO error occurs.
     */
    int exec() throws IOException;


    /**
     * Get the File for stdio. The File is unique for each instance of this
     * class. name : 'executable name'-'hash code'-stdout.exe
     *
     * @return The file with the output.
     */
    File stdout();


    /**
     * Get the File for stderr. The File is unique for each instance of this
     * class. name : 'executable name'-'hash code'-stdout.exe
     *
     * @return The
     */
    File stderr();


    /**
     * Handle the current output from stdout.
     *
     * @param handler the handler object. Pass 'null' for removing an existing
     * handler.
     */
    void setStdoutHandler(StdHandler handler);


    /**
     * Handle the current output from stderr.
     *
     * @param handler the handler object. Pass 'null' for removing an existing
     * handler.
     */
    void setStderrHandler(StdHandler handler);

}