Get Acquainted with Eclipse Plug-Ins
Discover Eclipse plug-ins. Begin by learning how to create one, archive it for installation, and debug it
by Kevin Jones

June 27, 2005

You often hear Eclipse described as a "platform" rather than as an IDE. What does this mean? Eclipse consists of two major parts: the core and the plug-ins. The job of the core part of Eclipse is to load the Eclipse runtime and then load all the plug-ins that are specified by the user, which means that nearly all of the functionality in Eclipse is provided in the form of plug-ins.

Why does this architecture make it a platform? You can remove all the plug-ins that make Eclipse an IDE and replace them with plug-ins for any other application you need, so Eclipse becomes the platform for other tools. Let's take a look at plug-in development within Eclipse.

In this and future columns we will develop a plug-in, and we will use Eclipse 3.1 to develop it. Subsequent code should work in Eclipse 3.0, but some of the dialogs shown in examples will be different. The reason for choosing 3.1 is that by the time you read this column, 3.1 will be shipping (or at least it will very nearly be shipping); certainly by the time we get a full, working plug-in 3.1 will be available.

Creating a plug-in in Eclipse is relatively straightforward, as Eclipse has a plug-in project wizard. The plug-in we'll create will be for a JDBC table viewer, which will let you run ad-hoc queries against any JDBC-supported database and display the results in tabular format. To create this plug-in project, open Eclipse, select File | New | Project, and then select Next in the Plug-in Project dialog. Enter the project name. Each plug-in has an identifier that you will enter shortly.

If you look in your <<ECLIPSE HOME>>/plugins directory you will see a number of directories with names like org.apache.ant_xxx and org.eclipse.core.boot_xxxx. The first part of these names, up to the "_," is the plug-in ID. By convention the name of the project should match the identifier of the plug-in, so we should give the project a reasonable name. For the viewer enter the project name com.develop.kevinj.jdbcviewer. I generally change the output folder name to "classes," but this is a personal preference.

Select Next to open the Plug-in Content dialog. This dialog allows you to provide information to describe the plug-in. You can accept the defaults, but you may want to change the values for Plug-in name and Plug-in provider. For the JDBC Viewer I chose the name Jdbcviewer Plug-in and Developmentor for the provider. You can change these names later if you get bored with them.

Keeping Tabs
The next dialog allows you to choose a template for the plug-in. The template simply lets the wizard generate some boilerplate code that most plug-ins will use. Choose Plug-In with a View and select Next. You can name the views and Java classes involved, as well as the category for the plug-in. For the JDBC Viewer the class name I chose was JDBC Viewer; the View name was JDBC Table View, and the category was Developmentor. Before selecting Next, uncheck the Add the View to the Resource Perspective check box. For the moment, turning off this setting will make our life simpler. Select Next and in the final dialog turn off all the options and select Finish. That's it: you have your first plug-in.

Let's take a tour of the plug-in before we install it. After the wizard finishes, Eclipse should now show you an Overview page, which is a tabbed pane that shows information about the plug-in. The tabs allow you to specify options for the plug-in.

For now, select the plugin.xml tab. This tab shows you the plug-in's manifest. Each plug-in has a manifest, which is an XML file. Eclipse reads all the manifests at start-up time. Each manifest describes the plug-in and provides naming, dependency, and extensibility information to Eclipse. You can see the manifest for our project in Listing 1. Notice that the manifest contains the details entered into the wizard, such as the class and package names, and the names used to identify the plug-in.

The wizard also generates two Java source code files: the Plug-in class and the View class. The plug-in has a couple of methods of interest. It has a default constructor and a static getDefault() method. Plug-ins are Singletons; when Eclipse loads it creates an instance of the plug-in, but whenever Eclipse wants a reference to that instance it calls getDefault() to retrieve it.

The plug-in class also has a start() and a stop() method. These methods are called when the plug-in is first loaded, and just before it is finally unloaded the base class implementations of these methods store and retrieve such items as the plug-in's preferences. The View class extends ViewPart, which, as you can guess, is an Eclipse base class used to display Eclipse views. The key method here is:

public void createPartControl(
  Composite parent) 

This method creates the control that will appear in the view. Notice that the default code is to create a table that is populated with images and labels, which in this case is a JFace table viewer. JFace is an extension to SWT that provides extra classes for you to work at a higher level than individual widgets—the TableViewer is an example. Viewers abstract away access to a control through a model that represents the data to be displayed. The images and labels are specified through two providers: ViewContentProvider and ViewLabelProvider. The code at this moment is fairly inconsequential, but as the plug-in progresses much work will be done here.

Zip Up
Now that we've built a plug-in, it would be nice to see it working. To do so we have to create a ZIP file that we can give to users to install, and you create it with another wizard! Select File | Export, choose Deployable Plug-Ins and Fragments, and then select Next. You can make various choices in the Export dialog (see Figure 1). First, ensure that your plug-in is selected. Then choose an archive for the plug-in, which is the ZIP file into which the plug-in code and data will be saved. Choose whether you want the source shipped with the plug-in, and then choose whether you want the plug-in packaged as a JAR file. This last option is new to Eclipse 3.1. In versions of Eclipse before 3.1, plug-ins were shipped as a zipped directory that had to be unzipped into the Eclipse plugins directory. In Eclipse 3.1 a JAR file containing the plug-in can be placed directly into the plugins directory.

Select Finish and Eclipse builds the ZIP file containing the plug-in. Once the ZIP file is created you can browse to the directory to which you saved the file and then unzip the plug-in into the Eclipse/plugins directory (note that the ZIP file will contain the directory structure of the plug-in, including the plugins directory). Once you've installed the plug-in by unzipping it you can view it. Select Window | Show View | Other, select your category, and then select your plug-in. You should see the view appearing at the bottom of the main Eclipse window (see Figure 2). Take a moment to savor your achievement—your first plug-in!

Debugging plug-ins could be interesting. A plug-in is part of Eclipse, so you will be using Eclipse to debug itself. To help with this task, when debugging a plug-in Eclipse will start another copy of itself. The second copy, sometimes called the Run-time workbench, will be the version of Eclipse that loads the plug-in. The Development workbench will host the debugger itself.

To launch the debugger select Run | Debug, or the Debug button on the toolbar to launch the Debug dialog. Right-click on Eclipse Application, and select New. Rename the configuration to something (your choice), and then select the Plug-Ins tab. Select Choose Plug-Ins and Fragments to Launch from the List, and then check that the JDBC Viewer plug-in is selected in the Workspace Plug-ins section and is not selected in the External Plug-Ins section. Select Apply (just in case) and then Debug.

You can set breakpoints in the Development workbench. For example, try setting breakpoints in the constructor in the Plugin class, and then load the plug-in in the Run-time workbench. You should see the breakpoint hit inside the Development workbench.

This introduction to plug-ins demonstrates how to create one. In upcoming columns I'll expand on this plug-in and explain how to use Eclipse features to create high-quality tools. Plug-in development can help you understand the Eclipse architecture, and I'll introduce other topics within Eclipse that are important, such as JFace. We may digress to cover such topics in detail, so the discussions may not be linear; however, the series hopefully will be a reasonably complete guide to plug-in development.

About the Author
Kevin Jones is a developer who researches and teaches Java programming and explores HTTP and XML. He lives in the U.K. and works for Developmentor, a training company based in the United States and Europe that specializes in technical training on Java and Microsoft platforms. Contact Kevin at .