Support free tutorials:











vogella training Training Books



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

Lars Vogel

Version 6.0

09.10.2013

Revision History
Revision 0.1 - 6.0 14.02.2009 - 17.07.2013 Lars
Vogel
created, 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.


Table of Contents

1. Why migrate an Eclipse 3.x RCP application?
1.1. Support for Eclipse 3.x API
1.2. Technical reasons for migrating to Eclipse 4 RCP
1.3. Future development is based on Eclipse 4
2. Running Eclipse 3.x plug-ins on top of Eclipse 4
2.1. Using the compatibility layer
2.2. How to use the compatibility layer
2.3. Value of using the compatibility layer
3. Using the Eclipse 4 programming model in 3.x applications
3.1. Wrapper classes for Eclipse 3.x
3.2. Validation
4. Using Eclipse 3.x components in Eclipse 4
4.1. Officially not supported
4.2. Workaround
5. Migration to Eclipse 4
5.1. Migration to Eclipse 4
5.2. Reuse of platform components
6. Learn more about Eclipse 4 RCP development
7. Support free vogella tutorials
7.1. Thank you
7.2. Questions and Discussion
8. Links and Literature
8.1. Source Code

Get the book Eclipse IDE book

1. Why migrate an Eclipse 3.x RCP application?

1.1. Support for Eclipse 3.x API

The Eclipse platform team has created a compatibility layer which maps the 3.x API to the 4.x API. This allows you to run Eclipse 3.x RCP applications and plug-ins unmodified on top of an Eclipse 4 runtime.

See Section 2.1, “Using the compatibility layer” for more information on this compatibility layer.

The Eclipse platform team has indicated that they plan to support this compatibility layer for an unlimited period of time. Therefore, if you have an existing Eclipse 3.x application, you do not have to migrate to the Eclipse 4.x API.

1.2. Technical reasons for migrating to Eclipse 4 RCP

If you use the compatibility layer, you have to use the existing Eclipse 3.x API within your application.

One important technical reason to migrate to the Eclipse 4.x API is that it provides a consistent and well-designed API. The concept of the application model and dependency injection makes your application code concise and flexible. Services and the renderer toolkit can be replaced, which adds more flexibility to your implementation.

The event service and the extensible Eclipse context hierarchy provide very powerful ways to communicate within your application.

1.3. Future development is based on Eclipse 4

The Eclipse 3.x API is effectively frozen. In addition to the technical advantages the focus of development is concentrated on the Eclipse 4.x API. New features will only be available for Eclipse 4 implementations.

Therefore, if you want to participate in future enhancements of the Eclipse platform, you should migrate to the Eclipse 4.x API.

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

2.1. Using the compatibility layer

You can run your Eclipse 3.x RCP application unmodified on the Eclipse 4 runtime. This only requires that your Eclipse 3.x application does only use official released API. If it uses internal API, you have to rewrite this part or your application.

The compatibility layer converts the relevant extension point information into the application model at runtime and maps the released 3.x API into 4.x API calls.

New programming concepts of Eclipse 4 such as dependency injection for views (parts using Eclipse 3.x API) do not work (out of the box) with the compatibility layer.

2.2. How to use the compatibility layer

The easiest way to migrate your Eclipse RCP application to Eclipse 4.3 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. 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.

Afterwards you can start your Eclipse 3.x application on top of Eclipse 4 without any change in your coding.

Note

This assumes that your Eclipse 3.x application does not use any 3.x internal API. Eclipse marks internal packages with the x-internal flag in the MANIFEST.MF file.

If your 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

2.3. Value of using the compatibility layer

Migrating your Eclipse 3.x plug-in and RCP application ensures that you do not use internal API. Using the compatibility layer currently requires that you use the 3.x API.

3. Using the Eclipse 4 programming model in 3.x applications

3.1. Wrapper classes for Eclipse 3.x

The e4 tools project provides a component which allows you to migrate your existing Eclipse 3.x views and editors to POJOs and to use dependency injection as a programming model for these components. The project provides wrapper classes which can wrap POJOs. The wrapper class is used in the extension points and performs the dependency injection on the POJO class.

This tooling is provided by the org.eclipse.e4.tools.compat plug-in. You can install the Eclipse 3.x bridge via the e4 tools update site.

Installing the bridge

To use the functionality in your Eclipse 3.x application add the following plug-ins to your MANIFEST.MF file.

  • org.eclipse.e4.tools.compat

  • org.eclipse.e4.core.contexts

You can now create your Java implementation for a view similar to the implementation of an Eclipse 4.3 part.

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;
 
    @PostConstruct
    public void createPartControl(Composite parent) {
        viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL
                | SWT.V_SCROLL);
        viewer.setContentProvider(ArrayContentProvider.getInstance());
        TableViewerColumn column = new TableViewerColumn(viewer, SWT.NONE);
        column.getColumn().setWidth(100);
        column.setLabelProvider(new ColumnLabelProvider(){
            @Override
            public String getText(Object element) {
                return element.toString();
            }
        });
         
        // provide the input to the ContentProvider
        viewer.setInput(new String[] { "One", "Two", "Three" });
    }
 
    @Focus
    public void setFocus() {
        viewer.getControl().setFocus();
    }
} 

In your plugin.xml file you use an concrete implementation of the DIViewPart class from the org.eclipse.e4.tools.compat plug-in to define your views. Such an implementation is demonstrated in the following listing.

package example.compat;
 
import org.eclipse.e4.tools.compat.parts.DIViewPart;
 
import example.compat.parts.View;
 
public class ViewWrapper extends DIViewPart<View> {
 
    public ViewWrapper() {
        super(Part.class);
    }
 
} 

3.2. Validation

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

Tip

It is planned for Eclipse 4.4 that you can also use dependency injection and POJO for extension based contributions. See Bug report for supporting POJOs in plugin.xml based extensions points for Views, Editors, Handlers for details.

4. Using Eclipse 3.x components in Eclipse 4

4.1. Officially not supported

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

Eclipse 4.4 plans to enhance the support for mixing 3.x and 4.x API components. See Bug report for Eclipse IDE not being expendable via fragments or processors.

4.2. Workaround

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 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:

https://github.com/fredrikattebrant/Simple-4x-RCP-app 

5. Migration to Eclipse 4

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

Migrating such components would involve:

  • Converting existing user interface contributions via extension points to the application model.

  • Removing the usage of Singleton objects from the Eclipse platform, e.g. Platform or PlatformUI and use the dependency injection programming model.

5.2. Reuse of platform components

Most Eclipse IDE components are still based on the Eclipse 3.x API. The Eclipse platform plans to migrate more and more existing components to the Eclipse 4.x API over time. For customers this means that certain components which could be reused in Eclipse 3.x RCP application are not available by default.

Currently most components, for example, the perspective switcher, the view switcher, the Progress view, the new project wizard is based on the Eclipse 3.x API and therefore cannot be used directly in an Eclipse 4 RCP application.

6. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

7. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

7.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

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

8. Links and Literature

8.1. Source Code

Source Code of Examples

Eclipse E4 - Wiki

Blog post about using Eclipse 3.x components in Eclipse4

Eclipse RCP

Eclipse EMF

Dependency Injection