Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

Eclipse e4. This tutorial describes how to use an life cycle handler for Eclipse RCP application.

1. Eclipse application life cycle

1.1. Connecting to the Eclipse application life cycle

If an application is started or stopped, it typically requires some central setup or shutdown. For example you want to connect to a database or close the database connection.

The Eclipse platform allows you to register a class for predefined events of this life cycle. For example you can use these life cycle hooks to create a login screen or an interactive splash screen before the application is started.

1.2. Accessing application startup parameters

The IApplicationContext object which can be injected into your life cycle class contains information about the startup parameters of your application. You can access these parameters via the getArguments() method.

The access is demonstrated by the following snippet.

// access the command line arguments
String[] args = (String[])
    applicationContext.
            getArguments().
            get(IApplicationContext.APPLICATION_ARGS);

A parameter can be a flag or can have a parameter and a value. You can use a method similar to the following to evaluate this.

private String getArgValue(String argName, IApplicationContext appContext,
            boolean singledCmdArgValue) {
    // Is it in the arg list ?
    if (argName == null || argName.length() == 0)
        return null;

    if (singledCmdArgValue) {
        for (String arg : args) {
            if (("-" + argName).equals(arg))
                return "true";
        }
        return "false";
    }
    // not a singleCmdArgValue
    for (int i = 0; i < args.length; i++) {
        if (("-" + argName).equals(args[i]) && i + 1 < args.length)
            return args[i + 1];
    }
}

1.3. Close static splash screen

If you configured in your product configuration file that a static splash screen should be used, you can call the applicationRunning() method on the IApplicationContext object. You typically call this method if you want to replace the static splash screen with a dynamic screen developed with SWT.

1.4. How to implement a life cycle class

The org.eclipse.core.runtime.product extension point allows you to define a class as life cycle callback via a property.

The key for this property is lifeCycleURI and it points to the class via the bundleclass:// schema.

In the class you can annotate methods with the following annotations. These methods are called by the framework depending on the life cycle of your application.

Table 1. Life cycle annotations
Annotation Description

@PostContextCreate

Is called after the Application’s IEclipseContext is created, can be used to add objects, services, etc. to the context. This context is created for the MApplication class.

@ProcessAdditions

Is called directly before the model is passed to the renderer, can be used to add additional elements to the model.

@ProcessRemovals

Same as @ProcessAdditions but for removals.

@PreSave

Is called before the application model is saved. You can modify the model before it is persisted.

1.5. Example life cycle implementation

The following example shows how to register a class in your plugin.xml file as life cycle handler. To avoid that the code wraps we use testing as BundleSymbolicName and package, you need to replace that with the correct values for your life cycle class.

<plugin>

   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
        name="testing"
        application="org.eclipse.e4.ui.workbench.swt.E4Application">
         <property
            name="appName"
            value="testing">
         `
         <property
           name="applicationXMI"
           value="testing/Application.e4xmi">
         `
         <property
           name="applicationCSS"
           value="platform:/plugin/testing/css/default.css">
         `
         <property
           name="lifeCycleURI"
           value="bundleclass://testing/testing.LifeCycleManager">
         `
      </product>
   </extension>

</plugin>

The following class displays a Shell until the startup process of your application has finished. You could extend this example to show a progress bar.

package testing;

import org.eclipse.e4.core.services.events.IEventBroker;
import org.eclipse.e4.ui.workbench.UIEvents;
import org.eclipse.e4.ui.workbench.lifecycle.PostContextCreate;
import org.eclipse.equinox.app.IApplicationContext;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Shell;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventHandler;

// for a extended example see
// https://bugs.eclipse.org/382224

public class LifeCycleManager {
    @PostContextCreate
    void postContextCreate(final IEventBroker eventBroker, IApplicationContext context) {
        final Shell shell = new Shell(SWT.SHELL_TRIM);

        // register for startup completed event and close the shell
        eventBroker.subscribe(UIEvents.UILifeCycle.APP_STARTUP_COMPLETE,
                new EventHandler() {
                    @Override
                    public void handleEvent(Event event) {
                        shell.close();
                        shell.dispose();
                        eventBroker.unsubscribe(this);
                    }
                });
        // close static splash screen
        context.applicationRunning();
        shell.open();
    }
}

2. Exercise: Life cycle hook and a login screen

In this exercise you create a splash screen which allows the user to enter his or her credentials. This assumes that you have created a PasswordDialog class which allows the user to enter this user and password.

2.1. Create a new class

The following development is done again in the com.example.e4.rcp.todo plug-in.

Create the com.example.e4.rcp.todo.lifecycle package and add the following class.

package com.example.e4.rcp.todo.lifecycle;

import org.eclipse.e4.ui.workbench.lifecycle.PostContextCreate;
import org.eclipse.equinox.app.IApplicationContext;
import org.eclipse.jface.window.Window;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.widgets.Display;
import org.eclipse.swt.widgets.Monitor;
import org.eclipse.swt.widgets.Shell;

import com.example.e4.rcp.todo.dialogs.PasswordDialog;

// for a extended example see
// https://bugs.eclipse.org/382224
public class Manager {
    @PostContextCreate
    void postContextCreate(IApplicationContext appContext, Display display) {
        final Shell shell = new Shell(SWT.SHELL_TRIM);
        PasswordDialog dialog = new PasswordDialog(shell);

        // close the static splash screen
        appContext.applicationRunning();

        // position the shell
        setLocation(display, shell);

        if (dialog.open() != Window.OK) {
            // close the application
            System.exit(-1);
        }
    }

    private void setLocation(Display display, Shell shell) {
        Monitor monitor = display.getPrimaryMonitor();
        Rectangle monitorRect = monitor.getBounds();
        Rectangle shellRect = shell.getBounds();
        int x = monitorRect.x + (monitorRect.width - shellRect.width) / 2;
        int y = monitorRect.y + (monitorRect.height - shellRect.height) / 2;
        shell.setLocation(x, y);
    }
}
The life cycle annotations are not yet released as official API.

2.2. Register life cycle hook

Register the Manager class as life cycle handler in your plugin.xml file.

For this, open the plugin.xml file of your application plug-in and select the Extensions tab.

Open the org.eclipse.core.runtime.products extension, right click on the existing entry and create a new property.

Lifecycle registration in the product extension part 1

Enter lifeCycleURI as name for the property and use bundleclass://com.example.e4.rcp.todo/com.example.e4.rcp.todo.lifecycle.Manager as the value.

Life cycle registration in the product extension part 1

The following snippet shows the resulting plugin.xml file.

<plugin>
   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
        name="to-do"
        application="org.eclipse.e4.ui.workbench.swt.E4Application">
         <property
               name="appName"
               value="to-do">
         `
 <property
    name="lifeCycleURI"
    value=
"bundleclass://com.example.e4.rcp.todo/com.example.e4.rcp.todo.lifecycle.Manager">
  `
  <!-- other properties omitted -->
      </product>
   </extension>

</plugin>

2.3. Validating

Start your application. The login dialog should get displayed and your application should be started after the user selects the Login button.

3. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book.

4. About this website

5. Eclipse 4

5.1. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2017 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.