The Eclipse IDE provides multiple downloads which can be used to develop Eclipse based applications and plug-ins. The most commonly used are:

Download either one of them. The packages include a Java runtime, no additional download is needed for them.

We describe two alternatives:

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

Use the settings similar to the following screenshots.

Press Next.

Press Next.

Press Next.

On the last wizard page, select the Create sample content (parts, menu etc.) flag. Via this flag you configure that the generated application has example content, e.g., a view 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 launch your Eclipse application by pressing the Launch an Eclipse application hyperlink. This selection is highlighted in the following screenshot.

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

If you see an empty window, you pressed Press Finish after selecting the template or forgot to select the Create sample content flag in the last tab.

To fix that, delete the generated plug-in and perform the creation again, this time selecting the correct values in Exercise: Create an RCP application with the wizard.

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

The following table describes the supported URI patterns. The example assumes that the bundle is called test to have a short name.

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

An example for 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 gives 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 in the application during runtime of the application, are written back to the model. For example, if the user positions 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 which 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 Featurename is a link to the model element which you want to extend. The following table lists some Featurename values and their purposes.

A processor allows contributing to the model via program code. This enables the dynamic creation of model elements during the start of the application.

The usage of model fragment and model processors is explained later in https://learn.vogella.com/courses/rich-client-platform once you learned about menu, command and handlers and the Eclipse services.

Create a new plug-in project via the File  New  Other…​  Plug-in Development  Plug-in Project menu entry with the following name:

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

On the next wizard page ensure the following settings are made:

Press the Finish button.

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

Open the project and ensure that no Java classes were created in the src folder.

In the manifest editor switch to the Dependencies tab and ensure that there are no entries.

Create a new feature project called 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 called 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 called 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 0.0.1 (or any other three numbers separated by dots) as this is required for the command line build. Also ensure that you have select 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 result should look similar to the following screenshot.

Switch to the Configuration tab in the product editor and press the Add Recommended…​ button. These settings are for example used by the Maven/Tycho build system, hence 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 an ID with the taskmanager suffix, 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 undesired during development, as the latest state from the application model file should be used. To ensure that always the latest version of your application model is used, add the following parameter to your product configuration file.

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

Your command line build which you configure later should create a executable named Tasksman. Switch to the Launching tab and 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, which 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 the usage of classes from other plug-in.

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 plug-ins as dependencies:

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

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 plug-ins as dependencies to your contribute.parts plug-in.

Also add the following package dependencies.

Set the Activate this plug-in when one of its classes is loaded flag in the MANIFEST. This enables the registration of the fragment via the MANIFEST.MF

Create the following class.

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

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

Press the Finish button.

The fragment creation wizard also adds the Model-Fragment key 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 code, the versions have been removed in this listing, as the versions you see 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 coding:

Now switch to the Supplementary tab and add the following tag:

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

As you add a part descriptor, this element will not be visible in the RCP application.

Add the Eclipse model spy to your runtime application and ensure that you see the part descriptor. Optional create a new handler which opens a new part based on this part descriptor. This can be done similar to the implementation of the editor per task.

The programming model in Eclipse supports constructor, method and field injection according to the Java Specification Request 330 (JSR330). Eclipse also defines additional annotations for the purpose of dependency injection. The most important annotations are covered in Annotations to define class dependencies in Eclipse, other more special annotations are covered in their corresponding chapters.

The Eclipse dependency framework ensures that the key and the type of the injected object is correct. For example, if you specify that you want to have an object of type Todo for the "xyz" key, as shown in the following field declaration, the framework will only inject an object if it finds one with an assignable type.

The following table gives an overview of dependency injection related annotations based on JSR330 and the Eclipse specific ones.

The Eclipse runtime creates objects for the Java classes referred by the application model. During this instantiation the Eclipse runtime scans the class definition for annotations. Based on these annotations the Eclipse framework performs the injection.

Eclipse does not automatically perform dependency injection on objects which are created in your code with the new operator.

The Eclipse framework tracks which object expressed a dependency to which key and type. If the value to which a key points changes, the Eclipse framework re-injects the new value in the object which expressed a dependency to the corresponding type. This means applications can be freed 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 will inject the new value.

The re-injection only works on methods and fields which are marked with @Inject. It will not work on parameters injected into constructors and methods which are marked with @PostConstruct, as these methods are only executed 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 dynamically queries for a fitting OSGi service in the OSGi registry.

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

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 key. The value (to which the key points) can be injected into other objects. But unlike a map, the Eclipse context is hierarchical and can also 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 to a Composite object via a field declaration similar to: @Inject Composite parent; Since parts have different local contexts they can receive different objects of the type Composite.

Currently the following model elements implement the MContext interface and therefore have their own context:

The Eclipse framework creates the context hierarchy based on the application model during the start process. By default, it places certain objects under predefined keys into the context, e.g., services to control the Eclipse framework functionality.

