/*
 * Moonlight|3D Copyright (C) 2005 The Moonlight|3D team
 * 
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation; either version 2.1 of the License, or (at your option)
 * any later version.
 * 
 * This library 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 Lesser General Public License for more
 * details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 * 
 * Created on Jan 5, 2005
 */
package ml.core.plugins;

import java.util.ArrayList;

/**
 * This is the interface all Moonlight|3D plugins are required to implement.
 * 
 * @author gregor
 */
public interface Plugin {
	/**
	 * Return the name of this plugin. Usually this is the full name of Plugin class,
	 * e.g. ml.ui.plugins.view.Plugin.<br>
	 * 
	 * <b>NOTE:</b> This function maybe called at any time during plugin lifetime,
	 * in particular before load() has been called and after unload() has been called.
	 * 
	 * @return plugin name
	 */
	public String getName();

	/**
	 * Return a list of plugins this plugin depends on. Even if a plugin has no dependencies
	 * it should not return null but a valid ArrayList with no entries instead.
	 *  
	 * <b>NOTE:</b> This function maybe called at any time during plugin lifetime,
	 * in particular before load() has been called and after unload() has been called.<br>
	 * 
	 * If your plugin has optional features that depend on the presence of another
	 * plugin, do not add the name of the other plugin here or it will prevent your
	 * plugin from being loaded. Instead, factor these optional features out into
	 * an additional plugin that depends on the base plugin with the core features.
	 * 
	 * @return list of dependencies
	 */
	public ArrayList<String> getDependencies();

	/**
	 * Load an initialise the plugin. This function will only be called if all
	 * dependencies have been satisfied, i.e., all dependencies have been loaded
	 * successfully. If this function throws an error, it will be assumed that
	 * the loading of the plugin has failed. In that case, it is treated as if
	 * it were not present. All dependent plugins will subsequently fail to
	 * load.
	 * 
	 * @throws java.lang.Exception
	 */
	public void load() throws java.lang.Exception;

	/**
	 * Unloads the plugin. This function will only be called if all dependent
	 * plugins have been unloaded successfully, so that this plugin might
	 * be able to unload itself savely.
	 * 
	 * @throws java.lang.Exception
	 */
	public void unload() throws java.lang.Exception;
}