Eclipse Corner Article

What the heck is a plug-in anyway?

Summary

The Eclipse Platform is based on the notion of plug-ins. Plug-ins are a simple but powerful mechanism that allow developers and users to construct complex tool sets by composing functionality (i.e., plug-ins). There are of course a number of subtleties in how plug-ins are defined and how they interact. This article attempts to demystify plug-ins and make it easier to create and manage Eclipse Platform configurations.

By Debbie Wilson and Jeff McAffer, IBM OTI Labs
March 9, 2004

Why Plug-ins?

One of the main design points of the Eclipse Platform is that it is extremely extensible. Another is that it is uniform. The Eclipse plug-in model is key in satisfying both of these goals. A plug-in is a piece of functionality which can be added to the Platform. Tools or applications are constructed by creating one or more plug-ins. How tools or applications are factored into plug-ins depends on the nature of the tool or application.

The Eclipse Platform itself, for example, is made up entirely of plug-ins: some 50 or so in all. Even the runtime which manages plug-ins, is itself a plug-in! Plug-ins interact via well defined API's. Since everything is a plug-in and plug-ins interact via public interfaces, all plug-ins are equal in the system. There are no plug-ins which get special treatment or privileges. For example, the Workbench UI is a plug-in which presents the resource model defined by the Resources plug-in. Since the Workbench accesses the Resources plug-in only via API, all other plug-ins have exactly the same opportunities for manipulating resources.

It follows from this, that capabilities are added to the Platform incrementally, by adding plug-ins. Each new plug-in ties into the API of existing plug-ins and provides new functionality. Still other plug-ins then build on the API of these new plug-ins to add still more functionality to the Platform. And so on...

Another design point that makes Eclipse extremely extensible is its policy of lazy plug-in activation. Only those plug-ins with code that is actually being used are activated. Lazy activation is key to supporting a large base of installed plug-ins, only some of which are needed in any given user session. Until a plug-in's code is loaded, it has a negligible memory footprint and impact on start up time.

What is a Plug-in?

Note: This article covers plug-ins as they are in Eclipse 2.1. While there are some changes coming in Eclipse 3.0, the basic model described here will continue to be accurate.

Fundamentally, plug-ins are defined by an XML manifest file called plugin.xml. An example plug-in manifest is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<plugin
    id="com.example.myplugin"
    name="My Plugin"
    version="2.0.0"
    provider-name="Example Plug-ins Inc.">
</plugin>

Each plug-in is contained in a file system directory or at a base URL on a server, with a plug-in manifest file (as seen above) and anything else it needs.

A typical plug-in consists of Java code in a JAR library, some read-only files, and other resources such as images, web templates, message catalogs, native code libraries, translation files, etc. Most plug-ins contribute executable code though not all. Documentation plug-ins, for example, contribute online help in the form of HTML pages. If a plug-in does contain code it must either be written in Java or be callable from Java.

The above plug-in example is very simple. The following sections show how the following elements of the plug-in architecture are used to round out the specification of a plug-in.

Libraries define the location of executable code.
Prerequisites define dependencies between plug-ins.
Extension points allow other plug-ins to contribute information in a well-defined manner.
Extensions contribute information to the extension points of other plug-ins.
Fragments allow a plug-in to be extended without the need to modify anything related to the existing plug-in.

What is a Library?

The first thing you are likely to want to do with a plug-in is define the location of the plug-in's executable code and/or resources. library entries in plugin.xml (see example below) describe the shape of these contributions.

<?xml version="1.0" encoding="UTF-8"?>
<plugin
    id="com.example.myplugin"
    name="My Plugin"
    version="2.0.0"
    provider-name="Example Plug-ins Inc.">

  <runtime>
    <library name="mylibrary.jar" type="code">
      <export name="*"/>
    </library>
  </runtime>

</plugin>

library elements specify a portion of the plug-in's local classpath. Each plug-in has two classpaths: one for code libraries and one for resource libraries. Correspondingly, library elements have a type attribute whose value is either code or resource (code is the default). Code libraries contain Java class files as well as any associated resources. There is no need to artificially separate resources from the code as code libraries can contain both. Libraries defined as type resource on the other hand, can contain only resources (properties files, images).

The distinction allows the classloaders to ignore resource libraries while loading classes, as they are guaranteed to contain only resources (e.g., translated properties files). This translates into performance improvements as there are fewer places to look for classes. Note that both the code and resource libraries are consulted when loading resources.

Each library element identifies a files system location (directory or jar file) which contains the code and/or resources. The path specified is relative to the plug-in's file system directory and cannot resolve to a location outside the scope of the plug-in (for example, "../../foo.jar" is not allowed).

