Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

Eclipse Launcher Framework. This tutorial describes how the define custom launcher for additional programs. In this tutorial Eclipse 4.3 is used. Level of this tutorial: Advanced

1. Eclipse Launching Framework

The Eclipse IDE supports launching of other programs. Launching in this context is defined as running or debugging a program from within the Eclipse IDE. A launcher is a set of Java classes in an Eclipse plug-in that performs launching.

The framework allows defining launch configuration types which defines how launch configuration are created.

The org.eclipse.debug.core plug-in is responsible for of creating and persisting launch configurations on behalf of the configuration type and org.eclipse.debug.ui provides the base functionality to display and change an existing launch configuration.

2. Launch configuration in general

The easiest way to create a launch configuration is using the Run Configuration…​ dialog. This dialog can be accessed in several ways.

  • By typing Run Configurations…​ in the Quick Access

  • By holding Ctrl while pressing the green launch button.

    run exc
  • By using the drop down menu of the green launch button

    run exc

    and clicking on Run Configurations…​ in the menu.

In the Run Configuration…​ you can choose between different launch configuration types:

run configurations

How to create new launch configurations is described within the picture above.

2.1. Export a launch configuration

Those launch configurations can also be exported to a *.launch file. You can reach the export wizard via export command in the file menu or by typing Export (Launch Configuration) in the Quick Access.

export launch configuration

When pressing Next you can choose, which launch configuration you want to export. You can also define a location to store the *.launch file.

launch configuration export wizard

The exported Eclipse Application Launch Configuration.launch file looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<launchConfiguration type="org.eclipse.pde.ui.RuntimeWorkbench">
<booleanAttribute key="append.args" value="true"/>
<booleanAttribute key="askclear" value="true"/>
<booleanAttribute key="automaticAdd" value="true"/>
<booleanAttribute key="automaticValidate" value="false"/>
<stringAttribute key="bootstrap" value=""/>
<stringAttribute key="checked" value="[NONE]"/>
<booleanAttribute key="clearConfig" value="false"/>
<booleanAttribute key="clearws" value="false"/>
<booleanAttribute key="clearwslog" value="false"/>
<stringAttribute key="configLocation" value="${workspace_loc}/.metadata/.plugins/org.eclipse.pde.core/Eclipse Application Launch Configuration"/>
<booleanAttribute key="default" value="true"/>
<booleanAttribute key="includeOptional" value="true"/>
<stringAttribute key="location" value="${workspace_loc}/../runtime-EclipseApplication"/>
<booleanAttribute key="org.eclipse.jdt.launching.ATTR_USE_START_ON_FIRST_THREAD" value="true"/>
<stringAttribute key="org.eclipse.jdt.launching.JRE_CONTAINER" value="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
<stringAttribute key="org.eclipse.jdt.launching.PROGRAM_ARGUMENTS" value="-os ${target.os} -ws ${target.ws} -arch ${target.arch} -nl ${target.nl} -consoleLog"/>
<stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.pde.ui.workbenchClasspathProvider"/>
<stringAttribute key="org.eclipse.jdt.launching.VM_ARGUMENTS" value="-Xms40m -Xmx512m"/>
<stringAttribute key="pde.version" value="3.3"/>
<stringAttribute key="product" value="org.eclipse.sdk.ide"/>
<booleanAttribute key="show_selected_only" value="false"/>
<stringAttribute key="templateConfig" value="${target_home}/configuration/config.ini"/>
<booleanAttribute key="tracing" value="false"/>
<booleanAttribute key="useCustomFeatures" value="false"/>
<booleanAttribute key="useDefaultConfig" value="true"/>
<booleanAttribute key="useDefaultConfigArea" value="true"/>
<booleanAttribute key="useProduct" value="true"/>
</launchConfiguration>

As you can see your launch configuration is stored in a XML format, which contains the specific settings of your custom launch configuration.

2.2. Import a launch configuration

The exported launch configuration can of cause be imported as well. You can reach the import wizard via import command in the file menu or by typing Import (Launch Configuration) in the Quick Access.

import launch configuration

When pressing Next you can look for a *.launch file in your file system, and import it.

launch configuration import wizard

After we successfully imported a certain *.launch file, we can choose and run this launch configuration with the Run Configuration…​ dialog.

3. How a launch can be triggered

Three different ways to trigger a launch exist.

  • Pass a launch configuration to an ILaunchConfigurationDelegate, which runs the launch configuration

  • Use an ILaunchShortcut and determine with an IEditorPart how a launch should be done

  • Use an ILaunchShortcut and determine with an ISelection how a launch should be done

3.1. Creating a new launch configuration type

 The org.eclipse.debug.core plugin provides the org.eclipse.debug.core.launchConfigurationTypes extension point, where a new launch configuration type can be added. The extension point can be configured as follows.

<extension point="org.eclipse.debug.core.launchConfigurationTypes">
    <launchConfigurationType
        name="Example launch"
        delegate="com.example.ExampleLaunchConfigurationDelegate"
        modes="run, debug"
        id="com.example.launchConfigurationType">
    </launchConfigurationType>
</extension>

The different modes are ILaunchManager.RUN_MODE, ILaunchManager.DEBUG_MODE and ILaunchManager.PROFILE_MODE. You can set one or more of these modes, as depicted in the programlisting above. The delegate must be an implementation of the ILaunchConfigurationDelegate interface, which contains just one method. This method is responsible for the actual launch. The ILaunchConfiguration contains launching attributes, which can be read by using one the its getAttribute methods. Therefore we also specify an interface with key constants for the custom attributes:

