To develop Eclipse plug-ins and applications, you need to download an Eclipse IDE suitable for this task. The Eclipse project offers multiple downloads specifically for this purpose. The most commonly used options are:

This chapter describes both alternatives, with the SDK download being the recommended one.

Create a project named com.example.e4.rcp using the File  New  Other…​  Plug-in Development  Plug-in Project menu entry.

Use settings similar to the following screenshots.

Press Next.

Press Next.

Press Next.

On the last wizard page, select the Create sample content (part, menu, command…​) flag. This flag adds example content to the generated application, for example a part and some menu and toolbar entries.

Open the generated product file by double-clicking on the product file.

Switch to the Overview tab in the editor and press the Launch an Eclipse application hyperlink to start your application. This option is highlighted in the screenshot below.

As a result, your Eclipse application should start. The application should look similar to the following screenshot.

If you see an empty window, it means you pressed the Finish button prematurely (after selecting the template) or forgot to select the Create sample content flag on the last tab.

To fix this, delete the generated plug-in and create it again, making sure to select the correct values as described in Exercise: Create an RCP application using the Eclipse wizard.

Model elements can point to a class or to a static resource via a Uniform Resource Identifier (URI). For this purpose, Eclipse supports two URI patterns. In most cases, Eclipse instantiates the referred objects or resources lazily. For example, the classes for a part are instantiated when the part becomes visible.

The following table describes the supported URI patterns. The example assumes that the bundle is called test for brevity.

For example, a part has a Class URI attribute that points to a Java class via the bundleclass:// URI. This class provides the specific implementation of the part.

An example of a static resource reference is the Icon URI attribute of a part. This attribute can point to an icon that is used for the part.

The following text provides an overview of the available model elements in the application model.

Every plug-in can contribute to the application model via:

These model contributions must be registered via the org.eclipse.e4.workbench.model extension point. They are read during startup and are used to build the runtime application model.

This runtime application model reflects your current application. Changes during the application’s runtime are written back to the model. For example, the user can move a part into another stack via drag and drop.

If the Eclipse application is closed, these changes are recorded and saved in the workbench.xmi file. This file is located in the .metadata/.plugins/org.eclipse.e4.workbench folder. If certain model elements should not be persisted during shutdown, you can add the constant persistState defined via IWorkbench.PERSIST_STATE to the persistedState of the model element.

You can change the application via your code by changing the model elements. The Eclipse platform has listeners registered on most parts of the model, and updates the application if you change the model.

A model fragment is a file that typically ends with the .e4xmi extension. It specifies additional model elements and which model element it extends. For example, a fragment can contribute a new menu containing several new menu entries to the main menu of the application.

In the fragment the Feature Name is a link to the model element that you want to extend. The following table lists some Feature Name values and their purposes.

If you want to contribute to an element of the application model you can:

The following table gives several examples of how you can use XPath expressions to define the model element you want to extend.

Fragments define the desired position of new model elements via the Position in List attribute. The following values are allowed:

Fragments of independent plug-ins are processed in the order of the dependencies in the MANIFEST.MF file. Therefore, the use of first and index might not always give the desired result.

With a processor you can modify the application model via program code during the start of the application. This enables the dynamic creation, removal or modification of model elements.

Create a new plug-in project via the File  New  Other…​  Plug-in Development  Plug-in Project menu entry.

On the first wizard page, enter com.vogella.tasks.ui as the project name and press the Next button.

On the next wizard page, ensure the following settings:

Press the Finish button.

If you click the Next button instead of Finish, the wizard shows you a template selection page. Do not select a template, and finish the wizard.

Open the project and verify that the src folder contains no Java classes.

Open the META-INF/MANIFEST.MF file. In the manifest editor, switch to the Dependencies tab and ensure that there are no entries.

Create a new feature project named com.vogella.tasks.feature via File  New  Other…​  Plug-in Development  Feature Project.

You can press the Finish button on the first wizard page.

Afterwards, select the Included Plug-ins tab in the editor of the feature.xml file. Press the Add…​ button and include the com.vogella.tasks.ui plug-in into this feature.

Create a new project named com.vogella.tasks.product via the File  New  Other…​  General  Project menu entry.

Press Finish.

Right-click on the com.vogella.tasks.product project and select New  Other…​  Plug-in Development  Product Configuration.