By default, everything in a code library is considered private (i.e., known only within the scope of the plug-in). Portions of a library are made visible outside its containing plug-in using the export sub-element. Plug-ins can export some, all or none of their libraries by specifying patterns in the name attribute of the export tag.

A library entry contained in our example plug-in, com.example.myplugin is shown in the snippet above. It shows a code library called "mylibrary.jar" which is exported in total.

What is a Plug-in Prerequisite?

Plug-ins must declare their dependencies on other plug-ins using a requires element in their plug-in manifest file. Typically dependencies arise from inter-plug-in class references. If a plug-in A requires plug-in B, plug-in B is said to be a prerequisite of plug-in A. Continuing our example, the manifest below shows the plugin.xml expressing a dependency on com.example.anotherplugin.

<?xml version="1.0" encoding="UTF-8"?>
<plugin
    id="com.example.myplugin"
    name="My Plug-in"
	 version="2.0.0"
    provider-name="Example Plug-ins Inc.">

  <requires>
    <import plugin="com.example.anotherplugin"
        version="2.1.3"
        match="equivalent"/>
  </requires>

  <runtime>
    <library name="mylibrary.jar" type="code">
      <export name="*"/>
    </library>
  </runtime>

</plugin>

In this example, com.example.myplugin (My Plugin) can access any of the classes in com.example.anotherplugin (Another Plugin) which are explicitly exported in its library statements.

Notice that the import statement is qualified by a version number and matching rule. Versions refine the dependencies between plugins and help the runtime choose between different installations of the same plug-in. In general the runtime picks the most recent version which matches given the matching rule. Eclipse version numbers are a four part string of the form major.minor.service.tag. Versions are compared using one of four matching rules.

perfect: All four components of the version must match.
equivalent: major and minor must match and others must sort after
compatible (default): major must match and others must sort after
greaterOrEqual: Any version which is a perfect match or sorts lexographically after

Plug-in dependencies are transitive. That is, if Another Plugin requires some plug-in, say Final Plugin, then My Plugin will not be enabled unless both Another Plugin and Final Plugin are present. This is easy to see since Another Plugin would be disabled if its prerequisites are not present (e.g., Final Plugin is missing). Similarly, My Plugin would also be disabled if its prerequisite, Another Plugin, is not present. Under no circumstances are circular dependencies permitted. Any plug-in involved in a cycle will be disabled at runtime.

Class visibility through the dependency chain is not transitive unless explicitly stated. That is, My Plugin cannot see the classes in Final Plugin. This effectively encapsulates the implementation of Another Plugin. Where transitivity is required, the export attribute of the import tag is used to re-export the classes exported by imported plug-ins. (try saying that a few times quickly!). For example, Another Plugin can explicitly re-export its import of Final Plugin:

    <import plugin="com.example.finalplugin" export="true"/>

Finally, plug-in prerequisite statements can be made optional by adding the optional="true" attribute to the import tag (see below for an example). Marking an import as optional simply states that if the specified plug-in is not found at runtime, the dependent plug-in should be left enabled. This is used when a plug-in can be used in many scenarios or it is reasonable to operate with reduced function. It allows the creation of minimal installs that cover functional subsets. Authors of plug-ins using optional prerequisites should take special care to avoid or handle the ClassNotFoundExceptions which will occur when the optional plug-in is not present.

    <import plugin="com.example.finalplugin" optional="true"/>

What are Extensions and Extension Points?

Extension points are a mechanism used by plug-ins to indicate they are willing to accept contributions from other plug-ins. An extension is a plug-in's way of contributing information to these extension points. For example, a UI plug-in might expose an extension point for menu actions. A plug-in wishing to contribute an action to the UI would define an extension for the UI's menu action extension point.

Extension points have a globally unique id constructed from the defining plug-in id and a simple id specified in the extension point itself. The example below is from the org.eclipse.ui plug-in. The full identifier of the extension point is therefore org.eclipse.ui.actionSets. All extension points have this relatively simple form.

  <extension-point name="Action Sets" id="actionSets"/>

The exact form of extensions is defined by the plug-in which defines the extension point being extended. In the above example, the UI plug-in specifies what information is needed to define the menu action as well as the form of that information. For example, the UI needs an icon and label to draw and a class to instantiate and run when the menu entry is selected. Extensions which identify classes to run are called executable extensions. The type characteristics (e.g., superclass, interfaces) of the class are also defined by the extension point itself. The snippet below shows an example UI extension.

  <extension
      point="org.eclipse.ui.actionSets">
    <actionSet
        label="Example"
        visible="false"
        id="com.example.actions">
      <action
          id="com.example.action1"
          class="com.example.CoolAction"
          icon="icons/action1.gif"
          label="Cool Action"
      </action>
    </actionSet>
  </extension>

