/*******************************************************************************
* Copyright (c)                                                                *
*           2005   Tristan Allwood,                                            *
*           2005   Daniel Burke,                                               *
*           2005   Marc Hull,                                                  *
*           2005   Ekaterina Itskova,                                          *
*           2005   Steve Zymler                                                *
*                                                                              *
* Permission is hereby granted, free of charge, to any person obtaining a      *
* copy of this software and associated documentation files (the                *
* "Software"), to deal in the Software without restriction, including          *
* without limitation the rights to use, copy, modify, merge, publish,          *
* distribute, sublicense, and/or sell copies of the Software, and to           *
* permit persons to whom the Software is furnished to do so, subject to        *
* the following conditions:                                                    *
*                                                                              *
* The above copyright notice and this permission notice shall be included      *
* in all copies or substantial portions of the Software.                       *
*                                                                              *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS      *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                   *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.       *
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY         *
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,         *
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE            *
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                       *
*******************************************************************************/
/*
 * Created on 28-Oct-2004
 *
 */
package uk.ac.ic.doc.kevlar.core.framework.internal.execute;

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

import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentInstance;
import uk.ac.ic.doc.kevlar.api.programs.returnValues.IReturnModel;
import uk.ac.ic.doc.kevlar.core.framework.internal.IProgramInstance;
import uk.ac.ic.doc.kevlar.publicInterfaces.IInputPipe;
import uk.ac.ic.doc.kevlar.publicInterfaces.IJVMEnvironment;
import uk.ac.ic.doc.kevlar.publicInterfaces.INodeID;
import uk.ac.ic.doc.kevlar.publicInterfaces.IOutputPipe;

/**
 * This represents the 'execution' system, managing programs that are to be run.
 * 
 * Environment variables are case sensitive.
 * 
 * @author ToRA
 * 
 */
public interface IExecutionEngine {

    /**
     * Creates a program instance from the provided information
     * 
     * @param className
     *            The ClassName of the 'program' to execute
     * @param jarFileLocation
     *            Where the jar file containing this program can be found
     * @param args
     *            The arguments applied to this program
     * @param env
     *            The JVM environment this program runs in This is not used for
     *            the moment.
     * @param retMod
     *            The return model that describes return values from the
     *            process.
     * @param ins
     *            The input pipes attached to this program
     * @param outs
     *            The output pipes attached to this program
     * @param fini
     *            Code to be executed when the std-in reader thread exits.
     * @return A handle to the ProgramInstanceImpl
     * @throws NullPointerException
     *             if anything here (except env) is null.
     * 
     */
    IProgramInstance createProgramInstance(String className,
            String jarFileLocation, IJVMEnvironment env, IReturnModel retMod,
            IArgumentInstance args, Map<INodeID, IInputPipe> ins,
            Map<INodeID, IOutputPipe> outs, Runnable fini);

    /**
     * Get the current environment variable mappings.
     * 
     * Environment variables <b>are case sensitive </b> and <b>may contain any
     * valid character for a string </b>
     * 
     * @return An unmodifiable map of String->Strings representing name,value
     *         pairs of the current environment variables.
     */
    Map<String, String> getEnvironmentVariables();

    /**
     * @return A File representation of the absolute path of the current working
     *         directory
     */
    public File getCurrentWorkingDirectory();

    /**
     * Sets the current working directory. If an invalid (ie doesn't exist or
     * isn't directory) path is used, this method does nothing. The current cwd
     * <b>can </b> be a directory that is unreadable
     * 
     * @param cwd
     *            A File representation of the new current working directory
     *            used for child processes.
     */
    public void setWorkingDirectory(File cwd);

    /**
     * Set all the environemnt variables for this execution engine in one go.
     * The mappings in newVars will be the only mappings after this function
     * returns.
     * 
     * @param newVars
     *            A map of name to value's for the environment
     */
    void setEnvironmentVariables(Map<String, String> newVars);

    /**
     * Update an environment variable, either by replacement, or by appending
     * the given value to the end of the variable's existing value (if set).
     * 
     * @param name
     *            The name of the variable
     * @param value
     *            The value to give the variable. If this value is null and
     *            append is false, the variable will be removed.
     * @param append
     *            if false, the value of the variable name will be exactly
     *            value, otherwise it will be its previous value with 'value'
     *            appended directly on the end.
     */
    void updateVariable(String name, String value, boolean append);

}
