× Home Tutorials Training Consulting Products Books Company Donate Contact us

NOW Hiring

Quick links


Migrating Eclipse 3.x components and applications to Eclipse 4. This tutorial gives an overview on how to migrate Eclipse components and application based on the Eclipse 3.x application model to Eclipse 4. This also includes using the compatibility layer in the Eclipse platform to run plug-ins based on the Eclipse 3.x API.

1. Running and migrating an Eclipse 3.x RCP application

1.1. Using the Eclipse 3.x API on top of an 4.x runtime

It is possible to run Eclipse 3.x API based plug-ins and RCP applications on top of the Eclipse 4.x platform. The Eclipse 3.x API has been reworked to use the 4.x underneath. This is sometimes called the compatibility mode.

The Eclipse platform team plans to support this 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 the 4.x API

The Eclipse 3.x API is effectively frozen, therefore it is recommended to migrate to the latest 4.x API to participate and benefit from further enhancements in the Eclipse platform.

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

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

2.1. Using the compatibility mode

The Eclipse platform team has re-implemented the existing 3.x API on top of the 4.x API. This re-implementation is sometimes called the compatibility mode. Therefore, you can run an Eclipse 3.x RCP application nearly unmodified on the Eclipse 4 runtime. In this case your application code calls the 3.x API. Call to the 3.x API use internally the 4.x API. Relevant extensions are converted into application model elements at runtime.

Compatibility mode of 3.x API and 4.x API

This approach requires that your Eclipse 3.x application is based on released 3.x API. If it uses 3.x internals, you might have to adjust your code as this code might have been changed.

If a 3.x RCP application runs on top of an Eclipse 4.x runtime, the platform translates the information contained in the plugin.xml based extension into model elements. For example the extension point information for views is read and part descriptors are generated based on this information.

In this scenario you can start to convert certain parts of your application into Eclipse 4.x API based parts. Afterwards you have migrated sufficient parts of your application you should switch over completely.

2.2. The e4 API and e4 runtime terminology

This tutorial uses the term e4 API as a synonym for Eclipse 4.x API and the term e4 runtime as a synonym for the Eclipse 4.x runtime term.

2.3. Running 3.x RCP applications on top of an e4 runtime

To migrate your Eclipse RCP application to e4 API you have to exchange the target platform to an Eclipse 4.x version.

The following features includes the necessary Eclipse platform plug-ins required for this.

  • org.eclipse.rcp

  • org.eclipse.emf.ecore

  • org.eclipse.emf.common

Add these features (or the included plug-ins) to your product configuration file. Afterwards the Eclipse 3.x API based RCP application starts on top of an e4 runtime without requiring any change in your code.

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.

2.4. Benefit of adjusting the runtime to Eclipse 4.x

Running your Eclipse 3.x RCP application on top of an e4 runtime allows you to start migrating components of your application to the e4 API.

It also ensures that you do not use 3.x internal API and that you benefit from the latest Eclipse platform developments, e.g., security updates.

3. Using e4 API in 3.x applications

3.1. Using e4 API based components in a 3.x applications

It is possible to define new e4 API based components and use them in an application which still uses the Eclipse 3.x API. This allows contributing e4 API based views, menus and toolbars to such an application. By using this approach, you can convert these 3.x components step by step to e4 API. How this can be done is shown in the following chapters.

3.2. Extending the Eclipse IDE

The Eclipse IDE uses the same approach as an Eclipse 3.x application on top of an e4 runtime. The e4 API based extensions described in this chapter can, of course, also be used to extend the Eclipse IDE.

4. Using the e4 API in Eclipse 3.x based applications

See http://www.vogella.com/tutorials/EclipsePlugin/article.html - Eclipse Plug-in Tutorial to learn how to use the Eclipse 4.x API in your Eclipse 3.x API based application.

5. Migrating to an e4 API application without 3.x API usage

5.1. Migrating an Eclipse 3.x application completely to the e4 API

If you want to migrate your Eclipse 3.x RCP application completely to the e4 API, you can’t directly reuse existing plugin.xml based user interface components, e.g., 3.x API based views or editors.

Migrating these components involves: * Converting existing user interface contributions via extension points to the application model. * Removing the usage of Singleton objects of the Eclipse platform, e.g. Platform or PlatformUI and use the dependency injection programming model.

5.2. Using 3.x components in e4 API based applications

Using Eclipse 3.x. API based components in e4 API based application is currently not officially supported. Customers which are willing to debug and fix potential issues can still use this approach. As the potential issues depend on the plug-ins which are re-used and as this approach is officially not supported, it is hard to predict which issues are encountered.

The difference to Using e4 API in 3.x applications is that in the scenario described in this chapter you have an application that uses only the e4 API, i.e., the compatibility layer is not present.

While not supported, some implementations still use this approach which various workarounds. See Example for using 3.x components in e4 API based applications for a small example project.

5.3. Reusing 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 e4 API in future releases. 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 IDE perspective switcher, the view switcher, the Progress view, the new project wizard are based on the Eclipse 3.x API and therefore cannot be used without modifications in an e4 API based application.

5.4. Existing replacements for 3.x components for e4 API based applications

The http://www.vogella.com/company/index.html - vogella GmbH provides an Open Source project for an e4 based perspective switcher. See the following URL for details: https://github.com/vogellacompany/e4-perspective-switcher - e4 API based perspective switcher

The Eclipse platform team provides also an Eclipse 4 based progress view. See the following URL for details: https://wiki.eclipse.org/Eclipse4/ProgressView

5.5. Example for using 3.x components in e4 API based applications

If you choose to try this approach despite the warning, you have to define a LegacyIDE.e4xmi file similar to the Eclipse IDE and add your model components to this file. This file can be found in the org.eclipse.ui.workbench plug-in.

Point to that file via the applicationXMI parameter in your org.eclipse.core.runtime.products extension.

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


As said before, this approach is not officially supported by the Eclipse platform team. If you use this approach, you may find hard to solve issues.

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.

7. About this website

8.1. vogella GmbH training and consulting support


The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2016 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.