Chapter 8. Migrating to Eclipse 4.x

In the last chapter, we looked at the way Eclipse 4 RCP applications are built. We'll now look at how to migrate an existing solution based on Eclipse 3.x APIs to Eclipse 4.x, and the pros and cons of migrating to the new infrastructure.

In this chapter, we shall:

• Migrate an existing Eclipse 3.x view to an Eclipse 4.x view using the e4view extension

• Replace deprecated Action classes with generic classes

• Create code to show a toolbar, view menu, and pop-up menu

• Create an e4xmi fragment to migrate to Eclipse 4.x models

• Define commands, handlers, toolbars, view menus, and pop-up menus in the model

• Do forward selection between Eclipse 3.x views and Eclipse 4.x parts

Why Eclipse 4.x?

The first question that needs to be asked when migrating an application from the Eclipse 3.x APIs is "Why migrate to Eclipse 4.x at all?" If the goal is to provide plug-ins for an Eclipse IDE, then there may be little benefit from migrating existing plug-ins to the new APIs. Under the covers, Eclipse provides a compatibility layer that implements the Eclipse 3.x APIs, which will continue to work for some time; this allows plug-ins developed and tested against previous versions of Eclipse to work as before.

There are significant benefits from a rich client platform perspective; there really is little need to build Eclipse 3.x-based RCP applications any more. Since RCP applications tend to be self-contained units (and often do not support the same extensibility that the IDE does), it should be easy to move over to using it. This can be done piece by piece as the views or other functionality is migrated. The reasons for migrating to the Eclipse 4.x model for plug-ins for an...

Time for action – creating a migration component

In order to demonstrate how to migrate a plug-in to Eclipse 4.x technology, a simple example needs to be created. For this purpose, the Eclipse plug-in example library will be used, although the exact sample used by this book can also be checked out from the book's GitHub repository at https://github.com/alblue/com.packtpub.e4/

1. Create a new plug-in project by navigating to the File | New | Project… menu and choosing the Plug-in Project option. Use com.packtpub.e4.migration as the name of the project, click on Next, and then accept the defaults by clicking on Finish.

2. Open the META-INF/MANIFEST.MF file and go to the Overview tab. Click on the Extensions link on the right-hand side, under the Extension/Extension Point Content group:

   

3. If a dialog Extension pages hidden is displayed, click on the Yes button to ensure that the Extensions tab is shown:

   

4. Go to the Extensions tab and click on the Add... button. Type views in the filter and uncheck the Show...

Time for action – updating to e4view

The e4view extension point allows a view to be loaded into an Eclipse 4.x application without the need of a specific superclass. This allows existing Eclipse 3.x views to be upgraded to an Eclipse 4.x view as follows.

1. Open the SampleView class and remove the extends ViewPart superclass definition. This will introduce some errors in the code, which will be fixed shortly.

2. Add a @PostConstruct annotation to the createPartControl method. Use Cmd + Shift + O on macOS or Ctrl + Shift + O on other platforms to automatically add the import javax.annotation.PostConstruct statement.

3. Add a @Focus annotation to the setFocus method. This time, the automatic import won't work, but a quick fix will suggest adding the dependency. Alternatively open the MANIFEST.MF file, go to the Dependencies tab, and add org.eclipse.e4.ui.di bundle as a dependency. Now switch back to the SampleView class, perform the organize imports with the previous keystroke, and import org.eclipse...

Time for action – upgrading the actions

The JFace Action class is used in pop-up menus using the Eclipse 2.x model, but in Eclipse 3.x and Eclipse 4.x, the separation between handlers (code that does the work) and commands (logical operations such as copy that may be processed by different handlers) allows for a more flexible system, as described in Chapter 4, Interacting with the User. The first step is to replace the actions with handlers.

1. Open the SampleView class and go to the makeActions method, which creates anonymous inner subclasses of Action with an associated run method. To convert these, they will need to be static inner classes, so highlight the first new Action expression and navigate to the Refactor | Convert Anonymous Class to Nested… menu.

