Eclipse RCP Cookbook – Basic Recipe

The next months there will be several blog posts related to Eclipse RCP and related technologies. They will be released as part of the Eclipse Cookbook, which is intended to be a collection of recipes that help in getting started with application development based on the Eclipse 4 platform and to get a basic understanding of several additional technologies in combination with the platform.

As we don’t want to start every future blog post with setting up the basics, we start with the basic recipe. In our case this means to setup the recommended project structure and explain the very basics. So the following blog post can also be seen as Getting Started with Eclipse 4 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 8
  • http://www.oracle.com/technetwork/java/javase/downloads/index.html
  • Simply run the executable and follow the installation instructions
• Eclipse IDE 4.4 (Luna)
  • https://www.eclipse.org/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 http://download.eclipse.org/releases/luna
    (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
    • Code Recommenders for Java Developers
    • Eclipse XML Editors and Tools
• Plug-in for Eclipse 4 development
  • Main Menu → Help → Install New Software…
  • Software Site http://download.vogella.com/luna/e4tools
    (At the time writing this blog post, the e4 tools are not part of the platform and the software site URL contains the build time stamp. This means it changes from time to time. The software site provided by vogella.com builds the same resources but provides a fixed URL. It can be used until the e4 core tools become part of the Eclipse platform itself.)
    • Eclipse e4 Tools (Incubation)
• 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 8 directory → OK
    • Click OK on the Preferences dialog
  • Specify Execution Environments
    • Main Menu → Window → Preferences → Java → Installed JREs → Execution Environments
    • Select JavaSE-1.8 in the Execution Environments list on the left
    • Select the previously connected JDK 8
    • Click OK on the Preferences dialog
  • Reduce the delay before the Content Assist box is automatically displayed
    • Main Menu → Window → Preferences → Java → Editor → Content Assist
    • set the “Auto activation delay (ms) to 40
  • 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 and Swing classes in the Open Type dialog, content assist and quick fix proposals
    • Main Menu → Window → Preferences → Java → Appearance → Type Filters
    • Add Packages… → java.awt.*
    • Add Packages… → javax.swing.*
    • 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
• 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, you should always specify and implement against a concrete target platform.

• Create the target platform project
  • Main Menu → File → New → Project → General → Project
  • Set name to de.codecentric.eclipse.tutorial.target
  • Click Finish
• Create a new target definition
  • Right click on project → New → Target Definition
  • Set the filename to de.codecentric.eclipse.tutorial.target.target
  • Initialize the target definition with: Nothing: Start with an empty target definition
• Add a new Software Site in the opened Target Definition Editor by clicking Add… in the Locations section
  • Select Software Site
  • Software Site http://download.eclipse.org/releases/luna
  • Disable Group by Category and filter for Eclipse
  • Select Eclipse Platform Launcher Executables
  • Select Eclipse RCP SDK
  • Click Finish
• 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 → Project → Eclipse 4 → Eclipse 4 Application Project
  • Set name to de.codecentric.eclipse.tutorial.app
  • Click Next
  • Set Name to codecentric Eclipse Tutorial Application
  • Select Execution Environment JavaSE-1.8
  • Click Finish
• Delete the generated icons folder and the generated .product file

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 e4 tools project created the Eclipse 4 model editor. By using the Eclipse 4 Application Project wizard from the e4 tools project, 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. 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 name to de.codecentric.eclipse.tutorial.inverter
  • Click Next
  • Select Execution Environment JavaSE-1.8
  • Ensure that Generate an Activator and This plug-in will make contributions to the UI are disabled
  • Click Finish
• Specify the dependencies via MANIFEST.MF
  • The Plug-in Manifest Editor should open immediately after project creation, to open it afterwards just double click on the file de.codecentric.eclipse.tutorial.inverter/META-INF/MANIFEST.MF in the Project Explorer
  • Add the following plug-ins to the Required Plug-ins on the Dependencies tab
    • org.eclipse.swt
    • org.eclipse.jface
    • javax.annotation
    • javax.inject
• Create a simple helper class that contains a method for inverting a given String
  • Right click on project → New → Class
  • Set Package to de.codecentric.eclipse.tutorial.inverter.helper
  • Set Name to StringInverter
  • Create the static helper method String invert(String)

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

1package de.codecentric.eclipse.tutorial.inverter.helper;
2 
3public class StringInverter {
4 
5    private StringInverter() {}
6 
7    public static String invert(String value) {
8        return new StringBuilder(value).reverse().toString();
9    }
10}

•  Add a part to the application model
  • Open the application model in the de.codecentric.eclipse.tutorial.app project
  • Add a container for the part to the window
    • Application → Windows and Dialogs → Trimmed Window → Controls → Add PartSashContainer
  • Add a part to the container
    • Application → Windows and Dialogs → Trimmed Window → Controls → PartSashContainer → Add Part
  • Create the part implementation
    • Click the Class URI link in the part detail view
    • Set the values in the opened dialog.
      Note that the part implementation will be located in the plug-in project, not the application project!
    • 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:

1package de.codecentric.eclipse.tutorial.inverter.part;
2 
3import javax.annotation.PostConstruct;
4 
5import org.eclipse.jface.layout.GridDataFactory;
6import org.eclipse.swt.SWT;
7import org.eclipse.swt.events.KeyAdapter;
8import org.eclipse.swt.events.KeyEvent;
9import org.eclipse.swt.events.SelectionAdapter;
10import org.eclipse.swt.events.SelectionEvent;
11import org.eclipse.swt.layout.GridLayout;
12import org.eclipse.swt.widgets.Button;
13import org.eclipse.swt.widgets.Composite;
14import org.eclipse.swt.widgets.Label;
15import org.eclipse.swt.widgets.Text;
16 
17import de.codecentric.eclipse.tutorial.inverter.helper.StringInverter;
18 
19public class InverterPart {
20 
21    @PostConstruct
22    public void postConstruct(Composite parent) {
23        parent.setLayout(new GridLayout(3, true));
24 
25        Label inputLabel = new Label(parent, SWT.NONE);
26        inputLabel.setText("String to revert:");
27        GridDataFactory.fillDefaults().applyTo(inputLabel);
28 
29        final Text input = new Text(parent, SWT.BORDER);
30        GridDataFactory.fillDefaults().grab(true, false).applyTo(input);
31 
32        Button button = new Button(parent, SWT.PUSH);
33        button.setText("Revert");
34        GridDataFactory.defaultsFor(button).applyTo(button);
35 
36        Label outputLabel = new Label(parent, SWT.NONE);
37        outputLabel.setText("Inverted String:");
38        GridDataFactory.fillDefaults().applyTo(outputLabel);
39 
40        final Text output = new Text(parent, SWT.READ_ONLY | SWT.WRAP);
41        GridDataFactory.fillDefaults().grab(true, true).span(2, 1).applyTo(output);
42 
43        button.addSelectionListener(new SelectionAdapter() {
44            @Override
45            public void widgetSelected(SelectionEvent e) {
46                output.setText(StringInverter.invert(input.getText()));
47            }
48        });
49 
50        input.addKeyListener(new KeyAdapter() {
51            @Override
52            public void keyPressed(KeyEvent e) {
53                if (e.keyCode == SWT.CR
54                        || e.keyCode == SWT.KEYPAD_CR) {
55                    output.setText(StringInverter.invert(input.getText()));
56                }
57            }
58        });
59    }
60}

 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 plugins
  • Main Menu → File → New → Feature Project
  • Set name to de.codecentric.eclipse.tutorial.feature
  • Click Next
  • Select Initialize from the plug-ins list
  • Select the following plug-ins
    • de.codecentric.eclipse.tutorial.app
    • de.codecentric.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 name to de.codecentric.eclipse.tutorial.product
  • Click Finish
• Create a new product configuration
  • Right click on project → New → Product Configuration
  • Set the filename to de.codecentric.eclipse.tutorial.app.product
• Configure the product
  • Select the Overview tab
    • Set the General Information
      

      ID:	de.codecentric.eclipse.tutorial
      Version:	1.0.0
      Name:	codecentric Eclipse Tutorial App

      Check The product includes native launcher artifacts

    • Select the Product Definition
      

      Product:	de.codecentric.eclipse.tutorial.app.product
      Application:	org.eclipse.e4.ui.workbench.swt.E4Application

      The product configuration is based on: features

  • Select the Dependencies tab
    • Add de.codecentric.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.

Step 6: Taste

• Start the application from within the IDE
  • Open the Product Configuration in the de.codecentric.eclipse.tutorial.product project
  • Select the Overview tab
  • Click Launch an Eclipse Application in the Testing section
• Export the application and start the deliverable
  • Open the Product Configuration in the de.codecentric.eclipse.tutorial.product project
  • Select the Overview tab
  • Click Eclipse Product export wizard in the Exporting section
  • Select a directory to export to in the Destination section of the export wizard
  • Leave the other options unchanged
  • Click Finish
  • After the export is done, open the directory the application was exported to and start the application by executing /eclipse/eclipse.exe

In both cases the application should look similar to the following screenshot.

You can also find the complete project setup and sources on GitHub .

In the future we will refine this basic recipe to add additional features, and we will also create new recipes by extending this one.

Please let me know what you think about this basic recipe. Although I have several recipes in mind, I’m also curious to hear which recipes you would be interested in.