Copyright © 2001 Object Technology International, Inc.
 Eclipse Corner Article

Your First Plug-in

Developing the Eclipse "Hello World" plug-in

Summary
The traditional Hello World program doesn't do that much, but it can be invaluable when exploring a new development environment. In this article we'll develop the Eclipse Hello World plug-in and show you how to integrate it with the Eclipse Workbench. After you read this article you should know how to use the Eclipse Java™ Development Tooling to create, run, and debug a simple plug-in that extends the Eclipse Platform. You'll see how to setup a project for your plug-in, edit the Java code, compile, and run or debug your plug-in in another launched copy of Eclipse. We'll be looking at plug-in manifest files, extensions, and extension points to see how plug-ins are described to Eclipse and how they are integrated with the Platform.

By Jim Amsden, OTI
Updated: November 14, 2001

Editor's note: This article describes Eclipse release 1.0. It has been superceded by the updated version of this article for Eclipse release 2.0.


The Eclipse Plug-in Development Environment (PDE) project provides a very nice environment for creating plug-ins and integrating them with the Eclipse Platform and/or other plug-ins. We're not proposing an alternative to PDE here. PDE is definitely the way to go. But sometimes its helpful to do things "by hand" in order to gain a more thorough understanding of how something works and how the pieces fit together. That's the approach we're going to take in this article. We'll develop a very simple plug-in implementing the Eclipse version of the classic Hello World sample. This will allow us to focus on the relationships between the various components of Eclipse and our plug-in without getting bogged down in the details of the example itself. We'll go raw as much as possible so we can see what's actually happening under the covers. Hopefully this will give you a better understanding of Eclipse, help you make better use of PDE, and give you some idea where to look when things don't go quite as planned.

The Problem

For the Eclipse Hello World program, let's start out with a simple design. We're going to add a button to the Workbench toolbar that when pressed, displays an information dialog containing the string "Hello World". Pressing OK dismisses the dialog. Nothing fancy, and certainly not anything that begins to exploit the full extensibility of Eclipse. But something we can easily use to get our feet wet. And it turns out that more complicated examples follow roughly the same pattern so we'll get a lot out of this very simple example.

So lets get started! I'll assume you've already downloaded the latest Eclipse code drop from eclipse.org, have it installed, and know how to start it up. If not, checkout the downloads page at the Eclipse site, and follow the instructions there.

Step 1: Getting ready to write Java code

Before we get started, we need to check some workbench preferences to make sure its configured properly for plug-in development. We'll be setting other properties later in the article, but for now, let's just set the default project layout and select the JRE we're going to use.

Setting the default project layout:  Edit the Java preferences by selecting the Window->Preferences menu item.  Expand the Java list item.  Click on the Java item and check the box corresponding to "Use 'src' and 'bin' folders as default in new Java projects".  If you do not alter this setting, all of the class files and source files will be placed in directories based at the root of the project.  This is fine for small scale development, but is not the structure you want when constructing bigger programs. 

Note:  The Hello World plug-in assumes that the project layout has been altered to use 'src' and 'bin' folders.  If you do not do this, you will get runtime errors when testing your plug-in.

Step 2: Creating the plug-in Project

Now we are ready to create a Java project for your plug-in. Go to the Navigator view, and select File->New->Project.  The project creation wizard has a list of categories each with a list of projects.  Select the Java category in the left hand list and Java project in the right. Creating a Java project vs. some other project creates a project which understands Java resources and how to manage changes in them. In the Java project wizard, enter a project name for your plug-in. Generally it is a good idea to use the plug-in name or id as the project name to make it easier to deploy you plug-in, and to make sure your plug-in name doesn't collide or get confused with some other plug-in. In our example, we'll use the plug-in id as the project name. Enter org.eclipse.examples.helloworld.

Step 3: Integrating with Eclipse

Before we can start writing our code, we need to determine how we're going to integrate with Eclipse. That's because all extensions to Eclipse are done through plug-ins, and plug-ins integrate with each other through extensions on extension points. Eclipse plug-ins typically provide extensions to the platform that support some additional capability or semantics. What is needed is a way for plug-ins to allow other plug-ins to change their behavior in a controlled manner.

