Support free tutorials



vogella training Training Books

Extending the Eclipse IDE - Plug-in development - Tutorial

Lars Vogel

Version 2.7

08.03.2015

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. Eclipse plug-ins and applications
1.1. Eclipse software components - Plug-ins
1.2. Advantages of developing Eclipse plug-ins
1.3. What is the Eclipse Rich Client Platform (Eclipse RCP)?
2. Extending the Eclipse IDE
3. Prerequisites
3.1. Development
3.2. Model spy
4. Download the Eclipse SDK
5. Installation the Eclipse IDE
5.1. Install the Eclipse IDE
5.2. Solving exit code=13 while starting the Eclipse IDE
6. Adding e4 commands, menus and toolbars to 3.x based applications
6.1. Adding e4 menu entries
6.2. Adding e4 toolbar entries
7. Exercise: Add a e4 menu and toolbar to the Eclipse IDE
7.1. Target of this exercise
7.2. Creating a plug-in project
7.3. Starting an Eclipse IDE with your plug-in
7.4. Adding the plug-in dependencies for the e4 API
7.5. Creating the handler class
7.6. Creating a model contribution
7.7. Adding a toolbar contribution
7.8. Validating the presence of the menu and toolbar contribution
8. Local deployment of your plug-in
8.1. Options for installation
8.2. Installing your plug-in from your Eclipse IDE
8.3. Export plug-in and put into dropins folder
8.4. Deployment using an update site
9. Exercise: Create a feature for your plug-in
9.1. Create a feature project
9.2. Create a category definition
10. Exercise: Create feature for your plug-in
10.1. Create an update site
10.2. Install feature via the Eclipse update manager
10.3. Validate installation
11. Adding Eclipse 4.x parts and perspectives to 3.x based applications
11.1. Adding Eclipse 4.x parts to Eclipse 3.x applications
11.2. Supporting part descriptors in an Eclipse 4.5 IDE
11.3. Adding perspectives to the Eclipse IDE via model snippets
12. Exercise: Adding e4view based parts to 3.x based applications
12.1. Target
12.2. Using e4part and the org.eclipse.ui.views extension point
12.3. Add the view to a perspective extension
12.4. Validating
13. Exercise: Adding e4 part descriptors to 3.x based applications
13.1. Target
13.2. Adding a part descriptor
13.3. Validating
14. Adding model addons to 3.x based applications
15. Contribute a menu to existing Part
15.1. Overview
15.2. Contribute to the Package Explorer
15.3. Restrict the extension - Visible When
16. Accessing the IEclipseContext from 3.x API
17. Resources and Marker
18. Tutorial: Create Markers for resources
19. Adapters
19.1. What are adapters?
19.2. Example
20. Eclipse Resources
21. Early startup actions
22. About this website
23. Links and Literature
23.1. Links and Literature

1. Eclipse plug-ins and applications

1.1. Eclipse software components - Plug-ins

An Eclipse application consists of several Eclipse components. A software component in Eclipse is called a plug-in. The Eclipse platform allows the developer to extend Eclipse applications like the Eclipse IDE with additional functionalities via plug-ins.

Eclipse applications use a runtime based on a specification called OSGi. A software component in OSGi is called a bundle but a bundle is also always a plug-in. Both terms can be used interchangeably. A software component in Eclipse is called a plug-in.

For example a new plug-in can create new menu entries or toolbar entries.

1.2. Advantages of developing Eclipse plug-ins

The Eclipse platform forms the basis of the most successful Java IDE and therefore is very stable and broadly used. It uses native user interface components which are fast and reliable. It has a strong modular approach based on the industry standard module system for Java (OSGi) that allows developers to design component based systems.

Companies such as IBM, SAP and Google use the Eclipse framework as a basis for their products and therefore need to ensure that Eclipse is flexible, fast and continues to evolve.

The Eclipse platform also fosters a large community of individuals which provide support, documentation and extensions to the Eclipse framework. Tapping into this ecosystem allows you to find required resources and information.

1.3. What is the Eclipse Rich Client Platform (Eclipse RCP)?

The Eclipse IDE version 2.0 started as a modular IDE application. In 2004 Eclipse version 3.0 was released. Eclipse 3.0 supported reusing components of the Eclipse platform to build stand-alone applications based on the same technology as the Eclipse IDE.

At this point the term Eclipse RCP was coined. Eclipse RCP is short for Eclipse Rich Client Platform and indicates that the Eclipse platform is used as a basis to create feature-rich stand-alone applications.

