/*
 * $Id$
 *
 * This file is part of the Cloud Services Integration Platform (CSIP),
 * a Model-as-a-Service framework, API and application suite.
 *
 * 2012-2022, 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.api.server;

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

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

  /**
   Exit value if the execution timed out.
  */
  public static final int TIMED_OUT = 1024;

  /**
   * 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;


  /**
   * Set the timeout.
   *
   * @param time the amount of the time unit.
   * @param unit the TimeUnit
   */
  void setTimeout(long time, TimeUnit unit);


  /**
   * 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);

}