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

import java.io.IOException;
import java.util.Collection;
import java.util.List;
import java.util.Set;

import uk.ac.ic.doc.kevlar.core.framework.IProgramIDDescription;
import uk.ac.ic.doc.kevlar.publicUtil.collections.Tuple;

/**
 * @author Daniel Burke
 *
 */
/**
 * @author Daniel Burke
 *
 */
public interface IHial {
    
    /**
     * Use to locate programs by keywords
     * @param keywords The keywords to search for
     * @return a list of search results in order of relevance
     */
    public List<IProgramSearchResult> search(Collection<String> keywords);
    
	/**
	 * set a listener to be informed of important upcoming events (and promitions) at the Hial. 
	 * @param listener, receives the events
	 */
	public void setGUIListener(IHialEventListener listener);

	/**
	 * The IProgramTreeNode is the root category (name="root", isRoot() is true)
	 * Set<IProgramIDDescription> is the set of all program descriptions.
	 * This function may hit the disk each time it's called
	 * @return Returns the category tree.
	 */
	public Tuple<IProgramTreeNode, Set<IProgramIDDescription> > getProgramTreeRoot();
	
	/**
	 * Save the program category tree
	 * @param programTree program tree to commit to disk.
	 */
	public void setProgramTree(IProgramTreeNode programTree);
	
    /**
     * @param listener receives events about the new context
     * @return a new context to build a new pipeline in.
     */
    IHialContext createNewContext(IHialContextListener listener);
    
    /**
     * @param context is the context to be removed.
     */
    void removeContext(IHialContext context);
    
    /**
     * Use this to convert a context into XML
     * @param context to save
     * @param guiCallback for saving gui specific information
     * @return xml string that represents the context
     */
    public String saveContext(IHialContext context, IGUIContextSaver guiCallback);
    
    /**
     * 
     * @param contextXml the XML string to load from
     * @param guiCallback receives messages containing instructions on what objects to add to the desired context as well as error messages
     * @throws XMLLoadingException if the XML is malformed in a way that can't be handled by the callback
     */
    public void loadContext(String contextXml, IGUIContextLoader guiCallback) throws XMLLoadingException;
    
    
    
    
    
    /**
     * Use this to save a context into an XML file.
     * @param context The context to save
     * @param guiCallback for saving GUI specific information
     * @param filename The relative or absolute filename to save to
     * @throws IOException if saving to the file fails in any way
     */
    public void saveContextToFile(String filename, IHialContext context, IGUIContextSaver guiCallback) throws IOException;

    /**
     * Use this to load a context from a context XML file.
     * @param guiCallback receives messages containing instructions on what objects to add to the desired context as well as error messages
     * @param filename The relative or absolute filename to load from
     * @throws IOException if saving to the file fails in any way
     * @throws XMLLoadingException if the XML is malformed in a way that can't be handled by the callback
     */
    public void loadContextFromFile(String filename, IGUIContextLoader guiCallback) throws IOException, XMLLoadingException;
    
    public String loadThumbnailStringFromFile(String filename) throws IOException, XMLLoadingException;
}
