ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


Eclipse Plugins Exposed, Part 1: A First Glimpse

by Emmanuel Proulx
02/09/2005 `

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:

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
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
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:

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)

Figure 3
Figure 3. Multi-page editor settings

"New Wizard" page (see Figure 4)

Figure 4
Figure 4. New wizard settings

Property Page (see Figure 5)

Figure 5
Figure 5. Property page settings

Eclipse generates a number of files at this point:

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.

Running and Debugging

You can test your plugin in a special sandbox called the runtime workbench. This way, even if the runtime workbench gets corrupted, Eclipse still works. This is available in the Overview page by clicking on either the link "Launch a runtime workbench" or "Launch a runtime workbench in Debug mode." The first time you run the runtime workbench, the folder eclipse\runtime-workbench-workspace is created. A new Eclipse instance is started. It is exactly like the normal Eclipse window, except now your plugin is available.

But first create a Java project from the menu File -> New -> Project and select Java Project. The name of the project should be Test. Figure 6 shows the runtime workbench with the wizard and editor we created.

Figure 6
Figure 6. Running the plugin

Now let's have a look at the Invokatron wizard. This is visible from the menu File -> New -> Other. Look at the category Invokatron Wizard. Select Invokatron Wizard and click Next. This wizard creates an empty Invokatron document. Select the Test project in the Container field and click Finish. A new Invokatron editor shows up. This editor has three pages: a text editor page, a Properties page (font selection), and a Preview page (sorted words, drawn with the selected font).

In the few next articles of this column, we'll add graphical widgets and Java code generation to our plugin.

Related Reading

Eclipse Cookbook
By Steve Holzner

Supporting Files

There are many places where you can specify what files are required for your plugin to compile and run. This makes things confusing for us Eclipse users. Let's try to clarify some of these issues.

Supporting files come in three categories:

  1. Classes and resources that form the plugin code itself. These are packaged together by the build process into one or more .jar files.
  2. Classes and resources that are needed to compile and run the plugin. These are to be included in the classpath, and we must specify that they'll be copied when exporting.
  3. Resources that are included with plugin, such as a readme.txt file. These aren't in the classpath.

The compilation environment can be set up in the Build page of the plugin editor. Again, this maps to the build.properties file. This page may be confusing at first, as it has four separate sections:

If your plugin uses a special library, make sure you add it to your project. Then add it to the Source Build and the Extra Classpath Entries.

Other important pages in the plugin editor are:

These are more advanced and will be covered in another article.

Exporting

Once the plugin is coded, and tested in the workbench, it is ready to be deployed to the "real" Eclipse environment. To do this, go to the Overview page and click on the Export Wizard link. The Export Options box allows you to choose among three types of deployments:

Once you click on Finish, the selected output is produced. If you elected to export as a directory structure, you'll have to restart Eclipse for the plugin to take effect.

Looking at the Examples and Source Code

The best source of information about writing Eclipse plugins is the set of many plugin examples that are provided with it. If I had to choose a single source of information to help me write Eclipse plugins, this would be it.

To download these plugins, simply go to the Eclipse downloads page and select the latest version of Eclipse. Then go to the middle of the page, where it says "Example Plug-ins," and download the .zip file (less than 2MB). Unzip this into the folder where Eclipse is located, such as c:\dev, for example. This will create many folders under the folders eclipse/features and eclipse/plugins. The source code for these examples is located in numerous .zip files in the folder C:\dev\eclipse\plugins, listed below.

Editor's Note: we have inserted line breaks in these paths to accommodate the page layout. Each should be all on one line, without spaces, in your work.

Example Code Location
SWT examples In the folder org.eclipse.sdk.examples.source_3.0.1\src...
  • Standalone
  • Address book
  • Clipboard
  • File Viewer
  • Hello World
  • Hover help
  • Image analyzer
  • Java syntax viewer
  • Text editor
...\org.eclipse.swt.examples_3.0.0\
    swtexamplessrc.zip
  • Workbench-integrated
  • Browser
...\org.eclipse.swt.examples.browser_3.0.0\
    browserexamplesrc.zip
  • Controls
...\org.eclipse.swt.examples.controls_3.0.0\
    controlssrc.zip
  • SWT Launcher
...\org.eclipse.swt.examples.launcher_3.0.0\
    launchersrc.zip
  • Layout
...\org.eclipse.swt.examples.layouts_3.0.0\
    layoutssrc.zip
  • Paint
...\org.eclipse.swt.examples.paint_3.0.0\
    paintsrc.zip
  • OLE
Special folder:
org.eclipse.sdk.examples.source.win32.win32.x86_3.0.1\
    src\org.eclipse.swt.examples.ole.win32_3.0.0\
    olewin32src.zip
Workbench Examples
  • Java editor
...\org.eclipse.ui.examples.javaeditor_3.0.0\
    javaeditorexamplesrc.zip
  • Template editor
...\org.eclipse.ui.examples.javaeditor_3.0.0\
    templateeditorexamplesrc.zip
  • Multi-page editor
...\org.eclipse.ui.examples.multipageeditor_2.1.0<\
    multipageeditorsrc.zip
  • Property sheet
...\org.eclipse.ui.examples.propertysheet_2.1.0\
    propertysheetsrc.zip
  • Readme tool
...\org.eclipse.ui.examples.readmetool_2.1.0\
    readmetoolsrc.zip
Help example Special folder
org.eclipse.help.examples.ex1_3.0.0
(There's no Java here; the HTML is in doc.zip)
Team examples
  • Repository providers
  • Synchronize participants
...\org.eclipse.team.examples.filesystem_3.0.0\
    teamfilesystemsrc.zip
File compare examples
  • Structure compare
...\org.eclipse.compare.examples_3.0.0\
    compareexamplessrc.zip
  • XML compare
...\org.eclipse.compare.examples.xml_3.0.0\
    xmlcompareexamplessrc.zip

There are also useful examples of GEF and Draw2D plugins. To get those, go to the GEF page and click on the latest version. Then locate "GEF Examples" in the middle of the Release Build page. Download the .zip file. At the time this was written, it was the file GEF-examples-3.0.1.zip (.5MB). Unzip this into the folder where Eclipse is located (for example, C:\dev). You will see two examples:

Example Code Location
  • Logic diagram example
org.eclipse.gef.examples.source_3.0.1\src\
    org.eclipse.gef.examples.logic_3.0.0\logicsrc.zip
  • Flow diagram example
org.eclipse.gef.examples.source_3.0.1\src\
    org.eclipse.gef.examples.flow_3.0.1\flowsrc.zip

Finding Information on Plugin Development

The first place to look is the examples the previous section. Secondly there's the help system, which is of good quality. This is in menu Help -> Help Content. The relevant categories are:

Conclusion

You now have enough information to create amazing, graphical plugins for Eclipse. With so many libraries at your service, only your imagination limits what you can do. The secret is to know what tools are at your disposal and to use the right tool for the right job. In the coming articles of this series, we will explore more areas of plugin development: menus, wizards, dialogs, GEF, Draw2D, etc.

Resources

The Web has many pages on Eclipse plugin development. Here are a few useful links:

Emmanuel Proulx is an expert in J2EE and Enterprise JavaBeans, and is a certified WebLogic Server 7.0 engineer. He works in the fields of telecommunications and web development.


Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.