The release of Eclipse in version 4.x simplified and unified the Eclipse programming model which is now based on state-of-the-art technologies, like dependency injection and declarative styling via CSS files.

Eclipse RCP applications benefit from the existing user interface and the internal framework, and can reuse existing plug-ins and features.

2. Extending the Eclipse IDE

The Eclipse IDE is basically an Eclipse RCP application to support development activities. Even core functionality of the Eclipse IDE is provided via a plug-in, for example the Java development or the C development tools are contributed as a set of plug-ins. Only if these plug-ins are present the Java or C development capabilities are available.

The Eclipse IDE functionality is heavily based on the concept of extensions and extension points. For example the Java Development Tools provide an extension point to register new code templates for the Java editor.

Via additional plug-ins you can contribute to an existing functionality, for example new menu entries, new toolbar entries or provide completely new functionality. But you can also create completely new programming environments.

3. Prerequisites

3.1. Development

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

3.2. Model spy

See Eclipse Model Spy to learn abou the model spy.

4. Download the Eclipse SDK

If you plan to build additional functionality upon the Eclipse platform, you should download the latest Eclipse release. Official releases are stable and a good foundation for building your additional functionality on top of it.

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 distribution which contains all necessary tools for plug-in development. Other packages adds more tools which are not required for Eclipse plug-in development.

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

Download Eclipse Plug-in IDE

5. Installation the Eclipse IDE

5.1. Install the Eclipse IDE

After you downloaded the file with the Eclipse distribution, unpack it to a local directory. Most operating systems can extract zip or tar.gz files in their file browser (e.g., Windows 7) with a right-click on the file and selecting "Extract all...".

Note

As a developer person you probably know how to extract a compressed file but if in doubt, search with Google for "How to extract a zip (or tar.gz on Linux and Mac OS) file on ...", replacing "..." with your operating system.

Extract Eclipse to a directory without spaces in its path and do not use a mapped network drive (Windows). Also avoid path names longer than 255 characters under Microsoft Windows. Installations of the Eclipse IDE sometimes have problems with such a setup.

After you extracted the compressed file you can start Eclipse, no additional installation procedure is required.

5.2. Solving exit code=13 while starting the Eclipse IDE

A common error is that the user downloads a 32 or a 64 bit version of Eclipse but tries to start it on a 64 or 32 JVM. Both versions must fit together as Eclipse contains native code. Unfortunately you can run a 32 bit JVM on a 64 bit operating system. Use java -version on the command line and if the output does not contain the word "Server" you are using the 32 bit version of Java and must use a 32 bit version of Eclipse.

6. Adding e4 commands, menus and toolbars to 3.x based applications

6.1. Adding e4 menu entries

Menus, handlers and commands can be contributed to an Eclipse application via model fragments. For this you only need to know the ID of the element to which you want to contribute. The ID of the Eclipse IDE and Eclipse 3.x RCP applications is hard coded to the org.eclipse.e4.legacy.ide.application value.

Tip

You can use the model spy from the e4 tools project to identify the ID of the element you want to contribute too. See Section 3.2, “Model spy”.

With the correct ID you can create model fragments that contribute to the corresponding application model element. This is demonstrated by the following screenshots.

Contributing to the Eclipse menu

The Parent-ID must be the ID of the menu your are contributing to.

Contributing to the Eclipse menu

Contributing to the Eclipse menu

The model fragment must be registered in the plugin.xml file via an extension to the org.eclipse.e4.workbench.model extension point, as demonstrated in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
   <extension
         id="id1"
         point="org.eclipse.e4.workbench.model">
      <fragment
            apply="notexists"
            uri="fragment.e4xmi">
      </fragment>
   </extension>

</plugin> 

6.2. Adding e4 toolbar entries

Similar to menus you can contribute toolbar contributions. This is demonstrated in Section 7.7, “Adding a toolbar contribution”.

7. Exercise: Add a e4 menu and toolbar to the Eclipse IDE

7.1. Target of this exercise

In this exercise you create a plug-in which contributes an e4 menu entry to a 3.x based application menu.

7.2. Creating a plug-in project

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

Enter the data as depicted in the following screenshots.

Press the Next button.

Press the Next button.

Select the Hello, World Command template and press the Next button. This template uses the 3.x API, which you convert to the e4 API in Section 7.6, “Creating a model contribution”.

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 a result the following project is created.

7.3. Starting an Eclipse IDE with your plug-in

Start a new Eclipse IDE instance and validate that your menu and toolbar entry is available. See ??? for more information on how to start an instance of the Eclipse IDE with your new plug-in.

A new Eclipse IDE starts, which has your new menu entry included. If you select this menu entry, a message box is displayed.