Create a product configuration file named taskmanagement.product inside the com.vogella.tasks.product folder.

Press the Finish button. The file is created and opened in an editor.

Press the New…​ button on the Overview tab of the product editor.

Use the following data:

Ensure that an ID, version, and name are set. Version should be set to 1.0.0. Also ensure that you have selected that the product configuration is based on plug-ins and features.

Select the Contents tab and add the following features via the Add Feature…​ button.

The expected output is shown in the screenshot below.

Switch to the Configuration tab in the product editor and press the Add Recommended…​ button. The Maven/Tycho build system uses these settings, so it is good practice to configure them.

Create an application model file in your com.vogella.tasks.ui plug-in via the File  New  Other…​  Eclipse 4  Model  New Application Model menu entry.

Enter your com.vogella.tasks.ui application plug-in as the container and use the file name suggested by the wizard.

Press the Finish button to create the application model file and to open it in an editor.

Add one window to your application model.

Right-click on the Windows node, and select Trimmed Window as depicted in the following screenshot.

Enter the com.vogella.tasks.ui.trimmedwindow.taskmanager ID, the position and size of the window, and a label as shown in the screenshot below.

If you start and close your application, the last state of the application is persisted by the framework and restored the next time you start this application. This is undesirable during development, as the latest state from the application model file should be used. To ensure that the latest version of your application model is always used, add the following parameter to your product file on the Launching tab.

The following screenshot shows this setting in the product configuration file.

Your command line build, which you will configure later, should create an executable named Taskman. On the Launching tab of your product file, enter Taskman in the Launcher Name field.

Open the product file and select the Overview tab. Press the Launch an Eclipse application hyperlink in the Testing section.

Validate that your application starts. You should see an empty window that can be moved, resized, minimized, maximized, and closed.

In this exercise, you create the basis of the application user interface. At the end of this exercise, your user interface should look similar to the following screenshot.

Open the Application.e4xmi file in the Eclipse model editor via a double-click or right-click on it and select Open With.

To use classes from other plug-ins in a plug-in, you need to add dependencies to them in the MANIFEST.MF file of the plug-in. In this exercise, you prepare to use classes from other plug-ins.

Open the META-INF/MANIFEST.MF file in your com.vogella.tasks.ui plug-in and select the Dependencies tab. Use the Add…​ button in the Required Plug-ins section to add the following plug-ins as dependencies.

Use the Add…​ button in the Imported Packages section to add the following packages.

The result should be similar to the following screenshot (versions may differ).

You can see the resulting changes on the MANIFEST.MF tab of the manifest editor. The following is a potential solution (plug-in versions have been removed from the listing).

Create a simple plug-in project named com.vogella.contribute.parts. The following description abbreviates the plug-in name to the contribute.parts plug-in.

In the MANIFEST.MF file, select the Dependencies tab.

Add the following entries as plug-in dependencies to your contribute.parts plug-in.

Also add the jakarta.annotation package dependency.

The manifest should look similar to the following listing. Version numbers have been removed as they change frequently.

Set the Activate this plug-in when one of its classes is loaded flag on the Overview tab of the MANIFEST.MF editor.

Create the following class.

Create a new model fragment via File  New  Other…​  Eclipse 4  Model  New Model Fragment.

Select the contribute.parts plug-in as the container and use parts.e4xmi as the name for the file.

Press the Finish button.

The model fragment wizard adds the Model-Fragment header for the registration and the org.eclipse.e4.ui.model.workbench dependency to your MANIFEST.MF file. To review this, open the MANIFEST.MF file and select the MANIFEST.MF tab in the editor. The resulting file should look similar to the following listing, in which the versions have been removed, as they depend on the release you are using.

Open the parts.e4xmi file in its editor. Select the Model Fragments node and press the Add button.

Use xpath:/ as Extended Element-ID and descriptors as Feature Name.

Right-click on this entry and select Add Child  PartDescriptor. Select the Part Descriptor and press the Find button for the Class URI field. Choose the AdditionalInformationPart class.

The generated entry should look like the following.

Switch to the Supplementary tab and add the View tag.

Add the new plug-in to your feature and start your application via the product file.

A part descriptor is only a template, so it is not visible in the RCP application until a part is created from it.

Add the Eclipse model spy to your runtime application and ensure that you see the part descriptor.