Eclipse provides an extensibility mechanism that is scalable, avoids name collisions, doesn't require compilation of the whole product as a unit, and supports multiple versions of the same component at the same time. Eclipse does this by introducing the notion of a plug-in which encapsulates functional extensions to the Platform. Each plug-in has a name, id, provider name, version, a list of other required plug-ins, and a specification for its runtime. A plug-in can also have any number of extension points that provide a portal into which other plug-ins can add their functionality. This is how Eclipse enables other plug-ins to handle the variability supported by your plug-in. In order to integrate with other plug-ins, a plug-in provides extensions on these extension points (perhaps even its own extension points in order to provide some default behavior).

A plug-in is described in an XML file called the plug-in manifest file. This file is always called plugin.xml, and is always contained in the plug-in sub-directory. The Eclipse Platform reads these manifest files and uses the information to populate and/or update a registry of information that is used to configure the whole platform.

In our case, we want to use a button on the Workbench toolbar, so the extension point we'd use is org.eclipse.ui.actionSets. An action set is a strategy for the addition and removal of menu and toolbar items. This strategy is executed if the user explicitly adds the action set to the workbench. A user can add an action set to the workbench by invoking Perspective->Show View->Other.. to display the available actions. To activate an action set, you would navigate the action set categories, select the desired action set, and press OK. A perspective can also add an action set to the initial page layout by invoking IPageLayout.addActionSet(id). For details on the actionSets extension point, open the help perspective and select Platform Plug-in Developer Guide->Reference->Extension Points Reference->org.eclipse.ui.actionSets.

Step 4: Creating the plug-in Manifest File

Now that we know what we've got to do, lets tell Eclipse about our plug-in by creating the plug-in manifest file. Use Fille->New->Other... and select Simple->File to create a file called plugin.xml in the org.eclipse.examples.helloworld project.

Edit the plugin.xml file so that it looks like this:

<?xml version="1.0"?>
<plugin
	name="Eclipse Hello World Example"
	id="org.eclipse.examples.helloworld"
	version="0.0.0"
	provider-name="OTI">
	
    <requires>
        <import plugin="org.eclipse.ui"/>
    </requires>

    <runtime>
		<library name="helloworld.jar"/>
	</runtime>
	
	<extension point = "org.eclipse.ui.actionSets">
	  <actionSet
		id="org.eclipse.examples.helloworld.HelloWorldActionSet"
        label="Hello World"
		visible="true"
		description="The action set for the Eclipse Hello World example">
		<menu
			id="org.eclipse.examples.helloworld.HelloWorldMenu"
			label="Samples">
			<separator name="samples"/>
		</menu>
		<action id="org.eclipse.examples.helloworld.actions.HelloWorldAction"
			menubarPath="org.eclipse.examples.helloworld.HelloWorldMenu/samples"
			toolbarPath="Normal"			
			label="Hello World"
			tooltip="Press to see a message"
			icon="icons/helloworld.gif"
			class="org.eclipse.examples.helloworld.HelloWorldAction"/>
        </actionSet>
    </extension>
</plugin>

You can use Eclipse to edit this file using the default text editor. To do so, select Window->Preferences, expand the Workbench entry, and select File Editors. Add resource extension xml, and add the default text editor to its associations. Now when you attempt to open an editor on a .xml file, you'll do so with the default text editor. This will do just fine for our simple example. PDE makes this a LOT easier for complex plug-ins.

Now lets take a look at the manifest file and see exactly what's there. First we see that we're declaring a plugin. That's always the root element of a plug-in manifest file. The attributes of the plugin element give the plug-in name, id, version, and provider name. The id is the really interesting attribute. It specifies the identifier the platform uses to reference this plug-in. Since this name has to be unique for all installed plug-ins, we use Java package naming conventions to create a unique id. Anything will do, but this is a reasonable convention that should be followed. You'll see how these ids are used a little later when we have to reference another plug-in's extension point.

