Migrating from Eclipse 3.x to Eclipse 4.x - Or: Which Platform to use?

The release of Eclipse 4.x (e4) raised the question of how to migrate existing Eclipse 3.x applications to Eclipse 4.x (e4). In this tutorial I will review the options for developing Eclipse plugins and applications with the new platform. Looking forward to your comments and additions. Previous parts (part 1-7 ) of this tutorial are available now as a downloadable PDF.

In the previous parts of this tutorial, we introduced the Eclipse 4 Application Platform including its features such as the Application Model, Dependency Injection, and the available services. All of those features provide great support for developing applications and in general Eclipse 4 does many things better than Eclipse 3.x. However, that does not mean that Eclipse 3.x, more precisely its API is decrepit. There are tons of existing plugins out there based on this API and they are still actively developed. The implementation of Eclipse 4 does not mean, that the 3.x API is no longer useful. This is especially true in the tools area, many of them, e.g. the java development tools, are and will probably stay on the 3.x API for a long time. Therefore, before you start an application, you will have to deal with the question of which API it is based. In the following sections, I will describe the most important options in detail.

Option 0 - Eclipse 3.x

This would mean you use an old version of the Eclipse platform (highest one is 3.8). Those versions do not contain any components from Eclipse 4. This option is only valid for existing tools, which are not actively developed anymore. There are no updates nor service releases for the 3.x stream anymore. Sooner or later, you will need to update to option 1, e.g. if the contained SWT version no longer supports your windowing system or if you need other fixes. The only alternative is to get Long Term Support for your Eclipse 3.x version. New projects should not use 3.x. We will not describe this option in more detail.

Option 1 - 3.x Compatibility Layer (3.x API) on Eclipse 4.x

This is the option used by most tools and applications which existed before Eclipse 4. The compatibility layer enables 3.x applications to run on the new Eclipse 4 platform without any code adaptation. Most existing projects use this option as a first step towards Eclipse 4. Besides the easy migration, you can still use all existing components and frameworks, even if they are not migrated to e4. Finally, your application stays backwards compatible, meaning it can still be run on 3.x

To ease migration, the compatibility layer provides the 3.x workbench API and translates all calls into the programming model of e4. In the background, it transparently creates an Application Model. For example, if the 3.x application registers a 3.x view using an extension point, the compatibility layer will create a Part for this view. One important criteria for existing applications to work well on the compatibility layer is that they should not use any internal workbench API. Aside from this, there should be no source code changes required. However, you will probably need to adapt the product or run a configuration of the application. Eclipse 4 needs additional plugins to work, and as there are no direct dependencies, this will not be automatically discovered. These are the plugins you will need to add:

org.eclipse.equinox.ds : The OSGi plugin enabling declarative services

org.eclipse.equinox.event: The OSGi event broker

org.eclipse.equinox.util: Required by the first two

org.eclipse.e4.ui.workbench.addons.swt: Enables features such as minimizing and maximizing parts.

We have mentioned before, that “there should be no source code changes required”. However, whether this is true, depends on the project and more precisely on the usage of the workbench API. In general, if you only rely on official API, your code should compile well and the basic functionality should generally work. However, there are things in Eclipse 4 which behave a little different than in Eclipse 3.x. The reason is obviously the reimplementation of all internals. These differences could be slight changes in the look and feel or the behavior, which implicitly worked on 3.x, but is not really guaranteed in the API. The only way to find out about those issues is to try to test an existing application based on the compatibility layer. Sometimes it is required to fix some remaining minor issues on the Eclipse 4 platform to fully support your application. It is impossible to estimate the required effort for migrating an existing application on the compatibility layer, without evaluating it. Some applications run without any adaptations, for others you need a few days or even weeks of work. For supporting your migration project, we offer developer support and sponsored development as professional services.

An obvious disadvantage of using the compatibility layer is that you won’t benefit from the new concepts, such as the application model, dependency injection and annotations provided by e4. Although, some other improvements will still work, such as CSS styling.

Option 2 - 3.x Compatibility Layer on Eclipse 4.x with some e4 components

There can be good reasons to keep an application on the compatibility layer, meaning the 3.x API. This is especially true for existing applications, as it requires almost no migration effort. Additionally, the Eclipse IDE itself is still based on the 3.x API, so if you extend it, you automatically need to use the compatibility layer.

However, it would still be useful to use some of the benefits of the Eclipse 4 programming model, especially for newly developed components. Additionally, it would be nice, if components could be developed in a way such that they can be used in a 3.x as well as in a pure Eclipse 4 application.

There are ways to integrate Eclipse 4 components into an 3.x application based on Eclipse 4.x. That enables you to use the Eclipse 4 benefits for newly developed components and still reuse all existing plugins. More details are described in the tutorial “Soft Migration to Eclipse 4.x”

This approach allows you to develop new parts of the application using the benefits of the Eclipse 4 programming model and as well as reuse all existing components. Further, the views developed in this way can be integrated into any pure e4 application without any adaptations.

Option 3 - A “pure” or “native” Eclipse 4 Application

The third option, primarily interesting for new projects, is to build a pure Eclipse 4 (e4) application without any compatibility layer. Any existing parts of an application should be completely migrated to e4. The major disadvantage of this option is that many existing components and frameworks cannot be reused. This affects components doing UI contributions such as Views. Examples would be the Error Log, the Console View, or existing editors. To use them in an e4 application they would have to be migrated to e4 as well. However, components without any workbench contributions should work in a pure e4 application. The advantage of this approach is obviously that you will have very clean design and you benefit from all the concepts in Eclipse 4, such as the Application Model, dependency injection, and the e4 services.

Option 4 - A “pure” Eclipse 4 Application integrating some 3.x components

In this option you would develop a pure Eclipse 4 application and reuse some 3.x components. Components without workbench dependencies can typically easily be integrated into a pure e4 application. Components with workbench dependencies have to be adapted. Depending on the component, this adaptation is often not much effort. Even UI components can often be easily reused or adapted to work with e4. However, this needs to be evaluated individually for each component. The good news is that if you rely on open source components, everybody is able to adapt those. To help you with evaluating and adopting existing components to Eclipse 4, we offer developer support and sponsored development as a professional services.

Conclusion

In the end, when and how to migrate to e4 is still one of those “it depends…” decisions. Probably the most important criteria is the number of existing components and the number of reused third-party components. If you use many existing components you require the 3.x API, and you should probably go for option 1 or 2. If you do not use a lot of 3.x based components, or if all of those components can easily be migrated, you should go for option 3 or 4.

And if you want to migrate even further than Eclipse 4.x, have a look at Eclipse Theia, the new web-based platform for tools, IDEs and RCP applications.

If you have additional options for migrating or mixing the two technologies, let me know and I will gladly add it to this post.

This tutorial and all other parts of the series are available as a downloadable PDF.

For more information, contact us:

Join me on Google+

@JonasHelming folgen

Jonas Helming and Maximilian Koegel

EclipseSource Munich leads

Author: Jonas Helming