Support free tutorials

vogella training Training Books

Extending the Eclipse IDE - Plug-in development - Tutorial

Lars Vogel

Version 2.6


Eclipse Plug-ins tutorial

This article describes the creation and deployment of Eclipse plug-ins. The article is based on Eclipse 4.4 (Luna) and Java 1.6.

Table of Contents

1. Developing Eclipse software components
1.1. Extending the Eclipse IDE
1.2. Developing Eclipse plug-ins
2. Prerequisites
3. Download the Eclipse standard distribution
4. Exercise: Developing a simple plug-in
4.1. Create project
4.2. Start an Eclipse IDE with your plug-in
5. Local deployment of your plug-in
5.1. Options for installation
5.2. Installing your plug-in from your Eclipse IDE
5.3. Export plug-in and put into dropins folder
6. Create update site for your plug-in
6.1. Creating update sites
6.2. Create feature project
6.3. Create category definition
6.4. Create an update site
6.5. Install feature via the Eclipse update manager
7. Exercise: Deploy and install your plug-in via update site
8. Contribute a menu to existing Part
8.1. Overview
8.2. Contribute to the Package Explorer
8.3. Restrict the extension - Visible When
9. Resources and Marker
10. Tutorial: Create Markers for resources
11. Adapters
11.1. Overview
11.2. Example
12. Accessing the IEclipseContext
13. Eclipse Resources
14. Tools
14.1. Eclipse Yari
14.2. VisualVM
14.3. JVM Monitor
15. Support this website
15.1. Thank you
15.2. Questions and Discussion
16. Links and Literature
16.1. Source Code
16.2. Eclipse Resources
16.3. vogella Resources

1. Developing Eclipse software components

1.1. Extending the Eclipse IDE

One of the advantages of using the Eclipse IDE is that the IDE can be extended by every developer. The developer can contribute new software components (plug-ins) for the Eclipse IDE. He even can offer custom extension points which can be extended again by other developers.

1.2. Developing Eclipse plug-ins

A software component in Eclipse is called a plug-in. The Eclipse IDE allows the developer to extend the IDE functionality via plug-ins.

For example, you can create new menu entries and associated actions via plug-ins.

2. Prerequisites

This tutorial assumes that you are already familiar with standard Java development and with the Eclipse IDE.

3. Download the Eclipse standard distribution

The Eclipse IDE is provided in different flavors. While you can install the necessary tools in any Eclipse package, it is typically easier to download the Eclipse Standard edition which contains all necessary tools.

Browse to the Eclipse download site and download the Eclipse Standard package.

Download Eclipse Plug-in IDE

Extract the zip file in a folder of your selection.


Avoid having special characters or spaces in the path to your extract Eclipse.

4. Exercise: Developing a simple plug-in

4.1. Create project

In this exercise you create a plug-in which contributes a menu entry to the standard Eclipse menu.

Create a new plug-in project called com.vogella.plugin.first via FileNewProjectPlug-in Development Plug-in Project.

Enter the data as depicted in the following screenshots.

Select the Hello, World Command! template and press the Next button.

The last page of the wizard allows you to customize the values of the wizard. You can leave the default values and press the Finish button.

Eclipse may ask you if you want to switch to the plug-in development perspective. Answer Yes if you are prompted.

As result the following project is created.

4.2. Start an Eclipse IDE with your plug-in

Eclipse allows you to start a new Eclipse IDE with your plug-in included.

For this, select either your project folder or your MANIFEST.MF file, right-click on it and select Run-AsEclipse Application.

A new Eclipse workbench starts. This runtime Eclipse has your new menu entry included. If you select this menu entry, a message box will be displayed.

5. Local deployment of your plug-in

5.1. Options for installation

You have several options to make your plug-in available in your Eclipse IDE. You can:

  • Install your plug-in directly into your Eclipse installation from your Eclipse IDE. This option is useful for a quick installation test during development.

  • Export your plug-in and copy it into your Eclipse installation into the dropins folder. This option is useful for a simple distribution scenario, you only have to provide the exported plug-in to your users. On the other hand it is not very convenient for the end user as it requires manual file copying and provides no simple way to update the plug-in.

  • Create a update site and use the Eclipse update manager to install it from this site. This is a bit more complex to setup but is the most simple for the end user and provides the developer with a simple way to provide updates to all users.

