Migrating from Eclipse 3.x to Eclipse 4 (e4)
Eclipse Juno 4.2 has been the first Release Train building on the new Eclipse 4 (e4) Application Platform. This raises the question of how to migrate existing Eclipse 3.x applications to Eclipse 4 (e4), e.g 3.7 Indigo. 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 and part 2) of this tutorial are available now as a downloadable PDF.
Option 1: Use the Compatibility Layer
The compatibility layer enables 3.x applications to run on the new Eclipse 4 platform without any code adaptation. In the beginning, most existing projects will probably use this option. 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.7.
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 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
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. Some other improvements will work though, such as CSS styling.
Option 2: A pure Eclipse 4 (e4) Application
The second 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.
Option 3: Compatibility Layer and Eclipse 4 (e4) Plugins
For this option, you would rely on the compatibility layer to reuse all existing components without any adaptations. New components would be developed following the e4 programming model, including dependency injection and annotations. There are three ways to integrate e4 elements into a compatibility layer application.
The first option is to use processors and fragments to add elements to the application model created by the compatibility layer. However, there are currently timing problems. When processors and fragments are being processed, the compatibility layer has not yet created the complete application model. (See this bug report. (https://bugs.eclipse.org/bugs/show_bug.cgi?id=376486). Therefore, this option might work for handles and views, but currently it doesn’t work for editors.
The second option for integrating Eclipse 4 components is to create a copy of the application model used by the compatibility layer, register it as the application model of your application and add new e4 components to it. The relevant model LegacyIDE.xmi can be found in in the plugin org.eclipse.ui.workbench.
The third option is to use the 3.x e4 bridge from the e4 tools project, developed by Tom Schindl. The goal of the bridge is to ease single sourcing applications on 3.x and e4, which means that views and editors can be used in 3.x and e4 in parallel. To enable this, the plugin org.eclipse.e4.tools.compat provides wrapper classes that implement the interfaces of 3.x. For example, the wrapper DIViewPart implements ViewPart. In the wrapper, you specify a class (POJO), which implements a view following the e4 programming model, including dependency injection. Essentially the wrapper is just a pointer to an e4 object. It will initialize the POJO using dependency injection.
A 3.x wrapper
public class ExampleViewWrapper extends DIViewPart{
public Example3xViewWrapper() {
super(ExampleE4View.class);
}
}
|
A e4 view:
public class ExampleView {
private Label label;
@Inject
public ExampleView(Composite parent){
label = new Label(parent, SWT.NONE);
label.setText("Hello World");
}
}
|
This approach allows you to develop new parts of the application using all the benefits of e4 and as well, reuse all existing components. Further, the views developed in this way can be integrated into any pure e4 application without any adaptations. The approach is described more in detail in this tutorial.
An Eclipse 4 (e4) Application including some 3.x components
In this option you would develop an e4 application and reuse some 3.x components. If they don’t access the workbench API, there shouldn’t be any problems. In some cases, even UI components can be easily reused or adapted to work with e4. However, this needs to be evaluated individually for each component.
In the end, when and how to migrate to e4 is still one of those “it depends…” decisions. Probably the most important criteria are the number of existing components and the number of reused third-party components. 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:
Jonas Helming and Maximilian Koegel
EclipseSource Munich leads
Author: Jonas Helming
About the Authors
