/*******************************************************************************
* Copyright (c) 2000, 2014 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-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>
*
* @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()
* @noimplement This interface is not intended to be implemented by clients.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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 = (String)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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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 beginning 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.
*/
@Deprecated
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 beginning 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.
*/
@Deprecated
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 = (String)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..
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
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.
*/
@Deprecated
public URL find(IPath path, Map<String,String> override);
}