The requires element is where you specify all the other plug-ins your plug-in depends on. In our case, we're using the actionSets extension of plug-in org.eclipse.ui, so we specify that plug-in here.

The plug-in runtime element is how you tell the platform where to find the classes in your plug-in. Essentially, the requires and the runtime elements go together to specify the "classpath" for the plug-in. This approach allows each plug-in to have its own classpath independent of any other plug-in. Further, each plug-in has its own classloader which is used to load all classes defined by that plug-in (i.e., the classes found in its library declarations).

Now we're finally getting to the real integration! The extension element (in our plugin.xml file) describes an extension on the org.eclipse.ui.actionSets extension point. In our example, we're extending the actionSets extension-point of plug-in org.eclipse.ui. The id of our extension, how the platform refers to it, is org.eclipse.examples.helloworld.HelloWorldActionSet while the display name is "Hello World". If you look at in the documentation referenced above for the actionSets extension-point, you'll see that it can have a number of action elements which describe the actions in the set. Each action has a class attribute that specifies the class that implements the required interface, org.eclipse.ui.IWorkbenchWindowActionDelegate. This is what we have to implement for our extension. You'll also need to provide the helloworld.gif file to provide an icon for your action. Anything will due for testing. Create the icons folder in you plug-in folder. All plug-in file and folder pathnames are relative to the plug-in folder.

Don't get confused between an extension-point element and an extension element with a point attribute. The extension-point element defines a hook into the platform while the extension specifies and instance of using the hook. The point attribute is the id of the extension-point you're extending.

Step 5: Setting up the plug-in Project

Switch to the Java perspective if you're not already there with Perspective->Open->Other and select the Java perspective (or if Java is available on the menu, you may select it directly). Then select the packages tab to view the packages in your project. You should only see the packages you've specified in your Java build path so far, probably just the JRE_LIB entry for your rt.jar. Since your going to be using the IWorkbenchWindowActionDelegate interface, and other parts of the platform to develop our example, you need to include the referenced plug-in runtimes in your Java build path.

From the plug-in manifest file above, we can see that we require plug-in org.eclipse.ui. Referencing the plug-in in the requires element of our plug-in allows the platform to find classes we reference at runtime, but it doesn't help the compiler at development time. We need to get this plug-in's runtime in your project's build path so we can compile against imported classes and interfaces. To do this, select the project and view its properties. Select the Java Build Path entry, and click on the Libraries tab. Then click on the Add External JARs... button and browse to <your eclipse install directory>\plugins\org.eclipse.ui, the directory for the Eclipse UI plug-in.

See why we like to have the plug-in ids correspond to the plug-in directory names? It makes it a lot easier to find things. In directory org.eclipse.ui you'll see the workbench.jar file. Select this file to add it to your build path. The Eclipse UI plug-in depends on the Eclipse SWT plug-in, so we will need to add that one too: org.eclipse.swt contains swt.jar.  The platform automatically provides a special runtime support plug-in: org.eclipse.core.runtime - you should also add the runtime.jar from this plug-in to your build path.  If your plug-in depends on any other plug-ins, you'll need to add their jar files too.  PDE takes care of all of these things for you, but we'll save that for another article.

Now we're ready to write the code and compile it against workbench.jar and swt.jar. The workbench has the JDK set, or project has all the jar files in its build path we need, and the plug-in manifest file tells us what classes we have to start with.

Step 6: Implementing the IWorkbenchWindowActionDelegate Interface

In this example, our implementation of interface IWorkbenchWindowActionDelegate is org.eclipse.examples.helloworld.HelloWorldAction. Go take a look at the JavaDoc for the IWorkbenchWindowActionDelegate interface to see what methods we need to implement. The JavaDoc is available from the Help->Help Contents menu item. Select "Platform Plug-in Developer Guide" from the drop-down menu, expand to Reference->Workbench->org.eclipse.ui. In addition to using standard Java package naming conventions, you should consider including the plug-in id as part of your package name. While not required, it will help you keep your code organized.

To create the implementation class, we'll first create a package for our plug-in. Select the src folder of the org.eclipse.examples.helloworld project in the packages view, right click, and select New->Package. Create a package named org.eclipse.examples.helloworld.

