blob: c10d077b25ac4219588ee2710b278e1bddd12141 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="Author" content="Joe Szurszewski">
<title>We Have Lift-off: The Launching Framework in Eclipse</title>
<link type="text/css" rel="stylesheet" href="../../default_style.css">
<body link="#0000ff" vlink="#800080">
<div align="right"> &nbsp; <font face="Times New Roman, Times, serif" size="2">Copyright
&copy; 2003 International Business Machines Corp.</font>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<td align="LEFT" valign="TOP" bgcolor="#0080C0"> <b><font face="Arial,Helvetica" color="#FFFFFF">&nbsp;Eclipse
Corner Article</font></b> </td>
<div align="left">
<img src="images/Idea.jpg" height="86" width="120" align="CENTER">
<h1 align="CENTER"> We Have Lift-off: The Launching Framework in Eclipse </h1>
The ability to launch (run or debug) code under development is fundamental to
an IDE. But because Eclipse is more of a tools platform than a tool itself,
Eclipse's launching capabilities depend entirely on the current set of installed
plug-ins. This article describes the API available to build launching plug-ins
and works through developing an example launcher using this API.
<p> <b>By Joe Szurszewski, IBM OTI Labs</b><br>
<font size="-1">January 8, 2003</font></p>
<hr width="100%">
To get the most out of this article, the reader should have a basic understanding
of the Eclipse plug-in architecture and the structure of <code>plugin.xml</code>
files. In addition, some knowledge of Java and Java terminology (VM, classpath,
etc.) is helpful, though not necessary.
<h2>In the beginning, there was nothing </h2>
<p>For purposes of this article, <i>launching</i> is defined as running or debugging
a program from within Eclipse, and a <i>launcher</i> is a set of Java classes
that live in an Eclipse plug-in that performs launching. As with most things
in Eclipse, there is no 'built-in' launching functionality. The base Eclipse
workbench can't launch a thing. It is only through plug-ins that Eclipse gains
the ability to launch. The Eclipse SDK does ship with a set of useful launchers
for launching local Java applications &amp; Java applets, connecting to remote
Java applications, launching JUnit test suites and starting an Eclipse workbench,
but if none of these satisfy your needs and you can't find a plug-in someone
else has written to do the job, you will need to write your own launcher. </p>
<h2>A little history</h2>
<p>Prior to 2.0, launching in Eclipse was somewhat inflexible and decentralized.
For these reasons and many others, the launching framework was overhauled for
2.0. The primary issues addressed were:</p>
<li>Allow developers to easily contribute launchers that are tightly integrated
with the platform.</li>
<li>Break the launcher/resource dependency. Previously, launchers only worked
on workspace resources.</li>
<li>Centralize the collection of launch-related attributes.</li>
<li>Allow users to save sets of launching attributes for reuse.</li>
<p>The downside of all these improvements is that there is no backward compatibility.
Eclipse 1.0 plug-ins that do launching will have to be reworked for 2.0. However,
such conversions are relatively painless, and should result in much improved
Let there be framework
<p> If you've decided to write your own launcher, you're in luck. Eclipse 2.0
plug-in developers have a rich API at their disposal to build plug-ins with
launching behavior. In 2.0, launching is centered around two main entities,
<b>LaunchConfigurations</b> and <b>LaunchConfigurationTypes</b>. At the simplest
level, LaunchConfigurationTypes are cookie cutters, and LaunchConfigurations
are the cookies made from these cookie cutters. When you as a plug-in developer
decide to create a launcher, what you are really doing is creating a specific
kind of cookie cutter that will allow your users to stamp out as many cookies
as they need. In slightly more technical terms, a LaunchConfigurationType (henceforth,
a 'config type') is an entity that knows how to launch certain types of launch
configurations, and determines what the user-specifiable parameters to such
a launch may be. Launch configurations (henceforth, 'configs') are entities
that contain all information necessary to perform a specific launch. For example,
a config to launch a HelloWorld Java application would contain the name of the
main class ('HelloWorld'), the JRE to use (JDK1.4.1, for example), any program
or VM arguments, the classpath to use and so on. When a config is said to be
'of type local Java Application', this means that the local Java application
cookie cutter was used to make this config and that only this config type knows
how to make sense of this config and how to launch it. </p>
<h2>Configs and working copies</h2>
<p> Plug-in developers don't need to directly concern themselves with the launch
configuration lifecycle. Once you've implemented a config type, the launching
infrastructure contributed by the Debug core plug-in (<code>org.eclipse.debug.core</code>)
takes care of creating and persisting configs on behalf of the config type,
and infrastructure provided by the Debug UI plug-in ( <code>org.eclipse.debug.ui</code>)
provides a dialog to manage configs (the 'LaunchConfigurationDialog'), as well
as other launching-related UI.</p>
<p>However, plug-in developers do need to know how to interact with configs. All
config objects implement the <code>org.eclipse.debug.core.ILaunchConfiguration</code>
interface which defines methods for retrieving information about the config,
but no methods for changing the config. This is because objects implementing
<code>ILaunchConfiguration</code> are immutable and cannot be changed. If you
wish to change a config, you must have a reference to an object that implements
the <code>org.eclipse.debug.core.ILaunchConfigurationWorkingCopy</code> interface.
This interface extends <code>ILaunchConfiguration</code>, but adds methods for
changing the contents of the config. The contents of a config consist of name/value
pairs called 'attributes'. An attribute specifies one discrete piece of information
about a config, for example the JRE to use when launching a Java-oriented config.
By looking at the API defined by <code>ILaunchConfiguration</code> and <code>ILaunchConfigurationWorkingCopy</code>,
you can see that attribute values must be one of 5 types:</p>
<li><code>java.util.List</code> (all elements must be of type <code>java.lang.String</code>)</li>
<li><code>java.util.Map</code> (all keys &amp; values must be of type <code>java.lang.String</code>)</li>
<p>This may seem limiting, but in practice, developers create <code>String</code>
mementos for complex data types and store these. </p>
<p> <img src="images/tip.gif" width="62" height="13"> <i>When referencing attribute
names in code, you should always use publicly available constants. This allows
other developers to access your attributes. </i></p>
<h2>Separating model and UI</h2>
<p> To use the launcher API, your plug-in must make some import declarations in
its <code>plugin.xml</code> file. If your plug-in declares a config type, it
<b>must</b> import <code>org.eclipse.debug.core</code>, and if your plug-in
declares anything related to launching UI, it <b>must</b> import <code>org.eclipse.debug.ui</code>.
In general, it is recommended that the UI and non-UI aspects of your launcher
be handled by two <i>different</i> plug-ins. Note that it is not required for
a launcher to have <i>any</i> associated UI. In this case, the launcher can
only be used programmatically from within code, not by a user (see the forthcoming
related article &quot;How to Launch Java Applications Programmatically&quot;
by Darin Wright). Even if your launcher has an associated UI, there may be times
when you or someone else wants to use your launcher programmatically. Without
a clean separation between UI &amp; non-UI code, a plug-in wishing to use your
launcher programmatically would have to import the standard UI plug-ins, which
may be inconvenient, inefficient or impossible. </p>
<h2>The Java applet example</h2>
<p>The rest of this article is concerned with developing a launcher for Java applets.
This launcher is actually part of the Eclipse SDK (as of version 2.1), so all
of the source code presented here can be viewed by downloading the SDK. The
non-UI parts of this launcher live in the <code>org.eclipse.jdt.launching</code>
plug-in, and the UI parts are contained in the <code>org.eclipse.jdt.debug.ui</code>
plug-in. Each XML declaration that follows is marked as being UI or non-UI in
nature. This is to help you separate out the UI components in launchers you
Declaring a launch configuration type
The first step in creating our applet launcher is declaring a
config type, as shown in the following snippet of XML from our
plug-in's <code>plugin.xml</code> file:
<h5> <u>Non-UI declaration</u> </h5>
&lt;extension point=&quot;org.eclipse.debug.core.launchConfigurationTypes&quot;&gt;
name=&quot;Java Applet&quot;
modes=&quot;run, debug&quot;
The most important part of this declaration is the
<code>delegate</code> attribute which specifies the
fully-qualified name of a class that implements the interface
The delegate is the brains of the launcher, and implements the
<code>launch()</code> method which launches a specified
<p> The <code>modes</code> attribute specifies one or both of <code>run</code>
&amp; <code>debug</code>. The debug infrastructure only supports these two modes
of launching, and to be useful, your config type must support at least one of
these. Among other things, this value tells the workbench where configs of your
type may appear in the UI. For example, if the launch configuration dialog is
opened in run mode, but your config type is for debug mode only, then your config
type and any associated configs will not appear. Note that if your config type
declares both modes, it is your delegate's responsibility in the <code>launch()</code>
method to handle both modes. </p>
<p>An optional attribute not present in the above declaration is <code>private</code>.
This is a boolean attribute that indicates whether the config type should appear
in the UI, if there is one. Setting this attribute to <code>true</code> effectively
makes your launcher usable for programmatic launching only. The default value,
if this attribute is omitted, is <code>false</code>.</p>
<p>Another optional attribute not shown above is <code>category</code>. This string-valued
attribute will be discussed later in the section on launch groups.</p>
<h2>Implementing a launch configuration type </h2>
<table border="1" cellspacing="0" bordercolor="#0000FF">
<td bgcolor="#FFFFCC" bordercolor="white">
<p> <b><font size="2">Source: <a href="">org.eclipse.jdt.internal.launching.JavaAppletLaunchConfigurationDelegate</a></font></b>
<p> As noted above, the work of implementing a config type boils down to creating
a delegate class that implements the interface <code>org.eclipse.debug.core.ILaunchConfigurationDelegate</code>.
The only method on this interface is: </p>
public void launch(ILaunchConfiguration configuration,
String mode,
ILaunch launch,
IProgressMonitor monitor) throws CoreException;
<p> The first argument, <code>configuration</code>, is the most important. This
specifies the config to be launched. The Debug UI framework ensures that your
delegate is never asked to launch a config of the wrong type, however there
is no such guarantee for programmatic launching, so you may want to verify the
type of the <code>config</code> argument. In simple terms, the job of the <code>launch()</code>
method is to extract all of the pertinent information from this config and then
act upon it. For our applet launcher, this information includes things such
as the name of the Applet class, the JRE to use, the width &amp; height of the
applet panel viewing area, the classpath to use and so on. Once this information
has been extracted from the config and checked for validity, it is used to first
generate an HTML file and then to launch an instance of the <code>appletviewer</code>
utility on this HTML file. </p>
<p> The <code>mode</code> attribute has a value of either ' <code>run</code>'
or ' <code>debug</code> ' . Once again, the Debug UI framework makes sure your
delegate is not asked to launch in a mode it can't handle, but with programmatic
launching, any developer can ask your delegate to do anything, so some sanity
checking is a good idea. </p>
<p> <img src="images/tip.gif" width="62" height="13"> <em>When specifying a launch
mode in code, you should never use a hard-coded <code>String</code>. Instead,
use one of the constants defined in <code>org.eclipse.debug.core.ILaunchManager</code>.</em>
<p> The third argument, <code>launch</code>, is the top-level debug model artifact
that represents a launch. This object is created before the <code>launch()</code>
method is called. The delegate's responsibility with respect to this argument
is to add the debug targets and/or processes that result from launching to it.
In our applet launcher, this is done inside the <code></code>
call. </p>
<p> The last argument, <code>monitor</code>, is the progress monitor you should
update during any long-running operations you perform. In addition, you should
periodically check this monitor to see if the user has requested that the launch
be canceled. This can be done via <code>monitor.isCanceled()</code>. Doing this
allows your users the chance to change their minds, which makes your launcher
much friendlier. Note that <code>monitor</code> may be <code>null</code> (for
example, during a programmatic launch). </p>
<p> The implementation of the <code>launch()</code> method for our applet launcher
delegate is made easier by that fact that the delegate extends <code>org.eclipse.jdt.launching.AbstractJavaLaunchConfigurationDelegate</code>.
This class provides common functionality that most Java-oriented launchers will
need. For example, it has methods to retrieve and verify Java-related config
attributes such as the main type, classpath, bootpath and VM. In addition, our
applet launcher takes advantage of some Java launching infrastructure in the
form of <code>org.eclipse.jdt.launching.IVMRunner</code>. The VMRunner's job
is simply to build a command line to launch the Java program, call <code>Runtime.exec()</code>
on this command line and add the resulting debug targets/processes to the ILaunch
object. The reason <code>IVMRunner</code> is an interface with several implementors
is that each VM type (1.1.x, 1.3/1.4, J9, etc.) has its own idiosyncrasies.
Also, there are different VMRunners for run &amp; debug modes. </p>
<p> <img src="images/tip.gif" width="62" height="13"> <em>If you are writing a
launcher that fires up a JVM, you should seriously consider making your delegate
extend <code>AbstractJavaLaunchConfigurationDelegate</code>. Also, you should
take advantage of the <code>IVMRunner</code> infrastructure as much as possible.</em>
<p>The following code fragment is taken from the <code>beginning of the launch()</code>
method of <code>JavaAppletLaunchConfigurationDelegate</code>:</p>
<pre><img src="images/tag_1.gif" width="24" height="13">&nbsp;String mainTypeName = verifyMainTypeName(configuration);
&nbsp;&nbsp;&nbsp;&nbsp;IJavaProject javaProject = getJavaProject(configuration);
<img src="images/tag_2.gif" width="24" height="13">&nbsp;IType type = JavaLaunchConfigurationUtils.getMainType(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mainTypeName, javaProject);
&nbsp;&nbsp;&nbsp;&nbsp;ITypeHierarchy hierarchy = type.newSupertypeHierarchy(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;new NullProgressMonitor());
&nbsp;&nbsp;&nbsp;&nbsp;IType javaLangApplet = JavaLaunchConfigurationUtils.getMainType(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;java.applet.Applet&quot;, javaProject);
<img src="images/tag_3.gif" width="24" height="13">&nbsp;if (!hierarchy.contains(javaLangApplet)) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;abort(&quot;The applet type is not a subclass of java.applet.Applet.&quot;);
<img src="images/tag_4.gif" width="24" height="13">&nbsp;IVMInstall vm = verifyVMInstall(configuration);
<img src="images/tag_5.gif" width="24" height="13">&nbsp;IVMRunner runner = vm.getVMRunner(mode);</pre>
<p>This code snippet is typical of the verification done by the <code>launch()</code>
<img src="images/tag_1.gif" width="24" height="13"> Use a framework method to
verify &amp; return the name of the 'main type', which in our case is the class
that extends <code> java.applet.Applet</code>.<br>
<img src="images/tag_2.gif" width="24" height="13"> Use a utility method to
return the <code>org.eclipse.jdt.core.IType</code> object for the Applet class.<br>
<img src="images/tag_3.gif" width="24" height="13"> Make sure that the specified
applet class really does extend <code>java.applet.Applet</code>.<br>
<img src="images/tag_4.gif" width="24" height="13"> Verify &amp; return the
<code>org.eclipse.jdt.launching.IVMInstall</code> object that corresponds to
the JRE specified in the configuration.<br>
<img src="images/tag_5.gif" width="24" height="13"> Ask the installed VM for
a VMRunner appropriate to the specified mode.</p>
<p>Further along in the <code>launch()</code> method is this snippet of code:</p>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;// Create VM config
<img src="images/tag_1.gif" width="24" height="13">&nbsp;VMRunnerConfiguration runConfig = new VMRunnerConfiguration(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;sun.applet.AppletViewer&quot;, classpath);
&nbsp;&nbsp;&nbsp;&nbsp;runConfig.setProgramArguments(new String[] {buildHTMLFile(configuration)});
&nbsp;&nbsp;&nbsp;&nbsp;String[] vmArgs = execArgs.getVMArgumentsArray();
&nbsp;&nbsp;&nbsp;&nbsp;String[] realArgs = new String[vmArgs.length+1];
&nbsp;&nbsp;&nbsp;&nbsp;System.arraycopy(vmArgs, 0, realArgs, 1, vmArgs.length);
&nbsp;&nbsp;&nbsp;&nbsp;realArgs[0] = javaPolicy;
<img src="images/tag_2.gif" width="24" height="13">&nbsp;runConfig.setVMArguments(realArgs);
<pre>&nbsp;&nbsp;&nbsp;&nbsp;// Bootpath
&nbsp;&nbsp;&nbsp;&nbsp;String[] bootpath = getBootpath(configuration);
<img src="images/tag_3.gif" width="24" height="13">&nbsp;runConfig.setBootClassPath(bootpath);
&nbsp;&nbsp;&nbsp;&nbsp;// Launch the configuration
&nbsp;&nbsp;&nbsp;&nbsp;this.fCurrentLaunchConfiguration = configuration;
<img src="images/tag_4.gif" width="24" height="13">&nbsp;, launch, monitor); </pre>
<p>This is the code that actually performs the launch:<br>
<img src="images/tag_1.gif" width="24" height="13"> Create a <code>VMRunnerConfiguration</code>,
which is just a convenience holder of various launch parameters. Notice the
program being launched is the <code>appletviewer</code> utility.<br>
<img src="images/tag_2.gif" width="24" height="13"> Resolve the VM arguments
and set them on the VMRunnerConfiguration.<br>
<img src="images/tag_3.gif" width="24" height="13"> Set the Java bootpath on
the VMRunnerConfiguration.<br>
<img src="images/tag_4.gif" width="24" height="13"> Ask the VMRunner to launch.
All information necessary to perform the launch is now contained in <code>runConfig</code>.
This method call will result in building a command line and passing it to <code>Runtime.exec()</code>.
If the launch mode was 'run', the resulting process is registered with the debug
infrastructure. If the launch mode was 'debug', the resulting process is used
to create a 'debug target', which is also registered. </p>
<p>On a Win32 machine, the command line built by the VMRunner to run a HelloWorld
applet with our applet launcher might look like:</p>
-classpath C:\TargetWorkspaces\eclipse\MyApplets
sun.applet.AppletViewer HelloWorldApplet1030633365864.html
<p> Debugging the same applet would result in the following command line: </p>
-classpath C:\TargetWorkspaces\eclipse\MyApplets
-Xdebug -Xnoagent
sun.applet.AppletViewer HelloWorldApplet1030634748522.html
<p> <img src="images/tip.gif" width="62" height="13"> <em>You can always see the
command line used to initiate a launch by right-clicking the resulting process
in the Debug View and selecting Properties. This is useful for debugging your
delegate.</em> </p>
<p> To summarize, implementing a config type (Java or otherwise) means implementing
the <code>launch()</code> method on your launch configuration delegate. This
method has 2 main tasks to perform: </p>
<li> Construct a command line and pass it to <code>Runtime.exec()</code> </li>
<li> Create debug targets/processes and add these to the ILaunch object </li>
<p> Note that the first task may sometimes <i>not</i> involve calling <code>Runtime.exec()</code>.
For example, the Remote Java Debug delegate does not need to execute anything
in the OS because the program to be debugged is already running (possibly on
another machine). In general though, if your delegate is launching something
under development in the Eclipse workspace, you will probably want to use <code>Runtime.exec()</code>.
<h2>Declaring a launch configuration type icon </h2>
<p> Now that we have a declared and implemented a config type, the next step is
to flesh out the various UI elements associated with the config type. First
up is an icon for the applet config type: </p>
<h5> <u>UI declaration</u></h5>
&lt;extension point=&quot;org.eclipse.debug.ui.launchConfigurationTypeImages&quot;&gt;
<p> Note that the <code>id</code> attribute is just a unique identifier, whereas
the <code>configTypeID</code> attribute should have the same value as the <code>id</code>
attribute for our config type declaration. Notice that the icon is declared
via a separate extension point instead of just being an attribute on the config
type declaration. This is in keeping with the goal of not forcing launcher contributors
to provide a UI.</p>
<h2>Implementing a launch configuration type icon </h2>
<p>There is no code to write when implementing a config type icon, you simply
need to create the icon. The icon should be 16x16, contain no more than 256
colors, and have a transparent background.</p>
Declaring a tab group
<p> The most important piece of UI to consider when developing a new launcher
is the 'tab group'. To understand how tab groups work, we need a little background
on the LaunchConfigurationDialog provided by the Debug UI plug-in. This dialog
(henceforth known as the 'LCD') is a central point for creating, managing, deleting
and launching configs of any config type. If you have used any 2.0 or later
version of Eclipse, you have probably seen the LCD: </p>
<img src="images/Screenshot1.gif" width="663" height="560">
The LCD is broken into two main regions:
<p> <img src="images/tag_1.gif" width="24" height="13"> The config tree shows
all configs currently defined in the workspace, grouped by config type. </p>
<img src="images/tag_2.gif" width="24" height="13"> The tabbed
folder lets users edit attributes of the config currently
selected in the tree. The contents of this tabbed folder are
specified when you declare a tab group.
The 6 tabs in the above figure show the launching attributes
for <b>HelloWorldApplet</b>. These same 6 tabs would appear if
either of the other two configs of type <b>JavaApplet</b> were
selected, though of course they would show different values.
If <b>InfiniteLoop</b> were selected, it would show a
<i>different</i> set of tabs because this config is of a
different config type. When you declare a tab group, you are
telling the LCD to use the tabs specified in your tab group
for configs of your config type. This makes perfect sense
because if your config type requires width &amp; height
attributes (for example) in order to launch properly, the only
way to get values for these attributes is via a set of tabs
that appear when a config of your type is selected in the LCD.
Another way to look at this is that if your config type
requires some attribute X in order to function, then somewhere
on a tab specified in your tab group, there better be some UI
widget that collects a value for X.
Here is the XML for declaring a tab group:
<h5> <u>UI declaration</u></h5>
&lt;extension point=&quot;org.eclipse.debug.ui.launchConfigurationTabGroups&quot;&gt;
<p> All that this declaration really does is associate a tab group implementation
(a class that implements the interface <code>org.eclipse.debug.ui.ILaunchConfigurationTabGroup</code>)
with a config type. Any time a config of the specified type is selected in the
LCD, the class named by the <code>class</code> attribute will be used to provide
the content of the tabbed folder.</p>
<h2>Implementing tab groups </h2>
<table border="1" cellspacing="0" bordercolor="#FFFFFF">
<td bgcolor="#FFFFCC" bordercolor="#0000FF">
<p> <b><font size="2">Source: <a href="">org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletTabGroup</a></font></b>
<p> The main job of a tab group is to specify the tabs that will appear in the
LCD and set their order. &nbsp;These tabs may have been specially written for
the&nbsp;particular config type in question, or they may be general purpose
tabs that appear for multiple config types. &nbsp;The tab group for our applet
launcher&nbsp;creates 6 tabs, of which 4&nbsp;already existed (<code>JavaArgumentsTab,
JavaJRETab, JavaClasspathTab, CommonTab</code>) and 2&nbsp;which were written
just for our applet launcher (<code>AppletMainTab </code>and<code> AppletParametersTab</code>):</p>
<pre>public void createTabs(ILaunchConfigurationDialog dialog, String mode) {
ILaunchConfigurationTab[] tabs = new ILaunchConfigurationTab[] {
new AppletMainTab(),
new AppletParametersTab(),
new JavaArgumentsTab(),
new JavaJRETab(),
new JavaClasspathTab(),
new CommonTab()
<p>A tab group is free to mix &amp;&nbsp;match any combination of existing and
custom-written tabs. &nbsp;The only proviso is that tabs you wish to reuse must
be in public (not internal) packages. &nbsp;In the simplest case, <i>all</i>
of the tabs would be preexisting tabs and the work of providing a UI for our
config type in the LCD would be done&nbsp;once we had defined a class similar
to <code>JavaAppletTabGroup</code>. &nbsp;</p>
<p><img src="images/tip.gif" width="62" height="13" border="0"> <i>If you are
implementing a tab group for a Java-oriented config type, you should consider
reusing some or all of the Java tabs in the <code>org.eclipse.jdt.debug.ui.launchConfigurations</code>
<p><img src="images/tip.gif" width="62" height="13" border="0"> <i><u>All</u>
tab groups should include <code>org.eclipse.debug.ui.CommonTab</code>. &nbsp;This
tab contains UI that allows users to make their configs 'local' or 'shared',
mark configs as 'favorites' and control perspective switching when launching.
&nbsp;By convention, this tab is the last tab in the tab group.</i></p>
<p>If you decide that you need to write one or more of your own tabs, you need
to understand the tab lifecycle defined by <code>org.eclipse.debug.ui.ILaunchConfigurationTab</code>,
an interface which all tabs must implement. &nbsp;There is a convenience abstract
class, <code>org.eclipse.debug.ui.AbstractLaunchConfigurationTab</code> that
implements this interface and provides useful implementations of many of its
methods. Whenever possible, you should extend this abstract class.</p>
<p>The first two events in a tab's life cycle are calls to <code>setLaunchConfigurationDialog(ILaunchConfigurationDialog)</code>and
<code>createControl()</code> in that order.&nbsp;The first simply notifies the
tab of the LCD object that owns it. Tabs make frequent calls to methods on the
LCD, so a&nbsp;tab needs to have a reference to it. &nbsp;The second method
creates&nbsp;the GUI widgetry for the tab and lays it&nbsp;out. &nbsp;</p>
<table border="1" cellspacing="0" bordercolor="#FFFFFF" width="503">
<td bgcolor="#FFFFCC" bordercolor="#0000FF"> <p> <a href=""><b><font size="2">Source:
<p>To illustrate the rest of the methods on <code>ILaunchConfigurationTab</code>,
the <code>AppletParametersTab</code> implementation will be discussed. This
class makes three field declarations you need to be aware of:</p>
<li> <code>private Text widthText;</code></li>
<li><code>private Text heightText;</code></li>
<li><code>private Text nameText;</code>
<p>where <code>Text</code> is the SWT text-field widget.</p>
<p>The three most important methods on a tab are the following 'value copying'
<ul type="disc">
<li><code>public void setDefaults(ILaunchConfigurationWorkingCopy configuration);</code></li>
<li><code>public void performApply(ILaunchConfigurationWorkingCopy configuration);</code></li>
<li><code>public void initializeFrom(ILaunchConfiguration configuration);</code></li>
<p>In general terms, the first two methods copy&nbsp;values from the tab to a
working copy,&nbsp;while the third method copies&nbsp;values from&nbsp;a working
copy&nbsp;to&nbsp;the tab. &nbsp;The <code>setDefaults()</code> method is called
when a new config is&nbsp;created. &nbsp;This method&nbsp;sets default values
for all attributes it understands on the working copy argument. &nbsp;This is
done differently depending on the nature of the attributes collected by the
tab. &nbsp;The <code>AppletMainTab</code> checks the current workbench selection
or active editor to determine default values for the Project &amp; Applet class
attributes. &nbsp;The <code>CommonTab</code> sets hard-coded defaults, and the
<code>JavaJRETab</code> sets the default JRE to be the JRE marked as the workbench
default in the Java preferences. </p>
<p>The <code>performApply()</code> method reads current values from the GUI widgets
on the tab and sets the corresponding attribute values on the working copy argument:</p>
<pre>public void performApply(ILaunchConfigurationWorkingCopy configuration) {
<p>The <code>initializeFrom()</code> method does the opposite of the <code>performApply()</code>
method. &nbsp;It reads attribute values out of the config argument, and sets
these values in the corresponding GUI widgets:</p>
<pre>public void initializeFrom(ILaunchConfiguration config) {
&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fWidthText.setText(Integer.toString(config.getAttribute(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IJavaLaunchConfigurationConstants.ATTR_APPLET_WIDTH, &quot;200&quot;)));
&nbsp;&nbsp;&nbsp;&nbsp;} catch(CoreException ce) {
&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_2.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fHeightText.setText(Integer.toString(config.getAttribute(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IJavaLaunchConfigurationConstants.ATTR_APPLET_HEIGHT, &quot;200&quot;)));
&nbsp;&nbsp;&nbsp;&nbsp;} catch(CoreException CE) {
&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_3.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fNameText.setText(config.getAttribute(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IJavaLaunchConfigurationConstants.ATTR_APPLET_NAME, &quot;&quot;));
&nbsp;&nbsp;&nbsp;&nbsp;} catch(CoreException CE) {
<p><img src="images/tag_1.gif" width="24" height="13"> Extract the value of the
width attribute from the config and put it in the corresponding <code>Text</code>
<img src="images/tag_2.gif" width="24" height="13"> Extract the value of the
height attribute from the config and put it in the corresponding <code>Text</code>
<img src="images/tag_3.gif" width="24" height="13"> Extract the value of the
name attribute from the config and put it in the corresponding <code>Text</code>
In all cases, if there is an error retrieving the attribute value, the <code>Text</code>
widget is filled with a default value.</p>
<p>Both <code>performApply(</code>) and <code>initializeFrom()</code> are&nbsp;called
frequently, for example, whenever the user selects a new tab. &nbsp;Thus, they
should not perform long-running operations.</p>
<p>The remaining methods on <code>ILaunchConfigurationTab</code> are also fairly
straightforward. The <code>isValid(ILaunchConfiguration)</code> method returns
<code>true</code> if all of the attributes in the tab currently have values
that permit launching, within the context of the specified config:</p>
<pre>public boolean isValid(ILaunchConfiguration launchConfig) {
&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Integer.parseInt(fWidthText.getText().trim());
&nbsp;&nbsp;&nbsp;&nbsp;} catch(NumberFormatException nfe) {
<img src="images/tag_2.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;setErrorMessage(&quot;Width is not an integer&quot;);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return false;
&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Integer.parseInt(fHeightText.getText()Trim());
&nbsp;&nbsp;&nbsp;&nbsp;} catch(NumberFormatException nfe) {
<img src="images/tag_2.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;setErrorMessage(&quot;Height is not an integer&quot;);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return false;
<img src="images/tag_3.gif" width="24" height="13">&nbsp;return true;
<p><img src="images/tag_1.gif" width="24" height="13"> The config can be launched
only when both the <code>width</code> &amp; <code>height</code> attributes have
valid integer values. <br>
<img src="images/tag_2.gif" width="24" height="13"> The appropriate response
to a validation failure is calling <code>AbstractLaunchConfigurationTab.setErrorMessage(String)</code>
with a description of the failure and returning <code>false</code>.<br>
<img src="images/tag_3.gif" width="24" height="13"> The other attribute values
this tab is responsible for cannot be checked for validity, so at this point
we declare the tab valid.</p>
<p> The <code>canSave()</code> method is similar to <code>isValid()</code>, and
returns <code>true</code> if all of the attributes in the tab have values that
permit saving. </p>
<p><img src="images/tip.gif" width="62" height="13" border="0"> <i>If you implement
your own tab, consider making it public API so that others can&nbsp;reuse it.</i></p>
<p>If you compare the API on <code>ILaunchConfigurationTabGroup</code> and <code>ILaunchConfiguration</code>,
you will see a number of similarities. In particular, the following methods
are common:</p>
<li> <code>public void initializeFrom(ILaunchConfiguration configuration);
<li><code>public void performApply(ILaunchConfigurationWorkingCopy configuration);
<li><code>public void setDefaults(ILaunchConfigurationWorkingCopy configuration);</code>
<li><code>public void launched(ILaunch launch);
<p>You will recognize the 3 'value copying' lifecycle methods for tabs, along
with <code>launched(ILaunch)</code> which is simply a callback that happens
when a successful launch has occurred. In most cases, the tab group is not interested
in these calls and simply forwards them on to its tabs. When this is true, you
should make your tab group extend <code>org.eclipse.debug.ui.AbstractLaunchConfigurationTabGroup</code>.
This abstract class implements these 4 methods to simply loop through all owned
tabs and make the corresponding call on each. The applet launcher tab group
extends this abstract class. However, there are situations when you might want
to implement some of these methods at the tab group level. Suppose you are reusing
someone else's tab that specifies a default value for an attribute you don't
like. You can change this default value and still reuse the tab by implementing
the <code>setDefaults()</code> method on your tab group to first call <code>setDefaults()</code>
on the tab in question (which sets the undesirable default value), then directly
set the attribute in question to the value you prefer. In this way, you 'override'
the one value you care about, while leaving the others as specified in the tab.</p>
<h2>Declaring launch shortcuts </h2>
<p> As useful as the LCD is, there are many times when users don't want to bother
with it. They simply want to launch a program. This is where 'launch shortcuts'
come in. A launch shortcut allows users to identify a resource in the workbench
(either via selection or the active editor) and launch that resource with a
single click <i>without</i> bringing up the LCD. Launch shortcuts are <i>not</i>
useful when a user needs to tweak launch configuration attributes because the
user gets no chance to set these. Launch shortcuts <i>are</i> useful when the
user is happy with default values for all config attributes and wants to launch
in a hurry. </p>
The following figure shows how launch shortcuts appear in the
<img src="images/Screenshot2.gif" width="685" height="355">
<p> <img src="images/tag_1.gif" width="24" height="13"> The 'Run As' sub-menu
of the 'Run' drop-down menu shows all config types that have registered a launch
shortcut in the current perspective. Selecting one of the 'Run As' sub-menu
choices activates the corresponding launch shortcut. </p>
<p> This is the XML to declare the applet launch shortcut: </p>
<h5> <u>UI declaration</u></h5>
&lt;extension point=&quot;org.eclipse.debug.ui.launchShortcuts&quot;&gt;
label=&quot;Java Applet&quot;
modes=&quot;run, debug&quot;&gt;
&lt;perspective id=&quot;org.eclipse.jdt.ui.JavaPerspective&quot;/&gt;
&lt;perspective id=&quot;org.eclipse.jdt.ui.JavaHierarchyPerspective&quot;/&gt;
&lt;perspective id=&quot;org.eclipse.jdt.ui.JavaBrowsingPerspective&quot;/&gt;
&lt;perspective id=&quot;org.eclipse.debug.ui.DebugPerspective&quot;/&gt;
<p> Though the screenshot showed only the 'Run' shortcuts, launch shortcuts apply
equally to both modes. The <code>modes</code> attribute specifies which of the
drop-down menus include the shortcut. In addition to being mode sensitive, launch
shortcuts can also be configured to only appear in certain perspectives. The
<code>perspective</code> sub-elements list each perspective in which the shortcut
will be available. Only those perspectives that make sense for a particular
shortcut should be specified. For example, specifying a C++ perspective for
the Java applet launcher wouldn't be generally useful. Following this rule of
thumb leads to better UI scalability.</p>
<h2>Implementing launch shortcuts </h2>
<table border="1" cellspacing="0" bordercolor="#0000FF" width="504">
<td bgcolor="#FFFFCC" bordercolor="#FFFFFF">
<p> <b><font size="2">Source: <a href="">org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletLaunchShortcut</a></font></b>
<p> The first step in implementing a launch shortcut is determining if you even
need to. &nbsp;Launch shortcuts are strictly conveniences that make user's lives
easier by allowing them to create a config, set all attributes to default values
and launch that config in a single mouse click. &nbsp;If you don't provide a
shortcut for your config type, users can always bring up the LCD 'manually',
create a config of the desired type and launch it. &nbsp; </p>
<p><img src="images/tip.gif" width="62" height="13"> <i>There are two ways to
bring up the LCD: (1) Choose Run... or Debug... from the drop-down menus to
bring up the LCD on the last launched config or (2) As of 2.1, you can Ctrl
click a favorite or history item in the drop-down menus to bring up the LCD
on the corresponding config.</i></p>
<p>Launch shortcut classes&nbsp;must implement the <code>org.eclipse.debug.ui.ILaunchShortcut</code>
interface. &nbsp;This interface defines two <code>launch()</code> methods: </p>
<ul type="disc">
<li> <code>public void launch(ISelection selection, String mode);</code> </li>
<li> <code>public void launch(IEditorPart editor, String mode);</code> </li>
<p> The only difference between them is how the entity to be launched is specified.
&nbsp;In the first method, it's via a workbench selection, in the second it's
as an editor part. &nbsp;Typically, both of these methods will defer the real
work of creating a config and launching it to a helper method once the entity
to be launched has been resolved:</p>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;public void launch(IEditorPart editor, String mode) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IEditorInput input = editor.getEditorInput();
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IJavaElement javaElement =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(IJavaElement) input.getAdapter(IJavaElement.class);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (javaElement != null) {
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;searchAndLaunch(new Object[] {javaElement}, mode);
<pre>&nbsp;&nbsp;&nbsp;&nbsp;public void launch(ISelection selection, String mode) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (selection instanceof IStructuredSelection) {
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;searchAndLaunch(((IStructuredSelection)selection).toArray(), mode);
&nbsp;&nbsp;&nbsp;&nbsp;protected void searchAndLaunch(Object[] search, String mode) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IType[] types = null;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (search != null) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;try {
<img src="images/tag_2.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;types = AppletLaunchConfigurationUtils.findApplets(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;new ProgressMonitorDialog(getShell()), search);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} catch (Exception e) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Handle exceptions */
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IType type = null;
<img src="images/tag_3.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (types.length == 0) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;getShell(), &quot;Applet Launch&quot;, &quot;No applets found.&quot;};
<img src="images/tag_4.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} else if (types.length &gt; 1) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;type = chooseType(types, mode);
<img src="images/tag_5.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} else {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;type = types[0];
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (type != null) {
<img src="images/tag_6.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;launch(type, mode);
&nbsp;&nbsp;&nbsp;&nbsp;protected void launch(IType type, String mode) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;try {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ILaunchConfiguration config = findLaunchConfiguration(type, mode);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (config != null) {
<img src="images/tag_7.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;config.launch(mode, null);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} catch (CoreException e) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Handle exceptions*/
<p><img src="images/tag_1.gif" width="24" height="13"> Both <code>launch()</code>
methods from the <code>ILaunchShortcut</code> interface defer the real work
to <code>searchAndLaunch()</code>. Notice that in the first <code>launch()</code>
method, we have to resolve the entity to launch from the editor, whereas in
the second, the selection contains the candidate entities to launch.<br>
<img src="images/tag_2.gif" width="24" height="13"> Since there may be more
than one candidate entity to launch, we first filter out any that aren't applets.<br>
<img src="images/tag_3.gif" width="24" height="13"> We handle the case of no
applets to launch by showing an informational dialog.<br>
<img src="images/tag_4.gif" width="24" height="13"> If there is more than one
applet available to launch, ask the user to choose one.<br>
<img src="images/tag_5.gif" width="24" height="13"> Otherwise, there's exactly
one applet.<br>
<img src="images/tag_6.gif" width="24" height="13"> If there's an applet to
launch, do so.<br>
<img src="images/tag_7.gif" width="24" height="13"> Launch a config corresponding
to the applet. The <code>findLaunchConfiguration()</code> method first attempts
to find an existing config for the applet. Failing this, a new config is created
and returned. Note that the actual launching happens by just calling <code>launch()</code>
on the config. </p>
<p>In most cases, a launch shortcut is maximally useful if it performs the following
steps: </p>
<ol type="1">
<li> Resolve something to launch from the specified selection or editor </li>
<li> Check to see if there is an existing config based on the resolved entity,
if there is launch it </li>
<li> Otherwise, create a new config and populate it with default attribute values,
except for those directly related to the resolved entity </li>
<li> Launch the new config </li>
<p> However, there is nothing in the <code>ILaunchShortcut</code> interface that
requires you to follow these steps. &nbsp;For example, you could create a launch
shortcut implementation that skipped step 2. &nbsp;This way, <i>every</i> time
the shortcut was invoked, a new config would be created. &nbsp;This would normally&nbsp;lead
to a flood of duplicate configs, however if the default value for an&nbsp;attribute
was somehow time-dependent, this could be useful. &nbsp;Another variation might
be to open the LCD on the newly created config. This might be necessary if some
attribute has no reasonable default value and must be specified by the user.
Note that even in this case, the shortcut saves time and keystrokes by creating
a config and populating most of its attributes with appropriate values. The
user only has to supply the required attribute(s), then click Run or Debug.</p>
<p> In summary, launch shortcuts are optional. &nbsp;If you choose to implement
one, you should consider making it as useful as possible to your users. This
might mean avoiding duplicate configs, or saving as many keystrokes as possible.
&nbsp;In the end though, the <code>ILaunchShortcut</code> contract is very flexible
and just&nbsp;provides a way to insert an action into a particular place in
the UI.</p>
<h2>Declaring a launch group</h2>
<p><img src="images/tip.gif" width="62" height="13"> <i>Most developers writing
launchers will not need to worry about 'launch groups', but they are covered
here for completeness. </i></p>
<p>Launch groups (introduced in Eclipse 2.1) are an organizational construct for
config types whose primary purpose is to provide a way to filter configs &amp;
configs types in the UI. Standard UI components supplied by the launching framework
such as the LCD are set up to always filter their contents with a single active
launch group. In addition, the workbench tracks separate launch histories for
each launch group. The Eclipse SDK provides two default launch groups, a standard
'Run' launch group and a standard 'Debug' launch group. When you open the LCD
by choosing 'Debug...' from the debug drop-down menu, you are actually asking
the LCD to open and display only configs that satisfy the filtering criteria
specified by the standard 'Debug' launch group. </p>
<p>The filtering criteria of a launch group are specified in two pieces, a <code>mode</code>
attribute (run or debug) and an optional <code>category</code> attribute. Remember
that the config type declaration also included an optional <code>category</code>
attribute. The purpose of this attribute is now clear - it serves to associate
config types with launch groups. If a launch group specifies a value for its
<code>category</code> attribute, then only config types that specify the same
value for their <code>category</code> attributes are considered to belong to
that launch group. The <code>mode</code> attribute serves to further refine
which configs &amp; config types belong to a specific launch group. Recall that
config types declare their support for one or both of the allowable modes, run
and debug. A launch group must specify exactly one of these modes in its declaration.
We can now specify the complete filtering algorithm used to apply launch groups
to UI elements such as the LCD:</p>
<li> A config type is visible if it supports the mode of the currently active
launch group <i><b>and</b></i> specifies the same category as the currently
active launch group.</li>
<li> A config is visible if its config type is visible.</li>
<p>This is the XML declaration of the standard 'Run' &amp; 'Debug' launch groups:</p>
<h5> <u>UI declaration</u></h5>
<pre>&lt;extension point = &quot;org.eclipse.debug.ui.launchGroups&quot;&gt;
id = &quot;org.eclipse.debug.ui.launchGroup.debug&quot;
mode = &quot;debug&quot;
label =&quot;Debug&quot;
image = &quot;icons/full/ctool16/debug_exc.gif&quot;
bannerImage = &quot;icons/full/wizban/debug_wiz.gif&quot;&gt;
id = &quot;;
mode = &quot;run&quot;
label = &quot;Run&quot;
image = &quot;icons/full/ctool16/run_exc.gif&quot;
bannerImage = &quot;icons/full/wizban/run_wiz.gif&quot;&gt;
<p>Notice that neither declaration specifies a <code>category</code>. This means
that only config types that also do not specify a category attribute will be
visible when one of these launch groups is active in the UI. All of the standard
launchers included in the SDK fall into this category: Java Application, Java
Applet, Remote Java Application, JUnit &amp; Run-time Workbench. </p>
<p>The rest of the available options for a launch group declaration are straightforward.
The <code>id</code>, as always, is merely a unique identifier for the launch
group, <code>label</code> is a human-readable description of the launch group,
and <code>image</code> and <code>bannerImage</code> are a 16x16 icon and a larger
image suitable for placing at the top of a wizard or dialog. Not shown above
is an optional <code>public</code> attribute that controls whether the launch
group's history is editable by the user in the workbench Debug preferences.
The default value if this attribute is not specified is <code>true</code>.</p>
<p>Given that the standard toolbar drop down actions always open the LCD with
one of the two default launch groups active, you might wonder about the usefulness
of launch groups. In other words, if all of the standard SDK launchers belong
to the empty category, and the LCD always opens on either the empty debug or
empty run launch group, what is the point? The answer is that unless you are
trying to use the launch config framework in new and clever ways, launch groups
aren't of much interest. However, if you want to use the launch config framework
to do things other than launch code under development, launch groups can be
useful. </p>
<p>As an example of a <i>useful</i> application of launch groups, we will look
at the external tools plug-ins. The purpose of the external tools plug-ins is
to allow developers to run things <i>other</i> than the code they are currently
developing. Sometimes these programs are tangential to the development process,
such as an MP3 player or a mail client. Other times, developers might want to
launch Ant scripts that build or deploy projects. This type of launching is
different from the launching discussed so far in this article, but it does have
many similarities. Because of the similarities, the launch config framework
was used as the basis of the launching-related pieces of the external tools
plug-ins. </p>
<p>Below is the declaration of two launch groups associated with external tools:</p>
<h5> <u>UI declaration</u></h5>
<pre>&lt;extension point = &quot;org.eclipse.debug.ui.launchGroups&quot;&gt;
id = &quot;org.eclipse.ui.externaltools.launchGroup&quot;
mode = &quot;run&quot;
category = &quot;org.eclipse.ui.externaltools&quot;
label = &quot;&amp;External Tools&quot;
image = &quot;icons/full/obj16/external_tools.gif&quot;
bannerImage = &quot;icons/full/wizban/ext_tools_wiz.gif&quot;&gt;
id = &quot;org.eclipse.ui.externaltools.launchGroup.builder&quot;
mode = &quot;run&quot;
category = &quot;org.eclipse.ui.externaltools.builder&quot;
label = &quot;&amp;External Tools&quot;
image = &quot;icons/full/obj16/external_tools.gif&quot;
bannerImage = &quot;icons/full/wizban/ext_tools_wiz.gif&quot;
public = &quot;false&quot;&gt;
<p>Notice that each launch group specifies its own <code>category</code>. This
is so that UI components don't display 'regular' external tool configs and 'builder'
external tool configs at the same time. It also means that there are two different
launch histories for these configs (though the 'builder' history is not public
so it does not appear in the Debug preferences). In addition, this means that
the external tools plug-ins are free to create launch configs as they see fit,
without fear that these configs might show up in the LCD when the user is trying
to run code they are developing. Finally, this means that the external tools
plug-ins can implement their own relaunching actions and not worry about accidentally
launching a program under development.</p>
<h2>Implementing a launch group</h2>
<table border="1" cellspacing="0" bordercolor="#0000FF" width="398">
<td bgcolor="#FFFFCC" bordercolor="#FFFFFF">
<p> <b><font size="2">Source: <a href="">org.eclipse.debug.ui.DebugUITools</a></font></b></p>
<p>Implementing a launch group does not require implementing any API. A launch
group exists simply as an XML declaration with no associated classes. However,
there is some launch group-related API you should be aware of. This API allows
developers to bring up the LCD with a specified launch group actively filtering
its contents. It is worth repeating that this is <b><i>not</i></b> something
most launcher developers need to worry about. It is only useful if you have
a need to show configs of a specific config type and mode separately from all
other configs. </p>
<p>The <code>DebugUITools</code> class defines the following two launch group-related
<pre><img src="images/tag_1.gif" width="24" height="13">&nbsp;public static int openLaunchConfigurationDialogOnGroup(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Shell shell, IStructuredSelection selection, String groupIdentifier);
<img src="images/tag_2.gif" width="24" height="13">&nbsp;public static int openLaunchConfigurationPropertiesDialog(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Shell shell, ILaunchConfiguration configuration, String groupIdentifier);</pre>
<p>Both of these methods are used to bring up UI components subject to filtering
provided by the specified launch group. In both cases, <code>groupIdentifier</code>
is the value of the <code>id</code> attribute in a launch group XML declaration,
and <code>shell</code> is just the SWT Shell that will be the parent of the
new UI component. </p>
<img src="images/tag_1.gif" width="24" height="13"> This method opens the LCD
and sets the tree selection to the specified selection, which may contain any
combination of <code>ILaunchConfigurationType</code>s and <code>ILaunchConfiguration</code>s.
<img src="images/tag_2.gif" width="24" height="13"> While the previous method
opens the entire LCD, this method opens just the tabbed folder properties area
for the specified config; the tree is not shown. This is useful for allowing the
user to edit a single config without any extraneous UI.
<p>One other related method on <code>DebugUITools</code> is:</p>
<pre>public static int openLaunchConfigurationDialog(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Shell shell, IStructuredSelection selection, String mode);</pre>
<p>This method opens the LCD much as method <img src="images/tag_1.gif" width="24" height="13">
did above, except that the launch group used for filtering is based on the value
of <code>mode</code>. If <code>mode</code> is '<code>debug</code>', the LCD
is opened on the empty 'Debug' launch group, otherwise it is opened on the empty
'Run' launch group. This can be useful even if you aren't defining launch groups,
since it allows developers to pop up the LCD with an arbitrary selection. </p>
<p>To summarize, most launcher developers will never need to concern themselves
with launch groups. They are a technique for filtering configs and config types
in the UI that is hidden from the user, in other words, the user has no way
to control which launch group is active in the UI. Launch groups are useful
when a developer uses the launch configuration framework to do something <i>other</i>
than write a launcher that launches user code under development.</p>
<h2>Declaring a launch configuration comparator</h2>
<p>The following discussion of launch configuration comparators is somewhat more
advanced than the previous sections, and the implementation example requires
a bit more knowledge of Java and the Eclipse JDT plug-ins (however launch configuration
comparators are <i><b>not</b></i> Java-specific and can be implemented for any
debug model). Launch configuration comparators are an entirely optional feature
of launchers, so this section and the following section on implementation can
be safely skipped.</p>
<p>Because all attributes on a config are defined by the developer, the Debug
core &amp; Debug UI infrastructures have no knowledge of attribute semantics.
They know only that there is a <code>String</code>-valued attribute named JRE,
not that this String is a memento that specifies the installed name and type
of the JRE. This gets to be a problem when the debug infrastructure needs to
perform comparisons with configs, for example, determine if two config objects
actually represent the same underlying configuration, or in the LCD, determine
if a config has been modified by the user. Without help from the developer,
the best the infrastructure can do is call <code>Object.equals(Object)</code>
on attribute values (or use <code>==</code> for primitive types). This may be
fine for some attributes, but you can imagine situations in which this would
be incorrect. For example, suppose your tab group collects a list of <code>String</code>s
as an attribute value, and suppose that order is not significant. Left to its
own devices, the Debug infrastructure would determine that two configs containing
the same list of Strings in their attribute values but in different orders,
were not equal. The solution to this problem lies in declaring a launch configuration
comparator. This is an entity that the Debug infrastructure will use to perform
all comparisons for attributes with a specified name. The Java Applet launcher
doesn't declare any comparators, but the standard Java Application launcher
<p><u><b>Non-UI declaration</b></u> </p>
<pre>&lt;extension point=&quot;org.eclipse.debug.core.launchConfigurationComparators&quot;&gt;
<p>This declaration tells the Debug infrastructure to use the class <code>RuntimeClasspathEntryListComparator</code>
any time it performs a comparison involving an attribute named &quot;<code>org.eclipse.jdt.launching.CLASSPATH</code>&quot;.
Note that this comparator will be used for <i>all</i> attributes with this name,
regardless of config type. This allows you to reuse comparators that have already
been implemented by other developers, but requires caution in attribute naming.</p>
<p><img src="images/tip.gif" width="62" height="13"> <i>When creating names for
config attributes, you should always prefix them with the fully qualified name
of your plug-in. This avoids potential collisions down the road if someone else
extends your launcher. It also avoids unintentionally using someone else's comparator.</i></p>
<h2>Implementing a launch configuration comparator</h2>
<table border="1" cellspacing="0" bordercolor="#0000FF" width="526">
<td bgcolor="#FFFFCC" bordercolor="#FFFFFF">
<p> <b><font size="2">Source: <a href="">org.eclipse.jdt.internal.launching.RuntimeClasspathEntryListComparator</a></font></b>
<p>To implement a launch configuration comparator, you simply need to implement
the standard Java library interface <code>java.util.Comparator</code>. This
interface defines a single method, <code>public int compare(Object o1, Object
o2)</code> that returns a negative value if <code>o1</code> is less than <code>o2</code>,
zero if <code>o1</code> equals <code>o2</code> and a positive value if <code>o1</code>
is greater than <code>o2</code>: </p>
<pre>&nbsp;&nbsp;&nbsp;&nbsp;public int compare(Object o1, Object o2) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List list1 = (List)o1;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;List list2 = (List)o2;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (list1.size() == list2.size()) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;for (int i = 0; i &lt; list1.size(); i++) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;String memento1 = (String)list1.get(i);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;String memento2 = (String)list2.get(i);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;try {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IRuntimeClasspathEntry entry1 =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IRuntimeClasspathEntry entry2 =
<img src="images/tag_1.gif" width="24" height="13">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!entry1.equals(entry2)) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return -1;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} catch (CoreException e) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return -1;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return 0;
&nbsp;&nbsp;&nbsp;&nbsp;return -1;
<p><img src="images/tag_1.gif" width="24" height="13"> This method simply reconstructs
<code>IRuntimeClasspathEntry</code> objects from the <code>String</code> mementos
stored in the <code>List</code> arguments, then calls <code>equals(Object)</code>
on these. The implementation of <code>equals()</code> on the <code>IRuntimeClasspathEntry</code>
objects will do an intelligent comparison.</p>
<p>Another use for comparators is disambiguating default values for attributes.
Consider an integer-valued attribute named 'address' whose default value is
zero. If the debug infrastructure is asked to compare two configs, one of which
has an address value of zero, and the other which has no address attribute,
it would normally declare these to be not equal. However the absence of an address
value should in most cases mean the same thing as a default address value. The
solution is to implement a comparator that encapsulates this logic. </p>
<p><img src="images/tip.gif" width="62" height="13"> <i>In the LCD, if you select
a config, then without making any changes to it select a different config and
are asked if you wish to save changes, the problem is probably due to a mismatch
between a default attribute value and no attribute value. Implement a comparator
to fix the problem.</i></p>
<h2>Putting it all together</h2>
<p>There are a couple of things to keep in mind while developing a launcher:</p>
<li>Putting your UI code in one plug-in and everything else in another plug-in
makes your launcher easier to maintain, facilitates programmatic launching,
and allows you or someone else to provide an alternate UI for your launcher.</li>
<li>If your delegate requires some attribute to function properly, there must
be UI somewhere in your tab group to collect it</li>
<li>The 3 main 'value copying' methods on tabs are called frequently and must
execute quickly. If you need to perform some sort of lengthy validation, consider
waiting until launch time to do it.</li>
<h2>Work smarter, not harder</h2>
<p>The first rule of implementing a launcher is to reuse as much as possible.
If you are implementing a Java-oriented launcher, there is a large amount of
code that is part of the Eclipse SDK, is public API and ready to be reused.
This article has pointed the opportunities for Java-oriented reuse. Non-Java
launchers can also take advantage of reuse. For example, consider extending
language-independent abstract API classes like: </p>
<li><code>org.eclipse.debug.ui.AbstractLaunchConfigurationTabGroup</code> </li>
<li><code>org.eclipse.debug.ui.AbstractLaunchConfigurationTab</code>. </li>
<p>To get further reuse outside of Java, you need to identify plug-ins that contain
code you wish to reuse. Encourage other plug-in developers to make their launching
related classes public so that you can reuse them, and consider making your
own launching-related classes public for the same reason. </p>
<h2>Source code</h2>
<p>The Java Applet launcher discussed in this article is part of the Eclipse SDK,
as of release 2.1. All UI code for this launcher is found in the <code>org.eclipse.jdt.debug.ui</code>
plug-in, while the non-UI code lives in the <code>org.eclipse.jdt.launching</code>
plug-in. </p>
<p>Special thanks to Olivier Thomann, the author of the original applet launcher
plug-in. Also thanks to Vadim Berestetsky, Erich Gamma, Paul Gooderham, Dave
Wathen and Darin Wright for reading early drafts of this article and providing
feedback and suggestions. </p>