Optionally, create a new direct menu item via the fragment to open this part descriptor.

The programming model in Eclipse supports constructor, method and field injection. It uses the annotations originally defined in Java Specification Request 330 (JSR 330), which have moved to the jakarta.inject namespace. The most important annotations are covered in Annotations to define class dependencies in Eclipse, more specialized annotations are covered in their corresponding chapters.

The Eclipse dependency framework verifies that the key and the type of the injected object are valid. For example, the following field declaration requests an object of type Task for the "xyz" key, and the framework only injects an object with an assignable type.

The following table gives an overview of the dependency injection annotations from JSR 330 and the Eclipse-specific ones.

The Eclipse runtime creates objects for the Java classes referred to by the application model. During this instantiation, the Eclipse runtime scans the class definition for annotations and performs the injection based on them.

Eclipse does not automatically inject dependencies into objects that are created with the new operator.

The Eclipse framework tracks which object expressed a dependency on which key and type. If the value associated with a key changes, the Eclipse framework re-injects the new value into all objects that depend on this key. This frees applications from having to install (and remove) listeners.

For example, you can define via @Inject that you want to get the current selection injected. If the selection changes, the Eclipse framework injects the new value.

The reinjection only works on methods and fields that are marked with @Inject. It does not work for constructor parameters or for methods marked with @PostConstruct, as these are executed only once.

OSGi services are available for dependency injection in Eclipse applications. If you define your custom OSGi services, you can inject them into your model objects. This removes the need to create singleton or factory implementations in your application to access data.

If a requested key is not found in the Eclipse context hierarchy, the Eclipse framework searches dynamically for a suitable OSGi service in the OSGi registry.

For example, if you have an OSGi service declared for the TaskService interface, you can inject it into a field of an Eclipse part via the following code snippet.

During startup of an Eclipse application, the Eclipse runtime creates an object based on the IEclipseContext interface. This object is called the context, or the Eclipse context.

The context is similar to a Map data structure, in which objects can be placed under a certain key. The key is a String, and in several cases the fully qualified class name is used as the key. The value (to which the key points) can be injected into other objects. Unlike a map, the Eclipse context is hierarchical and can dynamically compute values for requested keys.

For certain model objects (see Which model elements have a local context?), a local context is created. Such a context is associated with an application model object.

The different context objects are connected to form a hierarchical tree structure based on the structure of your application model. The highest level in this hierarchy is the application context.

A sample context hierarchy is depicted in the following picture.

Objects can be placed at different levels in the context hierarchy. This enables the same key to point to different objects in the hierarchy.

For example, a part can express a dependency on a Composite object via a field declaration similar to @Inject Composite parent;. Since parts have different local contexts, they receive different objects of the type Composite.

The following model elements implement the MContext interface and therefore have their own context.

During startup, the Eclipse framework creates the context hierarchy from the application model. By default, it assigns specific objects to predefined keys in the context, such as services that control Eclipse framework functionality.

The Eclipse platform creates both model objects and objects derived from class URI attributes. For each model element with its own context, the Eclipse framework determines which objects should be available in the local context of the model object. If required, it creates the Java objects referred to by the Class URI property of the model elements, for example, once a part becomes visible to the user.

After the initial creation of the Eclipse context hierarchy, the framework or the application code can change the key-value pairs stored in the context. In this case, objects created by the Eclipse framework are updated with the new values.

The context is only kept in memory, it is destroyed when the application stops.

As described in The objects on which Eclipse performs dependency injection, an object that is created by Eclipse can use annotations to describe its class dependencies.

During dependency injection for an object created by Eclipse, the Eclipse framework searches for a suitable object based on the specified key. The search starts in the local context associated with the application model object. If this key is not available, Eclipse continues to search in the parent context. This process continues until the application context has been reached.

The Eclipse context is not the only possible source of objects that can be injected. Other sources, covered in later chapters, are OSGi services, preferences, events and custom objects. The search happens (mostly) transparently for the caller of the injection.

For the class references in the application model, the Eclipse framework creates the corresponding objects when needed. Such an object has access to its corresponding model object via dependency injection.

For example, in the implementation of a part, you can access the model information of the part via @Inject MPart part;.

The Eclipse framework creates several objects in the context, including:

