Eclipse Platform
2.0

org.eclipse.core.runtime
Interface IPluginDescriptor


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.

This interface is not intended to be implemented by clients.

See Also:
getPlugin()

Method Summary
 URL find(IPath path)
          Returns a URL for the given path.
 URL find(IPath path, Map override)
          Returns a URL for the given path.
 IExtension getExtension(String extensionName)
          Returns the extension with the given simple identifier declared in this plug-in, or null if there is no such extension.
 IExtensionPoint getExtensionPoint(String extensionPointId)
          Returns the extension point with the given simple identifier declared in this plug-in, or null if there is no such extension point.
 IExtensionPoint[] getExtensionPoints()
          Returns all extension points declared by this plug-in.
 IExtension[] getExtensions()
          Returns all extensions declared by this plug-in.
 URL getInstallURL()
          Returns the URL of this plug-in's install directory.
 String getLabel()
          Returns a displayable label for this plug-in.
 Plugin getPlugin()
          Returns the plug-in runtime object corresponding to this plug-in descriptor.
 ClassLoader getPluginClassLoader()
          Returns the plug-in class loader used to load classes and resources for this plug-in.
 IPluginPrerequisite[] getPluginPrerequisites()
          Returns a list of plug-in prerequisites required for correct execution of this plug-in.
 String getProviderName()
          Returns the name of the provider of this plug-in.
 ResourceBundle getResourceBundle()
          Returns this plug-in's resource bundle for the current locale.
 String getResourceString(String value)
          Returns a resource string corresponding to the given argument value.
 String getResourceString(String value, ResourceBundle bundle)
          Returns a resource string corresponding to the given argument value and bundle.
 ILibrary[] getRuntimeLibraries()
          Returns all runtime libraries declared by this plug-in.
 String getUniqueIdentifier()
          Returns the unique identifier of this plug-in.
 PluginVersionIdentifier getVersionIdentifier()
          Returns the version identifier of this plug-in.
 boolean isPluginActivated()
          Returns whether the plug-in described by this descriptor has been activated.
 

Method Detail

getExtension

public IExtension getExtension(String extensionName)
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

public IExtensionPoint getExtensionPoint(String extensionPointId)
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

public IExtensionPoint[] getExtensionPoints()
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

public IExtension[] getExtensions()
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

public URL getInstallURL()
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.

Returns:
the URL of this plug-in's install directory

getLabel

public String getLabel()
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(java.lang.String)

getPlugin

public Plugin getPlugin()
                 throws CoreException
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

public ClassLoader getPluginClassLoader()
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(java.lang.String), isPluginActivated(), getResourceBundle()

getPluginPrerequisites

public IPluginPrerequisite[] getPluginPrerequisites()
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

public String getProviderName()
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(java.lang.String)

getResourceBundle

public ResourceBundle getResourceBundle()
                                 throws MissingResourceException
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

public String getResourceString(String value)
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.

Equivalent to getResourceString(value, getBundle())

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

getResourceString

public String getResourceString(String value,
                                ResourceBundle bundle)
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.

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
bundle - the resource bundle
Returns:
the resource string
See Also:
getResourceBundle()

getRuntimeLibraries

public ILibrary[] getRuntimeLibraries()
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

public String getUniqueIdentifier()
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

public PluginVersionIdentifier getVersionIdentifier()
Returns the version identifier of this plug-in.

Returns:
the plug-in version identifier

isPluginActivated

public boolean isPluginActivated()
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

public URL find(IPath path)
Returns a URL for the given path. Returns null if the URL could not be computed or created.

Returns:
a URL for the given path or null It is not necessary to perform a 'resolve' on this URL.
Since:
2.0

find

public URL find(IPath path,
                Map override)
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
2.0

Copyright (c) IBM Corp. and others 2000, 2002. All Rights Reserved.