public interface SampleLaunchConfigurationAttributes {

    public static final String CONSOLE_TEXT = "com.vogella.custom.launcher.console.text";
}

The LaunchConfigurationDelegate implementation, which works with this attribute may look like this:

public class SampleLaunchConfiguration extends LaunchConfigurationDelegate {

    @Override
    public void launch(ILaunchConfiguration configuration, String mode, ILaunch launch, IProgressMonitor monitor)
            throws CoreException {
        String attribute = configuration.getAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT, "Simon says \"RUN!\"");
        System.out.println(attribute);
    }

}

Usually a ILaunchConfigurationDelegate is invoked by the UI of org.eclipse.debug.ui, which is covered in Launch Configuration UI.

3.2. Using the ILaunchShortcut for ISelections and IEditorParts

In some cases, one would rather create a default launch configuration from an ISelection or an IEditorPart, than manually configuring a launch configuration. With this approach it is up to the programmer to determine how a launch should be done according the current ISelection or IEditorPart. Such an ILaunchShortcut can be defined with the org.eclipse.debug.ui.launchShortcuts extension point.

<extension
    point="org.eclipse.debug.ui.launchShortcuts">
    <shortcut
        class="com.examole.launcher.LaunchShortcut"
        icon="icons/vogella.png"
        id="com.example.sample.shortcut"
        label="Sample Shortcut"
        modes="run, debug">
        <contextualLaunch>
            <enablement>
                <with
                    variable="selection">
                    <count
                        value="+">
                    </count>
                </with>
            </enablement>
        </contextualLaunch>
    </shortcut>
</extension>

The referenced LaunchShortcut class must implement ILaunchShortcut.

public class LaunchShortcut implements ILaunchShortcut {

    @Override
    public void launch(ISelection selection, String mode) {
        System.out.println("Selection: " + mode);
    }

    @Override
    public void launch(IEditorPart editor, String mode) {
        System.out.println("Editor: " + mode);
    }

}

After implementing this, you can run the Sample Shortcut from a editor’s popup menu or on a ISelection, such as a Java class file.

run as sample shortcut

4. Launch Configuration UI

The  org.eclipse.debug.ui plugin provides a user interface for the launch configurations.

A popular example for java developers is the java launch configuration dialog.

sample java application launch config ui

Previously we created a launch configuration delegate and in order run it from the UI, we can use the org.eclipse.debug.ui.launchConfigurationTabGroups extension point.

<extension
    point="org.eclipse.debug.ui.launchConfigurationTabGroups">
    <launchConfigurationTabGroup
        class="com.example.VogellaTabGroup"
        id="com.example.launchConfigurationTabGroup"
        type="com.example.launchConfigurationType">
    </launchConfigurationTabGroup>
</extension>

Here we reference to the com.example.launchConfigurationType, which we previously created.

Before we implement the tab group, we define a custom AbstractLaunchConfigurationTab, which will be placed on the tab group.

public class SampleTab extends AbstractLaunchConfigurationTab {

    private Text text;

    @Override
    public void createControl(Composite parent) {

        Composite comp = new Group(parent, SWT.BORDER);
        setControl(comp);

        GridLayoutFactory.swtDefaults().numColumns(2).applyTo(comp);

        Label label = new Label(comp, SWT.NONE);
        label.setText("Console Text:");
        GridDataFactory.swtDefaults().applyTo(label);

        text = new Text(comp, SWT.BORDER);
        text.setMessage("Console Text");
        GridDataFactory.fillDefaults().grab(true, false).applyTo(text);
    }

    @Override
    public void setDefaults(ILaunchConfigurationWorkingCopy configuration) {
    }

    @Override
    public void initializeFrom(ILaunchConfiguration configuration) {
        try {
            String consoleText = configuration.getAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT,
                    "Simon says \"RUN!\"");
            text.setText(consoleText);
        } catch (CoreException e) {
            // ignore here
        }
    }

    @Override
    public void performApply(ILaunchConfigurationWorkingCopy configuration) {
        // set the text value for the CONSOLE_TEXT key
        configuration.setAttribute(VogellaLaunchConfigurationAttributes.CONSOLE_TEXT, text.getText());
    }

    @Override
    public String getName() {
        return "Vogella sample launch tab";
    }

}

With this tab we can set our SampleLaunchConfigurationAttributes.CONSOLE_TEXT attribute to the ILaunchConfiguration.

In the com.example.SampleTabGroup, we can use existing AbstractLaunchConfigurationTab implementations, like the CommonTab, or the SampleTab from above.

public class SampleTabGroup extends AbstractLaunchConfigurationTabGroup {

    @Override
    public void createTabs(ILaunchConfigurationDialog dialog, String mode) {
        setTabs(new ILaunchConfigurationTab[] { new SampleTab() ,new CommonTab()});
    }

}

A specific icon for the launch configuration can be defined by using the org.eclipse.debug.ui.launchConfigurationTypeImages extension point.

<extension
        point="org.eclipse.debug.ui.launchConfigurationTypeImages">
    <launchConfigurationTypeImage
            id="com.example.ui.launch.launchconfigurationtypeimage"
            configTypeID="com.example.launchConfigurationType"
            icon="icons/full/obj16/vogella.png">
    </launchConfigurationTypeImage>
</extension>

The result will look similar to this:

vogella launch ui

5. About this website

6. Eclipse Launcher Framework resources

6.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.