5.2. Installing your plug-in from your Eclipse IDE

You can install your plug-in directly into your running Eclipse IDE.

The Eclipse plug-in export wizard has an option for this. Open the export wizard via FileExportPlug-in DevelopmentDeployable plug-ins and fragments.

Export plug-in into host IDE

In the export wizard dialog select in this case Install into host. Repository. This is depicted in the following screenshot.

Export plug-in into host IDE

5.3. Export plug-in and put into dropins folder

If you export your plug-in locally, you can put it into the Eclipse dropins folder of your Eclipse installation. After a restart of your Eclipse your plug-in should be available and ready for use.

Open again the export wizard via FileExportPlug-in DevelopmentDeployable plug-ins and fragments.

Select the plug-in you want to export and the folder to which this plug-in should get exported.

Export plug-in into host IDE

Press the Finish button. This creates a JAR file with the exported plug-in in the selected directory.

Copy this JAR file to the dropins directory in your Eclipse installation directory and restart your running Eclipse.

After this restart your new plug-in is available in your Eclipse installation and ready to be used.

6. Create update site for your plug-in

6.1. Creating update sites

You can also create an update site for your plug-in. An update site consists of static files which can be placed on a file server or a web server. Other users can install Eclipse plug-in from this update site.

This requires that you create a feature project for the plug-in. You can export this feature project and use the Eclipse update manager to install the feature (with the plug-in).

By default, the Eclipse update manager shows only features with a category. Therefore, you should always include a category for your exported feature to make it easy for the user to install your feature.

6.2. Create feature project

Create a feature project for your plug-in and add your plug-in to this feature. You create a feature project via FileNewOther...Plug-in DevelopmentFeature Project.

Create the feature project similar to the following screenshots.

Creating a feature project for the plug-in export

Creating a feature project for the plug-in export

6.3. Create category definition

In your feature project create via the menu entry FileNewOther...Plug-in developmentCategory Definition a new category definition.

Press the New Category button and create a category with a name which describes your functionality. Add your feature to this category.

6.4. Create an update site

You can create an update site for your feature in a local directory on your machine. For this, select FileExportDeployable features.

To use your category, switch to the Options tab and select the path to your category.xml file in the Categorize repository option.

6.5. Install feature via the Eclipse update manager

Use the Eclipse update manager via HelpInstall new software to install this new feature into your Eclipse IDE.

Use the update manager and point to your local directory and select and install your feature. In case you don't see your feature, try deselecting the Group items by category flag. In this case you have forgotten to use your category during the export.

Restart the Eclipse IDE after the installation. Afterwards, the plug-in is available in your Eclipse installation and can be used.

7. Exercise: Deploy and install your plug-in via update site

Create a feature project for your com.vogella.plugin.first plug-in and export it as Eclipse update site.

Use the Eclipse update manager to install the new feature into your Eclipse IDE.

8. Contribute a menu to existing Part

8.1. Overview

In this example we will add a new context menu entry to the Package Explorer part. The context menu is displayed if the user selects a file in the package explorer via a right mouse click. We will offer the option to create a HTML page from a Java source file.

To contribute to an existing menu or toolbar, you need to know the corresponding ID. This ID can be found via the Menu Spy. See Eclipse Source Code Guide for details.

8.2. Contribute to the Package Explorer

This tutorial uses Eclipse Commands. See Eclipse Commands Tutorial to learn how to work with commands.

Create a new plug-in project called de.vogella.plugin.htmlconverter. Do not use a template.

Open the META-INF/MANIFEST.MF file. Select the Dependencies tab and add the following dependencies to your plug-in.

  • org.eclipse.jdt.core

  • org.eclipse.core.runtime

  • org.eclipse.core.resources

  • org.eclipse.core.expressions

Open the Extensions tab in your editor, or if the tab is not visible, click the Extensions link on the Overview tab. Add a command with the ID de.vogella.plugin.htmlconverter.convert and the default handler de.vogella.plugin.htmlconverter.handler.ConvertHandler to your plug-in.

