package org.eclipse.core.runtime;

/*
 * (c) Copyright IBM Corp. 2000, 2001.
 * All Rights Reserved.
 */

import java.util.MissingResourceException;
import java.util.ResourceBundle;
import java.net.URL;

/**
 * A plug-in descriptor contains information about a plug-in
 * obtained from the plug-in's manifest (<code>plugin.xml</code>) file.
 * <p>
 * Plug-in descriptors are platform-defined objects that exist
 * in the plug-in registry independent of whether a plug-in has
 * been started. In contrast, a plug-in's runtime object 
 * (<code>getPlugin</code>) generally runs plug-in-defined code.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 *
 * @see #getPlugin
 */
public interface IPluginDescriptor {
/**
 * Returns the extension with the given simple identifier declared in
 * this plug-in, or <code>null</code> if there is no such extension.
 * Since an extension might not have an identifier, some extensions
 * can only be found via the <code>getExtensions</code> method.
 *
 * @param extensionName the simple identifier of the extension (e.g. <code>"main"</code>).
 * @return the extension, or <code>null</code>
 */
public IExtension getExtension(String extensionName);
/**
 * Returns the extension point with the given simple identifier
 * declared in this plug-in, or <code>null</code> if there is no such extension point.
 *
 * @param extensionPointId the simple identifier of the extension point (e.g. <code>"wizard"</code>).
 * @return the extension point, or <code>null</code>
 */
public IExtensionPoint getExtensionPoint(String extensionPointId);
/**
 * Returns all extension points declared by this plug-in.
 * Returns an empty array if this plug-in does not declare any extension points.
 *
 * @return the extension points declared by this plug-in
 */
public IExtensionPoint[] getExtensionPoints();
/**
 * Returns all extensions declared by this plug-in.
 * Returns an empty array if this plug-in does not declare any extensions.
 *
 * @return the extensions declared by this plug-in
 */
public IExtension[] getExtensions();
/**
 * Returns the URL of this plug-in's install directory. 
 * This is the directory containing
 * the plug-in manifest file, resource bundle, runtime libraries,
 * and any other files supplied with this plug-in.
 *
 * @return the URL of this plug-in's install directory
 */
public URL getInstallURL() ;
/**
 * Returns a displayable label for this plug-in.
 * Returns the empty string if no label for this plug-in
 * is specified in the plug-in manifest file.
 * <p> Note that any translation specified in the plug-in manifest
 * file is automatically applied.
 * </p>
 *
 * @return a displayable string label for this plug-in,
 *    possibly the empty string
 * @see #getResourceString 
 */
public String getLabel();
/**
 * Returns the plug-in runtime object corresponding to this
 * plug-in descriptor. Unlike other methods on this object,
 * invoking this method may activate the plug-in.
 * The returned object is an instance of the plug-in runtime class
 * specified in the plug-in's manifest file;
 * if a class is not specified there, the returned object
 * is an internally-supplied one that does not react to life cycle requests.
 *
 * @return the plug-in runtime object
 * @exception CoreException 
 *   if this plug-in's runtime object could not be created.
 * @see #isPluginActivated
 */
public Plugin getPlugin() throws CoreException;
/**
 * Returns the plug-in class loader used to load classes and resources
 * for this plug-in. The class loader can be used to directly access
 * plug-in resources and classes. Note that accessing a resource will
 * <b>not activate</b> the corresponding plug-in. Successfully loading 
 * a class will <b>always activate</b> the corresponding plug-in.
 * <p> 
 * The following examples illustrate the direct use of the plug-in class
 * loader and its effect on plug-in activation (example ignores error
 * handling).
 *
 * <pre>
 *     ClassLoader loader = descriptor.getPluginClassLoader();
 *
 *     // Load resource by name. Will not activate the plug-in.
 *     URL res = loader.getResource("com/example/Foo/button.gif");
 *     InputStream is = loader.getResourceAsStream("splash.jpg");
 *
 *     // Load resource for class. Will activate the plug-in because
 *     // the referenced class is loaded first and triggers activation.
 *     URL u = com.example.Foo.class.getResource("button.gif");
 *
 *     // Load class by name. Will activate the plug-in.
 *     Class c = loader.loadClass("com.example.Bar");
 *
 *     // Load a resource bundle. May, or may not activate the plug-in, depending
 *     // on the bundle implementation. If implemented as a class, the plug-in
 *     // will be activated. If implemented as a properties file, the plug-in will
 *     // not be activated.
 *     ResourceBundle b = 
 *         ResourceBundle.getBundle("bundle", Locale.getDefault(), loader);
 * </pre>
 *
 * @return the plug-in class loader
 * @see IConfigurationElement#createExecutableExtension
 * @see #isPluginActivated
 * @see #getResourceBundle
 */
public ClassLoader getPluginClassLoader();
 /**
 * Returns a list of plug-in prerequisites required
 * for correct execution of this plug-in.
 *
 * @return an array of plug-in prerequisites, or an empty array
 * if no prerequisites were specified
 */
public IPluginPrerequisite[] getPluginPrerequisites() ;
/**
 * Returns the name of the provider of this plug-in.
 * Returns the empty string if no provider name is specified in 
 * the plug-in manifest file.
 * <p> Note that any translation specified in the plug-in manifest
 * file is automatically applied.
 * </p>
 *
 * @see #getResourceString 
 *
 * @return the name of the provider, possibly the empty string
 */
public String getProviderName();
/**
 * Returns this plug-in's resource bundle for the current locale. 
 * <p>
 * The bundle is stored as the <code>plugin.properties</code> file 
 * in the plug-in install directory, and contains any translatable
 * strings used in the plug-in manifest file (<code>plugin.xml</code>)
 * along with other resource strings used by the plug-in implementation.
 * </p>
 *
 * @return the resource bundle
 * @exception MissingResourceException if the resource bundle was not found
 */
public ResourceBundle getResourceBundle() throws MissingResourceException;
/**
 * Returns a resource string corresponding to the given argument value.
 * If the argument value specifies a resource key, the string
 * is looked up in the default resource bundle. If the argument does not
 * specify a valid key, the argument itself is returned as the
 * resource string. The key lookup is performed in the
 * plugin.properties resource bundle. If a resource string 
 * corresponding to the key is not found in the resource bundle
 * the key value, or any default text following the key in the
 * argument value is returned as the resource string.
 * A key is identified as a string begining with the "%" character.
 * Note, that the "%" character is stripped off prior to lookup
 * in the resource bundle.
 * <p>
 * Equivalent to <code>getResourceString(value, getBundle())</code>
 * </p>
 *
 * @param value the value
 * @return the resource string
 * @see #getResourceBundle
 */
public String getResourceString(String value);
/**
 * Returns a resource string corresponding to the given argument 
 * value and bundle.
 * If the argument value specifies a resource key, the string
 * is looked up in the given resource bundle. If the argument does not
 * specify a valid key, the argument itself is returned as the
 * resource string. The key lookup is performed against the
 * specified resource bundle. If a resource string 
 * corresponding to the key is not found in the resource bundle
 * the key value, or any default text following the key in the
 * argument value is returned as the resource string.
 * A key is identified as a string begining with the "%" character.
 * Note that the "%" character is stripped off prior to lookup
 * in the resource bundle.
 * <p>
 * For example, assume resource bundle plugin.properties contains
 * name = Project Name
 * <pre>
 *     getResourceString("Hello World") returns "Hello World"</li>
 *     getResourceString("%name") returns "Project Name"</li>
 *     getResourceString("%name Hello World") returns "Project Name"</li>
 *     getResourceString("%abcd Hello World") returns "Hello World"</li>
 *     getResourceString("%abcd") returns "%abcd"</li>
 *     getResourceString("%%name") returns "%name"</li>
 * </pre>
 * </p>
 *
 * @param value the value
 * @param bundle the resource bundle
 * @return the resource string
 * @see #getResourceBundle
 */
public String getResourceString(String value, ResourceBundle bundle);
/**
 * Returns all runtime libraries declared by this plug-in.
 * Returns an empty array if this plug-in has no runtime libraries.
 *
 * @return the runtime libraries declared by this plug-in
 */
public ILibrary[] getRuntimeLibraries();
/**
 * Returns the unique identifier of this plug-in.
 * This identifier is a non-empty string and is unique 
 * within the plug-in registry.
 *
 * @return the unique identifier of the plug-in 
 *		(e.g. <code>"org.eclipse.core.runtime"</code>)
 */
public String getUniqueIdentifier();
/**
 * Returns the version identifier of this plug-in.
 *
 * @return the plug-in version identifier
 */
public PluginVersionIdentifier getVersionIdentifier();
/**
 * Returns whether the plug-in described by this descriptor
 * has been activated. Invoking this method will not cause the
 * plug-in to be activated.
 *
 * @return <code>true</code> if this plug-in is activated, and
 *   <code>false</code> otherwise
 * @see #getPlugin
 */
public boolean isPluginActivated();
}