The context can be modified by the application code and the framework. As the Eclipse framework automatically tracks the dependencies of the objects it creates, it can update them as described in Dynamic dependency injection based on key-value changes.

The Eclipse platform places the part that is currently selected and the active shell into the IEclipseContext of the application object. The related keys are defined in the IServiceConstants interface.

For example, the following method tracks the active part in another part.

To track the active shell, use the IServiceConstants.ACTIVE_SHELL key.

The @Active annotation allows you to track values in a child context. The Eclipse framework keeps track of the current active branch in the hierarchy of the IEclipseContext. For example, if the user selects a part, the path in the IEclipseContext hierarchy from the root to the IEclipseContext of the part is the current active branch.

Whenever the active branch changes and the value of the referred key changes, this value is re-injected into the object that uses the @Active annotation.

The usage of this annotation is demonstrated by the following code snippet.

Eclipse dependency injection was developed for the Eclipse 4.x release. Code that is still based on the 3.x API and runs on a 4.x runtime can access objects available for dependency injection via the PlatformUI class.

If you use a framework in your application, you need to have a convention for how your application interacts with the framework. For example, if a Java object is responsible for handling a toolbar button click, the framework needs to know which method of this object needs to be called.

For this purpose, every framework defines an Application Programming Interface (API). This API defines how your code, and the objects created or controlled by the framework, interact with the framework. Typically, a framework uses inheritance or annotations for this purpose.

The "traditional" way of defining an API is via inheritance. This approach requires that your classes extend or implement framework classes and interfaces. The Eclipse 3.x platform API used this approach.

The framework defines, for example, an abstract class with methods to be implemented. In the example of the toolbar button, the method might be called execute(), and the framework calls this method once the button is clicked.

API definition via inheritance is a simple way to define an API, but it couples the classes tightly to the framework. For example, testing the class without the framework is difficult. It also makes extending or updating the framework difficult, because such an update may affect clients. This is why Eclipse 4.x no longer uses this approach.

The Eclipse 4.x platform API is based on annotations, for example, annotations identify which methods should be called at a certain point in time. These annotations are called behavior annotations.

The following table lists the available behavior annotations for parts.

The @PostConstruct and @PreDestroy annotations are included in the jakarta.annotation package. @Persist, @PersistState and @Focus are part of the org.eclipse.e4.ui.di package.

Eclipse defines additional behavior annotations for commands and for the application lifecycle, which are covered in the respective chapters.

Construct the user interface of a part in a method annotated with @PostConstruct. You could create the user interface in the constructor, but field and method injection have not been done at this point.

Creating the user interface in an @PostConstruct method requires that @Inject methods are aware that the user interface might not have been created yet.

Add the following method to your TodoOverviewPart, TodoDetailsPart, and PlaygroundPart classes. In case you created constructors for these classes, you can remove them.

Run your application and validate that the @PostConstruct method is called.

If you receive an error message similar to Unable to process "TodoOverviewPart#createControls()": no actual value was found for the argument "Composite"., ensure that you imported the SWT Composite.

Create the following class.

Change your playground part to the following.

Adjust your TodoDetailsPart class to get the new object injected.

Start your product and ensure that you see the correct output on the console. Afterwards, remove the System.out statement.

You can add menus and toolbars to your Eclipse application using the application model and position these entries at various locations. You can, for example, add a menu to a window or a part. Each element defines, directly or indirectly, one or more links to a class that is responsible for the execution. Such a class is called a handler class and defines the behavior once the menu or toolbar entry is selected.

The Eclipse application model allows you to specify commands and handlers.

You can use the Direct MenuItem or Direct ToolItem model elements. These entries define a reference to a class (handler class). The framework creates an instance of this handler class and calls its annotated methods when necessary. Menus and toolbars support separators.

A command is a declarative description of an abstract action that can be performed, for example, Save, Edit, or Copy.

A command is independent of its implementation details. The Eclipse framework does not provide standard commands, so you have to create all required commands in your application model.

The behavior of a command is defined via a handler. A handler model element points to a class (handler class) via the contributionURI property of the handler. This attribute is displayed as Class URI in the model editor.

Commands are used by the Handled MenuItem and Handled ToolItem model elements.

Prefer commands over direct (menu or tool) items. Commands together with handlers allow you to define different handlers for different scopes (application, window or part), and you can define key bindings for the commands.

