This article, a two part one, introduces IBM's "Eclipse" IDE. This was published in the "Linux For You" magazine in the July and August 2004 issues Visit LFY Website

The Eclipse IDE : Part 2

Eclipse is not just an excellent Java IDE. Its plugin based architecture allows it to be anything you want it to be. This second and concluding part shows you how.



Read the first part
1. Background

In the first part of this article ("Using the Eclipse IDE"), you have seen an overall view of what the Eclipse IDE has to offer, especially if you are a Java programmer. While the Java Development Tools (JDT) of Eclipse makes it stand out as an exceptionally capable Java IDE, the real goal of the Eclipse project, as we have seen, is to be a tool integration platform. This is achieved by the plugin based architecture of Eclipse which allows you to integrate your tools seamlessly into the Eclipse IDE. Before we see how we can achieve that, we must take a look at the Eclipse architecture in somewhat greater detail.

2. The Eclipse Architecture

Almost all of the functionality you see in the Eclipse IDE is due to plugins. But there is an overall manager of all these plugins - this is the base platform upon which all plugins conceptually reside. This "manager" of plugins or "base platform" actually goes by the name of the Eclipse Platform Runtime . It is this platform runtime"s job to handle the discovery of new plugins, initialization of existing plugins and maintaining a common registry of information about these plugins. Everything in Eclipse apart from this runtime is a plugin.

At this point we need to understand the concept of extensibility and Extension Points as applied to the Eclipse platform. Let's say you want to add a button to the Eclipse Workbench toolbar (i.e. the main toolbar in the Eclipse IDE). This is one of the most common forms of extensions - an extension to the Workbench UI. This is possible because the Workbench UI defines several " Extension Points" , which are, simply speaking, where the UI may be extended. As another example, an external plugin may define a new type of editor for particular types of files. This is again possible because the Workbench allows other plugins to contribute a new editor for certain types of files. We shall see this concept in action once we create our own plugin.

The Eclipse Architecture is best explained with the following well-known diagram (Figure 1).

fig1
Figure 1: Eclipse Architecture

The Eclipse SDK, or the zip file you extracted and installed is nothing but a collection of the Eclipse base Platform Runtime, core elements of Eclipse including the Workbench and the Workspace among other things, and several other collections of plugins such as the Java Development tools (JDT) or the Plugin Development Environment (PDE).

The Workbench constitutes the user interface aspects of Eclipse. From a typical user's point of view, the Workbench and the Eclipse IDE may be considered as the same thing. All the editors, views and perspectives you see make up this Workbench. (If you have forgotten what these terms mean, you may wish to look at their explanations in the first part of this article). The Eclipse user interface is built on top of SWT and JFace. SWT or, the Standard Widgets Toolkit is a portable GUI toolkit that is in turn built upon the native widgets of the underlying operating system. This explains why the UI widgets of Eclipse appear exactly like those of the operating system it is running on. Most other Java based IDEs have a "Java look and feel", which is not always completely consistent to that of the native operating system. JFace is a UI framework for common UI based tasks, and it is heavily used in Eclipse as well.

Loosely speaking, the Workspace is the top level container of all the resources of the current user. The Workspace typically contains several projects, each of which map to directories on the file system. In Eclipse parlance, a Resource refers to the core elements of the Workspace - files, folders and projects. Resources have several behaviours that may be captured in the Eclipse platform. For instance, one may monitor any changes in a resource, by adding special resource "listeners". A good example of this is evident in the Java Development Tools. When you save any of your Java sources, the changes in the file automatically invoke the Java compiler to create the .class files. This assumes that you have the option " Perform build automatically on resource modification" selected ( Window->Preferences->Workbench ).

The Help and Team components show the Eclipse help system and the Eclipse "Team" functionality (features relating to CVS etc.). The diagram also shows several plugins integrated into the Eclipse platform, which includes some we have encountered - the JDT and the PDE. With this background, let us dive into what Eclipse plugins actually are.

3. Plugin Architecture

