|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
IPluginRegistry.getPluginDescriptor()
. The code should be
updated to use one of the bundle discovery mechanisms such as
Platform.getBundle()
.
The resulting bundle object can be used
to carry out the adaptation steps outlined for each of the
IPluginDescriptor
methods.
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.
getPlugin()
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 = 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 = 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.ACTIVEwhere bundle is the bundle associated with
the relevant plug-in. |
Method Detail |
public IExtension getExtension(String extensionName)
Platform.getExtensionRegistry().getExtension(id + "." + extensionName)where
id
is the plug-in id.
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.
extensionName
- the simple identifier of the extension (e.g. "main"
).
null
public IExtensionPoint getExtensionPoint(String extensionPointId)
Platform.getExtensionRegistry().getExtensionPoint(id, extensionPointId)where
id
is the plug-in id.
null
if there is no such extension point.
extensionPointId
- the simple identifier of the extension point (e.g. "wizard"
).
null
public IExtensionPoint[] getExtensionPoints()
Platform.getExtensionRegistry().getExtensionPoints(id)where
id
is the plug-in id.
public IExtension[] getExtensions()
Platform.getExtensionRegistry().getExtensions(id)where
id
is the plug-in id.
public URL getInstallURL()
bundle.getEntry("/");where
bundle
is the bundle associated with
the relevant plug-in or simply use the getEntry
API
to construct the desired URL.
Plugin.getStateLocation
.
getPlugin()
,
Plugin.getStateLocation()
public String getLabel()
bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_NAME)where
bundle
is the bundle associated with
the relevant plug-in.
Note that any translation specified in the plug-in manifest file is automatically applied.
getResourceString(String)
public Plugin getPlugin() throws CoreException
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.
CoreException
- if this plug-in's runtime object could not be created.isPluginActivated()
public ClassLoader getPluginClassLoader()
bundle.loadClass(className)where
bundle
is the bundle associated with
the relevant 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);
IConfigurationElement.createExecutableExtension(String)
,
isPluginActivated()
,
getResourceBundle()
public IPluginPrerequisite[] getPluginPrerequisites()
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);where
bundle
is the bundle associated with
the relevant plug-in. The resultant elements array contains one
entry for each required plug-in.
public String getProviderName()
bundle.getHeaders().get(org.osgi.framework.Constants.BUNDLE_VENDOR)where
bundle
is the bundle associated with
the relevant plug-in.
Note that any translation specified in the plug-in manifest file is automatically applied.
getResourceString(String)
public ResourceBundle getResourceBundle() throws MissingResourceException
Platform.getResourceBundle(bundle)where
bundle
is the bundle associated with
the relevant plug-in.
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.
MissingResourceException
- if the resource bundle was not foundpublic String getResourceString(String value)
Platform.getResourceString(bundle, value)where
bundle
is the bundle associated with
the relevant plug-in.
Equivalent to getResourceString(value, getResourceBundle())
value
- the value
getResourceBundle()
public String getResourceString(String value, ResourceBundle resourceBundle)
Platform.getResourceString(bundle, value, resourceBundle)where
bundle
is the bundle associated with
the relevant plug-in.
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"
value
- the valueresourceBundle
- the resource bundle
getResourceBundle()
public ILibrary[] getRuntimeLibraries()
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);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..
public String getUniqueIdentifier()
bundle.getSymbolicName()where
bundle
is the bundle associated with
the relevant plug-in.
"org.eclipse.core.runtime"
)public PluginVersionIdentifier getVersionIdentifier()
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.
public boolean isPluginActivated()
bundle.getState == org.osgi.framework.Bundle.ACTIVEwhere
bundle
is the bundle associated with
the relevant plug-in.
true
if this plug-in is activated, and
false
otherwisegetPlugin()
public URL find(IPath path)
Platform.find(bundle, file)where
bundle
is the bundle associated with
the relevant plug-in.
null
if the URL
could not be computed or created.
path
- path relative to plug-in installation location
null
It is not
necessary to perform a 'resolve' on this URL.public URL find(IPath path, Map override)
Platform.find(bundle, path, override)where
bundle
is the bundle associated with
the relevant plug-in.
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.
path
- file path relative to plug-in installation locationoverride
- 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.
null
. It is not
necessary to perform a 'resolve' on this URL.
|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.