/*******************************************************************************
* 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.                       *
*******************************************************************************/
package uk.ac.ic.doc.kevlar.core.framework.internal;

import java.util.Map;

import uk.ac.ic.doc.kevlar.api.programs.arguments.ArgumentModelProvider;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentInstance;
import uk.ac.ic.doc.kevlar.api.programs.descriptions.ProgramDescriptionProvider;
import uk.ac.ic.doc.kevlar.api.programs.returnValues.ReturnModelProvider;
import uk.ac.ic.doc.kevlar.core.framework.exceptions.InvalidProgramException;
import uk.ac.ic.doc.kevlar.publicInterfaces.IJVMEnvironment;
import uk.ac.ic.doc.kevlar.publicInterfaces.IInputPipe;
import uk.ac.ic.doc.kevlar.publicInterfaces.INodeID;
import uk.ac.ic.doc.kevlar.publicInterfaces.IOutputPipe;

/**
 * TODO: toa02 move this interface out of public interfaces
 * This is the interface that the framework gets as access to a program.
 * 
 * NOTE: Programs do not implement this interface, for that see elsewhere.
 * @see uk.ac.ic.doc.kevlar.publicInterfaces.AbstractProgram for what programs must implement.
 * 
 * @author tora
 */
public interface IProgram {
    /* for the moment, just a placeholder until we define it */

    /**
     * Used to get all the information on the programs arguments.
     * 
     * @return The data structure that lays out the argument model for the
     *         program
     * @throws
     *         uk.ac.ic.doc.kevlar.core.framework.exceptions.InvalidProgramException
     *         if the program has been removed
     */
    public ArgumentModelProvider getArgumentModelProvider() throws InvalidProgramException;

    /**
     * @return A description model for this program
     * @throws
     *         uk.ac.ic.doc.kevlar.core.framework.exceptions.InvalidProgramException
     *         if the program has been removed
     */
    public ProgramDescriptionProvider getDescription() throws InvalidProgramException;

    /**
     * @return A return model for this program
     * @throws
     *         uk.ac.ic.doc.kevlar.core.framework.exceptions.InvalidProgramException
     *         if the program has been removed
     */    
    public ReturnModelProvider getReturnModelProvider();
    
    /**
     * Runs the program instance, using the given input and output pipes,
     * within the given environment.
     * 
     * This will automatically create a new thread, and fork a new JVM
     * 
     * This method returns when the program has finished.
     * @param args The arguments to provide to this program.
     * @param env The environment to use
     * @param ins The input pipes to provide
     * @param outs The output pipes to provide
     * @return a handle to the now running program.
     */
    public IProgramInstance run(IArgumentInstance args, IJVMEnvironment env, Map<INodeID, IInputPipe> ins,
            Map<INodeID, IOutputPipe> outs);

    /**
     * @return true iff this is a trusted builtin method that runs in this JVM.
     */
    public boolean isBuiltin();
    
    /**
     * @return The canonical name of the class that 'backs' or will be invoked when this IProgram is invoked
     */
    public String getCanonicalName();
    
}