Plugins are, simply put, external tools that provide extra functionality to the core Eclipse platform and are completely integrated into it. Each plugin contains "extension points", and there are two ways in which extension points may appear in the definition of a plugin.

a) A plugin may define new extension points. This allows other plugins to extend this plugin at these well defined points.

b) A plugin may contribute to extension points (which are already defined elsewhere). This means that this plugin extends the functionality of other plugins at these extension points.

In this article, we shall use extension points in the sense implied in part b) above, i.e. we shall extend the functionality of existing plugins. Plugins are written in Java, but the "wizards" present in Eclipse make the whole affair of creating a plugin quite simple. Before creating a plugin, however, here is a diagram that shows what a typical plugin consists of in the file system.

fig2
Figure 2: Components of a typical plugin

The diagram shows the plugin folder of " JUnit " [ http://www.junit.org ] - a testing framework for Java. The "about.html" file contains a description of the plugin. But the important components are the other three files shown, each of which is described in brief below:

a) The JAR file (junit.jar in this case): This archive contains the actual Java classes for the plugin.

b) The plugin manifest (plugin.xml): This file essentially describes the plugin and must be named plugin.xml. We shall see the structure of this XML file in greater detail shortly.

c) The plugin properties (plugin.properties): This file, as the name suggests contains some properties of the plugin (in plaintext format).

The Plugin Manifest File (plugin.xml)

No plugin is complete without a proper manifest file (that is, its own plugin.xml file). The Eclipse platform runtime reads this information from the XML file and loads the plugin. The file contains descriptions of several aspects of the plugin, including the following:

  • Name, ID, provider and version of the plugin
  • Dependencies, i.e. a list of other plugins that are pre-requisites for this plugin
  • Extensions defined by this plugin (where other plugins can extend this plugin)
  • Extension points this plugin contributes to (where this plugin extends other plugins)
  • Location of the code.

Writing this XML manifest file manually may be tedious and error-prone. Fortunately, the Eclipse PDE provides a GUI based editor of plugin manifest files that makes the process of creation/modification of these files a matter of a few mouse clicks and text entries, as we shall see in the next section. Let us get working on our first Eclipse plugin.

4. Creating a "Hello World" Plugin

After the simple "Hello World" program in part one of this article, it's now time to build a "Hello World" plugin with the help of the Eclipse PDE. This plugin adds a menu to the Eclipse IDE menu bar (with one menu item) and a button to the toolbar. Clicking on either result in the same Action - showing a message box with "Hello World" written on it. Although the PDE already contains a template for a "Hello World" plugin, I shall not use that since it is too trivial that way. Moreover, we need to familiarize ourselves with the basic steps involved in creating any plugin.

Okay, let's start. Create a new project. In the dialog, select "Plug-in Development" and "Plug-in Project" in the left and right panes. Click "Next" and name your project com.linuxforu.helloworld . In the next dialog, the plugin-id is set to this name by default. This plugin-id must be unique in your system. Leave the options as they are and click on "Next" . You will be presented with a dialog similar to the one shown in figure 3.

fig3
Figure 3: Plugin Code Generators

Do not be tempted to choose " Hello, World "; instead opt for the " Default Plug-in Structure " in the available list. Note however, the large set of options Eclipse provides to get you started on your plugin.

In the next step, de-select the three "Plug-in code generation options" since we won't need them for our plugin. Make sure the dialog should looks like the one shown in figure 4.

fig4
Figure 4: Final step of the Wizard

When you click "Finish" , Eclipse generates the base plugin manifest file (plugin.xml) file for you and opens the "Plug-in Manifest Editor" in the editor area. If you are asked whether to switch to the plugin development perspective, do so. Figure 5 shows the IDE at this point.

fig5
Figure 5: Plug-in Welcome Screen