Next, select the newly created package, right click, and select New->Class. (If you prefer using the tool bar, there are buttons to create a package and a class, among other Java-specific buttons.)  In the dialog that comes up, verify the package name is org.eclipse.examples.helloworld (it won't be if you didn't select it first), and fill in the class name HelloWorldAction as specified in the class attribute of the action element in our extension (see the manifest file plugin.xml). The superclass java.lang.Object is fine, but add the interface IWorkbenchWindowActionDelegate. Just click on the Add... button on the right and start typing IWorkbenchWindowActionDelegate. You'll see the selection list zero in as you type. Select IWorkbenchWindowActionDelegate and click OK. You'll see org.eclipse.ui.IWorkbenchWindowActionDelegate in the list of interfaces your class is going to implement. For convenience, click on the Inherited abstract methods check box so the new class wizard will create stubs for all the interface methods you need to implement. This will save you a lot of typing. If you don't see the class in the selection list that you expect, this is a good indication that your Java build path isn't including everything it needs. Check your build path in the project preferences and try again. 

Now we have our IWorkbenchWindowActionDelegate implementation class. From the interface we have four methods to implement, init and dispose from IWorkbenchWindowActionDelegate, and run and selectionChanged from IActionDelegate. Edit the class, and provide the method implementations given below.

package org.eclipse.examples.helloworld;


import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.IWorkbenchWindowActionDelegate;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.ui.PlatformUI;
import org.eclipse.swt.widgets.Shell;


/** HelloWorldAction is a simple example of using an
 * action set to extend the Eclipse Workbench with a menu 
 * and toolbar action that prints the "Hello World" message.
 */
public class HelloWorldAction implements IWorkbenchWindowActionDelegate {
	IWorkbenchWindow activeWindow = null;

	/** Run the action. Display the Hello World message
	 */		
	public void run(IAction proxyAction) {
		// the proxyAction has the UI information from the manifest file
		Shell shell = activeWindow.getShell();
		MessageDialog.openInformation(shell, "Hello World", "Hello World!");
	}

	/**
	 * @see IActionDelegate#selectionChanged(org.eclipse.jface.action.IAction, 
     *                                       org.eclipse.jface.viewers.ISelection)
	 */
	public void selectionChanged(IAction proxyAction, ISelection selection) {
		// do nothing, action is not dependent on the selection
	}
	
	/**
	 * @see IWorkbenchWindowActionDelegate#init(org.eclipse.ui.IWorkbenchWindow)
	 */
	public void init(IWorkbenchWindow window) {
		activeWindow = window;
	}
	
	/**
	 * @see IWorkbenchWindowActionDelegate#dispose()
	 */
	public void dispose() {
		//  nothing to do
	}
}

The code isn't too complicated, so I won't cover it in any more detail. Other articles will be addressing the specific Eclipse features we're using, but we want to focus on plug-ins and the end-to-end integration story rather than the code specifics in this article.

Step 7: Testing your plug-in

We're ready to test our plug-in! The best way to do this is to use two Eclipse workbenches, one for plug-in development, and another for testing and debug. Let's call them the development workbench and the testing workbench to avoid confusion. To do this we'll need to startup another workbench (the testing workbench) telling it where our plug-in is so it can load it when needed. PDE includes a launcher for this, but we can do it by hand with just a little more work. To make this a little easier to follow, let's assume you installed Eclipse on Windows® in c:\eclipse. Let's also assume that you started up your plug-in development workbench on workspace c:\workspace. This would be done by running Eclipse with:

c:\eclipse\eclipse -data c:\workspace

Now your org.eclipse.examples.helloworld project will be in c:\workspace\org.eclipse.examples.helloworld. If you installed Eclipse in some other directory, or used a different workspace, adjust your pathnames accordingly.

Next, we'll need a way to invoke our testing workbench. We don't want to use the same instance the Eclipse workbench for both development and test for a number of reasons:

Starting up Eclipse with Eclipse is really quite easy. Just create a Java project called say, "Eclipse Launcher". In the Java Build Path for this project, add the external jar: c:\eclipse\startup.jar. This file contains the Eclipse launcher main program that we'll need to startup our test workbench.

