Eclipse Platform Release 3.7

## org.eclipse.core.runtime
Interface IPluginDescriptor

Deprecated. `IPluginDescriptor` was refactored in Eclipse 3.0. Most of the functionality has moved to `Platform` and the plug-in descriptor has been replaced with the OSGi `Bundle` object.

This interface must only be used by plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in.

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 `Platform` methods but need not be interrogated itself. There are a small number of plug-in descriptor method equivalents supplied by `Bundle` itself. The details are spelled out in the comments on each `IPluginDescriptor` method.

Clients of this interface have a reference to an `IPluginDescriptor` 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:

- the descriptor was discovered using methods such as `IPluginRegistry.getPluginDescriptor()`. The code should be updated to use one of the bundle discovery mechanisms such as `Platform.getBundle()`.
- the descriptor is from the plug-in itself. The code should be updated to use the plug-in's bundle instead.
- 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.

The resulting bundle object can be used to carry out the adaptation steps outlined for each of the `IPluginDescriptor` methods.

    public interface IPluginDescriptor

A plug-in descriptor contains information about a plug-in obtained from the plug-in's manifest (`plugin.xml`) file.

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 (`getPlugin`) generally runs plug-in-defined code.

See Also:
  `getPlugin()`
Restriction:
  This interface is not intended to be implemented by clients.

Method Summary

`URL`

`find(IPath path)`
Deprecated. Use

         Platform.find(bundle, file)

where `bundle` is the bundle associated with the relevant plug-in.

`URL`

`find(IPath path, Map override)`
Deprecated. Use

         Platform.find(bundle, path, override)

where `bundle` is the bundle associated with the relevant plug-in.

`IExtension`

`getExtension(String extensionName)`
Deprecated. Use

         Platform.getExtensionRegistry().getExtension(id + "." + extensionName)

where `id` is the plug-in id.

`IExtensionPoint`

`getExtensionPoint(String extensionPointId)`
Deprecated. Use

         Platform.getExtensionRegistry().getExtensionPoint(id, extensionPointId)

where `id` is the plug-in id.

`IExtensionPoint[]`

`getExtensionPoints()`
Deprecated. Use

         Platform.getExtensionRegistry().getExtensionPoints(id)

where `id` is the plug-in id.

`IExtension[]`

`getExtensions()`
Deprecated. Use

         Platform.getExtensionRegistry().getExtensions(id)

where `id` is the plug-in id.

`URL`

`getInstallURL()`
Deprecated. Use

         bundle.getEntry("/");

where `bundle` is the bundle associated with the relevant plug-in or simply use the `getEntry` API to construct the desired URL.

`String`

`getLabel()`
Deprecated. Use

         bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_NAME)

where `bundle` is the bundle associated with the relevant plug-in.

`Plugin`

`getPlugin()`
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., `MyPlugin.getInstance()`). If this method is being used to activate a plug-in then the following code is equivalent:

         bundle.start()

where `bundle` is the bundle associated with the relevant plug-in.

`ClassLoader`

`getPluginClassLoader()`
Deprecated. Use

         bundle.loadClass(className)

where `bundle` is the bundle associated with the relevant plug-in.

`IPluginPrerequisite[]`

`getPluginPrerequisites()`
Deprecated. Use

         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);

where `bundle` is the bundle associated with the relevant plug-in. The resultant elements array contains one entry for each required plug-in.

`String`

`getProviderName()`
Deprecated. Use

         bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VENDOR)

where `bundle` is the bundle associated with the relevant plug-in.

`ResourceBundle`

`getResourceBundle()`
Deprecated. Use

         Platform.getResourceBundle(bundle)

where `bundle` is the bundle associated with the relevant plug-in.

`String`

`getResourceString(String value)`
Deprecated. Use

         Platform.getResourceString(bundle, value)

where `bundle` is the bundle associated with the relevant plug-in.

`String`

`getResourceString(String value, ResourceBundle resourceBundle)`
Deprecated. Use

         Platform.getResourceString(bundle, value, resourceBundle)

where `bundle` is the bundle associated with the relevant plug-in.

`ILibrary[]`

`getRuntimeLibraries()`
Deprecated. Use

         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);

where `bundle` is the bundle associated with the relevant plug-in. The resultant elements array contains one entry for each entry on the bundle's classpath..

`String`

