/*******************************************************************************
* 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 24-Oct-2004
 *
 * Created by Steve Zymler
 */
package uk.ac.ic.doc.kevlar.core.framework;

import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentInstance;
import uk.ac.ic.doc.kevlar.publicInterfaces.INodeID;

/**
 * @author Daniel Burke and Steve Zymler
 *
 *  IContext will identify a context that is holding a pipeline in
 *  the process of being built. It is used by the GUI/HIAL to build
 *  pipelines within the framework. 
 */
public interface IContext 
{
    /**
	 * @return a long that identifies the context holding a pipeline
	 * 			in the framework.
	 */
	long getID();
    
    /**
     * 
     * @param id is the id of the program we want to add to the context
     * @param refID is the id that the program should be known as
     * If succesful, a programAdded event is raised,
     * else a programAddFailed event is raised
     */
    void addProgram(IProgramID id, long refID);
    
    /**
     * 
     * @param programID is the IProgramInstance you want to remove.
     * A programRemoved event is raised
     */
    void removeProgram(long programID);
    
    /**
     * @param fromProgramID is the program's id you want to connect from.
     * @param fromNodeID is the output node of fromProgram you want to connect from.
     * @param toProgramID is the program instance you want to connect to.
     * @param toNodeID is the input node of toProgram you want to connect to.
     * @param refID the pipe should be known as in the system
     * If successful, a pipeAdded event is raised, else a pipeAddFailed event is raised
     */
    void addPipe( long fromProgramID, INodeID fromNodeID,
    		long toProgramID, INodeID toNodeID, long refID );
    
    /**
     * 
     * @param pipeID is the pipe's id we want to remove.
     * A pipe removed event is raised
     */
    void removePipe(long pipeID);
    
    /** 
     * This function updates the program's argument 
     * instance. 
     * NOTE: The new argument instance will cause updated
     * IO nodes and available arguments for the program
     * Therefore this function may involve an invocation of the type checker.
     * @param instance The current argument assignments
     * @param programID The program's id to which the argument instance belongs.
     * A programStateChanged event is raised
     */
    
    void updateArgumentInstance(IArgumentInstance instance, long programID);

    
    /** 
     * 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
     * Therefore this function may involve an invocation of the type checker.
     * @param argName the argument to add
     * @param programID The program's id to which the argument should be added.
     * A programStateChanged event is raised
     */
    public void addArgument(String argName, long programID);

    /**
     * @return true iff the context has been removed from the framework system 
     */
	public boolean isDestroyed();
	
	/**
	 * Warning: If multiple threads are going to be using the framework,
	 * the user of this function must synchronize(framework).
	 * Otherwise there is a risk that the program will be destroyed
	 * between getting it and using it.
	 * 
	 * @param refID
	 * @return the PipelineInstance that represents the 
	 */
	public IPipelineProgram getProgram(long refID);
	
	/**
	 * Warning: If multiple threads are going to be using the framework,
	 * the user of this function must synchronize(framework).
	 * Otherwise there is a risk that the pipe will be destroyed
	 * between getting it and using it.
	 * 
	 * @param refID
	 * @return the PipelineInstance that represents the 
	 */
	public IPipe getPipe(long refID);
	
	/**
	 * Execute the current context's pipeline.
	 *
	 */
	public void execute();
}