Startup.jar contains a class called org.eclipse.core.launcher.UIMain which is the main program for Eclipse UI applications. Next we have to set the program arguments for UIMain so it knows where everything is, including our plug-in. The details of launching Eclipse and loading classes will be covered in a future article, so we'll only cover what you need to get it working here. Go to the Package view, expand startup.jar and package org.eclipse.core.launcher, and edit the properties of UIMain. Set the program arguments to:

-data c:\tempWorkspace -dev bin -plugins c:\workspace\.plugin-path

-data c:\tempWorkspace is the fully qualified path name to a temporary platform workspace used for testing your plug-in. You can use any workspace you want as long as its not the same one you are using for your development workbench. Only one instance of Eclipse can be running on a platform workspace at a time because the platform meta-data cannot be shared.

-dev bin specifies that the bin directory of every plugin should be added to that plug-ins class path. This will help the platform find the classes you have just written and compiled.

-plugins c:\workspace\.plugin-path is the fully qualified pathname to a file that contains plug-in path URLs. These URLs tell the Eclipse boot loader where to find plug-ins. We'll be telling it to look in the Eclipse plugins directory, and your development workspace since its projects are plug-in sub-directories. For example: File c:\workspace\.plugin-path might contain:

platformPath = file:C:/eclipse/plugins/
pluginDevelopmentPath = file:C:/workspace/

The plug-in path file can be called anything you want, and can be part of the plug-in project for simplicity. This would allow everything associated with the plug-ing development to be managed, versioned, edited, etc. completely withing the platform (i,e. youdon't have to edit files in the file system directly). I didn't do this because my whole workspace just happens to be used to develop a number of plug-in examples, so its convenient to have a plug-in path for the workspace as a whole rather than separate ones for each plug-in.

We're ready to roll! Running the platform is easy. Just select UIMain, and press the run button on the Workbench toolbar. This will invoke your test workbench on the temporary workspace you specified above, and update the registry with information from your plug-in manifest file.

Now we can test the Hello World actions. You'll see the Hello World icon that was specified in the icon attribute of the action element in our plug-in manifest file on the Workbench toolbar (if you don't provide an icon, it will appear as a gray or red square). Move the cursor over it and you'll see the hover help you entered. Click and you see the message. Not quite as simple as printf("Hello World"); but it looks a lot nicer.  To turn off the Hello World action set (and remove the associated button), select Perspective->Customize and expand the Other category.  Now you can uncheck the Hello World item.

When you turn off the Hello World action set, you'll see that the icon is removed from the toolbar and you can no longer invoke the plug-in action.

Debugging your plug-in

Debugging your plug-in is just as easy. Just open your Java source and put a breakpoint where you would like to start debugging. Then debug your test workbench by selecting UIMain in the Eclipse Launcher project and pressing the debug button on the toolbar. The workbench will open a debug perspective page, and you'll see the Eclipse process running. Eclipse will come up, and be ready for you to invoke your plug-in. Again, enable the Hello World actions and click on the Hello World button. The test workbench will halt at your breakpoint and you'll see your code, breakpoint, and variables in the debug perspective in your development workbench. Go ahead and experiment with the debugger. Then press resume when ready, and up comes the message.

Note: If your debugging using Eclipse running on jdk1.2.2, there are a couple of additional DLLs you need. Files dt_socket.dll and jtwp.dll provide the jdk1.3 debug API on jdk1.2.2. These are available at http://java.sun.com/products/jpda/download.html.

Conclusion

We've seen the complete development of a plug-in extension to Eclipse from design to debug and test. We've done all the development, testing, and debugging using Eclipse itself and the Java Development Tooling. The Hello World example doesn't do much, and the complexity per function is pretty high. But more complex plug-ins follow the same pattern, and Eclipse provides a lot more than we've seen with this simple example. You should now have a pretty good idea how all the pieces fit together and what it means to develop and integrate a plug-in. Now its time to do something real. You'll want to use PDE for that, so look for that article coming soon.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.