2. In the Convert Anonymous Class to Nested dialog that appears, ensure that public and static are selected, and give it the name HandlerOne:

   

3. Do the same steps for the other two actions, calling them HandlerTwo and DoubleClick.

4. To fix the compile...

Time for action – creating toolbars

The first step is to add the toolbar icons, which are the informational icons in the top right. In the original implementation, these were direct Action elements inserted into a ToolBar, which is part of the Eclipse 3.x interface. To achieve this with Eclipse 4.x, models using MDirectToolItem will be created and added to an MToolBar.

1. Create a private method createToolBar in the SampleView class. Add a call to the bottom of the createPartControl method to ensure that it is called at view creation time.

2. Inside the createToolBar method, create an instance of an MDirectToolItem object using the MMenuFactory.INSTANCE.createDirectToolItem() expression. It may be necessary to follow the quick-fix to add org.eclipse.e4.ui.model.workbench to allow the automatic import to find the class. Assign it to a local variable one.

3. Add a tooltip Action 1 tooltip by calling one.setTooltip().

4. To show the informational icon, a platform URI must be created. This uses the fully qualified...

Time for action – adding the view menu

The next step is to add the view menu, which is the drop-down menu shown by the triangle in the top-right of the original view. Adding this takes the same pattern as before, but the drop-down menu requires an additional tag to be shown as a view menu.

1. Add a method createViewMenu in the SampleView class. Add a call to the createPartControl method so that it is called when the view is created.

2. In the createViewMenu method, create an instance of MMenu using MMenuFactory.INSTANCE.createMenu().

3. Add the menu to the part using part.getMenus().add(menu).

4. To configure the menu as a view menu, add a tag ViewMenu using menu.getTags().add("ViewMenu").

5. As with toolbar items, a menu item can either be handled or direct. A direct menu item is associated directly with a handler implementation class. Create a direct menu item with MMenuFactory.INSTANCE.createDirectMenuItem() and store it in a local field one. Set the tooltip and label appropriately, and use the same icon...

Time for action – adding the pop-up

A pop-up menu is very similar to creating a toolbar or view menu; however, there are a few extra steps required to hook it up to the viewer and to ensure that the right pop-up menu is connected to the right part. As with the view menu, a tag is required; but instead of being a generic hard-coded value, the pop-up tag requires a tight binding with the pop-up menu.

1. Create a method called createPopupMenu in the SampleView class. It will need to take an SWT Control parameter, which will be the one that is used to trigger the menu.

2. Ensure that the createPopupMenu is called from the end of the createPartControl method, passing in the control from the viewer as the argument:

   createPopupMenu(viewer.getControl());

3. First, create a pop-up menu with a MMenuFactory.INSTANCE.createPopupMenu() call. Assign it to a local variable menu, so that it can be referred to throughout the method.

