Eclipse_RCP_Cookbook_Basic_Recipe.md

Eclipse RCP Cookbook – Basic Recipe

With this tutorial we start with the basic recipe. In our case this means to setup the recommended project structure and explain the very basics. It can also be seen as Getting Started with Eclipse 4 RCP without the typical Hello World approach. Please note that despite the project structure, not every implementation detail in the basic recipe is considered to be best practice. We will add some seasoning and extend the basic recipe in further extended recipes.

Cookware

• JDK >= 17
  • e.g. Eclipse Temurin
  • Simply run the executable and follow the installation instructions
• Eclipse IDE >= 2024-03
  • Eclipse IDE Downloads
  • Choose the package that fits your needs the best, e.g. Eclipse for RCP and RAP Developers
  • After starting the IDE and choosing a workspace, update the IDE to ensure the latest service release is installed. This is necessary to get the latest bugfixes and security patches.
    • Main Menu → Help → Check for Updates

Ingredients

• Plug-ins for Java and Plug-in development (if they are not already installed with the Eclipse package)
  • Main Menu → Help → Install New Software…
  • Software Site https://download.eclipse.org/releases/latest
    (if the Eclipse for RCP and RAP Developers package was chosen, this step is not necessary)
    • Eclipse Java Development Tools
    • Eclipse Plug-in Development Environment
• Workspace preferences configuration
  The following steps are personal recommended settings that make working with the Eclipse IDE more comfortable.
  • Connect installed JDKs
    This allows you to have a look into the Java sources on debugging
    • Main Menu → Window → Preferences → Java → Installed JREs → Add…
    • Select Standard VM → Select a JDK directory e.g. the previously installed JDK 17 → OK
    • Click OK on the Preferences dialog
  • Specify Execution Environments
    • Main Menu → Window → Preferences → Java → Installed JREs → Execution Environments
    • Select JavaSE-17 in the Execution Environments list on the left
    • Select the previously connected JDK 17
    • Click OK on the Preferences dialog
  • Configure to automatically insert braces and semicolons at the correct position for a better fluent typing
    • Main Menu → Window → Preferences → Java → Editor → Typing → Automatically insert at correct position
    • Check Semicolons
    • Check Braces
    • Click Apply
  • Configure default actions that should be triggered on Save
    • Main Menu → Window → Preferences → Java → Editor → Save Actions
    • Check Perform the selected actions on save
    • Check Organize imports
    • Check Additional actions
    • Click Apply
  • Hide AWT classes in the Open Type dialog, content assist and quick fix proposals
    • Main Menu → Window → Preferences → Java → Appearance → Type Filters
    • Add Packages… → java.awt.*
    • Click Apply
  • Ensure to find classes that are available in the target platform but not yet in the plug-in project dependencies
    • Main Menu → Window → Preferences → Plug-in Development
    • Check Include all plug-ins from target in Java search
    • Click Apply
  • Enable DS Annotation processing
    • Main Menu → Window → Preferences → Plug-in Development → DS Annotations
    • Check Generate descriptors from annotated sources
    • Click Apply
  • Plug-in Development perspective
    • Activate the Plug-in Development perspective
    • Main Menu → Window → Open Perspective → Other… → Plug-in Development

Preparation

Step 1: Specify the Target Platform

The target platform specifies the plug-ins and versions that are used to build and needed to run an Eclipse RCP application. If no target platform is specified, the current active one is used, which is the Eclipse IDE you are working with. As an application shouldn’t update when the IDE is updated, it is best practice to always specify and implement against a concrete target platform.

• Create the target platform project

  • Main Menu → File → New → Project → General → Project
  • Set name to org.fipro.eclipse.tutorial.target
  • Click Finish

• Create a new target definition

  • Right click on project → New → Target Definition
  • Set the filename to org.fipro.eclipse.tutorial.target.target
  • Initialize the target definition with: Nothing: Start with an empty target definition
  • Click Finish

• Add a new Software Site in the opened Target Definition Editor

  • Alternative A
    • Switch to the Source tab and add the following snippet to the editor

  <target name="E4 Cookbook Target Platform" sequenceNumber="1568034040">
      <locations>
          <location 
              includeAllPlatforms="false" 
              includeConfigurePhase="false"
              includeMode="planner" 
              includeSource="true" 
              type="InstallableUnit">
              
              <unit 
                  id="org.eclipse.equinox.executable.feature.group"
                  version="3.8.2400.v20240213-1244" />
              <unit 
                  id="org.eclipse.sdk.feature.group"
                  version="4.31.0.v20240229-1022" />
              <repository 
                  location="https://download.eclipse.org/releases/2024-03" />
          </location>
      </locations>
  </target>

  • Alternative B
    • By clicking Add... in the Locations section
    • Select Software Site
    • Software Site https://download.eclipse.org/releases/2024-03
    • Disable Group by Category and filter for Eclipse
    • Select Eclipse Platform Launcher Executables
    • Select Eclipse Project SDK
    • Click Finish