7.4. Adding the plug-in dependencies for the e4 API

Add a dependency to the org.eclipse.e4.core.di plug-in in the manifest file of the newly created plug-in.

7.5. Creating the handler class

Create the following class based on the generated handler class.

package com.vogella.plugin.first.handlers;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Shell;

public class SampleE4Handler {

  @Execute
  public void execute(Shell shell) {
    MessageDialog.openInformation(shell, "First", "Hello, e4 API world");
  }
} 

7.6. Creating a model contribution

Select NewOther...Eclipse 4ModelNew Model Fragment from the context menu of the plug-in project.

Create Model Fragment, step 1

Press the Finish button.

Create Model Fragment, step 2

Create three model fragment entries in your new file, all of them should be contributing to the org.eclipse.e4.legacy.ide.application element id.

Use the following screenshots to define the new contribution.

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

Create Model Fragment, step 2

7.7. Adding a toolbar contribution

Also add a toolbar contribution for the same command.

Create Model Fragment, step 2

Warning

When this document was written, the model editor had a bug. If you enter a Parent-ID to the toolbar contribution, that information is not persisted in the xmi code. Therefore, ensure that your settings are actually reflected in the fragment file. You can do this by closing the file and opening it again.

If you read this and the bug is still present, you have to enter the Parent-ID directly in the xmi. For this switch to the XMI tab of the editor and enter the parent ID directly. Use the org.eclipse.ui.main.toolbar value. The file is only saved, if you enter the information syntactically correct.

Create Model Fragment, step 2

Create Model Fragment, step 2

Add a toolbar and a handled tool item to your contribution.

Create Model Fragment, step 2

Create Model Fragment, step 2

7.8. Validating the presence of the menu and toolbar contribution

Start a new instance of the Eclipse IDE and validate that your menu and the toolbar are is contributed. If they are not visible in the window, check via the model spy for potential issues.

Create Model Fragment, step 2

8. Local deployment of your plug-in

8.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 an 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 simplest approach for the end user. It also allows to provide updates to all users.

8.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

8.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.

8.4. Deployment using an update site

You can 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 by providing them a link to the 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.

9. Exercise: Create a feature for your plug-in

9.1. Create a 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

9.2. Create a 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.

10. Exercise: Create feature for your plug-in

10.1. 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.

10.2. 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.

Note

If you put the resulting files on a webserver under a public accessible URL, your users could install your features from this URL.

10.3. Validate installation

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

11. Adding Eclipse 4.x parts and perspectives to 3.x based applications

11.1. Adding Eclipse 4.x parts to Eclipse 3.x applications

As a reminder, the term POJO (Plan Old Java Object) is used to describe a Java class without inheritance of a framework class.

As of the Eclipse 4.4 release you can also use a POJO in an extension for the org.eclipse.ui.views extension point. Use the e4view entry in the context menu of the extension to archive this. The resulting object is created via dependency injection.

For such a kind of view the existing toolbar and view extension point contributions do not work. To add for example a toolbar to your e4view, get the MToolbar injected into its implementation and construct the entries in your source code.

11.2. Supporting part descriptors in an Eclipse 4.5 IDE

The Eclipse 4.5 IDE release will support the contribution of part descriptor model elements via fragments or processors.

If you use the org.eclipse.e4.legacy.ide.application ID to contribute your part descriptors, the views can be opened via the WindowShow ViewOther... dialog or via the Quick Access. This requires that you add the View tag to such a part descriptor.

Eclipse 3.x API RCP applications running on top of a 4.5 or higher runtime can use the same approach.

11.3. Adding perspectives to the Eclipse IDE via model snippets

Your model fragment or processor can also contribute a perspective to an Eclipse 4.x IDE. For this add a perspective via a snippet. This snippet must again contribute to the application via the org.eclipse.e4.legacy.ide.application ID.

This approach can also be used to contribute a perspective to your Eclipse 3.x API based RCP application running on top of an Eclipse 4.x runtime but this depends on the specifics of your application.

12. Exercise: Adding e4view based parts to 3.x based applications

12.1. Target

In this exercise you create an Eclipse 3.x RCP application and add a POJO part to it based on the e4view element available to contribute an extension point based view.

12.2. Using e4part and the org.eclipse.ui.views extension point

Create an Eclipse 3.x RCP application based on the RCP application with a view template via FileNewOther...Plug-in Project. Call the project com.vogella.rcp.eclipse3x.e4view and select the options similar to the following screenshots.

Add org.eclipse.e4.ui.di as a dependency to the manifest of your new plug-in.