A plug-in can define any number of extension points and extensions. Further, any given extension point may be extended by any number of extensions. Extensions can extend extension points defined in their own plug-in or in others. It follows, therefore, that extension points can accept extensions from their own plug-in or other plug-ins.

Extending an extension point does not imply a dependency relationship. Rather, it is a statement that if there is an extension point with the given id (point attribute in the extension tag), add the given extension. Otherwise, do nothing. Doc plug-ins for example have no need to get classes from the Help plug-ins -- they simply add extensions to Help system extension points.

What is a Plug-in Fragment?

Fragments allow optional functionality/content to be added to existing plug-ins. For example, the base Eclipse contains only English messages. Fragments are used to add message catalogs containing other languages (e.g., French, Italian) without modifying the existing plug-ins. Note that fragments can only add function/content to plug-ins. They cannot override that which the plug-in already contains. Fragments are added to the base plug-in in no particular order and fragments for missing plug-ins are ignored.

It is not surprising to find that fragments are very similar to plug-ins; they are defined with a single manifest file, called fragment.xml, in a file system directory which contains everything the fragment needs. Each fragment must be associated with a particular plug-in. And any given plug-in can have any number of fragments associated with it.

Further, fragments can contribute libraries, prerequisites, extension points or extensions using standard syntax. These contributions are seamlessly merged into the fragment's base plug-in. That is, extensions and extension points from a fragment appear to come from/be part of (respectively) the base plug-in, libraries are put on the base plug-in's classpath and prerequisites contribute to the plug-in's prerequisite chain.

Below, is an example of a simple NL fragment for com.example.myplugin.

<?xml version="1.0" encoding="UTF-8"?>
<fragment
    id="com.example.myplugin.addon1"
    name="Example Add-on 1 Fragment"
    version="2.1.2"
    provider-name="Eclipse.org"
    plugin-id="com.example.myplugin"
    plugin-version="2.1.0"
    match="compatible">

  <runtime>
    <library name="nl1.jar"/>
  </runtime>
</fragment>

This fragment contributes additional jars which contain translations of the messages used by the hosting plug-in itself. In this case the jar contains files named according to the standard Java locale-based lookup strategy (e.g., message_en_US.properties, message_jp_JP.properties). Since the jars are added to the plug-in's classpath, the plug-in classloader will find these resources automatically.

The Plug-in Model at Runtime

All of the information we have discussed so far has dealt with physical plug-in information stored in the Eclipse environment. We will now talk about the runtime version of all this plug-in information.

The Plug-in Registry

When the Eclipse Platform starts, it first discovers all available plug-ins and fragments. The install/update component of Eclipse and a user-defineable plug-in path are used to determine directories where plug-ins and fragments can be found. Each plug-in/fragment directory may contain exactly one manifest file named plugin.xml or fragment.xml.

Once the discovery is completed, the platform parses the discovered manifest files and builds a plug-in registry. Manifests which cannot be loaded are skipped and the failure is noted in the platform's log (typically under in <workspace>/.metadata/.log). The registry is then resolved. That is, it is examined to ensure the structure is useful and sane, and its structures are cross linked. Resolution includes the following steps:

each element in the list (plug-in, fragment, extension point, etc.) must have all of the required fields. Required fields are those fields with the tag "#REQUIRED" in the appendix "DTD's for plugin.xml and fragment.xml".
each fragment must be associated with a plug-in
each plug-in must have access to any prerequisite plug-ins (after version compatibility matching) unless a prerequisite has been denoted as optional
each extension must be matched with an extension point

An error message is logged if any problems are encountered and the offending element is removed from the plug-in registry. This allows Eclipse to continue running even if there are minor problems. The resulting plug-in registry is available via the org.eclipse.core.runtime plug-in's API. The whole plug-in registry is available through IPluginRegistry and individual plug-ins can be examined with IPluginDescriptor.

Changes to the set of installed plug-ins are only detected when Eclise is restarted.

Plug-in Activation

When Eclipse starts up, only those plug-ins needed to build the plug-in registry and get things started are activated. All other plug-ins (the vast majority of plug-ins) remain dormant. When something happens causing the code within a plug-in to be loaded, that particular plug-in is activated. That is, classloading is the only trigger for plug-in activation. Plug-ins are only activated if the class loaded comes from the plug-in's local classpath (i.e., one of its libraries). Loading classes from a prerequisite does not count. This is the basis for Eclipse's lazy plug-in activation policy.