The Eclipse PDE has just generated a base plugin that does nothing, that is, it has no contributions defined. To do that, we need to add some extensions. Switch over to the " Extensions" page in the manifest editor, and click "Add..." . Choose "Generic Wizards" , then "Schema-based Extension" and click " Next" . You will be presented with a long list of existing extension points, as shown in figure 6. Choose " org.eclipse.ui.actionSets" and click " Finish ".

fig6
Figure 6: Selecting an extension point

This needs some explanation. Remember that our objective is to add a menu/toolbar to the Eclipse Workbench. This sort of an enhancement to Eclipse is known as an "Action Contribution". Eclipse provides a variety of extension points that allow you to contribute actions to the IDE. The following is a list of some of these extension points, and where the contributions show up in practice.

Contribution Location Extension Point
Menus,
Toolbars
Workbench window
Views
Editors
org.eclipse.ui.actionSets
org.eclipse.ui.viewActions
org.eclipse.ui.editorActions
Context menus Editors, Views etc. org.eclipse.ui.popupMenus

In fact, the list of available extension points is quite long! From custom wizards ( org.eclipse.ui.newWizards ) to editors ( org.eclipse.ui.editors ) to incremental compilers ( org.eclipse.core.resources.builders ), Eclipse provides you with the flexibility to build almost anything. Since in our plugin, we want to add menus and toolbars to the Eclipse Workbench window, the extension point we shall use is org.eclipse.ui.actionSets .

Having selected the appropriate extension point (figure 6), we need to add the child tag "actionSet" to actually define what we are going to do. Do this by right-clicking on extension in the " All Extensions" list and select " New->actionSet" . In the "Properties" view, set the following properties for this actionSet:

id com.linuxforu.helloworld.actionSet
label HelloWorld Action Set
visible true

Let's create the menu now. Right click on " HelloWorld Action Set (actionSet) " and create a new menu. In the properties view, set the following:

id HelloWorldMenu
label &HelloWorld Menu

Next create a menu separator (right click the menu and select New->separator ). Set the following property of the separator:

name HelloWorldGroup

Now we need to add the action to associate with this menu. Again, select the " HelloWorld Action Set" , right click, and add a New->action. In its properties view, set the following:

tooltip This is the tool tip
id com.linuxforu.helloworld.HelloWorldAction
label Hello World
menubarPath HelloWorldMenu/HelloWorldGroup
toolbarPath HelloWorldGroup

What we have just done is this: first we have defined a menu and a menu separator. Next, we have added an action. This action's "menubarPath" refers to the menu we have created. This action also defines a toolbarPath. Hence, in effect the action tag declares an action that is available from the main menu or the toolbar. The action has another attribute called "class". When the user clicks on the menu item or toolbar, the class specified in the "class" attribute will be instantiated an its "run" method called.

To specify the class to use when the action is invoked, go to the " class" attribute in the Properties view and click on the small ellipsis button to the right. This fires up a class selection dialog. Choose " Generate a new Java class". In the package name field, click on " Browse" and select com.linuxforu.helloworld from the available packages. In the " Class name" field, enter " HelloWorld ". Figure 7 shows what the dialog should look like at this point:

fig7
Figure 7: Class selection dialog

Clicking on " Finish" opens the generated class in the editor area for further editing. This is the class that is invoked (its " run" method is called) when the action is selected by the user. We need to implement the message box showing "Hello World" here. To do that, make the following four changes to this Java file:

1] Add a member variable to the class:

private IWorkbenchWindow win;

2] In the " init" method of this class, add the following line:

win = window;

3] Add the following import to the file:

import org.eclipse.jface.dialogs.MessageDialog;

4] Implement the " run" method by adding the following code:

MessageDialog.openInformation(win.getShell(), "HelloWorld Plugin", "Hello World");

Basically, we have accessed the Eclipse Workbench through the private "win" variable, which is set in the "init" method. In the run method, we have used this variable in the JFace call MessageDialog.openInformation which shows a message box titled "HelloWorld Plugin", having the text "Hello World".

That's it! Our plugin is done. Before you test the plugin, switch back to the plugin Manifest Editor and move over to the source page. When you were entering information via the manifest editor, this XML file was being generated behind the scenes for you. Make sure that it looks something like the one shown in listing 1.

