The Eclipse plug-in model for Lotus Notes and Domino

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.

Platform

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:

FavoritesPlugin.getDefault().getBundle()

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

 Home: Introduction
 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