package de.uka.ipd.consensus.foundation.ontology;

import java.io.IOException;
import java.io.InputStream;
import java.util.Collection;

/**
 * <p>The interface for modules that can import (and optionally merge) ontologies from a certain file format.
 * 
 * <p>An ImportHandler can be registered with <code>OntologyManager.addImportHandler()</code>.
 * However, it's easier just to declare all import handlers (their fully qualified classes) as a comma separated list
 * under the "<code>cf.importhandler</code>" key in the <code>ConsensusFoundation.properties</code> configuration file.
 * 
 * <p>The declared import handlers will be loaded by <code>OntologyManager.init()</code>. Instantiation will only be
 * successful if one of the following constructors is available (the first one that matches will be used):
 * <ul>
 *   <li><code>MyImportHandler(Properties config, LoggingManager log, OntologyManager om)</code>
 *   <li><code>MyImportHandler(LoggingManager log, OntologyManager om)</code>
 *   <li><code>MyImportHandler(OntologyManager om)</code>
 *   <li><code>MyImportHandler()</code>
 * </ul>
 * The <code>Properties</code> parameter contains all entries from <code>ConsensusFoundation.properties</code>.
 * 
 * @author Thomas Much
 * @version 2006-06-14
 * @see OntologyManager
 * @see ExportHandler
 */
public interface ImportHandler {

	/**
	 * Imports an ontology from the given InputStream.
	 * This method will be called from the OntologyManager during startup of the application, it replaces an existing ontology.
	 * <p>This method is responsible for closing the stream!</p>
	 * @param in the InputStream to read the ontology from
	 * @throws IOException if an IO error occurrs while reading the stream
	 * @throws OntologyManagerException if the ontology cannot be loaded for logical reasons
	 */
	public void importOntology(InputStream in) throws IOException,OntologyManagerException;
	
	
	/**
	 * If this handler supports ontology merging, this method can be called by an application to merge an ontology into the existing ontology.
	 * <p>This method is responsible for closing the stream!</p>
	 * @param in the InputStream to read the ontology from
	 * @param errors an empty collection provided by the caller, into which the method can put all exceptions that happen during the merge
	 * @throws IOException if an IO error occurrs while reading the stream
	 * @see #canMerge()
	 */
	public void mergeOntology(InputStream in, Collection errors) throws IOException;

	
	/**
	 * Signals whether this handler can not only load (import), but also merge ontologies
	 * @return <code>true</code> if the handler can merge ontologies, <code>false</code> otherwise
	 * @see #mergeOntology(InputStream, Collection)
	 */
	public boolean canMerge();

	
	/**
	 * Returns the file extensions of the ontology format that this handler can load, e.g. "xtm".
	 * @return the file extension for the handlers ontology file format
	 */
	public String getExtension();
	
	
	/**
	 * Returns a short description about this import handler.
	 * @return a description about this handler
	 */
	public String getDescription();

}