`getUniqueIdentifier()`
Deprecated. Use

         bundle.getSymbolicName()

where `bundle` is the bundle associated with the relevant plug-in.

`PluginVersionIdentifier`

`getVersionIdentifier()`
Deprecated. Use

         String version = (String) bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VERSION);
         new PluginVersionIdentifier(version);

where `bundle` is the bundle associated with the relevant plug-in.

`boolean`

`isPluginActivated()`
Deprecated. Use

         bundle.getState == org.osgi.framework.Bundle.ACTIVE

where `bundle` is the bundle associated with the relevant plug-in.

Method Detail

### getExtension

    IExtension getExtension(String extensionName)

  Deprecated. Use

           Platform.getExtensionRegistry().getExtension(id + "." + extensionName)

  where `id` is the plug-in id.

  Returns the extension with the given simple identifier declared in this plug-in, or `null` if there is no such extension. Since an extension might not have an identifier, some extensions can only be found via the `getExtensions` method.

  Parameters:
    `extensionName` - the simple identifier of the extension (e.g. `"main"`).
  Returns:
    the extension, or `null`

### getExtensionPoint

    IExtensionPoint getExtensionPoint(String extensionPointId)

  Deprecated. Use

           Platform.getExtensionRegistry().getExtensionPoint(id, extensionPointId)

  where `id` is the plug-in id.

  Returns the extension point with the given simple identifier declared in this plug-in, or `null` if there is no such extension point.

  Parameters:
    `extensionPointId` - the simple identifier of the extension point (e.g. `"wizard"`).
  Returns:
    the extension point, or `null`

### getExtensionPoints

    IExtensionPoint[] getExtensionPoints()

  Deprecated. Use

           Platform.getExtensionRegistry().getExtensionPoints(id)

  where `id` is the plug-in id.

  Returns all extension points declared by this plug-in. Returns an empty array if this plug-in does not declare any extension points.

  Returns:
    the extension points declared by this plug-in

### getExtensions

    IExtension[] getExtensions()

  Deprecated. Use

           Platform.getExtensionRegistry().getExtensions(id)

  where `id` is the plug-in id.

  Returns all extensions declared by this plug-in. Returns an empty array if this plug-in does not declare any extensions.

  Returns:
    the extensions declared by this plug-in

### getInstallURL

    URL getInstallURL()

  Deprecated. Use

           bundle.getEntry("/");

  where `bundle` is the bundle associated with the relevant plug-in or simply use the `getEntry` API to construct the desired URL.

  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 `Plugin.getStateLocation`.

  Returns:
    the URL of this plug-in's install directory
  See Also:
    `getPlugin()`, `Plugin.getStateLocation()`

### getLabel

    String getLabel()

  Deprecated. Use

           bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_NAME)

  where `bundle` is the bundle associated with the relevant plug-in.

  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.

  Note that any translation specified in the plug-in manifest file is automatically applied.

  Returns:
    a displayable string label for this plug-in, possibly the empty string
  See Also:
    `getResourceString(String)`

### getPlugin

    Plugin getPlugin()
                     throws CoreException

  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., `MyPlugin.getInstance()`). If this method is being used to activate a plug-in then the following code is equivalent:

           bundle.start()

  where `bundle` is the bundle associated with the relevant plug-in.

  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.

  Returns:
    the plug-in runtime object
  Throws:
    `CoreException` - if this plug-in's runtime object could not be created.
  See Also:
    `isPluginActivated()`

### getPluginClassLoader

    ClassLoader getPluginClassLoader()

  Deprecated. Use

           bundle.loadClass(className)

  where `bundle` is the bundle associated with the relevant plug-in.

  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 not activate the corresponding plug-in. Successfully loading a class will always activate the corresponding plug-in.

  The following examples illustrate the direct use of the plug-in class loader and its effect on plug-in activation (example ignores error handling).

           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);

  Returns:
    the plug-in class loader
  See Also:
    `IConfigurationElement.createExecutableExtension(String)`, `isPluginActivated()`, `getResourceBundle()`

### getPluginPrerequisites

    IPluginPrerequisite[] getPluginPrerequisites()

  Deprecated. Use

           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);

  where `bundle` is the bundle associated with the relevant plug-in. The resultant elements array contains one entry for each required plug-in.

  Returns a list of plug-in prerequisites required for correct execution of this plug-in.

  Returns:
    an array of plug-in prerequisites, or an empty array if no prerequisites were specified

