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

import java.io.IOException;
import java.io.OutputStream;

/**
 * <p>The interface for modules that can export the ontology in a certain file format.
 * 
 * <p>An ExportHandler can be registered with <code>OntologyManager.addExportHandler()</code>.
 * However, it's easier just to declare all export handlers (their fully qualified classes) as a comma separated list
 * under the "<code>cf.exporthandler</code>" key in the <code>ConsensusFoundation.properties</code> configuration file.
 * 
 * <p>The declared export 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>MyExportHandler(Properties config, LoggingManager log, OntologyManager om)</code>
 *   <li><code>MyExportHandler(LoggingManager log, OntologyManager om)</code>
 *   <li><code>MyExportHandler(OntologyManager om)</code>
 *   <li><code>MyExportHandler()</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 ImportHandler
 */
public interface ExportHandler {

	/**
	 * Exports the ontology to a given OutputStream. Can be called by an application.
	 * <p>This method is responsible for closing the stream!</p>
	 * @param out the OutputStream to write the ontology to
	 * @param exportInternals a flag if internal element shall be exported (like users and the "created-by" association)
	 * @throws IOException if an IO error occurs while writing the ontology
	 * @throws OntologyManagerException if the ontology cannot be exported for some other reason
	 */
	public void exportOntology(OutputStream out, boolean exportInternals) throws IOException,OntologyManagerException;

	
	/**
	 * Returns the content (MIME) type that this handler will export, e.h. "text/xml".
	 * @return the content type of an ontology exported by this handler
	 */
	public String getContentType();
	
	
	/**
	 * Returns the file extensions of the ontology format that this handler can export, e.g. "xtm".
	 * @return the file extension for the handlers ontology file format
	 */
	public String getExtension();
	
	
	/**
	 * Returns a short description about this export handler.
	 * @return a description about this handler
	 */
	public String getDescription();

}