Add this command to the menu via the extension point org.eclipse.ui.menus and use popup:org.eclipse.jdt.ui.PackageExplorer as the locationURI. Set the label to Create HTML for this contribution.

The resulting file plugin.xml should look like the following.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
  <extension point="org.eclipse.ui.menus">
    <menuContribution locationURI="popup:org.eclipse.jdt.ui.PackageExplorer">
      <command commandId="de.vogella.plugin.htmlconverter.convert"
        label="Create HTML" style="push">
  <extension point="org.eclipse.ui.commands">
    <command defaultHandler="de.vogella.plugin.htmlconverter.handler.ConvertHandler"
      id="de.vogella.plugin.htmlconverter.convert" name="Convert">


Eclipse allows to save additional information for each file. You can use the IResource interface and the setPersistentProperty() and getPersistentProperty() methods. With these functions you can save Strings on files. We use these functions to save a directory for Java source files which were already exported via HTML.

Create the following ConvertHandler class.

package de.vogella.plugin.htmlconverter.handler;


import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.QualifiedName;
import org.eclipse.jdt.core.ICompilationUnit;
import org.eclipse.jdt.core.JavaModelException;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.swt.widgets.DirectoryDialog;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.ui.handlers.HandlerUtil;

public class ConvertHandler extends AbstractHandler {
  private QualifiedName path = new QualifiedName("html", "path");