### getProviderName

    String getProviderName()

  Deprecated. Use

           bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VENDOR)

  where `bundle` is the bundle associated with the relevant plug-in.

  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.

  Note that any translation specified in the plug-in manifest file is automatically applied.

  Returns:
    the name of the provider, possibly the empty string
  See Also:
    `getResourceString(String)`

### getResourceBundle

    ResourceBundle getResourceBundle()
                                     throws MissingResourceException

  Deprecated. Use

           Platform.getResourceBundle(bundle)

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns this plug-in's resource bundle for the current locale.

  The bundle is stored as the `plugin.properties` file in the plug-in install directory, and contains any translatable strings used in the plug-in manifest file (`plugin.xml`) along with other resource strings used by the plug-in implementation.

  Returns:
    the resource bundle
  Throws:
    `MissingResourceException` - if the resource bundle was not found

### getResourceString

    String getResourceString(String value)

  Deprecated. Use

           Platform.getResourceString(bundle, value)

  where `bundle` is the bundle associated with the relevant plug-in.

  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.

  Equivalent to `getResourceString(value, getResourceBundle())`

  Parameters:
    `value` - the value
  Returns:
    the resource string
  See Also:
    `getResourceBundle()`

### getResourceString

    String getResourceString(String value,
                             ResourceBundle resourceBundle)

  Deprecated. Use

           Platform.getResourceString(bundle, value, resourceBundle)

  where `bundle` is the bundle associated with the relevant plug-in.

  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.

  For example, assume resource bundle plugin.properties contains name = Project Name

           getResourceString("Hello World") returns "Hello World"
           getResourceString("%name") returns "Project Name"
           getResourceString("%name Hello World") returns "Project Name"
           getResourceString("%abcd Hello World") returns "Hello World"
           getResourceString("%abcd") returns "%abcd"
           getResourceString("%%name") returns "%name"

  Parameters:
    `value` - the value
    `resourceBundle` - the resource bundle
  Returns:
    the resource string
  See Also:
    `getResourceBundle()`

### getRuntimeLibraries

    ILibrary[] getRuntimeLibraries()

  Deprecated. Use

           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);

  where `bundle` is the bundle associated with the relevant plug-in. The resultant elements array contains one entry for each entry on the bundle's classpath..

  Returns all runtime libraries declared by this plug-in. Returns an empty array if this plug-in has no runtime libraries.

  Returns:
    the runtime libraries declared by this plug-in

### getUniqueIdentifier

    String getUniqueIdentifier()

  Deprecated. Use

           bundle.getSymbolicName()

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns the unique identifier of this plug-in. This identifier is a non-empty string and is unique within the plug-in registry.

  Returns:
    the unique identifier of the plug-in (e.g. `"org.eclipse.core.runtime"`)

### getVersionIdentifier

    PluginVersionIdentifier getVersionIdentifier()

  Deprecated. Use

           String version = (String) bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VERSION);
           new PluginVersionIdentifier(version);

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns the version identifier of this plug-in.

  Returns:
    the plug-in version identifier

### isPluginActivated

    boolean isPluginActivated()

  Deprecated. Use

           bundle.getState == org.osgi.framework.Bundle.ACTIVE

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns whether the plug-in described by this descriptor has been activated. Invoking this method will not cause the plug-in to be activated.

  Returns:
    `true` if this plug-in is activated, and `false` otherwise
  See Also:
    `getPlugin()`

### find

    URL find(IPath path)

  Deprecated. Use

           Platform.find(bundle, file)

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns a URL for the given path. Returns `null` if the URL could not be computed or created.

  Parameters:
    `path` - path relative to plug-in installation location
  Returns:
    a URL for the given path or `null` It is not necessary to perform a 'resolve' on this URL.
  Since:
    2.0

### find

    URL find(IPath path,
             Map override)

  Deprecated. Use

           Platform.find(bundle, path, override)

  where `bundle` is the bundle associated with the relevant plug-in.

  Returns a URL for the given path. Returns `null` 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, `null` 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.

  Parameters:
    `path` - file path relative to plug-in installation location
    `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 `null`, or does not contain the required substitution argument, the default is used.
  Returns:
    a URL for the given path or `null`. It is not necessary to perform a 'resolve' on this URL.
  Since:
    2.0

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.