/*******************************************************************************
* 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.List;

import uk.ac.ic.doc.kevlar.core.framework.IPipe;

/**
 * @author Daniel Burke
 * Guarantee: The thread that these notifications are received in
 * has a synchornisation lock on the framework context.
 * That is good if you need to call 
 * IHialContext::getProgram(IRefObject)
 * or 
 * IHialContext::getPipe(IRefObject)
 *
 * 
 * but it's bad if you need to do any serious processing that takes
 * time in any of these event handlers.
 * In such a case, you should spawn a thread.
 * 
 */
public interface IHialContextListener
{
	
    /**
     * Called after a successful call to IContext.addPipe
     * @param refID the id that was passed to IContext.addPipe
     */
	public void pipeAdded(IRefObject refID);
	/**
	 * Called after an unsuccessful call to IContext.addPipe
	 * @param refID the id that was passed to IContext.addProgram
	 * @param problemPipes the pipes that failed the type check when the pipe was added
	 * Note: pipe
	 */
	public void pipeAddFailed(IRefObject refID, List<IPipe> problemPipes);
	/**
	 * Called when a program's argument changes cause
	 * some pipes to no longer be type-checked
	 * Therefore they are removed from the system
	 * @param refID the id of the pipe that has failed
	 */
	public void pipeFailed(IRefObject refID);
	/**
	 * Called after a call to IContext.removePipe
	 * @param refID the id of the removed pipe
	 */
	public void pipeRemoved(IRefObject refID);
	
    /**
     * Called after a successful call to IContext.addProgram
     * @param refID the id that was passed to IContext.addProgram
     */
	public void programAdded(IRefObject refID);
	/**
	 * Called after an unsuccessful call to IContext.addProgram
	 * @param refID the id that was passed to IContext.addProgram
	 */
	public void programAddFailed(IRefObject refID);
	
	/**
	 * Called if a program is removed by the program loader
	 * (Can happen if the Jar file is deleted)
	 * All pipes are guaranteed to be lost before this is called
	 * @param refID the id program that had to be removed
	 */
	public void programFailed(IRefObject refID);
	
	/**
	 * Called after a call to IContext.removeProgram
	 * @param refID the removed program's id
	 */
	public void programRemoved(IRefObject refID);
	/**
	 * Called after a call to IContext.addArgument or 
	 * IContext.updateArgumentInstance
	 * @param refID the id of the program that has new argument state
	 */
	public void programStateChanged(IRefObject refID);
	/**
	 * Called if a program is removed by the program loader
	 * (Called once for each connected pipe)
	 * Also called when a program's argument changes cause
	 * some pipes to have to be removed from the system
	 * due to the nodes dissapearing
	 * @param refID the id of the pipe that has failed
	 */
	public void pipeLost(IRefObject refID);
	
	/**
	 * WARNING: This function will not be called from the GUI thread
	 * Called after a call to executeContext(), called when
	 * all programs have finished executing.
	 */
	public void executionCompleted();
	
	/**
	 * WARNING: This function will not be called from the GUI thread
	 * Called after a call to executeContext() for each program
	 * as it finishes
	 * @param refID the program that finished executing
	 */
	public void executionCompleted(IRefObject refID);
}
