/* $Id: ModuleFactory.java,v 1.2 2007/05/10 00:37:51 m31 Exp $
 *
 * This file is part of the project "Hilbert II" - http://www.qedeq.org
 *
 * Copyright 2000-2007,  Michael Meyling <mime@qedeq.org>.
 *
 * "Hilbert II" is free software; you can redistribute
 * it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 */

package org.qedeq.kernel.bo.module;

import java.io.IOException;

import org.qedeq.kernel.base.module.Specification;
import org.qedeq.kernel.common.XmlFileExceptionList;

/**
 * Access to QEDEQ modules.
 *
 * @version $Revision: 1.2 $
 * @author  Michael Meyling
 */
public interface ModuleFactory {

    /**
     * Initialisation of ModuleFactory. This method should be called from the {@link Kernel}
     * directly after switching into ready state. Calling this method in ready state is not
     * supported.
     *
     * TODO mime 20070411: what about an appropriate closing method?
     */
    public void init();

    /**
     * Remove all modules from memory.
     */
    public void removeAllModules();

    /**
     * Clear local file buffer and all loaded QEDEQ modules.
     *
     * @throws  IOException Deletion of all buffered file was not successful.
     */
    public void clearLocalBuffer() throws IOException;

    /**
     * Get a certain module.
     *
     * @param   address     Address of module.
     * @return  Wanted module.
     * @throws  XmlFileExceptionList    Module could not be successfully loaded.
     */
    public QedeqBo loadModule(final String address) throws XmlFileExceptionList;

    /**
     * Get a certain module.
     *
     * @param   moduleAddress  Address of module.
     * @return  Wanted module.
     * @throws  XmlFileExceptionList    Module could not be successfully loaded.
     */
    public QedeqBo loadModule(final ModuleAddress moduleAddress) throws XmlFileExceptionList;

    /**
     * Load a certain module.
     *
     * @param  module   this is the current module.
     * @param  spec     specification of wanted module.
     * @return wanted module
     * @throws XmlFileExceptionList     Module could not be successfully loaded.
     */
    public QedeqBo loadModule(final QedeqBo module, final Specification spec)
            throws XmlFileExceptionList;

    /**
     * Load all QEDEQ modules from project web directory for current kernel.
     * LATER mime 20070326: dynamic loading from web page directory
     *
     * @return  Successful loading.
     */
    public boolean loadAllModulesFromQedeq();

    /**
     * Get list of all currently loaded QEDEQ modules.
     *
     * @return  All currently loaded QEDEQ modules.
     */
    public String[] getAllLoadedModules();

     /**
     * Get buffer directory for QEDEQ module files.
     *
     * @return  buffer directory.
     */
    public String getBufferDirectory();

    /**
     * Get directory for generated files.
     *
     * @return  Generation directory.
     */
    public String getGenerationDirectory();

    /**
     * Get {@link ModuleProperties} for an address.
     *
     * @param   address Look for this address.
     * @return  Existing or new {@link ModuleProperties}, if address is maleformed
     *          <code>null</code> is returned.
     */
    public ModuleProperties getModuleProperties(final String address);

}