• Switch to the Definition tab

  • Wait until the Target Definition is completely resolved (check the progress at the bottom right)
  • Activate the target platform by clicking Set as Target Platform in the upper right corner of the Target Definition Editor

The Target Definition should look similar to the following screenshot after all steps have been performed.

Step 2: Create the Application Project

The application project is a plug-in project that contains the application model and global application settings, like for example stylesheets.

• Create the application project
  • Main Menu → File → New → Plug-in Project
  • Set Project name to org.fipro.eclipse.tutorial.app
  • Click Next
  • Set Name to Eclipse Cookbook Application
  • Select Execution Environment JavaSE-17
  • Check This plug-in will make contributions to the UI
  • Set Create a rich client application? to Yes
  • Click Next
  • Select Eclipse RCP application
  • Click Next
  • Set Application window title: to Eclipse Cookbook Application
  • Click Finish
• Delete the generated icons folder and the generated .product file
• Update the build.properties and remove the icons folder from the bin.includes

The application model is one of the core parts of an Eclipse 4 application. It describes the structure of an application, including visual elements like windows and parts, as well as non-visual elements like commands, handlers and key bindings. But it does not specify the content of parts or how they are rendered. This way the application model is independent of the UI toolkit implementation.

Technically the application model is stored in an XMI file, that is read on application startup. Since editing a XMI file directly is not much fun, the Eclipse Model Editor. By using the Plug-in Project wizard to generate a rich client application, a default application model is created, specifiying the default addons and bindings and a first window to get started with a SWT based Eclipse 4 application.

• Add a part container to the application model
  • Open the application model Application.e4xmi in the org.fipro.eclipse.tutorial.app project
  • Add a container for the part to the window
    • Application → Windows → Trimmed Window → Controls → Add Part Sash Container
    • Set ID to org.fipro.eclipse.tutorial.app.main

The following picture shows the generated application model.

Step 3: Create the Plug-in Project

The following plug-in project is used as an example for a content plug-in. It will contain a simple view where a user is able to enter a text and invert it. It anticipates topics like details on the application model, dependency injection and SWT. More details on those topics are covered in later recipes. For the basic recipe simply follow the instructions.

• Create the plug-in project
  • Main Menu → File → New → Plug-in Project
  • Set Project name to org.fipro.eclipse.tutorial.inverter
  • Click Next
  • Ensure that Generate an Activator is disabled
  • Check This plug-in will make contributions to the UI
  • Set Create a rich client application? to No
  • Click Finish
• Open the MANIFEST.MF
  The Plug-in Manifest Editor should open immediately after project creation, to open it afterwards just double click on the file org.fipro.eclipse.tutorial.inverter/META-INF/MANIFEST.MF in the Project Explorer
  • Switch to the Overview tab
    • Check Activate this plug-in when on of its classes is loaded
      This is necessary for the Dynamic Contribution Mode we will use in the next section, so the plug-in gets activated on model fragment loading.
  • Switch to the Dependencies tab
    • Add the following plug-ins to the Required Plug-ins
      • org.eclipse.swt
      • org.eclipse.jface
    • Add the following packages to the Imported Packages
      • jakarta.annotation
      • jakarta.inject
• Create a simple helper class that contains a method for inverting a given String
  • Right click on project → New → Class
  • Set Package to org.fipro.eclipse.tutorial.inverter.helper
  • Set Name to StringInverter
  • Click Finish
  • Create the static helper method String invert(String)

The created helper method might look similar to the following snippet.

package org.fipro.eclipse.tutorial.inverter.helper;
 
public class StringInverter {
 
    private StringInverter() {}
 
    public static String invert(String value) {
        return new StringBuilder(value).reverse().toString();
    }
}

• Create a Model Fragment Definition
  The application model can be extended by other plug-ins via Model Fragments. This allows a clear separation.
  • Right click on project → New → Other... → Eclipse 4 → Model → New Model Fragment
  • Select Contribution Mode Dynamic
  • Click Finish
• Import the PartSashContainer from the application model
  • Select Imports
  • Select PartSashContainer in the details pane
  • Click on the Add button
  • Select the added Part Sash Container
  • Set the Reference-ID to org.fipro.eclipse.tutorial.app.main