The manifest editor pages are shown in the following table, along with a brief description of what the page does/XML tag means:

Page Contents
Welcome, Overview brief welcome page, overview of the plugin
Dependencies the <requires> tag - the plugins that are pre-requisites of this plugin
Runtime the <runtime> tag - the runtime libraries for the plugin
Extensions <extension> tags - the extension points contributed to
Extension Points <extension-point> tags - the extension points defined by this plugin itself (we have not used this)
Source the entire XML file (can be directly edited in this page)
The following listing shows the contents of the file plugin.xml.
<?xml version="1.0" encoding="UTF-8"?>
<plugin
   id="com.linuxforu.helloworld"
   name="Helloworld Plug-in"
   version="1.0.0"
   provider-name="LINUXFORU"
   class="com.linuxforu.helloworld.HelloworldPlugin">

   <runtime>
      <library name="helloworld.jar"/>
   </runtime>
   <requires>
      <import plugin="org.eclipse.core.resources"/>
      <import plugin="org.eclipse.ui"/>
   </requires>


   <extension
         point="org.eclipse.ui.actionSets">
      <actionSet
            label="HelloWorld Action Set"
            visible="true"
            id="com.linuxforu.helloworld.actionSet">
         <menu
               label="&HelloWorld Menu"
               id="HelloWorldMenu">
            <separator
                  name="HelloWorldGroup">
            </separator>
         </menu>
         <action
               label="Hello World"
               class="com.linuxforu.helloworld.HelloWorld"
               menubarPath="HelloWorldMenu/HelloWorldGroup"
               toolbarPath="HelloWorldGroup"
               id="com.linuxforu.helloworld.HelloWorldAction">
         </action>
      </actionSet>
   </extension>

</plugin>
Listing 1. The plugin.xml file

It is time to test our first plugin. Plugins cannot be run as standalone Java applications (the way we had run our first Java project in part one of this article). Instead, we need to create another instance of the Eclipse Workbench and test our plugin there. Eclipse allows us to do this by selecting Run->Run As->Run-time Workbench. Clicking on this menu item starts up another instance of Eclipse with our plug-in installed. After this second instance of Eclipse has finished loading, look out for our " HelloWorld Menu" in the main menu-bar. If you do not see this go to Window->Customize Perspective->Other and select "HelloWorld Action Set" (or simply click on Window->Reset Perspective ). You should now see a menu labeled " HelloWorld Menu" in the main menu-bar and a little red box in the main toolbar (since we had not defined an icon to use for the toolbar button). Clicking on either should show a message box having "Hello World" written in it. This is shown in figure 8.

fig8
Figure 8: Our "Hello World" plugin in action
5. Finally

Well, I will not present a list of all the classes, interfaces and functionalities that the Eclipse API has to offer, since that would be beyond the scope of this article (apart from the fact that it would easily take up a 1000 page book). It would also defeat the purpose of this article - showing you the power of Eclipse and getting you started in the world of Eclipse plugin development. This is why I have left you to figure out other aspects of plugin development such as packaging a plugin, creating " features" , the SWT/JFace toolkits and so on.

Though our "Hello World" plugin is not really spectacular or unique (it is in fact a common plugin in introductory tutorials such as this), it demonstrates the functionality Eclipse provides for integration into the IDE. There are several free, truly useful plugins out there - take a look at http://eclipse-plugins.info to see what I mean.

With this two-part bird's eye view of the Eclipse IDE, I hope I have been able to share with you the vision behind the goal of an open, extensible IDE that IBM initially had, and how Eclipse meets that goal. Eclipse has a very active developer community throughout the world (visit http://www.eclipse.org for more links). As Dave Thomson, Eclipse Project Program Director had put it, the capabilities of Eclipse are "limited only by your imagination"!


Return to part 1

Copyright (c) 2004 Rajorshi Biswas
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation. A copy of the license is included here.