| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html> | |
| <head> | |
| <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"> | |
| </head> | |
| <body link="#0000ff" vlink="#800080"> | |
| <div align="right"> <font face="Times New Roman, Times, serif" size="2">Copyright | |
| © 2003 International Business Machines Corp.</font> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td align="LEFT" valign="TOP" bgcolor="#0080C0"> <b><font face="Arial,Helvetica" color="#FFFFFF"> Eclipse | |
| Corner Article</font></b> </td> | |
| </tr> | |
| </table> | |
| </div> | |
| <div align="left"> | |
| <h1> | |
| <img src="images/Idea.jpg" height="86" width="120" align="CENTER"> | |
| </h1> | |
| </div> | |
| <p> | |
| </p> | |
| <h1 align="CENTER"> We Have Lift-off: The Launching Framework in Eclipse </h1> | |
| <blockquote> | |
| <b>Summary</b><br> | |
| 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> | |
| </blockquote> | |
| <hr width="100%"> | |
| <h2>Prerequisites</h2> | |
| 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 & 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> | |
| <ul> | |
| <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> | |
| </ul> | |
| <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 | |
| functionality.</p> | |
| <h2> | |
| Let there be framework | |
| </h2> | |
| <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> | |
| <ul> | |
| <li><b>boolean</b></li> | |
| <li><b>int</b></li> | |
| <li><code>java.lang.String</code></li> | |
| <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 & values must be of type <code>java.lang.String</code>)</li> | |
| </ul> | |
| <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 "How to Launch Java Applications Programmatically" | |
| 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 & 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 | |
| create.</p> | |
| <h2> | |
| Declaring a launch configuration type | |
| </h2> | |
| <p> | |
| 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: | |
| </p> | |
| <h5> <u>Non-UI declaration</u> </h5> | |
| <pre> | |
| <extension point="org.eclipse.debug.core.launchConfigurationTypes"> | |
| <launchConfigurationType | |
| name="Java Applet" | |
| delegate="org.eclipse.jdt.internal.launching.JavaAppletLaunchConfigurationDelegate" | |
| modes="run, debug" | |
| id="org.eclipse.jdt.launching.javaApplet"> | |
| </launchConfigurationType> | |
| </extension> | |
| </pre> | |
| <p> | |
| 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 | |
| <code>org.eclipse.debug.core.model.ILaunchConfigurationDelegate</code>. | |
| The delegate is the brains of the launcher, and implements the | |
| <code>launch()</code> method which launches a specified | |
| config. | |
| </p> | |
| <p> The <code>modes</code> attribute specifies one or both of <code>run</code> | |
| & <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"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="white"> | |
| <p> <b><font size="2">Source: <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt.launching/launching/org/eclipse/jdt/internal/launching/JavaAppletLaunchConfigurationDelegate.java">org.eclipse.jdt.internal.launching.JavaAppletLaunchConfigurationDelegate</a></font></b> | |
| </p> | |
| </td> | |
| </tr> | |
| </table> | |
| <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> | |
| <pre> | |
| public void launch(ILaunchConfiguration configuration, | |
| String mode, | |
| ILaunch launch, | |
| IProgressMonitor monitor) throws CoreException; | |
| </pre> | |
| <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 & 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> | |
| <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>IVMRunner.run()</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 & 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> | |
| <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"> String mainTypeName = verifyMainTypeName(configuration); | |
| IJavaProject javaProject = getJavaProject(configuration); | |
| <img src="images/tag_2.gif" width="24" height="13"> IType type = JavaLaunchConfigurationUtils.getMainType( | |
| mainTypeName, javaProject); | |
| ITypeHierarchy hierarchy = type.newSupertypeHierarchy( | |
| new NullProgressMonitor()); | |
| IType javaLangApplet = JavaLaunchConfigurationUtils.getMainType( | |
| "java.applet.Applet", javaProject); | |
| <img src="images/tag_3.gif" width="24" height="13"> if (!hierarchy.contains(javaLangApplet)) { | |
| abort("The applet type is not a subclass of java.applet.Applet."); | |
| } | |
| <img src="images/tag_4.gif" width="24" height="13"> IVMInstall vm = verifyVMInstall(configuration); | |
| <img src="images/tag_5.gif" width="24" height="13"> IVMRunner runner = vm.getVMRunner(mode);</pre> | |
| <p>This code snippet is typical of the verification done by the <code>launch()</code> | |
| method:<br> | |
| <img src="images/tag_1.gif" width="24" height="13"> Use a framework method to | |
| verify & 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 & 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> // Create VM config | |
| <img src="images/tag_1.gif" width="24" height="13"> VMRunnerConfiguration runConfig = new VMRunnerConfiguration( | |
| "sun.applet.AppletViewer", classpath); | |
| runConfig.setProgramArguments(new String[] {buildHTMLFile(configuration)}); | |
| String[] vmArgs = execArgs.getVMArgumentsArray(); | |
| String[] realArgs = new String[vmArgs.length+1]; | |
| System.arraycopy(vmArgs, 0, realArgs, 1, vmArgs.length); | |
| realArgs[0] = javaPolicy; | |
| <img src="images/tag_2.gif" width="24" height="13"> runConfig.setVMArguments(realArgs); | |
| runConfig.setWorkingDirectory(workingDirName);</pre> | |
| <pre> // Bootpath | |
| String[] bootpath = getBootpath(configuration); | |
| <img src="images/tag_3.gif" width="24" height="13"> runConfig.setBootClassPath(bootpath); | |
| // Launch the configuration | |
| this.fCurrentLaunchConfiguration = configuration; | |
| <img src="images/tag_4.gif" width="24" height="13"> runner.run(runConfig, 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> | |
| <pre> | |
| C:\Java\jdk1.4.1\bin\javaw.exe | |
| -Djava.security.policy=java.policy.applet | |
| -classpath C:\TargetWorkspaces\eclipse\MyApplets | |
| sun.applet.AppletViewer HelloWorldApplet1030633365864.html | |
| </pre> | |
| <p> Debugging the same applet would result in the following command line: </p> | |
| <pre> | |
| C:\Java\jdk1.4.1\bin\javaw.exe | |
| -Djava.security.policy=java.policy.applet | |
| -classpath C:\TargetWorkspaces\eclipse\MyApplets | |
| -Xdebug -Xnoagent | |
| -Djava.compiler=NONE | |
| -Xrunjdwp:transport=dt_socket,suspend=y,address=localhost:14983 | |
| sun.applet.AppletViewer HelloWorldApplet1030634748522.html | |
| </pre> | |
| <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> | |
| <ol> | |
| <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> | |
| </ol> | |
| <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>. | |
| </p> | |
| <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> | |
| <pre> | |
| <extension point="org.eclipse.debug.ui.launchConfigurationTypeImages"> | |
| <launchConfigurationTypeImage | |
| icon="icons/full/ctool16/java_applet.gif" | |
| configTypeID="org.eclipse.jdt.launching.javaApplet" | |
| id="org.eclipse.jdt.debug.ui.launchConfigurationTypeImage.javaApplet"> | |
| </launchConfigurationTypeImage> | |
| </extension> | |
| </pre> | |
| <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> | |
| <h2> | |
| Declaring a tab group | |
| </h2> | |
| <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> | |
| <p> | |
| <img src="images/Screenshot1.gif" width="663" height="560"> | |
| </p> | |
| <p> | |
| The LCD is broken into two main regions: | |
| </p> | |
| <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> | |
| <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. | |
| </p> | |
| <p> | |
| 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 & 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. | |
| </p> | |
| <p> | |
| Here is the XML for declaring a tab group: | |
| </p> | |
| <h5> <u>UI declaration</u></h5> | |
| <pre> | |
| <extension point="org.eclipse.debug.ui.launchConfigurationTabGroups"> | |
| <launchConfigurationTabGroup | |
| type="org.eclipse.jdt.launching.javaApplet" | |
| class="org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletTabGroup" | |
| id="org.eclipse.jdt.debug.ui.launchConfigurationTabGroup.javaApplet"> | |
| </launchConfigurationTabGroup> | |
| </extension> | |
| </pre> | |
| <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"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="#0000FF"> | |
| <p> <b><font size="2">Source: <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/internal/debug/ui/launcher/JavaAppletTabGroup.java">org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletTabGroup</a></font></b> | |
| </p> | |
| </td> | |
| </tr> | |
| </table> | |
| <p> The main job of a tab group is to specify the tabs that will appear in the | |
| LCD and set their order. These tabs may have been specially written for | |
| the particular config type in question, or they may be general purpose | |
| tabs that appear for multiple config types. The tab group for our applet | |
| launcher creates 6 tabs, of which 4 already existed (<code>JavaArgumentsTab, | |
| JavaJRETab, JavaClasspathTab, CommonTab</code>) and 2 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() | |
| }; | |
| setTabs(tabs); | |
| }</pre> | |
| <p>A tab group is free to mix & match any combination of existing and | |
| custom-written tabs. The only proviso is that tabs you wish to reuse must | |
| be in public (not internal) packages. 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 once we had defined a class similar | |
| to <code>JavaAppletTabGroup</code>. </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> | |
| package.</i></p> | |
| <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>. This | |
| tab contains UI that allows users to make their configs 'local' or 'shared', | |
| mark configs as 'favorites' and control perspective switching when launching. | |
| 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. 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. The first simply notifies the | |
| tab of the LCD object that owns it. Tabs make frequent calls to methods on the | |
| LCD, so a tab needs to have a reference to it. The second method | |
| creates the GUI widgetry for the tab and lays it out. </p> | |
| <table border="1" cellspacing="0" bordercolor="#FFFFFF" width="503"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="#0000FF"> <p> <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/debug/ui/launchConfigurations/AppletParametersTab.java"><b><font size="2">Source: | |
| org.eclipse.jdt.debug.ui.launchConfigurations.AppletParametersTab</font></b> | |
| </a></p></td> | |
| </tr> | |
| </table> | |
| <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> | |
| <ul> | |
| <li> <code>private Text widthText;</code></li> | |
| <li><code>private Text heightText;</code></li> | |
| <li><code>private Text nameText;</code> | |
| </li> | |
| </ul> | |
| <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' | |
| methods:</p> | |
| <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> | |
| </ul> | |
| <p>In general terms, the first two methods copy values from the tab to a | |
| working copy, while the third method copies values from a working | |
| copy to the tab. The <code>setDefaults()</code> method is called | |
| when a new config is created. This method sets default values | |
| for all attributes it understands on the working copy argument. This is | |
| done differently depending on the nature of the attributes collected by the | |
| tab. The <code>AppletMainTab</code> checks the current workbench selection | |
| or active editor to determine default values for the Project & Applet class | |
| attributes. 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) { | |
| configuration.setAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_WIDTH, | |
| (String)widthText.getText()); | |
| configuration.setAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_HEIGHT, | |
| (String)heightText.getText()); | |
| configuration.setAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_NAME, | |
| (String)nameText.getText()); | |
| configuration.setAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_PARAMETERS, | |
| getMapFromParametersTable()); | |
| }</pre> | |
| <p>The <code>initializeFrom()</code> method does the opposite of the <code>performApply()</code> | |
| method. 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) { | |
| try { | |
| <img src="images/tag_1.gif" width="24" height="13"> fWidthText.setText(Integer.toString(config.getAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_WIDTH, "200"))); | |
| } catch(CoreException ce) { | |
| fWidthText.setText(Integer.toString(DEFAULT_APPLET_WIDTH)); | |
| } | |
| try { | |
| <img src="images/tag_2.gif" width="24" height="13"> fHeightText.setText(Integer.toString(config.getAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_HEIGHT, "200"))); | |
| } catch(CoreException CE) { | |
| fHeightText.setText(Integer.toString(DEFAULT_APPLET_HEIGHT)); | |
| } | |
| try { | |
| <img src="images/tag_3.gif" width="24" height="13"> fNameText.setText(config.getAttribute( | |
| IJavaLaunchConfigurationConstants.ATTR_APPLET_NAME, "")); | |
| } catch(CoreException CE) { | |
| fNameText.setText(""); | |
| } | |
| updateParametersFromConfig(config); | |
| }</pre> | |
| <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> | |
| widget.<br> | |
| <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> | |
| widget.<br> | |
| <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> | |
| widget.<br> | |
| 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 called | |
| frequently, for example, whenever the user selects a new tab. 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) { | |
| setErrorMessage(null); | |
| try { | |
| <img src="images/tag_1.gif" width="24" height="13"> Integer.parseInt(fWidthText.getText().trim()); | |
| } catch(NumberFormatException nfe) { | |
| <img src="images/tag_2.gif" width="24" height="13"> setErrorMessage("Width is not an integer"); | |
| return false; | |
| } | |
| try { | |
| <img src="images/tag_1.gif" width="24" height="13"> Integer.parseInt(fHeightText.getText()Trim()); | |
| } catch(NumberFormatException nfe) { | |
| <img src="images/tag_2.gif" width="24" height="13"> setErrorMessage("Height is not an integer"); | |
| return false; | |
| } | |
| <img src="images/tag_3.gif" width="24" height="13"> return true; | |
| } | |
| </pre> | |
| <p><img src="images/tag_1.gif" width="24" height="13"> The config can be launched | |
| only when both the <code>width</code> & <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 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> | |
| <ul> | |
| <li> <code>public void initializeFrom(ILaunchConfiguration configuration); | |
| </code></li> | |
| <li><code>public void performApply(ILaunchConfigurationWorkingCopy configuration); | |
| </code></li> | |
| <li><code>public void setDefaults(ILaunchConfigurationWorkingCopy configuration);</code> | |
| </li> | |
| <li><code>public void launched(ILaunch launch); | |
| </code></li> | |
| </ul> | |
| <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> | |
| <p> | |
| The following figure shows how launch shortcuts appear in the | |
| UI: | |
| </p> | |
| <p> | |
| <img src="images/Screenshot2.gif" width="685" height="355"> | |
| </p> | |
| <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> | |
| <pre> | |
| <extension point="org.eclipse.debug.ui.launchShortcuts"> | |
| <shortcut | |
| id="org.eclipse.jdt.debug.ui.javaAppletShortcut" | |
| class="org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletLaunchShortcut" | |
| label="Java Applet" | |
| icon="icons/full/ctool16/java_applet.gif" | |
| modes="run, debug"> | |
| <perspective id="org.eclipse.jdt.ui.JavaPerspective"/> | |
| <perspective id="org.eclipse.jdt.ui.JavaHierarchyPerspective"/> | |
| <perspective id="org.eclipse.jdt.ui.JavaBrowsingPerspective"/> | |
| <perspective id="org.eclipse.debug.ui.DebugPerspective"/> | |
| </shortcut> | |
| </extension> | |
| </pre> | |
| <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"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="#FFFFFF"> | |
| <p> <b><font size="2">Source: <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt.debug.ui/ui/org/eclipse/jdt/internal/debug/ui/launcher/JavaAppletLaunchShortcut.java">org.eclipse.jdt.internal.debug.ui.launcher.JavaAppletLaunchShortcut</a></font></b> | |
| </p> | |
| </td> | |
| </tr> | |
| </table> | |
| <p> The first step in implementing a launch shortcut is determining if you even | |
| need to. 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. 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. </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 must implement the <code>org.eclipse.debug.ui.ILaunchShortcut</code> | |
| interface. 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> | |
| </ul> | |
| <p> The only difference between them is how the entity to be launched is specified. | |
| In the first method, it's via a workbench selection, in the second it's | |
| as an editor part. 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> public void launch(IEditorPart editor, String mode) { | |
| IEditorInput input = editor.getEditorInput(); | |
| IJavaElement javaElement = | |
| (IJavaElement) input.getAdapter(IJavaElement.class); | |
| if (javaElement != null) { | |
| <img src="images/tag_1.gif" width="24" height="13"> searchAndLaunch(new Object[] {javaElement}, mode); | |
| } | |
| }</pre> | |
| <pre> public void launch(ISelection selection, String mode) { | |
| if (selection instanceof IStructuredSelection) { | |
| <img src="images/tag_1.gif" width="24" height="13"> searchAndLaunch(((IStructuredSelection)selection).toArray(), mode); | |
| } | |
| } | |
| protected void searchAndLaunch(Object[] search, String mode) { | |
| IType[] types = null; | |
| if (search != null) { | |
| try { | |
| <img src="images/tag_2.gif" width="24" height="13"> types = AppletLaunchConfigurationUtils.findApplets( | |
| new ProgressMonitorDialog(getShell()), search); | |
| } catch (Exception e) { | |
| /* Handle exceptions */ | |
| } | |
| IType type = null; | |
| <img src="images/tag_3.gif" width="24" height="13"> if (types.length == 0) { | |
| MessageDialog.openInformation( | |
| getShell(), "Applet Launch", "No applets found."}; | |
| <img src="images/tag_4.gif" width="24" height="13"> } else if (types.length > 1) { | |
| type = chooseType(types, mode); | |
| <img src="images/tag_5.gif" width="24" height="13"> } else { | |
| type = types[0]; | |
| } | |
| if (type != null) { | |
| <img src="images/tag_6.gif" width="24" height="13"> launch(type, mode); | |
| } | |
| } | |
| } | |
| protected void launch(IType type, String mode) { | |
| try { | |
| ILaunchConfiguration config = findLaunchConfiguration(type, mode); | |
| if (config != null) { | |
| <img src="images/tag_7.gif" width="24" height="13"> config.launch(mode, null); | |
| } | |
| } catch (CoreException e) { | |
| /* Handle exceptions*/ | |
| } | |
| }</pre> | |
| <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> | |
| </ol> | |
| <p> However, there is nothing in the <code>ILaunchShortcut</code> interface that | |
| requires you to follow these steps. For example, you could create a launch | |
| shortcut implementation that skipped step 2. This way, <i>every</i> time | |
| the shortcut was invoked, a new config would be created. This would normally lead | |
| to a flood of duplicate configs, however if the default value for an attribute | |
| was somehow time-dependent, this could be useful. 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. 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. | |
| In the end though, the <code>ILaunchShortcut</code> contract is very flexible | |
| and just 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 & | |
| 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 & 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> | |
| <ul> | |
| <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> | |
| </ul> | |
| <p>This is the XML declaration of the standard 'Run' & 'Debug' launch groups:</p> | |
| <h5> <u>UI declaration</u></h5> | |
| <pre><extension point = "org.eclipse.debug.ui.launchGroups"> | |
| <launchGroup | |
| id = "org.eclipse.debug.ui.launchGroup.debug" | |
| mode = "debug" | |
| label ="Debug" | |
| image = "icons/full/ctool16/debug_exc.gif" | |
| bannerImage = "icons/full/wizban/debug_wiz.gif"> | |
| </launchGroup> | |
| <launchGroup | |
| id = "org.eclipse.debug.ui.launchGroup.run" | |
| mode = "run" | |
| label = "Run" | |
| image = "icons/full/ctool16/run_exc.gif" | |
| bannerImage = "icons/full/wizban/run_wiz.gif"> | |
| </launchGroup> | |
| </extension></pre> | |
| <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 & 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><extension point = "org.eclipse.debug.ui.launchGroups"> | |
| <launchGroup | |
| id = "org.eclipse.ui.externaltools.launchGroup" | |
| mode = "run" | |
| category = "org.eclipse.ui.externaltools" | |
| label = "&External Tools" | |
| image = "icons/full/obj16/external_tools.gif" | |
| bannerImage = "icons/full/wizban/ext_tools_wiz.gif"> | |
| </launchGroup> | |
| <launchGroup | |
| id = "org.eclipse.ui.externaltools.launchGroup.builder" | |
| mode = "run" | |
| category = "org.eclipse.ui.externaltools.builder" | |
| label = "&External Tools" | |
| image = "icons/full/obj16/external_tools.gif" | |
| bannerImage = "icons/full/wizban/ext_tools_wiz.gif" | |
| public = "false"> | |
| </launchGroup> | |
| </extension> | |
| </pre> | |
| <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"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="#FFFFFF"> | |
| <p> <b><font size="2">Source: <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.debug.ui/ui/org/eclipse/debug/ui/DebugUITools.java">org.eclipse.debug.ui.DebugUITools</a></font></b></p> | |
| </td> | |
| </tr> | |
| </table> | |
| <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 | |
| methods:</p> | |
| <pre><img src="images/tag_1.gif" width="24" height="13"> public static int openLaunchConfigurationDialogOnGroup( | |
| Shell shell, IStructuredSelection selection, String groupIdentifier); | |
| <img src="images/tag_2.gif" width="24" height="13"> public static int openLaunchConfigurationPropertiesDialog( | |
| 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. | |
| <br> | |
| <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( | |
| 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 & 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 | |
| does:</p> | |
| <p><u><b>Non-UI declaration</b></u> </p> | |
| <pre><extension point="org.eclipse.debug.core.launchConfigurationComparators"> | |
| <launchConfigurationComparator | |
| id="org.eclipse.jdt.launching.classpathComparator" | |
| class="org.eclipse.jdt.internal.launching.RuntimeClasspathEntryListComparator" | |
| attribute="org.eclipse.jdt.launching.CLASSPATH"/> | |
| </extension></pre> | |
| <p>This declaration tells the Debug infrastructure to use the class <code>RuntimeClasspathEntryListComparator</code> | |
| any time it performs a comparison involving an attribute named "<code>org.eclipse.jdt.launching.CLASSPATH</code>". | |
| 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"> | |
| <tr> | |
| <td bgcolor="#FFFFCC" bordercolor="#FFFFFF"> | |
| <p> <b><font size="2">Source: <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt.launching/launching/org/eclipse/jdt/internal/launching/RuntimeClasspathEntryListComparator.java">org.eclipse.jdt.internal.launching.RuntimeClasspathEntryListComparator</a></font></b> | |
| </p> | |
| </td> | |
| </tr> | |
| </table> | |
| <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> public int compare(Object o1, Object o2) { | |
| List list1 = (List)o1; | |
| List list2 = (List)o2; | |
| if (list1.size() == list2.size()) { | |
| for (int i = 0; i < list1.size(); i++) { | |
| String memento1 = (String)list1.get(i); | |
| String memento2 = (String)list2.get(i); | |
| try { | |
| IRuntimeClasspathEntry entry1 = | |
| JavaRuntime.newRuntimeClasspathEntry(memento1); | |
| IRuntimeClasspathEntry entry2 = | |
| JavaRuntime.newRuntimeClasspathEntry(memento2); | |
| <img src="images/tag_1.gif" width="24" height="13"> if (!entry1.equals(entry2)) { | |
| return -1; | |
| } | |
| } catch (CoreException e) { | |
| LaunchingPlugin.log(e); | |
| return -1; | |
| } | |
| } | |
| return 0; | |
| } | |
| return -1; | |
| }</pre> | |
| <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> | |
| <ul> | |
| <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> | |
| </ul> | |
| <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> | |
| <ul> | |
| <li><code>org.eclipse.debug.ui.AbstractLaunchConfigurationTabGroup</code> </li> | |
| <li><code>org.eclipse.debug.ui.AbstractLaunchConfigurationTab</code>. </li> | |
| </ul> | |
| <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> | |
| <h2>Acknowledgments</h2> | |
| <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> | |
| </body> | |
| </html> | |