/*******************************************************************************
* 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 29-Oct-2004
 *
 */
package uk.ac.ic.doc.kevlar.hial;

import java.util.Collection;
import java.util.Set;

import uk.ac.ic.doc.kevlar.api.programs.IProgramInfoNode;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentInstance;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IBasicArgumentInfo;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IInputOutputNodeTuple;
import uk.ac.ic.doc.kevlar.publicInterfaces.INodeID;
import uk.ac.ic.doc.kevlar.publicInterfaces.IProgramDescription;

/**
 * @author Daniel Burke
 *
 */
public interface IHialProgram {
	
	/**
	 * Once removeProgram() is called on the reference object
	 * for this program, this function will be true.
	 * @return true iff the program is destroyed.
	 */
	public boolean isDestroyed();
    
	/**
	 * Use to get the currently visible arguments that
	 * the user has added and changed it's value.
	 * @return current assigned arguments
	 */
    public Collection<IArgumentValuePair> getArgumentValues();
    
	public Collection<IBasicArgumentInfo> getAvailableArguments();
	
	public Collection<IBasicArgumentInfo> getInvalidArguments();
	
	public Collection<IBasicArgumentInfo> getAvailableButNotVisibleArguments();
    
	/**
	 * Get the current list of IO nodes
	 * @return tuple containing input and output node sets.
	 */
    public IInputOutputNodeTuple getIONodes();
   
    
    /**
     * Use this to get lots of useful info about the program
     * including the name, help and more.
     * @return a description for the program
     */
	public IProgramDescription getDescription();
	
	/**
	 * Use this to get lots of useful info about an argument.
	 * Including the help, validation pattern, and type.
	 * To get the type, use IBasicArgumentInfo.acceptVisitor.
	 * 
	 * Or, use instanceof T, for each T that is a function in
	 * IArgumentVisitor
	 * 
	 * @param argName the name of the argument
	 * @return information class about the argument
	 */
	public IBasicArgumentInfo getArgumentInfo(String argName);
	
    
    /** 
     * This function updates the program's argument 
     * instance. 
     * NOTE: The new argument instance will cause updated
     * IO nodes and available arguments for the program
     * @param values The current argument assignments
     * A programStateChanged event is raised
     */
    
    void updateArgumentValues(Collection<IArgumentValuePair> values);

    
    /** 
     * This function adds a new argument to the argument instance
     * This causes the argument to have it's initial value
     * NOTE: The new argument instance will cause updated
     * IO nodes and available arguments for the program
     * @param argName the argument to add
     * A programStateChanged event is raised
     */
    public void addArgument(IBasicArgumentInfo argName);


    /**
     * Get everything in one.
     * @return a set of all input nodes, all output nodes, and all argument value pairs.
     */
    public Set<IProgramInfoNode> getAllProgramInfoNodes();
    
    
    
    
    
    /**
     * Use to find out if a pipe is connected to a node on this program
     * @param id node id to check
     * @return true iff a pipe is connected
     */
	public boolean inputHasConnectedPipe(INodeID id);
	
    /**
     * Use to find out if a pipe is connected to a node on this program
     * @param id node id to check
     * @return true iff a pipe is connected
     */
	public boolean outputHasConnectedPipe(INodeID id);
	
    /**
     * Use to get the pipe connected to an input node
     * @param id node id to get pipe of
     * @return the pipe connected to the node or null if there is none
     */
	public IHialPipe getInputPipe(INodeID id);
	
    /**
     * Use to get the pipe connected to an output node
     * @param id node id to get pipe of
     * @return the pipe connected to the node or null if there is none
     */
	public IHialPipe getOutputPipe(INodeID id);
	
	/**
	 * Use to convert a weakly typed IArgumentInstance into a strongly typed IArgumentValuePair collection
	 * @param instance the instance to extract the argument value pairs from
	 * @return the equivalent collection of IArgumentValuePair
	 */
	public Collection<IArgumentValuePair> convertArgumentPairs(IArgumentInstance instance);

	/**
	 * Used to kill an executing program after the containing context is executed.
	 */
    public void kill();
}