In a handler class, exactly one method must be annotated with @Execute. In addition, you can annotate one method with @CanExecute. If multiple methods in a handler class are annotated with the same annotation, the framework executes only one of them. The Eclipse runtime uses dependency injection to provide the parameters of the method. The purpose of these annotations is described in the following table.

The following example demonstrates the implementation of a handler class.

A handler instance does not have its own IEclipseContext. It is executed with the Eclipse context of the active model element that has an Eclipse context. In most cases, this is the context of the active part.

Inject all required parameters into the method annotated with @Execute, as the handler class should retrieve its runtime information during execution.

If a command is selected, the runtime determines the relevant handler for the command. The application model allows you to create a handler for the application, a window and a part.

Each command can have only one valid handler for a given scope. The Eclipse framework selects the handler most specific to the currently selected model element.

For example, if you have two handlers for the "Copy" command, one for the window and another one for the part, the runtime selects the handler closest to the model element that is currently selected by the user.

The framework calls a method annotated with @CanExecute if the Eclipse context changes, for example, if you select a new part. If the method returns false, the framework disables the menu and tool items that point to that command. Menu items are evaluated whenever the menu is shown.

You can request the re-evaluation of the @CanExecute methods of tool items by sending out an event via the event broker. The event data is either UIEvents.ALL_ELEMENT_ID, the ID of a model element or a Selector.

The application model allows you to define mnemonics. A mnemonic appears as an underlined letter in the menu when the user presses and holds the Alt key and allows the user to quickly access menu entries by keyboard.

You specify mnemonics by prefixing the letter intended as the mnemonic with an ampersand (&) in the label definition. For example, if you use the label &Save, the S is underlined if the Alt key is pressed.

A good convention is to start IDs with the top-level package name of your project and to use only lowercase letters.

The IDs of commands and handlers should reflect their relationship. For example, if you implement a command with the com.example.contacts.command.show ID, use com.example.contacts.handler.show as the ID for the handler. If you have more than one handler for one command, add another suffix describing its purpose, for example, com.example.contacts.handler.show.details.

If you implement commonly used functions in your RCP application, for example, save or copy, use the existing platform IDs, as some Eclipse contributions expect these IDs to better integrate with the OS (for example, on macOS, preferences are normally placed under the first menu). A list of command IDs is available in org.eclipse.ui.IWorkbenchCommandConstants.

.Default IDs for commonly used commands

Open the Application.e4xmi file of your com.vogella.tasks.ui plug-in and select the Commands entry.

Via the Add…​ button you can create new commands. This selection is highlighted in the following screenshot.

The name and the ID are the important fields. Create the following commands.

Create the com.vogella.tasks.ui.handlers package for your handler classes.

All handler classes implement an execute() method annotated with @Execute.

Now, create the following classes by copying the above class.

Select the application-scoped Handlers entry in your application model and create the handlers from the following table for your commands. For handlers, the ID, command and class are the relevant fields.

Use the com.vogella.tasks.ui.handler prefix for all IDs of the handlers.

The application model editor shows both the name and the ID of the command. The class URI follows the bundleclass:// scheme, the table only lists the class name to stay readable. For example, the handler with the com.vogella.tasks.ui.handler.saveall ID uses the following class URI.

In your Application.e4xmi file select your TrimmedWindow entry in the model and flag the Main Menu attribute.

Assign the org.eclipse.ui.main.menu ID to your main menu.

Add two menus: one with the label File and another with the label Edit.

Also set the org.eclipse.ui.file.menu ID for the File menu. Use com.vogella.tasks.ui.menu.edit as ID for the Edit menu.

Add a Handled MenuItem model element to the File menu. This item should reference the Save command via the Command attribute.

Add a Separator after the Save menu item in your File menu. Also add a Handled MenuItem model element pointing to the Exit via the Command attribute.

Add all other commands you created to the Edit menu.

Afterwards, the menu structure should be like the following:

To test if your handler is working, change your ExitHandler class, so that it closes your application, once selected.

Validate that your handlers are called if you select them in the menu.

If you use the org.eclipse.ui.file.exit ID for your exit command, the Eclipse framework maps the menu entry to its default menu location on the macOS. If the exit entry is not visible in your menu, look for it in the default location on macOS (the application menu).