Create the following class.

package com.vogella.rcp.eclipse3x.e4view;

import javax.annotation.PostConstruct;

import org.eclipse.e4.ui.di.Focus;
import org.eclipse.jface.viewers.ArrayContentProvider;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;

public class ViewEclipse4x  {
  private TableViewer viewer;

  @PostConstruct
  public void createPartControl(Composite parent) {
    viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL
        | SWT.V_SCROLL);
    viewer.setContentProvider(ArrayContentProvider.getInstance());
    viewer.setLabelProvider(new LabelProvider());
    viewer.setInput(new String[] {"One", "Two", "Three"});
  }

  @Focus
  public void setFocus() {
    viewer.getControl().setFocus();
  }
} 

Afterwards add an e4view extension for the org.eclipse.ui.views extension point. For this use the Extensions tab of the plugin.xml editor.

Adding e4view entry

Eclipse 4.x based view

12.3. Add the view to a perspective extension

To be able to see the new view, add it to the existing perspective extension as depicted in the following screenshot.

Adding a view to an existing perspective

12.4. Validating

Start your Eclipse 3.x application and validate that the new part is displayed.

13. Exercise: Adding e4 part descriptors to 3.x based applications

13.1. Target

In this exercise you add a model based part contribution to an Eclipse 3.x RCP application.

13.2. Adding a part descriptor

Create a simple plug-in called com.vogella.plugin.partdescriptor.

Add the following dependencies to your manifest file.

  • org.eclipse.core.runtime

  • org.eclipse.jface

  • org.eclipse.e4.ui.model.workbench

  • org.eclipse.e4.ui.di

Create the following class

package com.vogella.plugin.partdescriptor;

import javax.annotation.PostConstruct;

import org.eclipse.e4.ui.di.Focus;
import org.eclipse.jface.viewers.ArrayContentProvider;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;

public class PartEclipse4x  {
  private TableViewer viewer;

  @PostConstruct
  public void createPartControl(Composite parent) {
    viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL
        | SWT.V_SCROLL);
    viewer.setContentProvider(ArrayContentProvider.getInstance());
    viewer.setLabelProvider(new LabelProvider());
    viewer.setInput(new String[] {"One", "Two", "Three"});
  }

  @Focus
  public void setFocus() {
    viewer.getControl().setFocus();
  }
} 

Add a new model fragment to this plug-in via FileNewOther...Eclipse 4ModelNew Model Fragment.

Adding a part descriptor to the Eclipse IDE

Adding a part descriptor to the Eclipse IDE

Adding a part descriptor to the Eclipse IDE

13.3. Validating

Start an instance of the Eclipse IDE and validate that you can open the parts via the Quick Access box (shortcut Ctrl+3).

Note

In Eclipse 4.4 the part descriptor can only be opened via the Quick Access box. In Eclipse 4.5 it is planned that it can also be opened via the WindowShow View menu entry.

14. Adding model addons to 3.x based applications

Similar to Section 6, “Adding e4 commands, menus and toolbars to 3.x based applications” you can add model add-ons to your Eclipse 3.x application. This allows you to register for the event service.

15. Contribute a menu to existing Part

15.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. To start the Menu Spy use ALT + Shift + F2 and click on the menu entry you are interested in.

15.2. Contribute to the Package Explorer

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"?>
<plugin>
  <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">
      </command>
    </menuContribution>
  </extension>
  <extension point="org.eclipse.ui.commands">
    <command defaultHandler="de.vogella.plugin.htmlconverter.handler.ConvertHandler"
      id="de.vogella.plugin.htmlconverter.convert" name="Convert">
    </command>
  </extension>

</plugin> 

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 java.io.BufferedWriter;
import java.io.FileWriter;
import java.io.IOException;

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");

  @Override
  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 = fileDialog.open();

    }
    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) {
      e.printStackTrace();
    }
  }

  private void write(String dir, ICompilationUnit cu) {
    try {
      cu.getCorrespondingResource().getName();
      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);
      writer.write("<html>");
      writer.write("<head>");
      writer.write("</head>");
      writer.write("<body>");
      writer.write("<pre>");
      writer.write(cu.getSource());
      writer.write("</pre>");
      writer.write("</body>");
      writer.write("</html>");
      writer.flush();
    } catch (JavaModelException e) {
    } catch (IOException e) {
      e.printStackTrace();
    }

  }
} 

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

