In-Depth

Extending Eclipse

• By Dwight Deugo
• March 31, 2003

In my October 2002 column, I talked about Eclipse, 'an IDE for anything and for nothing in particular.' Eclipse is a kind of universal tool platform. Its principal role is to provide tool providers with plug-in mechanisms and rules to create seamlessly integrated tools. Since then, I have had some e-mails asking me where to start to extend Eclipse, which is different from the question of how one uses Eclipse. The answer to that depends on what part of Eclipse you are using. For most, this is the Java or the Java Browsing perspectives, which provide several views and wizards to create Java apps. I'll begin to answer the first question by explaining how to add a menu button to Eclipse's Workbench toolbar. To add anything else, the same general process applies.

All extensions to Eclipse are done through plug-ins, which are integrated through extensions on extension points. You can see how many plug-ins Eclipse has by going to your installation directory for Eclipse and looking in the directory 'plugins.' Each of its sub-directories contains a plug-in that encapsulates functional extensions to the Eclipse Platform. Each plug-in has a name, ID, provider name, version, a list of other required plug-ins and a spec for its runtime. A plug-in can have any number of extension points that provide a connection into which other plug-ins can add their functionality, or a plug-in can provide extensions to existing extension points. We'll focus on how to extend an existing extension point.

Next, you need to create a project in Eclipse. Find the Navigator view intheResourcePerspectiveandselectFile->New->Project. The project creation wizard has a list of categories, each with a list of projects. Select 'plug-in development' in the left-hand list and 'plug-in project' on the right. Creating a plug-in project creates a project that understands Eclipse project resources and how to manage changes in them. In the plug-in project wizard, enter a project name for your plug-in and select 'custom plug-in wizard' when asked to select a plug-in code generator. In our example, we will use the plug-in ID carleton.examples.helloworld as the project name. The custom plug-in wizard will create a standard plug-in directory structure and provide for choosing additional content from a list of templates.

You also need to identify which extension point you are going to extend, and with what. A plug-in is described in an XML file called the plug-in manifest file. This file is called plugin.xml, and is contained in the plug-in sub-directory. Eclipse 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. The following is an example of a plugin.xml file, not including the (*#*) used for my reference:

<>
   id='carleton.examples.helloworld'
   name='Hello World Example'
   version='0.0.0'
   provider-name='Dwight Deugo'>

  
      (*1*)
  
  
      (*2*)
  

  
  point='org.eclipse.ui.actionSets'> (*3*)
      <>
   label='Hi There'
   description='The action set for the Hello World example'
   visible='true'
   id='carleton.examples.helloworld.HelloWorldActionSet'>
   <>
    label='Samples'
    id='carleton.examples.helloworld.HelloWorldMenu'>
           <>
    name='samples'>
          
        
   <>
    label='Hi There'
    icon='icons/ helloworld.gif' (*5*)
    tooltip='Press to see a message'
    (*4*) class='carleton.examples.helloworld.ui.HelloWorldAction'
            menubarPath='carleton.examples.helloworld.
           HelloWorldMenu/samples'
    toolbarPath='Normal'
          id='carleton.examples.helloworld.actions.
           HelloWorldAction'>
        
     
 

A manifest file first contains the ID, name, version and provider-name of the plug-in. Next (*1*) the name of the jar file(s) is identified to tell Eclipse where the code for the plug-in is. After that (*2*), any required plug-ins are identified. In our case, we need the org.eclipse.ui plug-in to access the menu support classes, since we are adding a Samples menu. Then we define an action set that identifies a menu labeled Samples containing one menu item, Hi There, and an associated class (*4*) carleton.examples.helloworld.ui.HelloWorldAction to execute a pre-defined method public void run(IAction proxyAction) when the menu item is selected.

How did I know to extend actionSets? I looked in the file C:\Program Files\eclipse\pluginsorg.eclipse.ui_2.1.0\doc\org_eclipse_ui_actionSets.html. All extension points are documented with what you will need to provide.

After creating the plugin.xml file, we just need to write the HelloWorldAction class and, as seen in the next column, create the icon file corresponding directory icons/helloworld.gif as defined in the plugin.xml file (*5*), and then build the jar file.

package carleton.examples.helloworld.ui;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.IWorkbenchWindowActionDelegate;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.jface.dialogs.MessageDialog;

public class HelloWorldAction implements IWorkbenchWindowActionDelegate {
IWorkbenchWindow activeWindow = null;

 public void run(IAction proxyAction) {
  Shell shell = activeWindow.getShell();
  MessageDialog.openInformation(
       shell,
       'Hello XML Web Services One',
       'Hello XML Web Services One');
 }

 public void selectionChanged(IAction proxyAction,
          ISelection selection) {
  // do nothing, action is not dependent on the selection
 }

 public void init(IWorkbenchWindow window) {
  activeWindow = window;
 }

 public void dispose() {
  //  nothing to do
 }
}

It's not much of an action, but it will help us to test that everything works. The defined response to selecting the menu item is to open a message dialog with the title and message set to 'Hello XML Web Services One.' You can test your extension by using Eclipse's built-in runtime Workbench launcher and, in this case, you don't need to worry about packaging everything up - a runtime plug-in directory will be constructed for you. The runtime Workbench launcher will start another Workbench complete with your extension. This is the best approach because any failures will show up in the original Workbench's debugger view, giving you the information you need to fix the problem. But, if all goes well, you can build your jar file and create your own plug-in subdirectory in Eclipse's 'plug-ins' directory. Then your changes will be part of Eclipse every time it starts up. First a button on a toolbar, next a new view. Stay tuned.