The model objects and the created objects based on the class URI attributes are created by the Eclipse platform. For each model element with a custom context the Eclipse framework determines which objects should be available in the local context of the model object. If required, it also creates the required Java objects referred by the Class URI property of the model elements. This is for example the case if a part is 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 which were created with the related Eclipse functionality (for example by the Eclipse dependency injection framework) are updated with the new values.

Objects in the context are persisted in memory (transient), i.e., once the application is stopped the context gets destroyed.

As described in On which objects does Eclipse perform dependency injection? an object which 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 fitting 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 main context has been reached.

As you learn in later chapters the Eclipse context is not the only possible source of objects which can get injected. Other examples which are covered later 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 a part via: @Inject MPart part;

The Eclipse framework creates several objects in the context. These are:

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 which 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 would allow you to track the current 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.

With the @Active annotation you can track values in the current active branch of a child element. Whenever the active branch changes and the value of the referred key changes this value is re-injected into the object which uses the @Active annotation.

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

The Eclipse dependency injection functionality 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 DI 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 you can interact with the framework from your code. The API also defines the interaction of application objects created or controlled by 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 which defines methods to be implemented.

In the example of the toolbar button the method might be called execute() and the framework knows that this method must be called once the button is clicked.

API definition via inheritance is a simple way to define an API, but it also 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 as such an update may affect clients. This is why the Eclipse 4.x does not use this approach anymore.

The Eclipse 4.x platform API is based on annotations, e.g., annotations are used to 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, @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 life cycle which are covered in the respective chapters.

It is recommended to construct the user interface of a part in a method annotated with the @PostConstruct annotation. It would also be possible to create the user interface in the constructor, but this is not recommended as 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 the following: Unable to process "TodoOverviewPart#createControls()": no actual value was found for the argument "Composite"., ensure that your import statement is correct.

You can also create objects using DI and make them available for other objects by placing them in the IEclipseContext. In case you want to use DI for the creation of your custom objects you can use the ContextInjectFactory as demonstrated in this example.

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 via the application model. These entries can be positioned at various places. You can, for example, add a menu to a window or a part. Each element define, directly or indirectly, one or several links to a class which is responsible for the execution. These classes are responsible for the behavior once the menu or toolbar entry is selected. Such a class is called handler class.

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

The usage of the commands and handlers model element is optional. You can use the Direct MenuItem or a Direct ToolItem model elements. These entries define a reference to a class (handler class). An instance of this handler class is created by the framework and its annotated methods are called by the framework if necessary. Menus and toolbars support separators.

A command is a declarative description of an abstract action which can be performed, for example, save, edit or copy.

A command is independent from its implementation details. The Eclipse framework does not provide standard commands, e.g., 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 the usage of commands over the usage of direct (menu or tool) items. Using commands together with handlers allows you to define different handlers for different scopes (applications or part) and you can define key bindings for the handler’s associated commands.

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

The following example demonstrates the implementation of a handler class.

A handler instance does not have its own Eclipse context ( IEclipseContext). It is executed with the Eclipse context of the active model element which has a Eclipse context. In most common cases this is the context of the active part.

All required parameters should be injected into the method annotated with @Execute, as you want the handler class to 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 model element.

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

A method annotated with @CanExecute is called by the framework, if a change in the Eclipse context happens. For example, if you select a new part. If the method returns false, the framework disables any menu and tool items that point to that command.

You can request the re-evaluation of the @CanExecute methods by sending out an event via the event broker.

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 to be the mnemonic with an ampersand (&) in the label definition. For example, if you use the label &Save, the S will be 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 lower case letters.

The IDs of commands and handlers should reflect their relationship. For example, if you implement a command with the com.example.contacts.commands.show ID, you should 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 to it, describing its purpose, e.g., com.example.contacts.handler.show.details.

In case you implement commonly used functions in your RCP application, e.g., save, copy, you should use the existing platform IDs, as some Eclipse contributions expect these IDs to better integrate with the OS (e.g., on Mac OS, preferences are normally placed under the first menu). A more complete list of command IDs is available in org.eclipse.ui.IWorkbenchCommandConstants.

Open the Application.e4xmi file of your com.vogella.tasks.ui plug-in and select the Commands entry. This selection is highlighted in the following screenshot.

Via the Add…​ button you can create new commands. 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.

Create now 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 the definition of handlers the ID, command and class are the relevant information.

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:// schema, the table only defines the class name to make the table more readable. For example, for the handler with the com.vogella.tasks.ui.handler.saveall id uses the following entry to point to his handler class.

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 name "File" and the other one with the name "Edit" in the Label attribute.

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 point to the Save command via the Command attribute.

Add a Separator after the Save: menu item into your File. 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.

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

Validate that your save 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 you don’t see your exit menu, in its defined position, check this location.