bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/IPluginDescriptor.java

/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime;

import java.net.URL;
import java.util.*;

/**
 * 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>
 *
 * @deprecated 
 * <code>IPluginDescriptor</code> was refactored in Eclipse 3.0.
 * Most of the functionality has moved to {@link Platform} and the 
 * plug-in descriptor has been replaced with the OSGi <code>Bundle</code> 
 * object.
 * <p>
 * This interface must only be used by plug-ins 
 * which explicitly require the org.eclipse.core.runtime.compatibility plug-in.
 * </p>
 * <p>
 * For most uses the bundle object can be treated as an opaque token
 * representing your plug-in to the system -- It must be supplied to various 
 * <code>Platform</code> methods but need not be interrogated itself.
 * There are a small number of plug-in descriptor method equivalents 
 * supplied by <code>Bundle</code> itself.  The details are spelled out
 * in the comments on each <code>IPluginDescriptor</code> method.
 * </p>
 * <p>
 * Clients of this interface have a reference to an <code>IPluginDescriptor</code> 
 * corresponding to a plug-in.  To adapt to the deprecation, the bundle corresponding
 * to the plug-in generally needs to be acquired. There are several cases:
 * <ul>
 * <li>the descriptor was discovered using methods such as 
 * <code>IPluginRegistry.getPluginDescriptor()</code>.  The code should be 
 * updated to use one of the bundle discovery mechanisms such as 
 * <code>Platform.getBundle()</code>.
 * </li>
 * <li>the descriptor is from the plug-in itself.  The code should be updated to
 * use the plug-in's bundle instead.
 * </li>
 * <li>the descriptor is supplied by a third party.  The plug-in writer must 
 * cooperate with that party to obtain a bundle rather than a descriptor.
 * </li>
 * </ul>
 * </p>
 * <p>
 * The resulting bundle object can be used
 * to carry out the adaptation steps outlined for each of the 
 * <code>IPluginDescriptor</code> methods.
 * </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>
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getExtensionRegistry().getExtension(id + "." + extensionName) 
	 * </pre>
	 * where <code>id</code> is the plug-in id.
	 */
	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>
	 * @deprecated  
	 * Use 
	 * <pre>
	 *     Platform.getExtensionRegistry().getExtensionPoint(id, extensionPointId) 
	 * </pre>
	 * where <code>id</code> is the plug-in id.
	 */
	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
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getExtensionRegistry().getExtensionPoints(id) 
	 * </pre>
	 * where <code>id</code> is the plug-in id.
	 */
	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
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getExtensionRegistry().getExtensions(id) 
	 * </pre>
	 * where <code>id</code> is the plug-in id.
	 */
	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. This directory is usually
	 * read-only. Plug-in relative information should be written to the location 
	 * provided by <code>Plugin.getStateLocation</code>.
	 *
	 * @return the URL of this plug-in's install directory
	 * @see #getPlugin()
	 * @see Plugin#getStateLocation()
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     bundle.getEntry("/");
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in or simply use the <code>getEntry</code> API
	 * to construct the desired URL.
	 */
	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(String)
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_NAME) 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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()
	 * @deprecated 
	 * In Eclipse 3.0 plug-in runtime objects are not globally managed and
	 * so are not generically accessible.  Rather, each plug-in is free to declare
	 * API which exposes the plug-in runtime object (e.g., <code>MyPlugin.getInstance()</code>).
	 * 
	 * If this method is being used to activate a plug-in then the following code is
	 * equivalent:
	 * <pre>
	 *     bundle.start()
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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(String)
	 * @see #isPluginActivated()
	 * @see #getResourceBundle()
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     bundle.loadClass(className)
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     import org.eclipse.osgi.util.ManifestElement;
	 *     import org.osgi.framework.Constants;
	 *     ...
	 *     String requires = bundle.getHeaders().get(Constants.REQUIRE_BUNDLE);
	 *     ManifestElement[] elements = ManifestElement.parseHeader(Constants.REQUIRE_BUNDLE, requires);
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.  The resultant elements array contains one
	 * entry for each required plug-in.
	 */
	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>
	 * @return the name of the provider, possibly the empty string
	 * @see #getResourceString(String)
	 * @deprecated
	 * Use 
	 * <pre>
	 *     bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VENDOR) 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getResourceBundle(bundle)
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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, getResourceBundle())</code>
	 * </p>
	 *
	 * @param value the value
	 * @return the resource string
	 * @see #getResourceBundle()
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getResourceString(bundle, value)
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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 resourceBundle the resource bundle
	 * @return the resource string
	 * @see #getResourceBundle()
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.getResourceString(bundle, value, resourceBundle) 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	public String getResourceString(String value, ResourceBundle resourceBundle);

	/**
	 * 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
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     import org.eclipse.osgi.util.ManifestElement;
	 *     import org.osgi.framework.Constants;
	 *     ...
	 *     String requires = bundle.getHeaders().get(Constants.BUNDLE_CLASSPATH);
	 *     ManifestElement[] elements = ManifestElement.parseHeader(Constants.BUNDLE_CLASSPATH, requires);
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.  The resultant elements array contains one
	 * entry for each entry on the bundle's classpath..
	 */
	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>)
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     bundle.getSymbolicName() 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	public String getUniqueIdentifier();

	/**
	 * Returns the version identifier of this plug-in.
	 *
	 * @return the plug-in version identifier
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     String version = (String) bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VERSION);
	 *     new PluginVersionIdentifier(version); 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	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()
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     bundle.getState == org.osgi.framework.Bundle.ACTIVE 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	public boolean isPluginActivated();

	/**
	 * Returns a URL for the given path.  Returns <code>null</code> if the URL
	 * could not be computed or created.
	 * 
	 * @param path path relative to plug-in installation location 
	 * @return a URL for the given path or <code>null</code>  It is not
	 * necessary to perform a 'resolve' on this URL.
	 * 
	 * @since 2.0
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.find(bundle, file) 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	public URL find(IPath path);

	/**
	 * Returns a URL for the given path.  Returns <code>null</code> if the URL
	 * could not be computed or created.
	 * 
	 * find will look for this path under the directory structure for this plugin
	 * and any of its fragments.  If this path will yield a result outside the
	 * scope of this plugin, <code>null</code> will be returned.  Note that
	 * there is no specific order to the fragments.
	 * 
	 * The following arguments may also be used
	 * 
	 *  $nl$ - for language specific information
	 *  $os$ - for operating system specific information
	 *  $ws$ - for windowing system specific information
	 * 
	 * A path of $nl$/about.properties in an environment with a default 
	 * locale of en_CA will return a URL corresponding to the first place
	 * about.properties is found according to the following order:
	 *   plugin root/nl/en/CA/about.properties
	 *   fragment1 root/nl/en/CA/about.properties
	 *   fragment2 root/nl/en/CA/about.properties
	 *   ...
	 *   plugin root/nl/en/about.properties
	 *   fragment1 root/nl/en/about.properties
	 *   fragment2 root/nl/en/about.properties
	 *   ...
	 *   plugin root/about.properties
	 *   fragment1 root/about.properties
	 *   fragment2 root/about.properties
	 *   ...
	 * 
	 * If a locale other than the default locale is desired, use an
	 * override map.
	 * 
	 * @param path file path relative to plug-in installation location
	 * @param override map of override substitution arguments to be used for
	 * any $arg$ path elements. The map keys correspond to the substitution
	 * arguments (eg. "$nl$" or "$os$"). The resulting
	 * values must be of type java.lang.String. If the map is <code>null</code>,
	 * or does not contain the required substitution argument, the default
	 * is used.
	 * @return a URL for the given path or <code>null</code>.  It is not
	 * necessary to perform a 'resolve' on this URL.
	 * 
	 * @since 2.0
	 * @deprecated 
	 * Use 
	 * <pre>
	 *     Platform.find(bundle, path, override) 
	 * </pre>
	 * where <code>bundle</code> is the bundle associated with 
	 * the relevant plug-in.
	 */
	public URL find(IPath path, Map override);
}