Eclipse Plugins Exposed, Part 1: A First Glimpse

A while ago I was repairing my car. I had to remove a bolt. I opened my wrench kit and tried to find the right socket. None of them worked. The bolt was metric. I used the socket that was the closest to the ideal size. That was a bad idea; I stripped the bolt and I had to buy a special tool to remove it. The moral of the story: always use the right tool for the right job.

Eclipse is an extremely popular Java Integrated Development Environment (IDE) and a strong competitor to NetBeans/SunOne Studio, JBuilder, and IntelliJ IDEA. The Java programmer community is rapidly moving towards Eclipse, as it is free, open source, of excellent quality, and extremely customizable.

This new monthly column is about writing plugins in Eclipse. Who is this column for? Many Eclipse users simply use the IDE out of the box without needing customization. Many will be using plugins made by other people. That is not the target audience of this column. Some Eclipse users will want to customize it. Some will develop tools for their company's employees. Some will want to sell tools that connect to their products. Some will want to resell Eclipse under another name with these tools pre-installed. These people constitute the target audience. The prerequisites for starting to write Eclipse plugins are knowing how to use Eclipse and write Java programs, and having a good understanding of the Standard Widget Toolkit (SWT) and Swing.

In this first installment of the column, let's explore the Eclipse plugin environment.

Setting up Eclipse

If you use Eclipse 3 already, you can skip this paragraph. If you don't, you first want to download and install it. This is done easily by downloading the latest stable version from the Eclipse downloads page and then unzipping this file into a folder, such as c:\dev. At the time this was written, it is the file eclipse-SDK-3.0.1-win32.zip (85MB download). This will create the folder c:\dev\eclipse.

Notice under this folder there's a folder named plugins. A quick peek and you will see dozens of already-installed plugins. Why is that? Because the core of Eclipse is relatively small; almost everything is a plugin.

Architecture

Eclipse is made of a small core, with many plugins layered on top. Some plugins are nothing more than libraries that other plugins can use. These are the many tools at your disposal for the job. The base libraries used by all plugins are:

• The Standard Widget Toolkit (SWT): Graphical components used everywhere in Eclipse: buttons, images, cursors, labels, etc. Layout management classes. This library is usually meant to be used instead of Swing.
• JFace: Classes for menus and toolbars, dialogs, preferences, fonts, images, text files, and base classes for wizards.
• The Plugin Developer Environment (PDE): Classes to help with the data manipulation, extensions, build process, and wizards.
• The Java Developer Toolkit (JDT): Classes used to programmatically manipulate Java code.

Each of these has its specialty, and some can be used independently (although they may be internally dependent on others). For example, SWT doesn't have to be only used for plugins; it can be used to create non-Eclipse, standalone applications (for more on SWT, see SWT: A Developer's Notebook). There are other libraries not listed here as well.

Figure 1 shows the relationship between the different layers of Eclipse.

Figure 1. Layered libraries

Installing GEF and Draw2D Runtime

By default, the two graphical-oriented libraries, Graphical Editor Framework (GEF) and Draw2D are not installed. We will need those in future articles, so let's install them. To download GEF and Draw2D, go to GEF's home page and click on Download, build 3.0.1 or later, then save the file GEF-SDK-3.0.1.zip (5.5MB). Unzip it into the Eclipse folder. This is the folder that contains the plugins subfolder. Yes, these two libraries also come in the form of plugins themselves.

What do these libraries provide? They form the base upon which you can create graphical plugins. Graphical plugins usually show objects like boxes and labels, linked together by lines and arrows. The drawing of these objects and connectors is handled by Draw2D. But drawing is just half of what a graphical editor does. The other half--editor commands, toolbars, drag-and-drop functionality, printing, etc.--is done by GEF.

Configuring PDE Options

Once everything is installed, the next step is to customize or at least get familiar with the plugin configuration options. These show up in the menu Window -> Preferences, under the category Plug-in Development. Explore the dozens of configuration options that are specific to plugins. In particular, you may want to have a look at the Target Environment category. This allows you to choose your default operating system, windowing system, CPU architecture, and language.

Also interesting is the Plug-in Development perspective. (A perspective is a set of view preferences including panes, views, toolbars, etc., targeted at a certain task; think of it as a "mode" in Eclipse.) This is available by going to the menu Window -> Open perspective -> Other, and choosing "Plug-in Development" from the list. This is similar to the Java perspective, but has a Plug-in view that displays all detected plugins. Figure 2 illustrates how to activate the perspective, and shows the perspective itself.

Figure 2. Plug-in Development perspective

Creating a Simple Plugin

The easiest way to create a plugin is by using the templates provided in the File -> New -> Plug-in Project wizard. Then enter a project name, like "Invokatron." What's that you'll say? The plugin we're going to build is the Invokatron, a code-generation graphical editor for Java code. This article will clear the path for Invokatron, but obviously this ambitious project won't be finished until a later installment.

On the next page, keep the defaults except for the class name. Enter invokatron.InvokatronPlugin. In the Plug-in Content page, enter any information that you see fit. In the Templates page, select the checkbox to enable templates. There are many templates to choose from:

• Hello, World
• Simple XML editor
• Multi-page editor and a wizard
• Perspective extension
• Popup-menu
• Property page
• View
• Customized Plug-in with one or many of the previous items

The wizard has a detailed description of all these choices. My favorite template is the Custom one, as you can mix and match what elements you'll be using. Note that there's a Plug-in Development category as well, with more choices (Feature, Feature patch, Fragment, Plug-in, Update site). These are used for more advanced contraptions that we'll discuss another day.

For this example, use the Customized Plug-in template. Select Multi-page editor, New File Wizard, and Property Page. On the next pages, enter the following values:

"Multi-Page Editor" page (see Figure 3)

• Java package name: invokatron.editor
• Editor class name: InvokatronEditor
• Editor contributor class name: InvokatronEditorContributor
• Editor name: Invokatron Editor
• File extension: invokatron

Figure 3. Multi-page editor settings

"New Wizard" page (see Figure 4)

• Java package name: invokatron.wizard
• Wizard category ID: Invokatron
• Wizard category name: Invokatron Wizard
• Wizard class name: InvokatronWizard
• Wizard page class name: InvokatronWizardPage
• Wizard name: Invokatron Wizard
• File extension: invokatron
• Initial file name: MyClass.invokatron

Figure 4. New wizard settings

Property Page (see Figure 5)

• Java package name: invokatron.properties
• Property page class: InvokatronPropertyPage
• Property page name: Invokatron Properties
• Target class: org.eclipse.core.resources.IFile
• Name filter: *.*

Figure 5. Property page settings

Eclipse generates a number of files at this point:

• plugin.xml: The main file that describes the plugin. It contains information to help with the code generation, libraries, plugin dependencies, and extension points.
• build.properties: The file used for describing the build process. Mainly, this is used to specify the needed libraries.
• invokatron/*.java: Plugin classes.
• sample.gif: The icon that shows up next to the menu item.

The plugin.xml file shows up in a multi-page editor, together with build.properties. The first page, Overview, allows you to export and run the plugin in a test environment. To export means to complete the plugin by generating some code, and then to compile and package it for release. We'll get to that soon.

Upon study of the InvokatronPlugin class, you will notice that it doesn't do much. Where's the code that adds the menu item? The framework simply generates the needed code from the information in the plugin.xml file. Have a look at this file now. The last section contains a list of extensions, which are places in Eclipse where classes can be "plugged in."

The produced project is part of the sample code, which is available in the Resources section.