Migrating an Eclipse RCP application to the Equo Framework

Introduction

This document describes how an Eclipse RCP application can be migrated to the Equo Framework. This process not only allows to move the Eclipse application to an Equo app slowly and consciously, but also it leverage all the benefits of the whole Equo Platform immediately. Benefits such as:

  • Autogeneration of installers for all platforms and operating systems.

  • Installers web site with easy to download artifacts.

  • Automated builds and CI/CD. Continuous Integration and Continuous Deployment can be correctly reached without effort.

  • Error reporting and Logging in one place and easy to access.

  • Release repositories out of the box.

  • Full integration with the different issue trackers so that all errors reported by users can be tracked.

  • Automated UI Testing with parallel testing execution [coming soon]

  • Analytics - Monitor how applications are being used and see how all adds up with analytics.

  • Alerts about application wrong behavior.

  • Automatic updates and push notifications.

To start the migration, the user can create an empty Equo Application with the Equo CLI tool.

Migration

There are actually two ways to convert an Eclipse RCP application into an Equo application. Below each explanation.

Progressively and Iteratively

To start the migration, an Equo application has to be created. A convenient starting point is to use the Equo CLI tool, which allows to automatically create a skeleton of an Equo application and a tailored Eclipse IDE for that application.

With this type of migration, the main application bundle will depends on (and include) all the bundles of the existing legacy application and the ones required by them. Note that the legacy Eclipse RCP app is embedded in this main bundle app. Just running this simple standalone bundle will run the whole Eclipse legacy application as an Equo application. This is just an example of how easy is to execute an Eclipse RCP application as an Equo application. Nevertheless, the main objective of the migration is to transform the old legacy bundles into a service oriented architecture, and also, to modify those bundles to provide an outstanding web-like UI.

Once the first main application bundle is created, the user can start moving the old bundles and creating new ones in order to change the look and feel of the Eclipse application and also its architecture. It’s important to remember that the Equo Framework not only targets the migration and creation of a modern, state-of-the-art desktop application, but it also provides a better service-oriented application architecture.

To begin with the migration it is recommended to start with the existing small bundles. Sometimes this is not possible and some bundles need to be strictly migrated, otherwise the app might have some errors or might not work at all. This is the case of bundles which use features that are specific to Eclipse and which do not work in an OSGI runtime (i.e. the Eclipse-BundleShape directive which allows to explode a bundle as directory.). Note that an Equo application runs in an OSGI runtime.

Once a bundle is moved or cloned from the Eclipse RCP application to the new created Equo app, it does not even have to be removed from the original Eclipse app. Changing the version range of that bundle in the Equo app main bundle to point to the new created one is enough. The user can modify the bundle. They can start adding new Equo features, contributing to Equo renderers, developing web-like UIs, connecting those UIs to their old backend in an easy way, and using the new Chromium browser.

A cool feature about the framework is that it allows to modify existing web pages easily and integrate them into the Equo application. It is a common scenario for companies to have web products but also a proprietary Eclipse RCP application which integrates to those web products. Those web products can now be easily integrated into the Eclipse RCP application. New UI elements can now be added to existing web pages, and they will only be shown in the desktop application. This could be the insertion of a button into a web-based view inside the Eclipse RCP application, or the removal of it, for example.

Equo Renderers

Equo renderers are provided out of the box. That means that just running the Eclipse application with all its bundle will open it with the new modern renderers (toolbar, dialogs, parts, etc). If you want to change them, or change the look and feel of the web-based widgets, it’s possible too. Super flexible.

Contributions to the renderers are straightforward thanks to the renderer engine, which allows to contribute domain specific elements through a simple JSON file.

The Equo renderer engine is completely in charge of handling the communication between the application (UI side) and the framework (pure Java side). It is its responsibility to execute the correct Eclipse command when an action is performed in a UI element.

Starting from scratch

Besides migrating an Eclipse RCP application bundle by bundle progressively and iteratively, it is possible to migrate it by starting an Equo application from scratch.

The main benefit that this approach provides is that the user can develop a new web UI from scratch and not be tied to any particular Eclipse RCP UI framework (and not be tied to Eclipse at all). Users can use the web UI framework of their choice (i.e. React JS, Angular JS, etc.) to develop the new UI. However, the old Java backend classes of the old Eclipse RCP app can still be used. That means that the old code which worked correctly does not need to be thrown away.

Users can start the application UI from scratch, developing the UI components from zero with HTML and Javascript frameworks, or they can take advantage of some of the components and UI templates that the Equo Framework provides (TBD). The benefits of the aforementioned Equo renderers are used by each template and UI control provided by the Equo Framework.

On the other hand, on the Java side, modifications are also required. Users can reuse the old classes, and even they may reuse entire bundles (bundles which are pure backend code, which do not have UI Eclipse code), but still some adapters and handlers need to be injected to handle all type of communication with the web side of the application.

The handlers and adapters mentioned above, which also exists in the Javascript side, would be the endpoints of the Javascript - Java communication, since the communication between the web side and the Java side is completely managed by the Equo Server component which lives inside the Equo framework. It is important to remark that the Equo Framework supports fully dual communication between a web page and the Java side of an application. This means that any web UI that lives locally or remotely can communicate seamlessly with the old Java backend in unprecedented ways.

Architecture and Migration Benefits

Some of the improvements and benefits in terms of Architecture that the Equo framework can provide:

  • Iterative and step-by-step migration process.

  • Better application organization and architecture - everything is an OSGI bundle.

  • A more lightweight application and a potential downsizing of the final Eclipse RCP product.

  • Automatic generation of Manifest and its directives. Gradle based.

  • No more dependencies problem. No more Maven POM files.

  • Centralized build in only one bundle.

  • A pure Java application which can be developed in any IDE or editor by any Java dev - No Eclipse RCP knowledge is required.

  • All the benefits of the Equo Platform out of the box (Installers, Analytics, CI/CD, etc).

Other Benefits

Equo provides a natural approach to migrate Eclipse RCP applications to Equo applications. Applications after migrated to Equo are pure OSGI applications, leveraging all the advantages that OSGI provides. For the end developer, Equo applications are just plain Java applications. This is a great advantage for team members too, since they only need to know Java, and not the complex Eclipse RCP frameworks. In addition to this, this is even a greater advantage for companies, since they just need to hire Java developers, since Eclipse special knoledge is not needed.