/*******************************************************************************
* 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 uk.ac.ic.doc.kevlar.core.framework.IProgramIDDescription;
import uk.ac.ic.doc.kevlar.publicInterfaces.INodeID;

/**
 * Usage note: At the moment, the HialContext implementation doesn't
 * start a new thread for functions, but it will do.
 * 
 * @author Daniel Burke
 */
public interface IHialContext { 
    
    /**
     * If succesful, a programAdded event is raised,
     * else a programAddFailed event is raised
     * @param description is the description of the program we want to add to the context
     * @param refID is the reference that the program should be known as.
     * 
     */
    void addProgram(IProgramIDDescription description, IRefObject refID);
    
    /**
     * A programRemoved event is raised
     * @param programRefID is the reference of the program you want to remove.
     * 
     */
    void removeProgram(IRefObject programRefID);
    
    /**
     * If successful, a pipeAdded event is raised, else a pipeAddFailed event is raised
     * @param fromProgramRefID is the reference of the program you want to connect from.
     * @param fromNodeID is the output node of fromProgram you want to connect from.
     * @param toProgramRefID is the reference of the program you want to connect to.
     * @param toNodeID is the input node of toProgram you want to connect to.
     * @param refID the reference that the new pipe should be known as in the system
     * 
     */
    void addPipe( IRefObject fromProgramRefID, INodeID fromNodeID,
            IRefObject toProgramRefID, INodeID toNodeID, IRefObject refID );
    
    /**
     * A pipe removed event is raised
     * @param pipeRefID is the reference of the pipe we want to remove.
     * 
     */
    void removePipe(IRefObject pipeRefID);
    
    /**
     * Remove all pipes and program
     *
     */
    public void removeAll();

    /**
     * @return true iff the context has been removed from the framework system 
     */
	public boolean isDestroyed();
	
	/**
	 * 
	 * @param refID
	 * @return the PipelineInstance that represents the 
	 */
	public IHialProgram getProgram(IRefObject refID);
	
	
	/**
	 * 
	 * @param refID
	 * @return the PipelineInstance that represents the 
	 */
	public IHialPipe getPipe(IRefObject refID);
	
	public Object getSyncRoot();
	
	
	/**
	 * Execute the context
	 * execution communication mechanism to be decided
	 */
    public void executeContext();
    
    /**
     * After executing a context, use this to kill all programs
     */
    public void killAll();
}