• Add a Model Fragment

  • Right click on Model Fragments and select Add child - Model Fragment

    Property	Value
    Extended Element-ID	org.fipro.eclipse.tutorial.app.main
    Feature Name	children

  • Select Part in the combo

  • Click on the Add button

  • Create the part implementation

    • Click the Class URI link in the part detail view
    • Set the values in the opened dialog

    Property	Value
    Package	org.fipro.eclipse.tutorial.inverter.part
    Name	InverterPart
    PostConstruct Method	check

    

    • Click Finish
    • Save the fragment.e4xmi file
    • Create the content in the method annotated with @PostConstruct
      Methods annotated with @PostConstruct are called after an object has been fully injected and also supports method parameter injection.
      • Use a GridLayout for arranging the items
      • Add a Label with text "String to invert:"
      • Add a Text field for inputs
      • Add a Label with text "Inverted String:"
      • Add a read-only Text field to show the output
      • Add a Button that will call the helper class method to invert the input value and show the result in the output field

If your are not familiar with SWT, you can use the following snippet as part implementation:

package org.fipro.eclipse.tutorial.inverter.part;
 
import jakarta.annotation.PostConstruct;
 
import org.eclipse.jface.layout.GridDataFactory;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.KeyAdapter;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.SelectionAdapter;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
 
import org.fipro.eclipse.tutorial.inverter.helper.StringInverter;
 
public class InverterPart {
 
    @PostConstruct
    public void postConstruct(Composite parent) {
        parent.setLayout(new GridLayout(3, true));
 
        Label inputLabel = new Label(parent, SWT.NONE);
        inputLabel.setText("String to revert:");
        GridDataFactory.fillDefaults().applyTo(inputLabel);
 
        final Text input = new Text(parent, SWT.BORDER);
        GridDataFactory.fillDefaults().grab(true, false).applyTo(input);
 
        Button button = new Button(parent, SWT.PUSH);
        button.setText("Revert");
        GridDataFactory.defaultsFor(button).applyTo(button);
 
        Label outputLabel = new Label(parent, SWT.NONE);
        outputLabel.setText("Inverted String:");
        GridDataFactory.fillDefaults().applyTo(outputLabel);
 
        final Text output = new Text(parent, SWT.READ_ONLY | SWT.WRAP);
        GridDataFactory.fillDefaults().grab(true, true).span(2, 1).applyTo(output);
 
        button.addSelectionListener(new SelectionAdapter() {
            @Override
            public void widgetSelected(SelectionEvent e) {
                output.setText(StringInverter.invert(input.getText()));
            }
        });
 
        input.addKeyListener(new KeyAdapter() {
            @Override
            public void keyPressed(KeyEvent e) {
                if (e.keyCode == SWT.CR
                        || e.keyCode == SWT.KEYPAD_CR) {
                    output.setText(StringInverter.invert(input.getText()));
                }
            }
        });
    }
}

Step 4: Create the Feature Project

A feature describes a list of plug-ins and other features which can be understood as a logical unit. It is therefore used to group plugins. As the mechanism for updating Eclipse applications (p2) only works based on feature projects, it is recommended to create feature based products (see Step 5).

• Create the feature project for our plug-ins
  • Main Menu → File → New → Feature Project
  • Set Project name to org.fipro.eclipse.tutorial.feature
  • Click Next
  • Select the following plug-ins
    • org.fipro.eclipse.tutorial.app
    • org.fipro.eclipse.tutorial.inverter
  • Click Finish

Step 5: Create the Product Project

A product is used to tie features (or plug-ins) together into a product together with several configurations.

• Create the product project
  • Main Menu → File → New → Project → General → Project
  • Set Project name to org.fipro.eclipse.tutorial.product
  • Click Finish
• Create a new product configuration
  • Right click on project → New → Product Configuration
  • Set the filename to org.fipro.eclipse.tutorial.app.product
  • Select Create a configuration file with basic settings
  • Click Finish
• Configure the product

  • Select the Overview tab

    • Set the General Information

    Property	Value
    ID	org.fipro.eclipse.tutorial
    Version	1.0.0.qualifier
    Name	Eclipse Cookbook Application
    The product includes native launcher artifacts	check

    • Select the Product Definition

    Property	Value
    Product	org.fipro.eclipse.tutorial.app.product
    Application	org.eclipse.e4.ui.workbench.swt.E4Application
    The product configuration is based on	features

  • Select the Contents tab

    • Add org.fipro.eclipse.tutorial.feature (our custom plugins)
    • Add org.eclipse.e4.rcp (necessary platform plugins)
    • Click Add Required to add org.eclipse.emf.ecore and org.eclipse.emf.common which are required by org.eclipse.e4.rcp

  • Select Configuration tab

    • Set the recommended plug-in start levels by clicking Add Recommended... in the Start Levels section

  • Optional: Select Launching tab

    • Add –clearPersistedState to the Program Arguments
      Prevents loading a persisted workbench on application startup. This is very helpful while developing an application, as otherwise changes to the application model would not be shown on the next startup for example.

Taste

• Start the application from within the IDE
  • Open the Product Configuration in the org.fipro.eclipse.tutorial.product project
  • Select the Overview tab
  • Click Launch an Eclipse Application in the Testing section

The application should look similar to the following screenshot.