Migrating Eclipse 3.x plug-ins and RCP applications to Eclipse 4 - Tutorial

Building Eclipse RCP applications based on Eclipse 4

Lars Vogel

Version 5.8


Revision History
Revision 0.1 14.02.2009 Lars
Revision 0.2 - 5.8 16.02.2009 - 10.04.2012 Lars
bug fixes and enhancements

Eclipse 4 and the Compatibility Layer

This tutorial gives an overview on how to use the Compatibility Layer in Eclipse 4 to run plug-ins based on the Eclipse 3.x API.

1. Compatibility Layer

1.1. Running Eclipse 3.x plug-ins on top of Eclipse 4

Eclipse 4 allows you to run Eclipse 3.x RCP applications and Eclipse 3.x plug-ins. Your Eclipse RCP application should have an existing product configuration file for the migration.

The compatibility layer supports the migration of existing Eclipse 3.x plug-ins and applications to Eclipse 4 and to start evaluating advantages of Eclipse 4, e.g. the application model and CSS based styling.

The compatibility layer converts the relevant extension point information into the application model. In the org.eclipse.platform plug-in you find the LegacyIDE.e4xmi file which defines the initial window and some model Addons.

If Eclipse is started in the compatibility mode, this file is read via the E4Workbench class. This class is part of the org.eclipse.e4.workbench.ui.internal package. E4Workbench will then convert the relevant extension points into elements of the application model.

New programming concepts of Eclipse 4 such as dependency injection for Views do not work (out of the box) with the compatibility layer.

1.2. Using features

The easiest way to migrate your Eclipse RCP application to Eclipse 4.2 is to have a feature based product configuration file which includes the standard org.eclipse.rcp feature.

In Eclipse 4 this feature has been upgraded to include most of the necessary additional plug-ins for the compatibility mode. If your product is based on this feature you can directly start your Eclipse 3.x product and it will work.

You only need to add two additional features to your product configuration file, the org.eclipse.emf.ecore and the org.eclipse.emf.common feature.

1.3. Using plug-ins

If you product configuration file is based on plug-ins you have to add the following plug-ins to it:

  • org.eclipse.e4.ui.workbench.addons.swt

  • org.eclipse.equinox.ds

  • org.eclipse.equinox.event

  • org.eclipse.equinox.util

  • org.eclipse.platform

  • org.eclipse.ui.forms

  • org.eclipse.ui.intro

After this change you should be able to start your existing application based on Eclipse 4.

2. Wrapping your Eclipse 4 components for Eclipse 3.x

To migrate your Views and Editors to Eclipse 4 you can use the org.eclipse.e4.tools.compat plug-in from the e4 tooling projects

To use this bridge in Eclipse 4.2 or Eclipse 3.8 just install the org.eclipse.e4.tools.e3x.bridge feature into your Eclipse IDE.

Afterwards add the following plug-ins to your MANIFEST.MF

  • org.eclipse.e4.tools.compat

  • org.eclipse.e4.core.contexts

You can now develop your Parts as Pojos:

          package example.compat.parts;

import javax.annotation.PostConstruct;

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

public class Part {
    public static final String ID = "example.compat.view";

    private TableViewer viewer;

    public void createPartControl(Composite parent) {
        viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL
                | SWT.V_SCROLL);
        TableViewerColumn column = new TableViewerColumn(viewer, SWT.NONE);
        column.setLabelProvider(new ColumnLabelProvider(){
            public String getText(Object element) {
                return element.toString();

        // Provide the input to the ContentProvider
        viewer.setInput(new String[] { "One", "Two", "Three" });

    public void setFocus() {

In your plugin.xml you use ViewWrapper to define your Views.

          package example.compat;

import org.eclipse.e4.tools.compat.parts.DIViewPart;

import example.compat.parts.View;

public class ViewWrapper extends DIViewPart<View> {

    public ViewWrapper() {


This way you can use the dependency injection already in your Eclipse 3.x plugin, have a better possibility to test your user interface components in plain JUnit test (they are just POJO) and get ready for for a full Eclipse 4 migration.

3. Mixing Eclipse 4 and Eclipse 3.x

Mixing Eclipse 4 and Eclipse 3.x. components is currently not officially supported in the Eclipse 4.2 release.

You can however define your own LegacyIDE.e4xmi file and add your model components to this file. Via the applicationXMI parameter in your org.eclipse.core.runtime.products extension point you point to that file.

For this approach you have to copy the standard LegacyIDE.e4xmi file and add your model components to it. This file can be found in the org.eclipse.ui.workbench plug-in.

A code example for this approach can be found under the following URL:


While this approach seems to work, it is currently not officially supported in the Eclipse 4.2 release.

4. Migration to Eclipse 4

If you want to migrate your Eclipse 3.x RCP application to the Eclipse 4 programming model, you can't directly reuse existing plugin.xml based user interface components, e.g. Views or Editors based on the definition in plugin.xml .

Components based on the plugin.xml file must be adjusted to avoid inheritance of Eclipse classes and to use the programming model based on @Inject . They also must be contributed to the application model.

Components which are not directly based on the plugin.xml file must be adjusted if they use Eclipse 3.x singletons, as for example Platform or PlatformUI , to access Eclipse API.

5. Future plans for migration

The Eclipse 4 team intend to provide support for such mixed mode hybrid applications in future Eclipse releases.

6. Questions and Discussion

Before posting questions, please see the vogella FAQ. If you have questions or find an error in this article please use the www.vogella.com Google Group. I have created a short list how to create good questions which might also help you.

About the Authors