The following is tip #5 from "Developing Eclipse plug-ins for Lotus Notes and Domino -- 7 tips in 7 minutes," excerpted from Chapter 3 of the book Eclipse: Building Commercial Quality Plug-ins, published by Addison-Wesley Publishing.
When Eclipse first launches, it scans each of the plug-in directories and builds an internal model representing every plug-in it finds. This occurs by scanning each plug-in manifest without loading the plug-ins. The methods in the next two subsections are useful if you want to display information about plug-ins or perform operations based on specific plug-in characteristics without taking the time and memory usage hit associated with loading plug-ins.
The org.eclipse.core.runtime.Platform class provides information about the currently executing Eclipse environment. Using this class, you can obtain information about installed plug-ins (also known as Bundles), extensions, extension points, command line arguments, job manager, installation location, and more. The following are some methods of note:
- asLocalURL(URL) - Translates a plug-in-relative URL to a locally accessible URL.
- find(Bundle bundle, IPath path) - Returns a URL to the resource in the specified bundle.
- getBundle(String) - Returns the bundle with the specified unique identifier.
- getBundleGroupProviders() - Returns an array of bundle providers that contain bundle groups that contain currently installed bundles.
- getExtensionRegistry() - Returns extension and extension point information.
- getJobManager() - Returns the platform job manager.
- getLog(Bundle) - Returns the log for the specified bundle.
- getProduct() - Returns the Eclipse product information.
- inDebugMode() - Returns true if Eclipse is in debug mode, as it is when the user specifies the -debug command line argument.
- resolve(URL) - Resolves a plug-in-relative URL to a URL native to the Java class library (e.g., file, http, etc.).
- run(ISafeRunnable) - Runs the given runnable in a protected mode. Exceptions thrown in the runnable are logged and passed to the runnable's exception handler.
Plug-ins and bundles
Information about the currently installed plug-ins, also known as Bundles, can be obtained using Platform.getBundleGroupProviders() or Platform. getBundle(String). Accessing a plug-in class, also known as a bundle activator, requires the containing plug-in to be loaded whereas interacting with the Bundle interface does not carry such a penalty. If you already have a plug-in class, such as the Favorites plug-in, then you can obtain the Bundle interface for that plug-in by using something like this:
After you obtain the Bundle object, several methods are of interest:
- getBundleId() - Returns the bundle's unique identifier (a long), assigned by Eclipse when the bundle was installed.
- getEntry(String) - Returns a URL for the specified '/'-separated bundle relative path name where getEntry("/") returns the bundle root. This provides access to resoures supplied with the plug-in that are typically read-only. Relative plug-in information should be written to the location provided by Plugin.getStateLocation().
- getHeaders() - Returns a dictionary of headers and values defined in the bundle's MANIFEST.MF file.
- getState() - Returns the current state of a plug-in, such as Bundle.UNINSTALLED, Bundle.INSTALLED, Bundle.RESOLVED, Bundle.STARTING, Bundle.STOPPING, Bundle.ACTIVE.
- getSymbolicName() - Returns the unique plug-in identifier (a java.lang.String), which is the same as the Bundle-SymbolicName declaration in the MANIFEST.MF.
The plug-in version number can be obtained using the getHeaders() method.
new PluginVersionIdentifier( bundle.getHeaders().get("Bundle-Version"))
Plug-in extension registry
You can access the plug-in extension registry using the Plaform. getExtensionRegistry() method. It contains plug-in descriptors, each representing a plug-in. The registry provides the following methods for extracting information about the various plug-ins without loading them.
- getConfigurationElementsFor(String extensionPointId) - Returns all configuration elements from all extensions configured into the identified extension point.
- getExtensionPoint(String extensionPointId) - Returns the extension point with the given extension point identifier in this plug-in registry.
Previously, extensions and extension-points did not change during execution, but that is slowly changing as the Eclipse plug-in model continues to align itself with OSGi. If you are interested in changes during execution, use addRegistryChangeListener(IRegistryChangeListener).
Tip: For more on the plug-in registry, activation, and lifecycle, check out the Equinox project at: www.eclipse.org/equinox.
Developing Eclipse plug-ins for Lotus Notes and Domino
Tip 1: The Eclipse plug-in structure for Lotus Notes and Domino
Tip 2: The Eclipse plug-in directory for Lotus Notes and Domino
Tip 3: The Eclipse plug-in manifest for Lotus Notes and Domino
Tip 4: The Eclipse plug-in class for Lotus Notes and Domino
Tip 5: The Eclipse plug-in model for Lotus Notes and Domino
Tip 6: Eclipse logging for Lotus Notes and Domino
Tip 7: Eclipse plug-in types for Lotus Notes and Domino
This chapter is excerpted from Eclipse: Building Commercial-Quality Plug-ins, 2nd Edition, by Eric Clayberg and Dan Rubel, published by Addison-Wesley Professional in March 2006. Copyright 2006 Pearson Education Inc. ISBN: 032142672X. Reprinted with permissions, all rights reserved. Click here to see a complete Table of Contents for this book. Click here for the chapter download.