4. Set the elementId of the menu to be that of the part, using menu.setElementId(part.getElementId...

Migrating to Eclipse 4.x patterns

Although the previous section demonstrated how to translate code from an Eclipse 3.x-based example into an Eclipse 4.x example, it's not the canonical way that Eclipse 4.x views or applications are written. Instead, the preferred approach is to generate a model fragment, loaded from a fragment.e4xmi file. This not only reduces the code but also dramatically simplifies the internationalization of messages.

Time for action – creating a model fragment

Eclipse 4.x applications use a model fragment to define the UI. It is necessary to create a model fragment to define the part descriptors, handlers, and commands to simplify the code shown previously. To start with, the e4view extension will be replaced by a part descriptor in the fragment.

1. Comment (or delete) the e4view extension from the plugin.xml to prevent it from being loaded.

2. Select the project, navigate to the File | New... menu, and choose New Model Fragment from the dialog.

   

3. In the newly opened fragment.e4xmi file, click on Model Fragments and click on Add to add a new fragment.

4. Enter org.eclipse.e4.legacy.ide.application as the Extended Element ID and descriptors as the Feature Name.

5. Select PartDescriptor from the drop-down menu and click on Add to add a new Part Descriptor with the following fields:

   1. ID: com.packtpub.e4.migration.views.SampleView

   2. Label: Sample View

   3. Icon URI: platform:/plugin/com.packtpub.e4.migration/icons/sample.gif ...

Time for action – migrating the commands and handlers

Menu items are typically decoupled from the code that is executed to promote flexibility and re-use. In both Eclipse 3.x and Eclipse 4.x, commands are used to represent logical operations whilst handlers are used to execute the code. In order to create menus, the handlers and commands must be defined in the fragment.

1. Open the fragment.e4xmi file and go to the Model Fragments element in the tree. Click on Add to add a new Model Fragment, and then use org.eclipse.e4.legacy.ide.application as the Extended Element ID and commands as the Feature Name.

2. Select Command from the drop-down menu and click on Add to add new commands. Create a command with the ID com.packtpub.e4.migration.command.one and a Name of Action 1; then do the same with com.packtpub.e4.migration.command.two and com.packtpub.e4.migration.command.double. It should now look like:

   

3. Click on Model Fragments and then Add to create a new Model Fragment, this time using a Feature Name...

Time for action – creating the view menu

The view menu is the dropdown shown with a triangular icon, and is currently created in the SampleView class in the createView method. This can be recreated in the fragment editor by adding a view menu to the part descriptor.

1. Open the fragment.e4xmi file and navigate to the Sample View part descriptor. Under that, there is a Menus element and a dropdown choice box. Select View Menu from the list and click on the Add button to add a View Menu.

2. In the newly created View Menu, there is a drop-down choice box. Choose Handled Menu Item and click on Add.

3. Add the following to the Handled Menu Item:

   1. Label: Action 1

   2. Tooltip: Action 1 tooltip

   3. Icon URI: platform:/plugin/org.eclipse.ui/icons/full/obj16/info_tsk.png or use the Find … button as before

   4. Ensure that the Enabled checkbox is selected

   5. Click on the Find … button next to the Command field and choose the Action 1 command from the list

4. The Handled Menu Item should look like this:

   

5. Comment out the createViewMenu...

Time for action – defining the pop-up view in the fragment

The pop-up menu can be created in an almost identical way to the view menu. As before, it needs to be registered with the menu service but the code can be dramatically simplified by representing it in the fragment.e4xmi file.

1. Go to the fragment.e4xmi file, and go to the Menus element beneath the Sample View part descriptor. Add a child Popup Menu to the Menus element, either with the context-sensitive menu and by choosing Add child | Popup Menu, or by selecting Popup Menu from the dropdown and clicking on the Add button.

2. In the newly created Popup Menu, set the ID to com.packtpub.e4.migration.views.SampleView.popup.

3. Select Handled Menu Item from the dropdown and click on Add.

4. Add the Action 1 similar to before by setting these:

   1. Label: Action 1

   2. Tooltip: Action 1 tooltip

   3. Icon URI: platform:/plugin/org.eclipse.ui/icons/full/obj16/info_tsk.png or use the Find … button as before

   4. Ensure that the Enabled checkbox is selected

   5. Click on the Find...

Summary

Eclipse 3.x applications will continue to work in the foreseeable future but the API is frozen and will not receive any updates. Being able to incrementally update an application by migrating views allows developers to take advantage of injection and UI management through fragments.

It's possible to migrate code by directly replacing the user interface building blocks with explicit calls to code services, as shown in the first half of this chapter. However, this will result in a large amount of code being written, which may be counter-productive. Instead, a more Eclipse 4.x-based approach is to create a model fragment file and define the parts, commands, handlers, toolbars, view menus, and pop-up menus in the fragment.

The next chapter will look at styling Eclipse 4.x applications.