The runtime plug-in model

The platform runtime engine is started when a user starts an application developed with Eclipse. The runtime implements the basic plug-in model and infrastructure used by the platform. It keeps track of all of the installed plug-ins and the function that they provide.

A plug-in is a structured component that contributes code (or documentation or both) to the system and describes it in a structured way. Plug-ins can define extension points, well-defined function points that can be extended by other plug-ins. When a plug-in contributes an implementation for an extension point, we say that it adds an extension to the platform. These extensions and extension points are declared in the plug-ins's manifest (plugin.xml) file.

Using a common extension model provides a structured way for plug-ins to describe the ways they can be extended, and for client plug-ins to describe the extensions they supply. Defining an extension point is much like defining any other API. The only difference is that the extension point is declared using XML instead of a code signature. Likewise, a client plug-in uses XML to describe its specific extension to the system.

A general goal of the runtime is that the end user should not pay a memory or performance penalty for plug-ins that are installed, but not used. The declarative nature of the platform extension model allows the runtime engine to determine what extension points and extensions are supplied by a plug-in without ever running it. Thus, many plug-ins can be installed, but none will be activated until a function provided by a plug-in has been requested according to the user's activity. This is an important feature in providing a scalable, robust platform.

Plug-ins and bundles

The mechanics for supporting plug-ins are implemented using the OSGi framework. From this standpoint, a plug-in is the same thing as an OSGi bundle. The bundle and its associated classes specify and implement the process for Java class-loading, prequisite management, and the bundle's life-cycle. For the rest of this discussion, we use the terms plug-in and bundle interchangeably, unless discussing a particular class in the framework.

Plugin

The Plugin class represents a plug-in that is running in the platform. It is a convenient place to centralize the life-cycle aspects and overall semantics of a plug-in. A plug-in can implement specialized function for the start and stop aspects of its life-cycle. Each life-cycle method includes a reference to a BundleContext which can supply additional information.

The start portion of the life-cycle is worth particular discussion. We've seen already that information about a plug-in can be obtained from the plug-in's manifest file without ever running any of the plug-in's code. Typically, some user action in the workbench causes a chain of events that requires the starting of a plug-in. From an implementation point of view, a plug-in is never started until a class contained in the plug-in needs to be loaded.

The start method has been a convenient place to implement initialization and registration behavior for a plug-in. However, it is important to realize that your plug-in can be started in many different circumstances. Something as simple as obtaining an icon to decorate an object can cause one of your plug-in's classes to be loaded, thus starting your plug-in. Over-eager initialization can cause your plug-in's code and data to be loaded long before it is necessary. Therefore, it's important to look closely at your plug-in's initialization tasks and consider alternatives to performing initialization at start-up.

• Registration activities such as registering listeners or starting background threads are appropriate during plug-in start-up if they can be performed quickly. However, it is advisable to trigger these actions as part of accessing the plug-in's data if the registration activities have side-effects such as initializing large data structures or performing unrelated operations.
• Initialization of data is best done lazily, when the data is first accessed, rather than automatically in the start-up code. This ensures that large data structures are not built until they are truly necessary.

Bundle Context

Life-cycle management is where the OSGi "bundle" terminology and the platform's "plug-in" terminology meet. When your plug-in is started, it is given a reference to a BundleContext from which it can obtain information related to the plug-in. The BundleContext can also be used to find out about other bundles/plug-ins in the system.

BundleContext.getBundles() can be used to obtain an array of all bundles in the system. Listeners for BundleEvent can be registered so that your plug-in is aware when another bundle has a change in its life-cycle status. See the javadoc for BundleContext and BundleEvent for more information.

Prior to 3.0, a plug-in registry (IPluginRegistry) was provided to supply similar information. For example, it could be queried for the plug-in descriptors of all plug-ins in the system. This registry is now deprecated and BundleContext should be used for this purpose. The platform registry is now used exclusively for information about extensions and extension points.

Bundle Activator

The BundleActivator interface defines the start and stop behavior implemented in Plugin. Although the Plugin class is a convenient place to implement this function, a plug-in developer has complete freedom to implement the interface for BundleActivator in any class appropriate for the plug-in's design. In fact, your plug-in need not implement this interface at all if it does not have specific life-cycle management needs.

Bundles

Underneath every plug-in lies an OSGi bundle managed by the framework. The Bundle is the OSGi unit of modularity. Fundamentally, a bundle is just a collection of files (resources and code) installed in the platform. Each bundle has its own Java class loader, and includes protocol for starting, stopping, and uninstalling itself. From the Eclipse platform point of view, Bundle is merely an implementation class. Plug-in developers do not extend the bundle class, but use Plugin or other BundleActivator implementations to represent the plug-in.

Extension points and the registry

While the "bundle" aspects of a plug-in may be interesting to the runtime plug-in and runtime tools, it is much more common that a plug-in is concerned with what extension points have been defined by plug-ins and what extensions are contributed by plug-ins. This information is provided by the platform extension registry, IExtensionRegistry.

Why might a plug-in want to know what extensions are present? A concrete example will help show the need for this information and the protocol for getting it.

Recall the workbench Show View dialog which shows all of the available views that have been installed in the platform.

We know that the category names and view names of all contributed views are specified in the plugin.xml file for any plug-in that contributes an extension for org.eclipse.ui.views. But how does the workbench find out this information? From the platform extension registry. The following code is a simplified snippet based on the workbench implementation of the Show View dialog:

	...
	IExtensionRegistry registry = Platform.getExtensionRegistry();
	IExtensionPoint point = registry.getExtensionPoint("org.eclipse.ui.views");
	if (point == null) return;
	IExtension[] extensions = point.getExtensions();
	for (int i = 0; i < extensions.length; i++)
		readExtension(extensions[i]);  //get the information about each extension
	...

We see above that the registry can be obtained from the Platform class. The protocol in IExtensionRegistry is used to find the extension point named org.eclipse.ui.views. Information in the registry about particular extension points or extensions can be found using protocol defined in IExtensionRegistry, IExtensionPoint, and IExtension. The javadoc for these classes provides detailed information about the registry protocol.

Once the extension definition of interest has been found, protocol in IConfigurationElement can be used to examine the individual attributes of an extension.