Many things can happen without activating a plug-in. In particular,

resources can be loaded (either from a resource or code library)
plug-in classloaders can ask other classloaders to load classes.
extensions and extension points can be examined without having to activate the plug-in that contains the extension.

Once a plug-in is activated it remains active until Eclipse shuts down. When Eclipse does shut down, all plug-ins are shut down in a dependents-first order. For example, if plug-in A requires plug-in B, then plug-in A will be shut down before plug-in B.

Plug-in Classloading

Libraries define the local classpath of a plug-in. Each library entry translates into an entry on the classpath of the plug-in's classloader. Earlier we discussed the concept of a code vs. a resource library. Resource libraries are loaded by a resource loader and do not figure into the strict classloading model.

Classloading in Eclipse follows the P-S-P model. That is, Parent-Self-Prerequisites.

Parent: Each plug-in classloader has the Eclipse boot plug-in's classloader as its parent. The boot plug-in loader's parent is the system classloader. Note that the standard Java AppClassloader (the one used to load the class containing main()) is not added to the classloading chain. As a result, the jars added to the JVM's classpath are ignored. Jars added to the JVM's bootclasspath are part of the system classloader and are considered during plug-in classloading.
Self: Self considers the libraries defined as part of this plug-in. All code libraries contributed by fragments to this plug-in are also considered. Libraries contributed by fragments appear after those contributed in the plug-in manifest (in indeterminant order). Libraries from the same manifest appear on the class path in the same order in which they were declared.
Prerequisites: Finally the exported libraries of the plug-in's prerequisites are considered. Prerequisites are queried in the order in which they were declared with the exception of the runtime plugin (org.eclipse.core.runtime). All plug-ins automatically have the Eclipse runtime plug-in (org.eclipse.core.runtime) added to their prerequisite list as the first prerequisite. All imports of the runtime plug-in are ignored.
Note that prerequisite consultation is transitive. When locating a class, a prerequisite plug-in will follow the same (though optimized) P-S-P model. Since all plug-in classloaders have the same parent, prerequisite loaders need not look there. Similarly, plug-ins which occur repeatedly in the transitive closure of the prerequisite graph are consulted at most once. Finally, prerequisite re-exporting rules are followed as described above.

Plug-in Data

The Eclipse Platform makes certain assumptions about the physical structure of a plug-in. Each plug-in or fragment is typically stored in a separate directory under a directory named plugins under your Eclipse install directory. The name of this directory is usually the same as the plug-in's id (though it may have the version number appended to it). In addition to the plugin.xml or fragment.xml file, there may be any number of folders under the plug-in's root folder.

Since Eclipse can be run on a wide range of machine configurations (i.e., operating system, window system) it needs a way of managing different forms of the same data (e.g., shared libraries). Eclipse provides four variables for use in library statements which resolve to parts of the current machine configuration.

os: The operating system on which Eclipse is currently running (e.g., win32, linux, solaris)
ws: The window system being used for the Eclipse UI (e.g., win32, motif, gtk)
arch: The type of processor in the machine (e.g., x86, ppc, sparc)
nl: The current locale (e.g., en_CA, jp_JP)

So, for example, if your plug-in uses windowing system-specific features, it may be necessary to provide a different library for each configuration. Using $ws$/<library name> in your plug-in manifest file directs Eclipse to look for the library in a window system directory with the same name as the current window system. The org.eclipse.swt plug-in uses this mechanism as follows:

  <runtime>
    <library name="$ws$/swt.jar">
      <export name="*"/>
    </library>
  </runtime>

The SWT plug-in has a series of directories of the form ws/<windowing system>/(e.g., ws/win32, ws/gtk, ws/motif). Each of these directories contains a different version of swt.jar. If you are working in an Eclipse environment in a win32 windowing system, the library name $ws$/swt.jar will match ws/win32/swt.jar. Note that in practice any given Eclipse install will have only one swt.jar (the one that matches the install). The jars are actually contributed by window system-specific fragments. Similar structures are seen in the Resources, and Update plug-ins. This mechanism allows the common elements to be put in the plug-in and have only the window system, operating system, ... specific parts in a fragment.

Summary

This article has set the stage for plug-ins: defining what they are, why they are important and concepts related to them. More detail on the exact form of plug-in/fragment markup can be found in the Eclipse help system. Eclipse plug-in developers are encouraged to look at existing plug-ins for further examples.