  public Object execute(ExecutionEvent event) throws ExecutionException {
    Shell shell = HandlerUtil.getActiveShell(event);
    ISelection sel = HandlerUtil.getActiveMenuSelection(event);
    IStructuredSelection selection = (IStructuredSelection) sel;

    Object firstElement = selection.getFirstElement();
    if (firstElement instanceof ICompilationUnit) {
      createOutput(shell, firstElement);

    } else {
      MessageDialog.openInformation(shell, "Info",
          "Please select a Java source file");
    return null;

  private void createOutput(Shell shell, Object firstElement) {
    String directory;
    ICompilationUnit cu = (ICompilationUnit) firstElement;
    IResource res = cu.getResource();
    boolean newDirectory = true;
    directory = getPersistentProperty(res, path);

    if (directory != null && directory.length() > 0) {
      newDirectory = !(MessageDialog.openQuestion(shell, "Question",
          "Use the previous output directory?"));
    if (newDirectory) {
      DirectoryDialog fileDialog = new DirectoryDialog(shell);
      directory =;

    if (directory != null && directory.length() > 0) {
      setPersistentProperty(res, path, directory);
      write(directory, cu);

  protected String getPersistentProperty(IResource res, QualifiedName qn) {
    try {
      return res.getPersistentProperty(qn);
    } catch (CoreException e) {
      return "";

  protected void setPersistentProperty(IResource res, QualifiedName qn,
      String value) {
    try {
      res.setPersistentProperty(qn, value);
    } catch (CoreException e) {

  private void write(String dir, ICompilationUnit cu) {
    try {
      String test = cu.getCorrespondingResource().getName();
      // Need
      String[] name = test.split("\\.");
      String htmlFile = dir + "\\" + name[0] + ".html";
      FileWriter output = new FileWriter(htmlFile);
      BufferedWriter writer = new BufferedWriter(output);
    } catch (JavaModelException e) {
    } catch (IOException e) {


If you start this plug-in, you should be able to create HTML output from a Java source file.

8.3. Restrict the extension - Visible When

Currently our context menu is displayed all the time. We would like to show it only if a source file is selected. For this we will use a "visible-when" definition.

Add the org.eclipse.core.expressions plug-in as dependency to your plug-in. Select your menu contribution. Using the right mouse add the condition to the command that it should only be visible if a file is selected which represents a ICompilationUnit from the org.eclipse.jdt.core package.

For this exercise you use the predefined variable activeMenuSelection which contains the selection in the menu and iterate over it. If the selection can get adapted to ICompilationUnit, then the contribution will be visible.

This will result in the following plugin.xml.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
               label="Create HTML"


If you now start your plug-in, the menu entry should only be visible if at least one compilation unit has been selected.

9. Resources and Marker

Eclipse represents Resources like Projects, Files, Folders, Packages as IResource.

Marker represent additional information for resources, e.g., an error marker. Every marker can have attributes (key / value combination). Markers can be displayed in the standard view, e.g., the Task, Bookmark or the Problems view. To be displayed in these views, you have to use predefined attributes.

The following will demonstrate how to create marker for a selected resource.

10. Tutorial: Create Markers for resources

Create a plug-in project "de.vogella.plugin.markers". Add the dependency to org.eclipse.core.resources", "org.eclipse.jdt.core" and "org.eclipse.jdt.ui". Create the command "de.vogella.plugin.markers.AddMarker" with the default handler AddMarkerHandler in the de.vogella.plugin.markers.handler class and add this command to the menu.

Create the following code.

package de.vogella.plugin.markers.handler;

import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.resources.IMarker;
import org.eclipse.core.resources.IResource;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.ui.handlers.HandlerUtil;

public class AddMarker extends AbstractHandler {

  public Object execute(ExecutionEvent event) throws ExecutionException {
    IStructuredSelection selection = (IStructuredSelection) HandlerUtil
    if (selection == null) {
      return null;
    Object firstElement = selection.getFirstElement();
    if (firstElement instanceof IJavaProject) {
      IJavaProject type = (IJavaProject) firstElement;

    return null;

  private void writeMarkers(IJavaProject type) {
    try {
      IResource resource = type.getUnderlyingResource();
      IMarker marker = resource.createMarker(IMarker.TASK);
      marker.setAttribute(IMarker.MESSAGE, "This a a task");
      marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH);
    } catch (Exception e) {

If you run, you can create a marker in the TODO list if you select a Java project and click your menu entry.

11. Adapters

11.1. Overview

Adapters help to display information about objects in view without having to adjust the existing views. In this example we will create a small view which allows to select objects and use the properties view to display them.

Adapters are used on several places, for example, you can use an adapter to display your data in the outline view. See Outline View Example for an example on how to do this.

11.2. Example

We will simply use an adapter to show our data in the property view. Create a new plug-in project de.vogella.plugin.adapter. Use the Plug-in with a view template with the following settings.

Add the dependency org.eclipse.ui.views in tab dependencies of plugin.xml.

Create the following data model.

package de.vogella.plugin.adapter.model;

public class Todo {
  private String summary;
  private String description;
  public String getSummary() {
    return summary;
  public void setSummary(String summary) {
    this.summary = summary;
  public String getDescription() {
    return description;
  public void setDescription(String description) {
    this.description = description;


Change the code of to the following. After this change, you should be able to run your project, open your view and see your to-do items.

package de.vogella.plugin.adapter.views;

import org.eclipse.jface.viewers.ArrayContentProvider;
import org.eclipse.jface.viewers.ITableLabelProvider;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.part.ViewPart;

import de.vogella.plugin.adapter.model.Todo;

public class SampleView extends ViewPart {
  public static final String ID = "de.vogella.plugin.adapter.views.SampleView";

  private TableViewer viewer;

  class ViewLabelProvider extends LabelProvider implements
      ITableLabelProvider {
    public String getColumnText(Object obj, int index) {
      Todo todo = (Todo) obj;
      return todo.getSummary();

    public Image getColumnImage(Object obj, int index) {
      return getImage(obj);

    public Image getImage(Object obj) {
      return PlatformUI.getWorkbench().getSharedImages()

/** * This is a callback that will allow us to create the viewer and initialize * it. */
public void createPartControl(Composite parent) { viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL); viewer.setContentProvider(new ArrayContentProvider()); viewer.setLabelProvider(new ViewLabelProvider()); getSite().setSelectionProvider(viewer); viewer.setInput(getElements()); }
/** * Passing the focus request to the viewer's control. */
public void setFocus() { viewer.getControl().setFocus(); } // Build up a simple data model private Todo[] getElements() { Todo[] todos = new Todo[2]; Todo todo = new Todo(); todo.setSummary("First Todo"); todo.setDescription("A very good description"); todos[0] = todo; todo = new Todo(); todo.setSummary("Second Todo"); todo.setDescription("Second super description"); todos[1] = todo; return todos; } }

To displays its values in the property view, add the extension point org.eclipse.core.runtime.adapters to your project. The data of the extension point should be like the following.


Implement the factory and the new class TodoPropertySource which implements IPropertySource.

package de.vogella.plugin.adapter;

import org.eclipse.core.runtime.IAdapterFactory;

import de.vogella.plugin.adapter.model.Todo;

public class TodoAdapterFactory implements IAdapterFactory {

  public Object getAdapter(Object adaptableObject, Class adapterType) {
    if (adapterType== IPropertySource.class && adaptableObject instanceof Todo){
      return new TodoPropertySource((Todo) adaptableObject);
    return null;

  public Class[] getAdapterList() {
    return new Class[] { IPropertySource.class };


package de.vogella.plugin.adapter;


import de.vogella.plugin.adapter.model.Todo;

public class TodoPropertySource implements IPropertySource {

  private final Todo todo;

  public TodoPropertySource(Todo todo) {
    this.todo = todo;

  public boolean isPropertySet(Object id) {
    return false;

  public Object getEditableValue() {
    return this;

  public IPropertyDescriptor[] getPropertyDescriptors() {

    return new IPropertyDescriptor[] {
        new TextPropertyDescriptor("summary", "Summary"),
        new TextPropertyDescriptor("description", "Description") };

  public Object getPropertyValue(Object id) {
    if (id.equals("summary")) {
      return todo.getSummary();
    if (id.equals("description")) {
      return todo.getDescription();
    return null;

  public void resetPropertyValue(Object id) {


  public void setPropertyValue(Object id, Object value) {
    String s = (String) value;
    if (id.equals("summary")) {
    if (id.equals("description")) {


If you run your workbench and open your View via WindowsShowViewOthersSample CategorySample View and the property view, you should be able to view your data.

12. Accessing the IEclipseContext

The Eclipse IDE uses the IEclipseContext to store central information about the IDE. You can access this information also from the Eclipse 3.X API which is demonstrated with the following snippets.

For example to access the context from a view you can use the following snippet.

// get the context of a part
IEclipseContext parentContext = (IEclipseContext) site.getService(IEclipseContext.class);

// or access directly a value in the context based on its key
EModelService service = (EModelService) site.getService(EModelService.class); 

This snippet demonstrates the access via a handler.

// the following example assumes you are in a handler

// get context from active window
IEclipseContext ec = (IEclipseContext) HandlerUtil.getActiveWorkbenchWindow(event)

// get context from active part
IEclipseContext ec = (IEclipseContext) HandlerUtil.getActivePart(event).

13. Eclipse Resources

You can register IResourceChangeListener on resources in Eclipse. For example, if you have a project, you can add or remove a resource listener to or from it.

// add listener

// Remove listener

// Example resource listener
private IResourceChangeListener listener = new IResourceChangeListener() {
    public void resourceChanged(IResourceChangeEvent event) {

    if (event.getType() == IResourceChangeEvent.PRE_CLOSE || event.getType() == IResourceChangeEvent.PRE_DELETE) {
        if (event.getResource().equals(project)) {
          // Project deleted or closed
          // do something

      if (resource == null)

      IResourceDelta delta = event.getDelta().findMember(new Path(resource.getURI().toPlatformString(false)));
      if (delta == null) {

      if (delta.getKind() == IResourceDelta.REMOVED) {
        // Resource delete
        // do something


14. Tools

14.1. Eclipse Yari

It's a comprehensive tool suite to debug, spy, spider, inspect and navigate Eclipse based application GUIs (Workbench or RCP). YARI

14.2. VisualVM

VisualVM is a debugging tool which can be integrated into Eclipse. Eclipse launcher for VisualVM

14.3. JVM Monitor

JVM Monitor is a Java profiler integrated with Eclipse to monitor CPU, threads and memory usage of Java applications. JVM Monitor

15. Support this website

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

15.1. Thank you

Please consider a contribution if this article helped you. It will help to maintain our content and our Open Source activities.

15.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

16. Links and Literature

16.1. Source Code

Source Code of Examples

16.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system