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
- 2. Running Eclipse 3.x plug-ins on top of Eclipse 4
- 3. Using e4 API in 3.x applications
- 4. Using the e4 API in Eclipse 3.x based applications
- 5. Migrating to an e4 API application without 3.x API usage
- 6. Learn more about Eclipse RCP development
- 7. Links and Literature
- 8. vogella training and consulting support
- Appendix A: Copyright, License and Source code
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.
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.
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.
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.
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.
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.
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.|
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.
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.
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.
See https://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.
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.
PlatformUI and use the dependency injection programming model.
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.
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.
The https://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
If you choose to try this approach despite the warning, you have to
file similar to the Eclipse IDE and add your
model components to this
file. This file can be found
Point to that file via the
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.
I hope you enjoyed this tutorial. You find an extended online training at the Eclipse RCP online training website.
Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.