Article-Plug-in-architecture/plugin_architecture.html - www.eclipse.org/articles - Git at Google


 <html>

 <head>
 <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
 <title>Notes on the Eclipse Plug-in Architecture</title>
 <link rel="stylesheet" href="../default_style.css">
 <link rel="stylesheet" href="specific_style.css">
 </head>

 <body LINK="#0000ff" VLINK="#800080">
 <div align="right">&nbsp; <font face="Times New Roman, Times, serif" size="2">Copyright
   &copy; 2003 Bolour Computing</font>
   <table border=0 cellspacing=0 cellpadding=2 width="100%">
     <tr>
       <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">&nbsp;Eclipse
         Corner Article</font></font></b></td>
     </tr>
   </table>
 </div>
 <div align="left">
   <h1><img src="images/Idea.jpg" height=86 width=120 align=CENTER></h1>
 </div>
 <p>&nbsp;</p>

 <h1 ALIGN="CENTER">Notes on the Eclipse Plug-in Architecture</h1>

 <blockquote>
 <b>Summary</b>

 <br>
 Eclipse plug-ins embody an architectural pattern for building an
 application from constituent parts. This article presents an in-depth view
 of the participant roles and collaborations of this architectural pattern,
 as they exist in an instance of the Eclipse workbench.  The goal is to
 provide an understanding of plug-ins, and of how plug-in extensions are
 defined and processed, independently of the mechanics of using the Eclipse
 workbench to produce plug-ins.

   <p><b> Azad Bolour, Bolour Computing</b> <br>
     <font size="-1">July 3, 2003</font> </p>

 <p><b>Table of Contents</b> <br>

 <a href="#1.">1. Introduction</a>
 <br>
 <a href="#2.">2. The Eclipse Plug-in Model</a>
 <br>
 <a href="#3.">3. Extension Processing</a>
 <br>
 <a href="#4.">4. Example: An Extensible Arithmetic Function Service</a>
 <br>
 <a href="#5.">5. Listener Extensions and the Observer Pattern</a>
 <br>
 <a href="#6.">6. Summary and Conclusions</a>

 </blockquote>

 <hr width="100%">


 <a name="1."> </a>
 <h2>
 1. Introduction
 </h2>

 <p> <a href="http://www.eclipse.org">Eclipse</a> is an extensible platform
 for building IDEs. It provides a core of services for controlling a set of
 tools working together to support programming tasks.  Tool builders
 contribute to the Eclipse platform by wrapping their tools in pluggable
 components, called <i>Eclipse plug-ins</i>, which conform to Eclipse's
 plug-in contract.  The basic mechanism of extensibility in Eclipse is that
 new plug-ins can add new processing elements to existing plug-ins. And
 Eclipse provides a set of core plug-ins to bootstrap this process.
 For a general introduction to Eclipse as an extensible IDE platform,
 see the literature available at <a href="http://www.eclipse.org">
 this site</a>.

 <p> Even though the Eclipse platform is specialized for building IDEs, the
 core of its concepts and facilities supports a general model for composing
 an application from constituent parts developed by multiple vendors.  This
 general model of system composition in Eclipse will be described and placed
 in the context of other software patterns in this article.  The article is
 intended for new plug-in developers who need to understand the overall
 model of how plug-ins work, either before, or in conjunction with, working
 through the mechanics of building plug-ins.

 <p> The article is structured as follows. Section 2 outlines the Eclipse
 plug-in model and the declarative specification of plug-ins and their
 relationships within this model.  Section 3 explains what plug-in
 developers must do programmatically to allow their plug-ins to be extended.
 Section 4 provides a complete example of an extensible plug-in and its
 extensions by other plug-ins. Section 5 contrasts the Eclipse plug-in
 model with the much simpler <i>observer pattern</i> of [1].  Section 6
 concludes the article by summarizing the main architectural concepts used
 in Eclipse plug-ins.

 <p> This article specifically avoids the mechanics of the required user
 interactions with the Eclipse plug-in development environment (PDE) to
 build and test plug-ins. See Beck and Gamma [2], Shavor, et. al. [3], the
 online help documentation, and other articles at <a
 href="http://www.eclipse.org">this site</a> for the required procedures to
 build and test plug-ins in the PDE.

 <p>
 The <a href="samples.zip">companion plug-ins zip file</a> includes
 the plug-in samples appearing in this article.
 <a href="#instructions">Installation instructions </a>
 for the samples appear at the end of this article.
 Also accompanying this article is the
 <a href="doc/index.html">samples API reference</a>.

 <a name="2."> </a>
 <h2>
 2. The Eclipse Plug-in Model
 </h2>

 <p> A plug-in in Eclipse is a component that provides a certain type of
 service within the context of the Eclipse workbench. By a component here I
 mean an object that may be configured into a system at system deployment
 time. The Eclipse runtime provides an infrastructure to support the
 activation and operation of a set of plug-ins working together to provide a
 seamless environment for development activities.  Within a running Eclipse
 instance, a plug-in is embodied in an instance of some <var>plug-in
 runtime class</var>, or <var>plug-in class</var>, for short.  The plug-in
 class provides configuration and management support for the plug-in
 instance. A plug-in class in Eclipse must extend
 <var>org.eclipse.core.runtime.Plugin</var>, which is an abstract class that
 provides generic facilities for managing plug-ins.

 <p> An Eclipse installation includes a <code>plugins</code> folder where
 individual plug-ins are deployed. Each plug-in is installed in its own
 folder under the <code>plugins</code> folder. A plug-in is described in an
 XML manifest file, called <code>plugin.xml</code>, residing in the
 plug-in's folder. The manifest file tells the Eclipse runtime what it needs
 to know to activate the plug-in.

 <p> The parsed contents of plug-in manifest files are made available
 programmatically through a <i>plug-in registry API</i>.  And parsed plug-in
 specifications are cached in an in-memory repository called the <i>plug-in
 registry</i>.  The Eclipse runtime instantiates an instance of each plug-in
 by using the plug-in registry API.  The plug-in registry API is also used
 by provider-supplied plug-in code to obtain information about
 plug-ins.

 <p>
 Here is what a minimal plug-in manifest file looks like:

 <p>
 <table width=350 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;plugin
   name="JUnit Testing Framework"
   id="org.junit"
   version="3.7"
   provider-name="Eclipse.org"&gt;
   &lt;runtime&gt;
     &lt;library name="junit.jar"&gt;
       &lt;export name="*"/&gt;
     &lt;/library&gt;
   &lt;/runtime&gt;
 &lt;/plugin&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 2.1. A Minimal Plug-in Manifest File.
 </td></tr> </table>

 <p> This manifest file describes a plug-in that provides the services of
 the <i>JUnit</i> testing infrastructure to the Eclipse workbench. (Note.
 To improve readability, the contents of Eclipse manifest files, such as
 this one, are reproduced in this article in their English localization.)

 <p>
 <a href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/misc/rplugman.html">
 The Eclipse Platform Plug-in Manifest Specification</a> documents
 the XML elements and attributes used in defining plug-ins.
 (This specification is also available in the Eclipse platform
 help documentation under <i>Platform Plug-In Developer Guide/Other
 reference information/Plug-in manifest</i>).

 <p> I am not going to focus on the contents of the plug-in manifest file
 at this time, except to note that each plug-in has a unique identifier (XML
 attribute <code>id</code>). The unique identifier is used to refer to a plug-in
 within the manifest files of other, related, plug-ins. The unique
 identifier may also be used within provider-supplied plug-in code to access
 the plug-in's running instance, as follows:

 <code>
 <pre>
     Plugin p = Platform.getPlugin(pluginID);
 </pre>
 </code>

 <p>
 Plug-in instances are managed by the Eclipse runtime, and
 are accessed by using the Eclipse platform as shown above. Plug-in
 instances are not constructed by application programs.

 <h3>
 2.1. Plug-in Deployment and Activation
 </h3>

 <p>
 Deploying a plug-in in an Eclipse installation involves
 copying the resources that constitute the plug-in (the manifest file,
 jar files, and other resources) into an individual folder
 for the plug-in, under the installation's <code>plugins</code> directory.
 Such a plug-in can then be <i>activated</i> by the Eclipse runtime
 when it is required to perform some function. Activating a plug-in means
 loading its runtime class and instantiating and initializing its
 instance.

 <p>
 The main function of a plug-in class is to do special processing during
 plug-in activation and deactivation, e.g., to allocate and release
 resources.  For simple plug-ins, like the <code>JUnit</code> plug-in above, no
 specific activation or deactivation processing is required, and therefore
 no specific plug-in class need be provided by the plug-in designer. In that
 case, the Eclipse runtime automatically provides a default plug-in class
 for the plug-in instance.

 <p> When the plug-in needs to do something specific to activate or
 deactivate itself, the plug-in designer subclasses
 <code>org.eclipse.core.runtime.Plugin</code>, provides overrides for the
 activation and deactivation methods of the class, respectively called
 <var>startup</var> and <var>shutdown</var>, and includes the
 fully-qualified name of this specific plug-in subclass as the value of the
 attribute <code>class</code> in the corresponding plug-in manifest file.

 <p> Eclipse includes a plug-in management kernel, known as the Eclipse
 <i>platform</i>, or the Eclipse <i>runtime</i>, and certain core plug-ins
 that are present in every Eclipse deployment. The identities of these core
 plug-ins are hard-coded into the Eclipse platform, and the platform knows to
 activate these plug-ins in each running instance of Eclipse. Non-core
 plug-ins, on the other hand, are activated when required by other plug-ins,
 as described below.

 <p> In the Eclipse model, a plug-in may be related to another plug-in by one
 of two relationships:

 <p>
 <ul>
 <li>
 <i>Dependency</i>. The roles in this relationship are <i>dependent
 plug-in</i> and <i>prerequisite plug-in</i>. A prerequisite plug-in supports the
 functions of a dependent plug-in.

 <li>
 <i>Extension</i>. The roles in this relationship are <i>host plug-in</i> and
 <i>extender plug-in</i>. An extender plug-in extends the functions of a
 host plug-in.

 </ul>

 <p> These relationships are specified declaratively in plug-in manifest
 files through the XML elements <code>requires</code> and
 <code>extension</code> (the details of which appear in later subsections).

 <p> A non-core plug-in that has been deployed in an Eclipse installation
 may be activated in a running instance of Eclipse if it is transitively
 related to a core Eclipse plug-in by the union of the dependency and the
 extension relations. Such a plug-in will be activated when its functions
 are required to support or to extend the functions of another plug-in.  A
 plug-in that is deployed but unreachable from any core plug-in via the
 dependency and extension relations might as well not be deployed from the
 point of view of plug-in activation.  Of course, even a reachable plug-in
 may remain unactivated in a running instance for some time (or for the
 lifetime of the instance), if no user action or other triggering event
 elicits its use.

 <h3>
 2.2. Dependency
 </h3>

 <p> When a plug-in is dependent on other plug-ins for its functions, the
 dependency is specified via a <code>requires</code> element in the plug-in manifest
 file.  Here is an example:

 <p>
 <table width=350 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;plugin
    id="com.bolour.sample.eclipse.demo"
    name="Extension Processing Demo"
    version="1.0.0"&gt;
    &lt;runtime&gt;
       &lt;library name="demo.jar"/&gt;
    &lt;/runtime&gt;
    &lt;requires&gt;
       &lt;import plugin="org.eclipse.ui"/&gt;
    &lt;/requires&gt;
 &lt;/plugin&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 2.2. Specifying Plug-in Dependencies.
 </td></tr> </table>


 <p>
 In this example, the sample plug-in <code>com.bolour.sample.eclipse.demo</code>
 is declared to be dependent on (i.e., to make use of) the base Eclipse
 UI plug-in <code>org.eclipse.ui</code>.

 <p> Dependency as defined in the plug-in manifest file is both a runtime
 and a compile-time directive. At runtime, Eclipse has to make sure that a
 prerequisite plug-in can be made available to a dependent plug-in when the
 dependent plug-in is activated. At compile time, Eclipse can be directed to
 augment the classpath for compiling a dependent plug-in by the jar files of
 all of its prerequisite plug-ins.

 <h3>
 2.3. Extension
 </h3>

 <p> When the facilities of a plug-in are to be made directly available to
 the user, one or more user interface elements have to be added to the base
 Eclipse workbench. For example, to make the workbench's <i>help</i> plug-in
 available to the user, <i>help</i> menu items must be added to the
 workbench user interface.

 <p> The process of adding some processing element or elements to a plug-in
 is known as an <i>extension</i>. This process is not restricted to UI
 elements, however. Any plug-in may allow other plug-ins to extend it by
 adding processing elements.  An extension is defined by an <i>extender
 plug-in</i> and causes a <i>host plug-in</i> to modify its behavior.
 Typically, this modification of behavior includes the addition of
 processing elements to the host plug-in (e.g., the addition of new menu
 items to the Eclipse workbench), and the customization of the behavior of
 these additional elements by services provided by the extender plug-in
 (e.g., the customization of new menu items by specific menu event
 handlers).

 <p> In simple cases, a single act of extension adds a single <i>callback
 object</i> to the environment, through which the host and extender plug-ins
 communicate. The callback object is different from the host and extender
 plug-in objects. And unlike these objects, which are components that are
 automatically instantiated and managed by the Eclipse platform, a callback
 object is a <i>plain old Java objects</i> that is instantiated and managed
 specifically by provider-supplied code.  A single act of extension can also
 add more than one callback object to the environment.  For example, Eclipse
 allows a set of menus to be added to its user interface via a single
 extension.

 <p> Note, however, that the extension model, per se, is quite general, and
 does not necessarily require that an extender plug-in provide custom
 callback objects. It is possible, for example, that the kind of behavior
 modification required of a host plug-in can be provided entirely by objects
 whose classes are known to the host plug-in at compile-time, so that an
 extension declaration serves merely to parameterize instances of such
 built-in classes.

 <p> Similarly, the extension model, per se, does not require that
 the host plug-in directly expose aspects of each of its extensions
 in its interface. For example, an extension may merely ask that
 an extender plug-in be notified of certain events known to occur
 in the host plug-in independently of the extender plug-in, without
 any changes visible in the host plug-in's interface.

 <p> A plug-in may allow itself to be augmented by different kinds of
 extensions. For example, the workbench UI allows both its menus and its
 editors to be extended. In each case, the extension must conform to a
 unique set of configuration and behavioral requirements. Therefore, an
 extensible plug-in provides different types of slots that extensions can
 plug into.  These slot types are called <i>extension points</i>.  In the
 remainder of this article I will use the compound form
 <i>extension-point</i> to refer to these slots.  An extension-point allows
 any number of extensions to be plugged into it.

 <p> <i>Extension</i> and <i>extension-point</i> are standard Eclipse
 plug-in terminology. <i>Host plug-in</i>, <i>extender plug-in</i>, and
 <i>callback object</i> are terms used in this article to describe
 the different roles of objects in an extension.

 <p> Figure 1 illustrates the relationships between the participants of an
 extension, in this case, the extension of the Eclipse workbench by the menu
 items of the Eclipse help system.  In this extension, the host plug-in is
 the Eclipse workbench user interface, <code>org.eclipse.ui</code>, whose
 menus can be extended via an extension-point known as
 <code>actionSets</code>. The extender plug-in is the Eclipse help system's
 user interface, <code>org.eclipse.help.ui</code>.  In order to make help
 functions available to the user, the help UI plug-in uses the
 <code>actionSets</code> extension-point to extend the workbench UI plug-in
 by specific help-related menu items, among them, <i>Help-&gt;Help
 Contents</i> and <i>Search-&gt;Help</i>. The extension is defined by the
 extender plug-in. And in this case, the single extension augments the
 workbench UI by multiple menu items.


 <P>
 <spacer type=vertical size=10>

 <CENTER>
 <IMG SRC="images/eclipse_extensions.jpg" ALT="Figure-1" BORDER="0">
 </CENTER>

 <BR>
 <table align=center width=600>
 <tr><td>
 Figure 1. Participants of a plug-in extension. The workbench UI plug-in
 is extended by the workbench help plug-in via an
 <i>actionSets</i> extension that defines specific help-related menu items.
 </td></tr>
 </table>

 <P>
 <spacer type=vertical size=10>

 <p>
 (The extension-point <i>power-strip</i> notation used in this article
 was devised by Don Estberg [5].)

 <p> Also shown in the figure are the classes of the extension's callback
 objects: that is, the classes of the help system's menu handlers.  As we
 will see shortly, callback classes are typically identified by name in the
 declarative specification of each extension.  Thus, this extension's
 <i>Help-&gt;Help Contents</i> menu specification declares its custom
 callback class (menu handler) to be <code>HelpContentsAction</code>.  And
 the extension's <i>Search-&gt;Help</i> menu specification declares its
 custom callback class (menu handler) to be
 <code>OpenHelpSearchPageAction</code> (see blow for details).

 <p> Note that to reduce clutter, package prefixes are not shown in this and
 later figures. Here the workbench plug-in class belongs to the
 <code>org.eclipse.ui.internal</code> package; and the help plug-in and
 related classes belong to the <code>org.eclipse.help.ui.internal</code>
 package.

 <p>
 The remainder of this section provides a detailed account of how
 extension-points and extensions are defined.

 <h4>
 2.3.1 Participants of an Extension
 </h4>

 <p>
 Let us now look more closely at the various roles played by the objects
 participating in an extension. There are two plug-in roles, <i>host</i>
 and <i>extender</i>, a generic role of a <i>callback</i> object,
 and <i>specific callback</i> roles defined by each extension-point.

 <h5>
 2.3.1.1. The Host Plug-in Role
 </h5>

 <p> In the context of a particular extension, a plug-in that stands in the
 <i>host</i> role provides the extension-point and is extended.  In addition
 to providing services in its own right, such a plug-in also acts as the
 coordinator and controller of a number of extensions.

 <p> Within the host plug-in's manifest file, an extension-point is declared
 in an <i>extension-point XML element</i>. Here is an example of
 such an element, culled from the base Eclipse workbench UI plug-in,
 <code>org.eclipse.ui</code>:

 <p>
 <table bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 &lt;plugin
 <img src="images/tag_1.gif" height=13 width=24 align=CENTER> id="org.eclipse.ui"
     name="Eclipse UI"
     version="2.1.0"
     provider-name="Eclipse.org"
     class="org.eclipse.ui.internal.UIPlugin"&gt;

 <img src="images/tag_2.gif" height=13 width=24 align=CENTER> &lt;extension-point id="actionSets" name="Action Sets"
       schema="schema/actionSets.exsd"/&gt;
     &lt;!-- Other specifications omitted. --&gt;
 &lt;/plugin&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 2.3. Declaring an Extension-Point.
 </td></tr> </table>

 <p>
 The documentation for this extension-point is provided in a
 <a
 href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/extension-points/org_eclipse_ui_actionSets.html">
 reference page</a>
 (and is also available in the Eclipse platform on-line help at
 <i>Platform Plugin Developer Guide/Reference/Extension Points
 Reference/Workbench/org.eclipse.ui.actionSets</i>). The documentation
 indicates, among other things, that this extension-point provides a plug-in
 slot for sets of menus, menu items, and buttons to be added to the
 base Eclipse workbench.

 <p>
 The extension-point specification

 <img src="images/tag_2.gif" height=13 width=24 align=CENTER>

 defines a unique identifier for the extension-point within this host
 plug-in. To identify an extension-point uniquely in global context, the
 extension-point identifier is prepended with the unique identifier of the
 host plug-in

 (as in <img src="images/tag_1.gif" height=13 width=24 align=CENTER>)

 to form a <i>fully-qualified</i> identifier for the extension-point.
 Thus, the fully-qualified identifier of the <code>actionSets</code>
 extension-point of the Eclipse UI plug-in is
 <code>org.eclipse.ui.actionSets</code>. Plug-ins that extend an extension-point
 refer to it by its fully-qualified identifier.

 <p>
 The extension-point specification

 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>)

 also declares an XML schema for the extensions of this extension-point,
 which provides the syntax for declaring menus, menu items, and buttons to
 be added to the workbench UI.  We'll have more to say about the structure
 and contents of such a schema in section 2.3.3.

 <h5>
 2.3.1.2. The Extender Plug-in Role
 </h5>

 <p> In the context of a particular extension, a plug-in that stands in the
 <i>extender</i> role defines the extension, typically making certain
 aspects of itself available to a host plug-in through the extension, and,
 in addition, causing the host plug-in to add certain processing elements to
 its environment. An extension is declared by using an
 <code>extension</code> XML element in the extender plug-in's manifest file.
 Here is an example of an extender plug-in, culled from the
 <code>org.eclipse.help.ui</code> plug-in manifest file, that extends the
 <code>actionSets</code> extension-point of Listing 2.3, by adding two menu
 items:

 <a name="listing2.5"> </a>
 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;plugin
         id="org.eclipse.help.ui"
         name="Help System UI"
         version="2.1.0"
         provider-name="Eclipse.org"
         class="org.eclipse.help.ui.internal.WorkbenchHelpPlugin"&gt;
     &lt;!-- ... --&gt;
     &lt;!-- Action Sets --&gt;
     &lt;extension
         <img src="images/tag_1.gif" height=13 width=24 align=CENTER> point="org.eclipse.ui.actionSets"&gt;
         &lt;actionSet
                 label="Help"
                 visible="true"
                 id="org.eclipse.help.internal.ui.HelpActionSet"&gt;
         <img src="images/tag_2.gif" height=13 width=24 align=CENTER> &lt;action
                 label="&amp;Help Contents"
                 icon="icons/view.gif"
                 helpContextId="org.eclipse.help.ui.helpContentsMenu"
                 tooltip="Open Help Contents"
                 class="org.eclipse.help.ui.internal.HelpContentsAction"
                 menubarPath="help/helpEnd"
                 id="org.eclipse.help.internal.ui.HelpAction"&gt;
             &lt;/action&gt;
             &lt;!-- ... other actionSet elements --&gt;
         <img src="images/tag_3.gif" height=13 width=24 align=CENTER> &lt;action
                 label="&amp;Help..."
                 icon="icons/search_menu.gif"
                 helpContextId="org.eclipse.help.ui.helpSearchMenu"
             <img src="images/tag_4.gif" height=13 width=24 align=CENTER> class="org.eclipse.help.ui.internal.OpenHelpSearchPageAction"
                 menubarPath="org.eclipse.search.menu/dialogGroup"
                 id="org.eclipse.help.ui.OpenHelpSearchPage"&gt;
             &lt;/action&gt;
         &lt;/actionSet&gt;
     &lt;/extension&gt;
 &lt;!-- ... --&gt;
 &lt;/plugin&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 2.4. Declaring an Extension.
 </td></tr> </table>

 <p>
 Note that in this extender plug-in, the <code>actionSets</code> extension-point
 is referred to by its fully-qualified identifier

 (<img src="images/tag_1.gif" height=13 width=24 align=CENTER>).

 <p> The portion of the <code>actionSets</code> extension shown in Listing 2.4
 defines two actions

 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>,
 <img src="images/tag_3.gif" height=13 width=24 align=CENTER>).

 The actions shown are made available through the workbench menu items
 <i>Help-&gt;Help Contents</i> and <i>Search-&gt;Help</i>, respectively.

 <h5>
 2.3.1.3. The Extension Callback Role
 </h5>

 <p> In the context of a particular extension, an object that stands in a
 <i>callback</i> role is a plain old Java object (not a plug-in) that is
 called by the host plug-in when certain events specified in the
 corresponding extension-point contract are recognized by the host plug-in.
 The interface for callback objects is provided by the host plug-in, and is
 documented in the documentation of the extension-point being extended. The
 implementation of callback objects is typically a custom class specific to
 the particular extension, and is furnished by the provider of the extender
 plug-in. Because the implementation of the callback object in the extender
 references the callback interface, which is typically packaged with the
 host, an extender plug-in typically also <i>depends on</i> the host
 plug-in.

 <a name="2.3.1.3.1."> </a>
 <h6>
 2.3.1.3.1. Specific Callback Roles
 </h6>

 <p> Each callback object fills a certain specific role within an extension.
 I will refer to these specific roles simply as <i>callback roles</i>. In
 the XML definition of an extension, callback roles are defined by child or
 descendent XML elements. The <code>actionSets</code> extension-point, for
 example, defines a descendent callback role known as <code>action</code>.
 Multiple callback objects may stand in this role within an
 <code>actionSets</code> extension, each servicing a particular workbench
 menu item or button.

 <p> When a custom implementation of a callback object is required, the XML
 schema of the corresponding extension-point typically includes an attribute
 for specifying the fully-qualified name of the custom callback implementation
 class. For the <code>help</code> UI plug-in, the name of the XML attribute
 designating an <code>action</code> class is "<code>class</code>",
 as exemplified in Listing 2.4

 (<img src="images/tag_4.gif" height=13 width=24 align=CENTER>).

 <p> But while the extender plug-in defines the required specific callback
 objects, and declares their custom implementation classes, the callback
 objects only come into existence as a result of specific action by the host
 plug-in (and usually only when they are required for the first time to
 perform some action on behalf of the extension).

 For example, in Listing 2.4

 <img src="images/tag_4.gif" height=13 width=24 align=CENTER>,

 the <code>action</code> callback
 class for the workbench <i>Search-&gt;Help</i> menu is specified
 by the extender plug-in <code>org.eclipse.help.ui</code> to be <code>OpenHelpSearchPageAction</code>
 (package <code>org.eclipse.help.ui.internal</code>).
 But the associated callback instance is created by the host plug-in
 <code>org.eclipse.ui</code>. In this case, the callback instance is created the
 first time the <i>Search-&gt;Help</i> menu item is invoked.

 <p> As extension designers for an extender plug-in, we need to know about
 the callback roles of an extension, and supply concrete callback objects
 for these roles. The roles are defined as particular elements in the XML
 schema associated with the extension-point (see section 2.3.3), and are
 described in the documentation of the XML schema, which, among other
 things, must include the interfaces expected of callback objects filling
 each role.

 <p> For example, the <code>actionSets</code>
 <a href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/extension-points/org_eclipse_ui_actionSets.html">
 reference page</a> introduced earlier
 specifies the callback interface for menu item actions to be <a
 href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/api/org/eclipse/ui/IWorkbenchWindowActionDelegate.html">
 org.eclipse.ui.IWorkbenchWindowActionDelegate</a>.  So the menu action handlers
 of the help system implement this interface. In this interface,
 the method whose implementation actually performs the menu action
 is declared as:

 <code>
 <pre>
     public void run(org.eclipse.jface.action.IAction action);
 </pre>
 </code>

 <p> Therefore, when a new service is to be made accessible through the main
 workbench menu, the service's plug-in provides an implementation of
 <code>IWorkbenchWindowActionDelegate</code> in which the <code>run</code>
 method invokes the service. And the fully-qualified name of the
 implementation class is added to the service's plug-in manifest file as the
 callback class of the service's menu.

 <h5>
 2.3.1.4. Non-Specific Service Objects
 </h5>

 <p> Note that not all XML elements used in defining an extension correspond
 to custom callback roles. Some elements may be purely descriptive,
 supplying, for example, certain parameters to the host plug-in to shape
 corresponding UI elements, or to use in creating non-custom internal host
 objects representing parts of the extension.  In our example, an
 <code>actionSet</code> element in and of itself (i.e., independently of its
 child elements) does not define a custom callback object. But such an
 element does cause an internal object to come into existence within the
 <code>org.eclipse.ui</code> plug-in to represent the action set.

 <p> Similarly, the <code>actionSets</code> extension-point allows the
 declaration of new top-level workbench menus through an
 <code>actionSet</code> <code>menu</code> element. But the action associated
 with a top-level menu is generic: "expose the list of lower-level menu
 items". Therefore, there is no need for an extender-specific callback
 object to be associated with a top-level workbench menu. And the workbench
 top-level menus are represented by internal workbench UI objects.

 <p> As users of extension-points, we need not be concerned with these
 non-specific internal objects supplied by the host plug-in.  But as designers
 of host plug-ins, we see that we have the flexibility to design complex
 extension structures, parts of which may be exposed as callbacks to be provided
 by extensions, and other parts of which would be generic, built-in to
 the host plug-in code, and possibly parameterizable through corresponding XML
 attributes of extensions.

 <h4>
 2.3.2. Relationships between Plug-ins and Extension Objects
 </h4>

 <p> The act of extension is quite a general concept in Eclipse, and to
 understand its full generality, it is useful to summarize the types of
 relationships that may exist between plug-in objects, extension-points, and
 callback objects.

 <ol>

 <p>
 <li>
 Multiple extension-points may exist in a host plug-in.

 <p>
 <li>
 A plug-in may act both as a host plug-in, exposing
 some extension-points, and as an extender plug-in, extending some
 plug-ins.

 <p>
 <li>
 Multiple plug-ins may extend a given extension-point.

 <p>
 <li>
 A given plug-in may extend a given extension-point multiple
 times.

 <p>
 <li>
 An extender plug-in may include different extensions
 of different host plug-ins.

 <p>
 <li>
 A single act of extension of an extension-point by a
 particular extension of a particular plug-in may create
 multiple callback objects.

 <p>
 <li>
 A plug-in can define extensions of its own extension-points.

 </ol>

 <p> Note. The idea of a plug-in extending itself may seem odd at first.
 A prominent example of a self-extending plug-in is the workbench UI
 itself. This plug-in adds various facilities, e.g., editors,
 to its own UI by extending its own extension-points.

 <h4>
 2.3.3. Extension-Point Schemas
 </h4>

 <p> A particular extension is defined by an XML configuration element in an
 extender plug-in.  The element provides the information required to
 instantiate and initialize the required callback objects for that
 extension, as well as the information required to customize the interface
 and behavior of the host plug-in.  When a host plug-in designer creates an
 extension-point, in addition to declaring the extension-point in its
 manifest file, the designer is also responsible for defining the
 configuration syntax for extensions to that extension-point.  This syntax
 is defined as an XML schema and stored in a file with a <code>.exsd</code>
 extension, e.g., <code>actionSets.exsd</code>.  The schema definition then
 becomes part of the documentation of the host plug-in.  (Eclipse includes
 an XML schema editor and a corresponding formatter for this purpose.)

 <p> The extension-point schema lets extender plug-in designers know how to
 parameterize their extensions.  (Eclipse also provides an extension
 configuration editor that is driven by the XML schema of an
 extension-point being extended.)

 <p> To get an idea of the structure and contents of extension-point
 schemas, you can browse the extension-point schemas for the Eclipse
 platform plug-ins. These schemas are available in each Eclipse installation
 below the folder <code>plugins/org.eclipse.platform.source_&lt;ver&gt;/src</code>
 (where <code>&lt;ver&gt;</code> is the version of Eclipse). Under this folder,
 the extension-point schemas for a given platform plug-in may be found in the
 folder <code>&lt;plugin&gt;_&lt;plugin_ver&gt;/schema</code>, where
 <code>&lt;plugin&gt;</code> is the id of the plug-in, and
 <code>&lt;plugin_ver&gt;</code> is the version of the plug-in. For example,
 for Eclipse 2.1, the <code>actionSets</code> extension-point schema,
 <code>actionSets.exsd</code>, may be found in the folder
 <code>org.eclipse.ui_2.1.0/schema</code> below the
 <code>platform.source</code> folder.

 <p>
 Here is a considerably abbreviated version of <code>actionSets.exsd</code>:

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;schema targetNamespace="org.eclipse.ui"&gt;
    &lt;element name="extension"&gt;
       &lt;complexType&gt;
          &lt;sequence&gt;
         <img src="images/tag_1.gif" height=13 width=24 align=CENTER> &lt;element ref="actionSet" minOccurs="1" maxOccurs="unbounded"/&gt;
          &lt;/sequence&gt;
          &lt;attribute name="point" type="string" use="required"&gt; &lt;/attribute&gt;
          &lt;attribute name="id" type="string"&gt; &lt;/attribute&gt;
          &lt;attribute name="name" type="string"&gt; &lt;/attribute&gt;
       &lt;/complexType&gt;
    &lt;/element&gt;
    &lt;element name="actionSet"&gt;
       &lt;complexType&gt;
          &lt;sequence&gt;
             &lt;element ref="menu" minOccurs="0" maxOccurs="unbounded"/&gt;
             &lt;element ref="action" minOccurs="0" maxOccurs="unbounded"/&gt;
          &lt;/sequence&gt;
          &lt;attribute name="id" type="string" use="required"&gt; &lt;/attribute&gt;
          &lt;attribute name="label" type="string" use="required"&gt; &lt;/attribute&gt;
          &lt;attribute name="visible" type="boolean"&gt; &lt;/attribute&gt;
          &lt;attribute name="description" type="string"&gt; &lt;/attribute&gt;
       &lt;/complexType&gt;
    &lt;/element&gt;
    &lt;element name="action"&gt;
       &lt;complexType&gt;
          &lt;choice&gt;
             &lt;element ref="selection" minOccurs="0" maxOccurs="unbounded"/&gt;
             &lt;element ref="enablement" minOccurs="0" maxOccurs="1"/&gt;
          &lt;/choice&gt;
          &lt;attribute name="id" type="string" use="required"&gt; &lt;/attribute&gt;
          &lt;attribute name="label" type="string" use="required"&gt; &lt;/attribute&gt;
          &lt;attribute name="toolbarPath" type="string"&gt;
          &lt;attribute name="icon" type="string"&gt; &lt;/attribute&gt;
          &lt;attribute name="tooltip" type="string"&gt; &lt;/attribute&gt;
          &lt;attribute name="class" type="string"&gt; &lt;/attribute&gt;
       &lt;/complexType&gt;
    &lt;/element&gt;
 &lt;/schema&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 2.5. Extension-Point Schema Definition (<code>.exsd</code> File).
 </td></tr> </table>

 <p>
 The schema defines an <code>actionSets</code> extension as an element that
 includes some attributes and a sequence of <code>actionSet</code>'s,
 and an <code>actionSet</code> as an element that includes some
 attributes and a sequence of <code>menu</code>s and <code>action</code>s.

 <p> In the full version of this file, each attribute is annotated with a
 human-readable <i>documentation element</i>. The documentation elements of
 extension-point schemas are used to generate HTML reference pages for
 extension-points (e.g., <a
 href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/extension-points/org_eclipse_ui_actionSets.html">
 the <code>actionSets</code> reference page</a> mentioned earlier in this
 article), similarly to the way in which Java API reference pages
 are generated via <code>javadoc</code>. Such a reference page is made
 available as part of the documentation of the host plug-in, and is
 integrated with the workbench's help system.

 <p>
 The reference page supports the two tasks that must be performed
 to plug new functionality into an extension-point, namely:

 <ul>

 <p>
 <li>
 Configuration of an extension in the extender plug-in's manifest file.

 <p>
 The reference page specifies the XML configuration syntax
 required for the extension.

 <p>
 <li>
 Provision of custom implementations for the extension-point's callback objects.

 <p> The reference page includes an API section for documenting the callback
 interfaces expected by the host plug-in for each callback role.

 </ul>

 <h5>
 2.3.3.1. Extension Members
 </h5>

 <p> What goes into an extension-point schema definition is up to the
 designer of the host plug-in. And the extension XML in the
 <a href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/reference/misc/rplugman.html">
 Eclipse Platform Plug-in Manifest Specification</a> is defined as an XML
 <code>ANY</code>, meaning that it is arbitrary. That designation is too general,
 however. In fact, an XML extension specification is always a (possibly
 degenerate) sequence of elements. I will refer to an item within this
 sequence of elements as an <i>extension member</i>.  An
 <code>actionSets</code>
 extension, for example, is a sequence of <code>actionSet</code> members.
 Often the members of an extension have the same element type: that is,
 the sequence represents a homogeneous list of members.

 <p> In XML, the number of elements of each type within a sequence may be
 bounded by using the <code>minOccurs</code> and the <code>maxOccurs</code>
 element definition attributes. This usage is illustrated in the
 <code>actionSets</code> schema (Listing 2.5, <img src="images/tag_1.gif"
 height=13 width=24 align=CENTER>), where an <code>actionSets</code>
 extension is specified to contain at least one, but an otherwise
 unrestricted number of <code>actionSet</code> elements.

 <p> When an extension-point defines a homogeneous sequence of members and
 allows its extensions to have more than one member, the extension-point is
 assigned a plural name. Such extension-points and their extensions
 may be referred to as <i>plural-form</i>. The plural form is typically
 provided as a shorthand for representing multiple single-member extensions.

 <p> The notion of an extension <i>member</i>, that is, a top-level XML
 element of an extension's (top-level) sequence, may be contrasted with the
 Eclipse notion of a <i>configuration element</i>, an arbitrary element
 (either a top-level element or a lower-level descendent element) in the XML
 specification of an extension. Both terms will be used here for the XML element
 itself and for its parsed programmatic representation.

 <a name="3."> </a>
 <h2>
 3. Extension Processing
 </h2>

 <p> In section 2, the extension model of Eclipse was presented at a high
 level, and the declarative specifications of extensions and their callback
 objects was introduced. In this section, we will see how such declarations are
 processed programmatically to support the obligations of a host plug-in
 under an extension-point contract. In other words, we will see the kind of
 code host plug-in designers must write for each extension-point they
 define.

 <p> Consider again the plug-in <code>org.eclipse.ui</code> and its
 <code>actionsSets</code> extension-point. When this plug-in is activated,
 the extension declarations in all plug-ins that extend it must be
 processed, so that the UI knows how to configure its menus and buttons, and
 what callback objects to call when corresponding menu and button events
 occur. This section presents the API calls provided by the Eclipse platform
 to aid in this type of extension processing, and exemplifies the idioms
 used by plug-in developers to process extensions by using these API calls.

 <h3>
 3.1. Obtaining References to the Extensions of an Extension-Point
 </h3>

 <p>
 How are the extension declarations processed for a given extension-point?
 Well, in general, the configuration of an extension is
 quite arbitrary. And the part of the system that has the knowledge
 of this configuration is the host plug-in, whose design produced
 the extension-point schema definition.
 For example, the knowledge of how to process the <code>actionsSets</code>
 extension of the UI help plug-in, <code>org.eclipse.help.ui</code>,
 resides within the plug-in that defines the <code>actionsSets</code>
 extension-point, namely, the plug-in <code>org.eclipse.ui</code>.

 <p> In order for a host plug-in to process the extensions of one of its
 extension-points, it needs to be able to obtain a list of those extensions
 from the Eclipse runtime, and, for each extension, to get a parsed version
 of that extension's members.

 <p> Recall that the plug-in registry API provides programmatic access to
 the parsed representation of all available plug-in specifications.
 This API provides methods for
 traversing the information about plug-ins, their components, and their
 relationships. A configuration element in the registry API (interface
 <var>IConfigurationElement</var>) represents the parsed version of an
 extension element in an extender plug-in's manifest file.
 The following sample code shows how to use the plug-in registry
 API to iterate over all members of all extensions of an extension-point.

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.demo;

 import org.eclipse.core.runtime.IConfigurationElement;
 import org.eclipse.core.runtime.IExtension;

 public interface IProcessMember {
     public Object process(IExtension extension,
       IConfigurationElement member);
 }

 package com.bolour.sample.eclipse.demo;

 import org.eclipse.core.runtime.IConfigurationElement;
 import org.eclipse.core.runtime.IExtension;
 import org.eclipse.core.runtime.IExtensionPoint;
 import org.eclipse.core.runtime.IPluginRegistry;
 import org.eclipse.core.runtime.Platform;

 public class ProcessExtensions {
 <img src="images/tag_1.gif" height=13 width=24 align=CENTER> public static void process(String xpid, IProcessMember processor) {
         IPluginRegistry registry = Platform.getPluginRegistry();
         IExtensionPoint extensionPoint =
             registry.getExtensionPoint(xpid);
         IExtension[] extensions = extensionPoint.getExtensions();
         // For each extension ...
     <img src="images/tag_2.gif" height=13 width=24 align=CENTER> for (int i = 0; i &lt; extensions.length; i++) {
             IExtension extension = extensions[i];
         <img src="images/tag_3.gif" height=13 width=24 align=CENTER> IConfigurationElement[] elements =
               extension.getConfigurationElements();
             // For each member of the extension ...
         <img src="images/tag_4.gif" height=13 width=24 align=CENTER> for (int j = 0; j &lt; elements.length; j++) {
                 IConfigurationElement element = elements[j];
             <img src="images/tag_5.gif" height=13 width=24 align=CENTER> processor.process(extension, element);
             }
         }
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 3.1. Iterating over the Extensions and the Members of an Extension-Point.
 </td></tr> </table>

 <p> The class <code>ProcessExtensions</code> provides an extension processing
 method <code>process</code> (<img src="images/tag_1.gif" height=13 width=24
 align=CENTER>), which uses the nested loop idiom for extension processing:
 loop over all extensions of the given extension-point

 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>),

 and for each extension, loop over all members of that extension

 (<img src="images/tag_4.gif" height=13 width=24 align=CENTER>).

 The <code>process</code> method is made generic by providing it with a
 member processing visitor: an instance of interface
 <code>IProcessMember</code> that is called back on for each member being
 processed

 (<img src="images/tag_5.gif" height=13 width=24 align=CENTER>).

 <p> Suppose this extension processing method is called with the
 id of the <code>actionSets</code> extension-point, namely,
 <code>org.eclipse.ui.actionSets</code>, as the first argument.  One of the
 extensions of the <code>actionSets</code> extension-point is the
 <code>help</code> extension of <a href="#listing2.5">Listing 2.4</a>, and
 that extension happens to have a single <code>actionSet</code> member. So
 when the <code>help</code> extension is reached in the outer loop, its
 <code>actionSet</code> member is supplied to the inner loop, and can be
 processed by the member processing visitor.

 <p> A similar processing loop occurs in the Eclipse workbench UI plug-in
 (the owner of the <code>actionSets</code> extension-point) when that
 plug-in is activated. And the UI plug-in can then pick apart the attributes
 and sub-elements of the <code>actionSet</code> member by using the methods of
 <var>IConfigurationElement</var> and related interfaces, and use them to
 configure the specified menu and button elements into the workbench user interface,
 and to instantiate the required callback objects, when required.

 <p> Within the member processing function called in the inner loop

 <img src="images/tag_5.gif" height=13 width=24 align=CENTER>,
 of course, the host plug-in is free to do
 whatever is necessary to process each member, as directed by that
 member's XML configuration element.

 <a name="shorthand"/>
 <h4>
 3.1.1. Extension-Point Member Traversal Shorthand
 </h4>

 <p>
 Listing 3.1 exemplifies the use of the method <code>IConfigurationElement[]
 getConfigurationElements()</code> to obtain the configurations of all members of
 an extension

 (Listing 3.1 <img src="images/tag_3.gif" height=13 width=24 align=CENTER>).

 A method with an identical signature also exists for an extension-point as a
 whole, that is, for the interface <code>IExtensionPoint</code>, and returns
 the configurations of all members of all extensions of an extension-point.
 By using this <i>shorthand</i> method, the extension/member nested loop
 (Listing 3.1, <img src="images/tag_2.gif" height=13 width=24 align=CENTER>,
 <img src="images/tag_4.gif" height=13 width=24 align=CENTER>)
 is reduced to a single loop spanning all members of all extensions of an
 extension-point. Often this simpler idiom is sufficient for processing
 an extension-point.

 <h4>
 3.1.2. Extension Processing in Action
 </h4>

 <p> By supplying a concrete extension processing visitor to the
 <code>process</code> method of our generic extension processing class

 (Listing 3.1 <img src="images/tag_1.gif" height=13 width=24 align=CENTER>),

 we can get a taste of extension processing in action. For example, to output
 identifying information about all extension members for a given
 extension-point, the following implementation of the visitor interface
 <code>IProcessMember</code> may be used:

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.demo;
 // imports ...
 public class PrintMemberIdentity implements IProcessMember {
     private String memberLabelAttribute = null;
     public PrintMemberIdentity(String memberLabelAttribute) {
         this.memberLabelAttribute = memberLabelAttribute;
     }
     public Object process(IExtension extension,
       IConfigurationElement member) {
         String label =
           extension.getDeclaringPluginDescriptor().getLabel() + "/"
           + member.getAttribute(memberLabelAttribute);
         System.out.println(label);
         return label;
     }
     public static void test(String extensionPoint,
       String memberLabelAttribute) {
         // Validate input ...
         System.out.println("Extension members of " + extensionPoint + ":");
         IProcessMember processor =
           new PrintMemberIdentity(memberLabelAttribute);
         ProcessExtensions.process(extensionPoint, processor);
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 3.2. Printing Identification Data for Extension-Point Members.
 </td></tr> </table>

 <p>
 For <code>actionSet</code> members, there is a labeling attribute whose name
 is <code>label</code>. So to get a printout of the identifying information
 for all <code>actionSet</code>s present in the current instance of the
 workbench, the following call may be used:

 <code>
 <pre>
     PrintMemberIdentity.test("org.eclipse.ui.actionSets", "label")
 </pre>
 </code>

 <p>
 And the call produces output lines such as:

 <pre>
 Java Development Tools UI/Java Element Creation
 Java Development Tools UI/Java Navigation
 Help System UI/Help
 CVS Team Provider UI/CVS
 Extension Processing Demo/Demo Menu Actions
 Eclipse UI/Resource Navigation
 ...
 </pre>

 <p> This extension processing demo is included with the
 companion plug-ins of this article. To try it out,
 see the plug-in <a href="#instructions">installation instructions </a> at
 the end of this article.

 <a name="3.2."> </a>
 <h3>
 3.2. Standardized Extension Processing
 </h3>

 <p> A principal function of extension processing is the instantiation of an
 extension's callback objects. As we shall see in section 3.3, for
 performance reasons, this function is normally performed in a lazy manner,
 as callback objects are required to do actual work. In this section,
 however, I will ignore this important performance optimization, and
 concentrate instead on the main functional aspects of callback
 instantiation.

 <p> Eclipse defines a standard for instantiating and initializing callback
 objects. As we have seen, a callback object is typically represented in a
 specific child-level or descendent XML element of an extension, and its
 fully-qualified class name is provided as the value of some attribute of
 this element. Also, the initial state of a callback object is usually
 completely parameterized by the corresponding element and its XML
 descendants. When these conditions hold, the callback object may be
 instantiated and initialized by using the standard callback object
 instantiation and initialization facilities of Eclipse.

 <p> Suppose that our extension processing code has traversed the parsed
 representation of an extension member to an element corresponding to a
 particular callback object (for example, an object standing in the
 <code>action</code> role within an <code>actionSets</code> extension).
 Suppose that this element is represented in a variable
 <code>IConfigurationElement element</code>, and that the name of this
 element's attribute designating the fully-qualified class name of the
 callback object is known to be <code>class</code>. Then, the method
 <code>createExecutableExtension(String classPropertyName)</code> of
 <code>IConfigurationElement</code> may be used to instantiate the callback
 object, as follows:

 <code>
 <pre>
 ICallback callback = (ICallback) element.createExecutableExtension("class")
 </pre>
 </code>

 <p>
 where <code>ICallback</code> is the expected interface for the
 corresponding callback role.

 <p>
 The method <code>createExecutableExtension</code> does two things:

 <ol>

 <p>
 <li>
 Instantiate a member of the required class by using its
 0-argument public constructor (one must exist).

 <p> The fully-qualified name of the required class is looked up in the
 configuration as the value of an attribute whose name is provided in the
 method's <code>classPropertyName</code> argument.

 <p>
 <li>
 Initialize this instance if it is initializable in a standard manner.

 <p>
 To become initializable in a standard manner, an extension class
 implements Eclipse's standard extension initialization interface
 <code>IExecutableExtension</code>:

 <code>
 <pre>
 package org.eclipse.core.runtime;
 public interface IExecutableExtension {
    public void setInitializationData(IConfigurationElement config,
      String classPropertyName, Object data) throws CoreException;
 }
 </pre>
 </code>

 <p> So if the instantiated callback object is an instance of
 <code>IExecutableExtension</code>, the method
 <code>createExecutableExtension</code> automatically calls
 <code>setInitializationData</code> on this extension object, giving it the
 configuration element of the callback object as a parameter (as well as its
 class attribute name, and a data parameter whose details are beyond the
 scope of this article, but can safely be ignored for now (see the Eclipse
 documentation for more details)).

 <p> What this initialization method actually does, of course, is up to the
 callback object's designer. The configuration of the callback object
 provided to this method as a parameter would drive the initialization
 process and would be reflected in the callback object's state by the
 initialization method.

 </ol>

 <p>
 A complete example of the use of this machinery to instantiate
 and initialize callback objects appears in section 4.

 <p> Note. As mentioned earlier and as we shall see in the next section,
 this entire machinery is generally used in a lazy fashion only, i.e.,
 when the callback object is actually required to do specific work. In the
 same spirit, a callback object's initialization method should, to the
 extent possible, defer time-consuming work to subsequent method calls on
 the object that would require or benefit from such work. For example, when
 a callback object manages access to a set of resources, it is often
 possible and preferable to open a managed resource only when it is actually
 required in a subsequent method call to the callback object.

 <h3>
 3.3. Lazy Extension Processing
 </h3>

 <p> When a host plug-in is activated, an eager processing of its extensions
 would cause the activation of all of its extender plug-ins, and,
 recursively, their extender plug-ins, down the plug-in hierarchy (or, more
 accurately, through the plug-in extension network). Activating all plug-ins
 reachable from a given plug-in involves loading their classes. And
 processing all extension-points of these plug-ins means loading the custom
 callback classes of all extensions of these extension-points.  As a result,
 an eager extension processing regime can considerably slow down plug-in
 activation, and therefore system startup.

 <p>
 Plug-in developers are therefore encouraged to attempt to delay
 the creation of extender-specific callback objects, until such
 objects are actually required to perform some action.

 <h4>
 3.3.1. Using Virtual Proxies in Lazy Extension Processing
 </h4>

 <p> One way to implement a lazy activation regime is to use a <i>virtual
 proxy</i> for each callback object during the activation of a
 host plug-in.  (See the <i>virtual</i> usage of the <i>proxy
 pattern</i> in [1].) Such a proxy stands in the role
 of a real callback object, and causes the real callback object to be
 instantiated only when some action is required of it. Often, it is possible
 to provide, within the proxy class, certain generic functions that are
 required of a callback object. These functions can then be furnished to
 the host plug-in without reference to particular custom extension
 classes, and without the need to activate particular extender plug-ins.

 <p>
 When using virtual proxies to initialize the extensions of a
 host plug-in, only a limited number of extension classes,
 one for each extension-point role, would be loaded in activating
 a host plug-in.

 <p>
 As an example, the internal package <code>org.eclipse.ui.internal</code>
 contains an abstract virtual proxy class called <code>PluginAction</code> for UI
 actions, and a number of concrete subclasses of this class.
 And initial extension processing for the <code>actionSets</code> extension
 point only instantiates such a proxy class for each UI action.

 <p>
 A generic constructor for an <i>action</i> proxy is defined in the abstract
 class <code>PluginAction</code>, and has the following signature:

 <code>
 <pre>
     public PluginAction(IConfigurationElement actionElement,
       String runAttribute, String definitionId, int style)
 </pre>
 </code>

 <p> The parameter <code>actionElement</code> provides a reference to the
 parsed representation of an extension XML element representing an action.
 And the parameter <code>runAttribute</code> identifies the XML attribute
 that represents the name of the custom action class to be instantiated to
 perform the action.  The <code>PluginAction</code> proxy class simply keeps
 track of these properties for later use in instantiating and initializing
 the real action object.

 <p> The proxy class fields action calls by implementing the workbench's
 <i>action</i> interface, called <code>IAction</code>. The first time a call
 is made on the <code>run</code> method of this interface, the proxy
 instantiates the custom action implementation class whose name is provided
 in <code>runAttribute</code>, The <code>run</code> method call is then
 dispatched to this custom action instance.  The custom action instance is
 known as the <i>action delegate</i>.

 <h5> 3.3.1.1. Callback Proxies versus Callback Adapters</h5>

 <p> In a canonical proxy pattern, both the proxy class and the delegate
 implementation class implement the <i>same</i> functional interface.  But
 it is not necessary to adhere to a strict interpretation of the proxy
 pattern in implementing the virtual proxies of callback objects. In fact,
 an implementation following the <i>adapter</i> pattern provides a more
 flexible mechanism for the purpose of lazy callback instantiation.

 <p> For example, the Eclipse UI action handler, <code>PluginAction</code>,
 is more precisely described as a <i>virtual adapter</i>. It implements a
 high-level interface <code>IAction</code> and adapts it to a lower-level
 interface, <code>IActionDelegate</code>, which is expected of implementers
 of custom action callbacks. And the two interfaces <code>IAction</code> and
 <code>IActionDelegate</code> are unrelated. The handler class
 <code>PluginAction</code> provides some basic services without reference to
 a particular custom action handler, and <i>adapts</i> the <code>run</code>
 method of of the workbench's <code>IAction</code> interface to the
 <code>run</code> method of the action callback interface
 <code>IActionDelegate</code> to actually perform a requested action.

 <p> (Note that the interface <code>IWorkbenchWindowActionDelegate</code>
 expected of custom workbench menu and buttons handlers, mentioned earlier
 in <a href="#2.3.1.3.1.">section 2.3.1.3.1</a>, is derived from the action
 callback interface <code>IActionDelegate</code>.)

 <p> Even though Eclipse developers do not necessarily use a strict proxy
 regime to affect lazy callback instantiation, the term <i>proxy</i> is
 commonly used in Eclipse parlance as a generic designation for internal objects
 used to <i>front</i> custom callback objects for the purpose of delaying
 their instantiation.

 <a name="4."> </a>
 <h2>
 4. Example: An Extensible Arithmetic Function Service
 </h2>

 <p> So far in this article, we have used only pre-existing extension-points.
 But with the machinery of extension processing in place, we are now ready
 to create an extension-point of our own. Our example extension-point
 is similar in its outline structure to the <code>actionSets</code> extension-point
 which we have been using so far.

 <p>
 <ol>

 <li>

 It provides a slot for augmenting the functions of a host plug-in
 by a custom set of services.

 <li>

 It has a plural form, so that each of its extensions
 is free to add more than one service to the host plug-in.

 <li>

 It requires each extension to provide concrete callback
 objects that embody the services provided by that extension.

 <li>

 It obligates the host to add elements to its user interface for each
 extension (actually for each member of each extension), so that the user
 may interact with the services provided by the extension.

 </ol>

 <p>
 In addition, our example provides for the specific initialization
 of callback objects by using the standard callback initialization facilities
 of Eclipse.

 <p> The goal is to illustrate these salient features of extensions with as
 simple an extension-point as possible. Our major concern, of course, is to
 illustrate architectural issues, patterns of usage, and extension
 processing.  User interface design issues are specifically excluded from
 this article.  In fact, our example uses a very simple user interface, just
 sufficient to illustrate the types of interactions required between the
 user interface functions and extension processing functions.

 <h3>
 4.1. The Example in Outline
 </h3>

 <p>
 The host plugin, which supplies the user interface for this example,
 will be referred to as the <i>UI plug-in</i>.

 <p> A single extension-point is defined in the UI plug-in, and supports the
 extension of the plug-in by a very simple type of service: a service that
 provides access to an integer arithmetic function of a single argument. The
 signature of the function is defined in the following callback interface:

 <code>
 <pre>
 package com.bolour.sample.eclipse.service.ui;
 public interface IFunction {
     public long compute(long x) throws ArithmeticException;
 }
 </pre>
 </code>

 <p> In our example, each member of each extension will provide an
 implementation of such a function through a callback object
 that implements the <code>IFunction</code> interface.

 <p> In order to illustrate the use of standard extension processing to
 initialize callback objects, we would like our functions to be configurable
 via configuration parameters (constants of the computation) supplied as XML
 attributes in extension declarations. Of course, we will have different
 classes of computations implemented by different callback classes, e.g.,
 addition of a parameter, multiplication by a parameter, etc.  And, in
 general, each type of computation would be parameterized differently.

 <p> But to keep our example simple, we stipulate that our computations may
 be parameterized by at most one integer parameter.  For example, if the
 function doubles the value of its argument, then it is considered as a
 multiplication by a constant factor of 2. And in this case the value 2 is
 supplied as an XML configuration parameter in the extension declaration of
 the corresponding callback object.

 <p> The UI plug-in provides an input field to enter the argument of a
 service function, a result field to display the function's value, and a
 <i>constant</i> field to display the constant parameter (if any) used in
 the computation.  Each function also requires a specific button for
 invoking it, and a specific label for giving information about it.
 Therefore, for each member of each extension, the UI plug-in adds a
 corresponding button and label to its user interface. And when the button is
 selected, the UI plug-in calls back to the associated service function.

 <p>
 Figure 2 shows the UI plug-in's user interface for a typical configuration
 of extender plug-ins.

 <P>
 <spacer type=vertical size=10>

 <CENTER>
 <IMG SRC="images/functions_grid_view.jpg" ALT="Figure-2" BORDER="0">
 </CENTER>

 <BR>
 <table align=center width=600>
 <tr><td>
 Figure 2. Service UI plug-in's function invocation view. Extensions
 of this host plug-in declare arithmetic functions that are made
 accessible through this plug-in's function invocation view.
 </td></tr>
 </table>

 <p> The UI plug-in class is <code>com.bolour.sample.eclipse.service.ui</code>.
 The extension-point is called <code>functions</code>.

 <h3>
 4.2. The Extension-Point
 </h3>

 <p>
 The <code>functions</code> extension-point is declared in the UI
 plug-in manifest file as follows:

 <code>
 <pre>
     &lt;extension-point id="functions" name="Functions"
       schema="schema/functions.exsd"/&gt;
 </pre>
 </code>

 <p> Here is the <a
 href="doc\com_bolour_sample_eclipse_service_ui_functions.html"> reference
 page</a> for this extension-point. (The source schema file for this
 extension, <code>functions.exsd</code> may be found in the <a
 href="samples.zip">companion plug-ins zip file</a>.) As indicated in the
 reference page, a <code>functions</code> extension is a sequence of
 <code>function</code> members each of which has the following attributes:

 <p>
 <ul>

 <li>
 <strong>class</strong>: The member function's custom callback class.

 <li>
 <strong>name</strong>: The member function's name. Used
 in labeling the function on the user interface.

 <li>
 <strong>constant</strong>: An optional attribute used to parameterize
 the member's function by a constant.

 </ul>

 <p> Complete examples of extensions using these attributes appear in the
 next section. For now, here is an example extension member declaration for
 a multiplication function,
 <code>compute(x)&nbsp;=&nbsp;constant&nbsp;*&nbsp;x</code>, with a constant
 factor of 2:

 <code>
 <pre>
 &lt;function
      name="DOUBLE"
      constant="2"
      class="com.bolour.sample.eclipse.service.multiplication.Multiplication"/&gt;
 </pre>
 </code>

 <p> In this case, the <code>Multiplication</code> class implements the
 standard Eclipse callback initialization interface
 <code>IExecutableExtension</code> to allow its instances to be initialized
 with the supplied constant factor.  The details are provided in <a
 href="#4.3.2.">section 4.3.2</a>.  Of course, the designer of a computation
 may decide not to parameterize it with a constant. The <i>echo</i>
 function, <code>compute(x)&nbsp;=&nbsp;x</code> (see <a
 href="#4.3.1.">section 4.3.1</a>), provides an example of such a
 non-parameterized computation. In this case, no specific initialization is
 required for the corresponding callback object, and the associated callback
 class would not implement <code>IExecutableExtension</code>.

 <p>
 Figure 3 shows the relationship between the functions UI plug-in
 and its extensions.

 <P>
 <spacer type=vertical size=10>

 <CENTER>
 <IMG SRC="images/services_extensions.jpg" ALT="Figure-3" BORDER="0">
 </CENTER>

 <CENTER>

 </CENTER>
 <BR>
 <table align=center width=600>
 <tr><td>
 Figure 3. The <code>functions</code> extension-point and its extensions.
 Sets of arithmetic functions are added to the UI
 plug-in by extending that plug-in's <code>functions</code> extension-point.
 </td></tr>
 </table>

 <p> At this point, we have in place all the information we need to create
 sample extensions of the <code>functions</code> extension-point.  So before
 getting into the implementation details of the UI plug-in, we will
 present sample extensions of this extension-point. Section 4.3 presents two
 such sample extensions. Then in section 4.4 we will return to the implementation
 of the UI plug-in by providing the details of extension
 processing in that plug-in.

 <h3>
 4.3. Extension Examples
 </h3>

 <a name="4.3.1."> </a>
 <h4>
 4.3.1. Echo: A Simple Extension
 </h4>

 <p>
 The echo service provides a function that echoes its input
 to its output. Its service class is defined as:

 <p>
 <table width=550 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.service.echo;
 import com.bolour.sample.eclipse.service.ui.IFunction;
 public class Echo implements IFunction {
     public long compute(long x) {
         return x;
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.1. The Echo Callback Function Class.
 </td></tr> </table>

 <p>
 The echo plug-in makes itself available to the user by extending
 the <code>functions</code> extension-point.
 Here is the specification of an echo
 extension.

 <p>
 <table width=550 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;extension
        id="functions.echo"
        name="EchoFunction"
        point="com.bolour.sample.eclipse.service.ui.functions"&gt;
    &lt;function
         name="ECHO"
         class="com.bolour.sample.eclipse.service.echo.Echo"/&gt;
 &lt;/extension&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.2. An Echo Extension Specification.
 </td></tr> </table>

 <p>
 This specification declares the service callback class, and specifies
 the name of the service operation to be <code>ECHO</code>.

 <p>
 Note that in this simple case, no specific state is required
 to initialize an <code>Echo</code> object. So the optional
 <code>constant</code> attribute is not used, and the
 <code>Echo</code> callback class does not implement
 the <code>IExecutableExtension</code> interface.

 <a name="4.3.2."> </a>
 <h4>
 4.3.2. Multiplication: An Extension with Custom Initialization
 </h4>

 <p> Suppose now that the service function to be provided is the
 multiplication of the input argument by a constant value.  Such a service
 is more useful if it can be configured at deployment time with the required
 multiplication factor. The function attribute <code>constant</code> is used
 for this purpose.

 <p>
 Here is a sample multiplication extension.

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;extension
     id="functions.multiplication"
     name="MultiplicationFunctions"
     point="com.bolour.sample.eclipse.service.ui.functions"&gt;
   &lt;function
      name="DOUBLE"
      constant="2"
      class="com.bolour.sample.eclipse.service.multiplication.Multiplication"/&gt;
   &lt;function
      name="TRIPLE"
      constant="3"
      class="com.bolour.sample.eclipse.service.multiplication.Multiplication"/&gt;
 &lt;/extension&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.3. A Multiplication Extension Specification.
 </td></tr> </table>

 <p>
 When this extension is processed, the attribute <code>constant</code> is
 interpreted as a multiplication factor.

 <p>
 The multiplication callback class is reproduced below (minimally redacted
 for brevity).

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.service.multiplication;
 import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IConfigurationElement;
 import org.eclipse.core.runtime.IExecutableExtension;
 import com.bolour.sample.eclipse.service.ui.IFunction;

 public class Multiplication implements IFunction, IExecutableExtension {

     private static final String FACTOR_ATTRIBUTE = "constant";
     private int factor = 0;

 <img src="images/tag_1.gif" height=13 width=24 align=CENTER> public long compute(long x) {
         return factor * x;
     }
 <img src="images/tag_2.gif" height=13 width=24 align=CENTER> public void setInitializationData(IConfigurationElement member,
       String classPropertyName, Object data) throws CoreException {

     <img src="images/tag_3.gif" height=13 width=24 align=CENTER> String s = member.getAttribute(FACTOR_ATTRIBUTE);
         try {
         <img src="images/tag_4.gif" height=13 width=24 align=CENTER> factor = Integer.parseInt(s);
         }
         catch (NumberFormatException ex) {
             // throw exception ...
         }
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.3. The Multiplication Function Callback Class.
 </td></tr> </table>

 <p>
 Note that the <code>compute</code> method
 (<img src="images/tag_1.gif" height=13 width=24 align=CENTER>)
 of this class provides the implementation of the service interface
 <code>IFunction</code>, and that the <code>setInitializationData</code> method
 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>)
 of this class provides the implementation of the standard initialization
 interface <code>IExecutableExtension</code>.

 <p> We will see in the next section that extension processing for the
 <code>functions</code> extension-point uses the standard callback
 instantiation method <code>createExecutableExtension</code>.  So because
 the <code>Multiplication</code> class implements the
 <code>IExecutableExtension</code> interface, the method
 <code>createExecutableExtension</code> automatically calls a callback
 instance's <code>setInitializationData</code> method, providing that
 instance's parsed XML element as a parameter. The initialization method can
 then extract the specified multiplication factor from the element's
 <code>constant</code> XML attribute, and keep track of it for future
 computations (<img src="images/tag_3.gif" height=13 width=24 align=CENTER>,
 <img src="images/tag_4.gif" height=13 width=24 align=CENTER>).


 <h3>
 4.4. Processing the "functions" Extension-Point
 </h3>

 <p> Now that we have examined some sample test cases for the
 <code>functions</code> extension-point, we are ready to dig deeper into the
 implementation of this extension-point and its defining UI plug-in.  Our
 extension-processing class is called <code>ProcessServiceMembers</code>.
 This class embodies the standard idioms of extension processing in Eclipse,
 specialized to the <code>functions</code> extension-point. In particular,
 this class implements a standard and lazy extension processing regime
 for the <code>functions</code> extension-point. A separate UI class
 called <code>FunctionsGrid</code> encapsulates all UI processing
 for our UI plug-in.

 <p> As usual in lazy extension processing, processing is required
 in two distinct phases of the operation of the application.

 <p> In the host plug-in startup phase, there is an initial run through the
 members of all extensions of the <code>functions</code> extension-point for
 the purpose of obtaining the configurations of these members, creating
 generic callback proxies, and building the user interface of the host
 plug-in.  In this phase, our extension processing code repeatedly calls a
 UI method called <code>addFunction</code> to augment the host plug-in's
 user interface with function invocation elements for each extension
 function

 (see Listing 4.4 <img src="images/tag_5.gif" height=13 width=24 align=CENTER>)


 <p> Then, in the interactive phase of the application, the specific
 callback objects required to perform the computations of each configured
 function are created in a lazy fashion, as calls are received by proxy
 objects. During this phase, selecting the UI button for a function causes a
 callback to that function through a proxy callback object provided by the
 extension processing class.  The call is delegated by the proxy to the real
 callback object. And the first time such a call is made to each proxy, the
 real callback object is instantiated and initialized via standard extension
 processing.

 <p>
 Section 4.4.1 outlines the extension processing class.
 Section 4.4.2 outlines the parts of the UI class that
 interact with extension processing. The bulk of the user interface
 code concerns UI details not directly related to extension processing
 and is therefore not presented in this article.

 <h4>
 4.4.1. The Extension Processing Class
 </h4>

 <p>
 Here is a redacted version of our initial extension processing function:

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.service.ui;
 public class ProcessServiceMembers {
     private static final String EXTENSION_POINT =
         "com.bolour.sample.eclipse.service.ui.functions";
     private static final String FUNCTION_NAME_ATTRIBUTE = "name";
     private static final String CLASS_ATTRIBUTE = "class";
     private static final String CONSTANT_ATTRIBUTE = "constant";
 <img src="images/tag_1.gif" height=13 width=24 align=CENTER> public static void process(FunctionsGrid grid)
       throws WorkbenchException {
         IPluginRegistry registry = Platform.getPluginRegistry();
         IExtensionPoint extensionPoint =
           registry.getExtensionPoint(EXTENSION_POINT);
         IConfigurationElement[] members =
           extensionPoint.getConfigurationElements();
         // For each service:
     <img src="images/tag_2.gif" height=13 width=24 align=CENTER> for (int m = 0; m &lt; members.length; m++) {
             IConfigurationElement member = members[m];
             IExtension extension = member.getDeclaringExtension();
             String pluginLabel =
               extension.getDeclaringPluginDescriptor().getLabel();
             String functionName =
               member.getAttribute(FUNCTION_NAME_ATTRIBUTE);
             String label = pluginLabel + "/" + functionName;
             Integer constant = null;
             String s = member.getAttribute(CONSTANT_ATTRIBUTE);
             if (s != null) {
                 try {
                     constant = new Integer(s);
                 }
             <img src="images/tag_3.gif" height=13 width=24 align=CENTER> catch (NumberFormatException ex) {
                     // Invalid function. Inform the user ... and ignore.
                     continue;
                 }
             }
         <img src="images/tag_4.gif" height=13 width=24 align=CENTER> IFunction proxy = new FunctionProxy(member);
         <img src="images/tag_5.gif" height=13 width=24 align=CENTER> grid.addFunction(proxy, functionName, label, constant);
         }
     }
     // ...
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.4. Extension Member Processing for Service Functions.
 </td></tr> </table>

 <p>
 The extension processing loop
 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>)
 follows the <a href="#shorthand">shorthand
 idiom for getting the members of all extensions of an extension-point</a>
 introduced in section 3.1.1.
 This run through the extension members of the <code>functions</code> extension-point
 creates a proxy callback object for each function

 (<img src="images/tag_4.gif" height=13 width=24 align=CENTER>),

 and adds this proxy and its associated UI widgets to the UI
 by calling the <code>addFunction</code> method of the UI's function
 grid

 (<img src="images/tag_5.gif" height=13 width=24 align=CENTER>).

 (The body of the <code>addFunction</code> method is presented later in
 <a href="#listing4.6">Listing 4.6</a>

 <img src="images/tag_1.gif" height=13 width=24 align=CENTER>.)

 <p> Note that certain configuration errors, such as an invalid constant in
 our example, can be detected in a generic manner, that is, without recourse
 to specific callback objects (whose instantiations we are deferring). Such
 errors should be handled during initial extension processing, so that, to the
 extent possible, the host plug-in is not polluted with invalid callback
 objects and associated widgets. Thus, when a non-integral constant is encountered in the
 initial extension processing of the <code>functions</code> extension-point,
 the corresponding misconfigured function is ignored

 (<img src="images/tag_3.gif" height=13 width=24 align=CENTER>).

 <p>
 During the interactive phase of the application, when a function
 call is received by a callback proxy, it must be delegated to the
 custom implementation of the function. And
 that implementation is instantiated in a lazy fashion the
 first time a call is received by a proxy. The details appear
 in the following code fragment.

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.service.ui;
 public class ProcessServiceMembers {
     // ...
     private static final String CLASS_ATTRIBUTE = "class";
     // ...
     private static class FunctionProxy implements IFunction {
         private IFunction delegate = null;      // The real callback.
         private IConfigurationElement element;  // Function's configuration.
         private boolean invoked = false;        // Called already.
         public FunctionProxy(IConfigurationElement element) {
             this.element = element;
         }
         public final long compute(long x) throws ArithmeticException {
             try {
                 getDelegate();
             }
             catch (Exception ex) {
                 throw new ArithmeticException("invalid function");
             }
             if (delegate == null) {
                 throw new ArithmeticException("invalid function");
             }
             return delegate.compute(x);
         }
         private final IFunction getDelegate() throws Exception {
             if (invoked) {
                 return delegate;
             }
             invoked = true;
             try {
                 Object callback =
                   element.createExecutableExtension(CLASS_ATTRIBUTE);
             <img src="images/tag_1.gif" height=13 width=24 align=CENTER> if (!(callback instanceof IFunction)) {
                     // throw exception ...
                 }
                 delegate = (IFunction)callback;
             }
         <img src="images/tag_2.gif" height=13 width=24 align=CENTER> catch (CoreException ex) {
                 // process and rethrow ...
             }
             return delegate;
         }
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.5. Extension Member Processing for Service Functions.
 </td></tr> </table>

 <p>
 This is a straightforward example of the use of the virtual proxy pattern,
 and other than error processing, which is discussed in the next section,
 requires no further comment.

 <h5>
 4.4.1.1. Error Processing
 </h5>

 <p> In the previous section, we saw that certain configuration errors may
 be detected in a generic manner during initial extension processing, and
 can be handled at that time. Unfortunately, not all configuration errors
 are of this variety, since deferring the instantiation of callback objects in
 a lazy regime also defers the detection of errors related to instantiating
 and initializing callback objects. We will call configuration errors
 that are detected during the interactive phase of the application,
 <i>interaction time</i> configuration errors.

 <p> Interaction time configuration errors fall into two categories:
 interface mismatches: callback classes that do not implement their required
 callback interfaces, and creation/initialization errors, e.g.,
 non-existent classes, or invalid specific configuration parameters (for
 example, 0 denominator for a division function).  In Listing 4.5, interface
 mismatches are detected at

 <img src="images/tag_1.gif" height=13 width=24 align=CENTER>,

 and creation/initialization errors are detected at

 <img src="images/tag_2.gif" height=13 width=24 align=CENTER>.

 Note that an error detected anywhere within the execution of
 <code>createExecutableExtension</code>, including an error in the
 initialization of a callback object, is communicated back to the caller via
 a <code>CoreException</code>.

 <p> In our application, an interaction time configuration error causes an
 <code>ArithmeticException</code> to be thrown. The exception is handled in
 the UI trivially by displaying <code>error</code> in the <code>result</code> field of
 function invocations. However, our simple application does not disable the
 UI elements associated with such misconfigured functions once the
 configuration error is detected, and allows the user to repeat the failure. A
 more sophisticated application might dynamically disable or remove user
 interface elements associated with misconfigured members of extensions.

 <p>
 The <a href="samples.zip">companion plug-ins zip file</a> includes
 a sample plug-in, <code>errortest</code>, that exemplifies
 configuration errors. By default the <code>functions</code>
 extension that includes these errors is commented out.
 To test the effect of configuration errors in this application,
 uncomment the <code>functions.error</code> extension in the
 <code>errortest</code> plug-in's manifest file, and restart
 Eclipse.

 <p> In summary, the late detection of configuration errors in lazy
 extension processing makes it more difficult to handle configuration
 errors gracefully.  And in general, a tension exists between application
 startup performance, graceful error processing, and the customizability of
 callback objects standing in a given role.

 <h4>
 4.4.2. The User Interface Class
 </h4>

 <p> This section outlines the user interface class of the UI plug-in
 insofar as it interacts with the extension processing class.

 <p>
 For each function specification included in an extension of
 the <code>functions</code> extension-point, initial extension
 processing adds a function invocation button and a corresponding
 label to the UI plug-in's user interface. Here is an abbreviated
 version of the UI code used for this purpose:

 <a name="listing4.6"> </a>
 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.service.ui;

 public class FunctionsGrid {
         private Composite buttons;      // Function invocation area.
     // ...
 <img src="images/tag_1.gif" height=13 width=24 align=CENTER> public void addFunction(IFunction function, String functionName,
       String label, Integer constant) {
         GridRow row = new GridRow(function, functionName, label, constant);
     }
     // ...
     private class GridRow {
         private IFunction function;     // Callback object.
         private Button button;          // UI widget.
         private Label functionLabel;    // UI widget.
         // Constant of the computation (for display only).
         private String constantDisplay;

         public GridRow(IFunction function, String functionName,
           String label, Integer constant) {
             // ...
         <img src="images/tag_2.gif" height=13 width=24 align=CENTER> this.function = function;
             this.constantDisplay =
               constant == null ?  "none" : constant.toString();
             button = new Button(buttons, SWT.NONE);
             button.setText(functionName);
             // ...
             button.addSelectionListener(new SelectionListener() {
                 public void widgetSelected(SelectionEvent e) {
                     handleButton(e);
                 }
                 // ...
             });
             functionLabel = new Label(buttons, SWT.NONE);
             functionLabel.setText(label);
             // ...
         }
     <img src="images/tag_3.gif" height=13 width=24 align=CENTER> public void handleButton(SelectionEvent e) {
             String t = input.getText();
             parameter.setText("");
             try {
                 int x = Integer.parseInt(t);
             <img src="images/tag_4.gif" height=13 width=24 align=CENTER> result.setText(String.valueOf(function.compute(x)));
                 parameter.setText(constantDisplay);
             }
             catch (Exception ex) {
                 result.setText("error");
             }
         }
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 4.6. Adding a Function to the User Interface.
 </td></tr> </table>

 <p> Extension processing makes a call to the <code>addFunction</code>

 (<img src="images/tag_1.gif" height=13 width=24 align=CENTER>)

 method of the UI to build a <i>grid row</i> that includes the required button
 and label. This method takes four arguments:

 <p>
 <ul>

 <li>
 <code>IFunction function</code>: provides the callback object to be called when the
 button is selected.

 <li>
 <code>String functionName</code>: provides the display name of the
 function's button.

 <li>
 <code>String label</code>: provides the text of the associated label.

 <li>
 <code>Integer constant</code>: provides the constant parameter (if any) used in the
 computation. The constant is transmitted to the UI for display purposes only,
 and is displayed along with the result of a computation when the corresponding
 button is selected.

 </ul>

 <p> Each invocation of the <code>addFunction</code> method is delegated to
 a <code>GridRow</code> constructor with identical parameters.  A
 <code>GridRow</code> encapsulates the representation of a function in the
 user interface. For each function, the <code>GridRow</code> constructor
 saves the reference to the callback object for future calls

 (<img src="images/tag_2.gif" height=13 width=24 align=CENTER>).

 It also associates a button event handler <code>handleButton</code>

 (<img src="images/tag_3.gif" height=13 width=24 align=CENTER>)

 with the button. When the button is later selected by the user,
 the event handler obtains the user input from the UI input field, invokes the
 service function associated with the button on that input, and displays the
 resulting value of the function (<img src="images/tag_4.gif" height=13
 width=24 align=CENTER>). It also displays the constant parameter (if any)
 used in the computation.

 <p> This completes the description of our arithmetic function invocation
 service  The function invocation UI plug-in and sample extender plug-ins
 are included in this article's companion samples.  See the <a
 href="#instructions">instructions</a> at the end of this article for
 configuring the companion plug-ins.

 <a name="5."> </a>
 <h3>
 5. Listener Extensions and the Observer Pattern
 </h3>

 <p>
 The previous section provided a simple example of what might be
 called the <i>service extension pattern</i>. Each member of
 a <i>service extension</i> defines a unique set of user
 interface widgets, and events on these widgets trigger
 callbacks to objects unique to the extension.

 <p> Other usage patterns of extensions are possible, of course.  And
 in this section we briefly outline one such pattern that is akin to the
 <i>observer</i> design pattern of [1]. Our examination of this usage
 pattern leads naturally to a comparison of the extension model of Eclipse
 with the much simpler observer pattern.

 <p> In the language of Java APIs, observers are called
 <code>listeners</code>, and the pattern of extension usage discussed in
 this section may be called the <i>listener extension pattern</i>. In the
 listener extension pattern, multiple extension members may listen for the
 same event in a host plug-in. And the host plug-in notifies all these
 extension members, or rather their associated listener callbacks, when the
 event occurs.

 <p> The Eclipse JDT JUnit plug-in <code>org.eclipse.jdt.junit</code> uses such a
 pattern to allow multiple observers within the Eclipse workbench to get
 notification of testing events, such as the start or the completion of a
 JUnit test.  This usage is covered in the Beck and Gamma manuscript [2],
 which is where I was first introduced to the listener extension pattern.

 <p> In the listener extension pattern, the host plug-in acts as the
 <i>subject</i> of the observation, and extender plug-ins act as the
 <i>observers</i> or <i>listeners</i>.  The host plug-in therefore
 provides an extension-point that may be called <code>listeners</code>, and
 a corresponding interface that may be called <code>IListener</code>.  Each
 extender plug-in then extends the <code>listeners</code> extension-point by
 supplying a specific listener that implements the <code>IListener</code>
 interface, or by supplying a sequence of such listeners.

 <p> Because the listeners are then specified declaratively through the
 plug-in extension mechanism, these listeners can be automatically
 registered for event notification by extension processing. The first time
 notification is required, the subject plug-in processes its
 <code>listeners</code> members, and for each member, instantiates a
 specific listener callback object and registers that listener for event
 notification.

 <p> The companion sample plug-ins include an example of the listener
 extension pattern, whose structure is shown in Figure 4.

 <P>
 <spacer type=vertical size=10>

 <CENTER>
 <IMG SRC="images/listeners_extensions.jpg" ALT="Figure-4" BORDER="0">
 </CENTER>

 <CENTER>

 </CENTER>
 <BR>
 <table align=center width=600>
 <tr><td>
 Figure 4. Extension structure of the <i>listener</i> extension pattern.
 Each member of each <i>listener</i> extension provides a notification callback
 for <i>subject</i> events.
 </td></tr>
 </table>

 <p>
 In this example, an update of the subject causes notifications to be
 broadcast to all members of all extensions of the <code>listeners</code>
 extension-point.

 <p>
 Here is the
 <a href="doc/com_bolour_sample_eclipse_listener_subject_listeners.html">
 reference page of the <code>listeners</code>
 extension-point</a>.

 <p> As configured out of the box, the example includes two plug-ins that
 extend the <code>listeners</code> extension-point, and are called
 <code>firstlistener</code> and <code>secondlistener</code>. Each of these
 plug-ins has an extension with two <code>listener</code> members,
 <code>ListenerX</code> and <code>ListenerY</code>. Thus, the first listener
 plug-in's extension specification looks like:

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 &lt;extension
     point = "com.bolour.sample.eclipse.listener.subject.listeners"&gt;
     &lt;listener
       class="com.bolour.sample.eclipse.listener.firstlistener.ListenerX"/&gt;
     &lt;listener
       class="com.bolour.smaple.eclipse.listener.firstlistener.ListenerY"/&gt;
 &lt;/extension&gt;
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 5.1. A Listener Extension Specification.
 </td></tr> </table>

 <p> The host plug-in defines a menu item, which, when selected, causes the
 state of the subject to be updated. In turn, the state change in the
 subject causes listener notifications to be broadcast to each listener
 configured into the system.

 <p> The listener callbacks in this example are trivial and simply print an
 informational message to standard output, as shown in the following
 listener class:

 <p>
 <table width=600 bgcolor="#CCCCCC"><tr><td>
 <code>
 <pre>
 package com.bolour.sample.eclipse.listener.firstlistener;
 import com.bolour.sample.eclipse.listener.subject.IListener;
 public class ListenerX implements IListener {
     public void listen() {
         System.out.println(this.getClass().getName() + " notified");
     }
 }
 </pre>
 </code>
 &nbsp;&nbsp;&nbsp;&nbsp;
 Listing 5.2. A Listener Callback Implementation.
 </td></tr> </table>

 <p>
 So running this example out of the box results in the following console
 messages:

 <p>
 <code>
 <pre>
 com.bolour.sample.eclipse.listener.secondlistener.ListenerX notified
 com.bolour.sample.eclipse.listener.secondlistener.ListenerY notified
 com.bolour.sample.eclipse.listener.firstlistener.ListenerX notified
 com.bolour.sample.eclipse.listener.firstlistener.ListenerY notified
 </pre>
 </code>

 </ol>

 <h3>
 5.1. The Eclipse Extension Model versus the Observer Pattern
 </h3>

 <p> As we have seen, the listener extension pattern is analogous to the
 observer pattern, except for its static deployment-time registration of
 listeners. So ignoring the dynamic nature of observer registrations,
 the observer pattern may be thought of as a specialization of
 the Eclipse extension model. In fact, modulo dynamic registration,
 the extension model of Eclipse adds power to the observer pattern
 at a number of levels:

 <ol>

 <p>
 <li>

 <strong>Callback Bundle versus Single Callback</strong>.
 A single extension may provide multiple callback objects.
 A single observer provides a single callback object.

 <p>
 <li>

 <strong>Differentiation of Extenders versus Uniform Treatment of Observers</strong>.
 Depending on the parameters of an extension and the specifics of the
 extension-point contract, different extensions of a given extension-point
 can be treated differently. In contrast, the observer pattern treats
 all observers of a given subject uniformly, notifying every one
 of an observable event.

 <p>
 <li>

 <strong>Arbitrary Semantics in Host versus Fixed Notification Semantics in Subject</strong>.

 There can be arbitrary parameterized host semantics associated with an
 extension instance. Based on the configuration of the extension, the
 host can accept a variety of customizable responsibilities under the
 extension contract, e.g., the provision of user interface elements.
 There is no such parameterization and customizability
 in the observer design pattern.

 </ol>

 <p> But a closer comparison exists between the Eclipse extension model and the
 extension model of a <i>microkernel</i> by so-called <i>internal servers</i>,
 e.g., OS device drivers (see, for example, the microkernel pattern in [4]).
 Both models allow a core set of services to be extended by additional
 provider-supplied services. But the Eclipse extension model generalizes the
 internal extension model of the microkernel architecture in two
 ways.  First, Eclipse plug-ins provide a packaging mechanism for sets of
 related extensions. Second, in Eclipse any plug-in may provide
 extension-points and make itself extensible by other plug-ins. In contrast,
 in the microkernel architecture, the microkernel core (e.g., an OS
 kernel) has unique standing as the sole extensible component in a system.

 <a name="6."> </a>
 <h2>
 6. Summary and Conclusions
 </h2>

 <p> The plug-in extension model of Eclipse provides a powerful and general
 paradigm for architecting extensible systems based on loosely-coupled
 components.  The principle use of this architecture, of course, is the
 Eclipse workbench.  But the basic extension model is an abstract
 architectural pattern quite apart from its specific incarnation in the
 workbench.

 <p>
 The principle facilities of this abstract model are:

 <ol>

 <p>
 <li>

 <strong>Deployment-time pluggable components</strong>.

 Plug-ins are components that are assembled into a system at deployment time. A
 plug-in is implemented in a running system as an instance of a plug-in
 class.  Characteristics of each plug-in are declaratively specified in a
 manifest file, which is interpreted at runtime to instantiate the plug-in
 and relate it to other plug-ins.

 <p>
 <li>

 <strong>Extension-points</strong>.

 A particular way in which a plug-in allows itself to be extended is embodied
 in an <i>extension-point</i>. An extension-point is defined by a plug-in that
 stands in a <i>host</i> role with respect to the extension-point, and may be
 extended by one or more plug-ins that stand in an <i>extender</i> role with
 respect the extension-point.  There is a contract associated
 with each extension-point.  The contract puts obligations on both the host
 and the extender plug-ins.

 <p>
 <li>

 <strong>Extensions as Parameterized Callback Bundles</strong>.

 An extension-point contract generally provides one or more
 callback interfaces, and requires extenders to provide custom
 implementations (callback objects) for these interfaces. Then
 the host is obligated to call back on these callback objects under
 certain conditions specified in the contract, and based on a particular
 extension's configuration parameters.

 <p>
 <li>

 <strong>Obligations of the Host</strong>.

 The host obligations under an extension-point contract may include
 additional requirements on the behavior of the host, such as a
 requirement on the host to augment its interface by additional
 processing elements.

 <p>
 <li>

 <strong>Obligations of the Extender</strong>.

 The extender describes the characteristics of an extension declaratively in
 its manifest file. The extension-point contract provides an XML schema for
 this description, and the extension specification in the extender's
 manifest file must conform to this schema. The schema includes slots for
 the concrete classes of the extension's callback objects, and for the
 parameters required to construct these objects. The concrete classes are
 furnished by the extender, and must conform to expected interfaces defined
 by the host. At runtime, the host instantiates the configured
 callback objects based on their configuration parameters.

 </ol>


 <p> In summary, Eclipse plug-ins offer a flexible model of extensibility,
 and their abstract architecture for composing systems out of
 loosely-coupled components provides a significant addition to the available
 repertoire of architectural patterns for software systems (see, e.g., [4]).

 <a name="instructions"> </a>
 <p><b>
 Sample Code Installation.
 </b>

 <p>
 To run the samples appearing in this article and view their source code,
 extract the contents of the <a href="samples.zip">companion plug-ins
 zip file</a> into your Eclipse installation.

 <p>
 In order to interact with the samples through the workbench,
 you will have to enable their user interface elements
 as follows:

 <ul>

 <p>
 <li>
 <i>Extension Processing Demo</i>.
 Bring up the <i>Windows-&gt;Customize
 Perspective</i> dialog, and under <i>Other</i>, enable <i>Demo Menu Actions</i>.
 Close the dialog. The <i>Demo</i> menu should now be available.

 <p>
 <li>
 <i>Arithmetic Service</i>.
 Bring up the <i>Windows-&gt;Customize
 Perspective</i> dialog, and under <i>Window-&gt;Show View</i> enable
 <i>Functions Grid View</i>, and close the dialog. In the workbench <i>Window-&gt;Show
 View</i> list, you should now see the list item <i>Functions Grid View</i>.
 Select that item to display the view for this sample.

 <p>
 <li>
 <i>Listener Extensions</i>.
 Bring up the <i>Windows-&gt;Customize
 Perspective</i> dialog, and under <i>Other</i> enable <i>Listener
 Menu Actions</i>. Close the dialog. The <i>Listener</i> menu should now
 be available.

 </ul>

 <p> Note that for simplicity, <i>standard output</i> and <i>standard
 error</i> are used to display messages in these samples. By default, on a
 <i>win32</i> platform, Eclipse uses the <i>javaw</i> virtual machine, which
 does not have an associated console for standard IO. To bring up Eclipse on
 a <i>win32</i> platform with an associated console, the Eclipse executable
 may be asked to use <i>java</i>, rather than <i>javaw</i>, by using the
 <code>-vm</code> option, e.g.,

 <code>
 <pre>
 eclipse -vm C:\jdk1.3.1_02\jre\bin\java.exe
 </pre>
 </code>

 <p>
 The samples have been tested with Eclipse 2.1 and JDK 1.3.1_02
 on Windows 2000.

 <p><b>
 References
 </b>

 <ol>
 <li value=1>
 Gamma, Erich, Richard Helm, Ralph Johnson, John Vlissides,
 <i>Design Patterns, Elements of Reusable Object-Oriented Software</i>,
 Addition-Wesley, 1995.
 <li value=2>
 Beck, Kent, and Erich Gamma,
 <a href="http://groups.yahoo.com/group/contributingtoeclipse/files/030410.pdf">
 <i>Contributing to Eclipse</i></a>
 (pre-publication draft) 2003.
 <li value=3>
 Shavor, S., Jim D'Anjou, et. al. <i>The Java Developer's Guide to
 Eclipse</i>, Addison-Wesley, 2003.
 <li value=4>
 Buschmann, Frank, et. al., <i>Pattern-Oriented Software Architecture, A
 System of Patterns, Volume 1</i>,
 John Wiley and Sons, 1996.
 <li value=5>
 Estberg, Don.
 <a href="http://eclipsewiki.swiki.net/2587"><i>How the Minimum Set of Platform
 Plugins Are Related</i></a>, Wiki Page 2587, Eclipse Wiki.

 </ol>

 <p><b>Acknowledgments</b> </br> This article originated in discussions within
 the <i>Silicon Valley Patterns Group</i> on Eclipse plug-ins. Thanks to the
 members of the group, and in particular to Tracy Bialik, Phil Goodwin, Jan
 Looney, Jerry Louis, Chris Lopez, Russ Rufer, Rich Smith, and Carol
 Thistlethwaite for the original conversations leading to these notes, and
 for many great suggestions for improving the content and presentation of
 the material.  Special thanks to Russ Rufer and Tracy Bialik for blazing
 the Eclipse trail for the rest of the group.  The group discussions were
 organized around a review of an early manuscript by Kent Beck and Erich
 Gamma: <a href="http://groups.yahoo.com/group/contributingtoeclipse/files/030410.pdf">
 Contributing to Eclipse </a>. These notes, therefore, owe much to Beck and
 Gamma for introducing us to the concepts and facilities of Eclipse
 plug-ins. Don Estberg devised the diagrammatic representation of
 extension-points used in this article, based on the <i>power-strip</i>
 metaphor. Thanks also to Don for his detailed comments. Finally, my thanks
 to Dennis Allard and Dan Conde for their generous offer of time in
 reviewing the final draft of this article, and to Jim des Rivi&egrave;res for his
 detailed review and numerous suggestions for enhancements.

 </body>

 </html>