15.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"?>
<plugin>
   <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">
            <visibleWhen
                  checkEnabled="false">
               <with
                     variable="activeMenuSelection">
                  <iterate
                        ifEmpty="false"
                        operator="or">
                     <adapt
                           type="org.eclipse.jdt.core.ICompilationUnit">
                     </adapt>
                  </iterate>
               </with>
            </visibleWhen>
         </command>
      </menuContribution>
   </extension>
   <extension
         point="org.eclipse.ui.commands">
      <command
            defaultHandler="de.vogella.plugin.htmlconverter.handler.Convert"
            id="de.vogella.plugin.htmlconverter.convert"
            name="Convert">
      </command>
   </extension>

</plugin> 

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

16. Accessing the IEclipseContext from 3.x API

The Eclipse 4.x IDE uses the IEclipseContext data structure to store central information about the IDE. You can access this information also via the Eclipse 3.x API. This approach is demonstrated with the following snippets. These code snippets assume that you are familiar with the 3.x API, if that is not the case you can skip this section.

For example, to access the context from an Eclipse 3.x API view, you can use the following snippet.

// get the context of a part
IEclipseContext partContext = 
  (IEclipseContext) getViewSite().getService(IEclipseContext.class);

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

This snippet demonstrates the access via an Eclipse 3.x API handler.

// the following example assumes you are in a handler

// get context from active window
IEclipseContext windowCtx = 
  (IEclipseContext) 
    HandlerUtil.getActiveWorkbenchWindow(event).
      getService(IEclipseContext.class);

// get context from active part
IEclipseContext ctx = 
  (IEclipseContext) HandlerUtil.getActivePart(event).
    getSite().getService(IEclipseContext.class); 

17. 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.

18. 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 {

  @Override
  public Object execute(ExecutionEvent event) throws ExecutionException {
    IStructuredSelection selection = (IStructuredSelection) HandlerUtil
        .getActiveSite(event).getSelectionProvider().getSelection();
    if (selection == null) {
      return null;
    }
    Object firstElement = selection.getFirstElement();
    if (firstElement instanceof IJavaProject) {
      IJavaProject type = (IJavaProject) firstElement;
      writeMarkers(type);

    }
    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) {
      e.printStackTrace();
    }
  }
} 

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

19. Adapters

19.1. What are adapters?

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.

19.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 SampleView.java 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.graphics.Image;
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()
          .getImage(ISharedImages.IMG_OBJ_ELEMENT);
    }
  }

  
/** * 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.

<extension
         point="org.eclipse.core.runtime.adapters">
      <factory
            adaptableType="de.vogella.plugin.adapter.model.Todo"
            class="de.vogella.plugin.adapter.TodoAdapterFactory">
         <adapter
               type="org.eclipse.ui.views.properties.IPropertySource">
         </adapter>
      </factory>
</extension> 

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

package de.vogella.plugin.adapter;

import org.eclipse.core.runtime.IAdapterFactory;
import org.eclipse.ui.views.properties.IPropertySource;

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

public class TodoAdapterFactory implements IAdapterFactory {

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

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

} 

package de.vogella.plugin.adapter;

import org.eclipse.ui.views.properties.IPropertyDescriptor;
import org.eclipse.ui.views.properties.IPropertySource;
import org.eclipse.ui.views.properties.TextPropertyDescriptor;

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

public class TodoPropertySource implements IPropertySource {

  private final Todo todo;

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


  @Override
  public boolean isPropertySet(Object id) {
    return false;
  }

  @Override
  public Object getEditableValue() {
    return this;
  }

  @Override
  public IPropertyDescriptor[] getPropertyDescriptors() {

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

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

  @Override
  public void resetPropertyValue(Object id) {

  }

  @Override
  public void setPropertyValue(Object id, Object value) {
    String s = (String) value;
    if (id.equals("summary")) {
      todo.setSummary(s);
    }
    if (id.equals("description")) {
      todo.setDescription(s);
    }
  }

} 

If you run your workbench and open your view via WindowsShowViewOthersSample CategorySample View and if you select a data element in your viewer you should see your data in the Properties view.

20. 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
project.getWorkspace().addResourceChangeListener(listener);

// Remove listener
project.getWorkspace().removeResourceChangeListener(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
        }
        return;
      }

      if (resource == null)
        return;

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

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

  }; 

21. Early startup actions

The Eclipse platform provides the org.eclipse.ui.startup extension point via the org.eclipse.ui plug-in.

Note

This extension point is not used for Eclipse 4 RCP applications, use a life cycle hook or model add-on to archive similar behavior.

To implement an extension to this extension point, select Add... on the Extensions tab of the plugin.xml editor and point to a class implementing the IStartup interface.

22. About this website

23. Links and Literature