blob: 03f3b54bfb14d855cb1beba8da6ec23918342b05 [file] [log] [blame]
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<title>Launching Java Applications</title>
<link 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 colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">&nbsp;Eclipse
Corner Article</font></font></b></td>
<div align="left">
<h1><img src="images/Idea.jpg" height=86 width=120 align=CENTER></h1>
<h1 ALIGN="CENTER">Launching Java Applications Programmatically</h1>
Application developers require the ability to run and debug code in order to
test it. Tool developers require the ability to launch Java&#153; applications
that assist in application development - for example, starting and stopping
a Web server on which servlets, JSPs, and HTML pages can be tested; or launching
a VM on which scrapbook evaluations can be performed. This article focuses on
the high-level API provided by the Java launching plug-in that tool developers
can leverage for the programmatic launching of local Java applications.
<p><b> By Darin Wright, IBM OTI Labs</b> <br>
<font size="-1">August 26, 2003</font> </p>
<hr width="100%">
<p>To get the most out of this article, the reader should have a basic understanding
of the Eclipse plug-in architecture, Java programming, and launching Java programs
from the command line. A basic understanding of the Eclipse launching framework
is also helpful - see the article <a href="">We
Have Lift-off: The Launching Framework in Eclipse</a>, by Joe Szurzsewski. Knowledge
of Tomcat is useful, but not required, as the examples are based on launching
a Tomcat server.</p>
<p>Application developers require the ability to run and debug code in order to
test it. This is, of course, the primary use of the Java launching support in
the Eclipse SDK - to launch applications being developed in the IDE. However,
tool developers also require the ability to launch Java applications that assist
in application development - for example, starting and stopping a Web server
on which servlets, JSPs, and HTML pages can be tested; or launching a VM on
which scrapbook evaluations can be performed.</p>
<p>In the Eclipse SDK, there are a variety of mechanisms available to Java developers
for launching Java VMs. At the most basic level, <code>java.lang.Runtime</code>
provides an API to launch a system process by specifying a raw command line.
At a slightly higher level, the Java launching plug-in provides an API to launch
a particular JRE (defined in the workspace preferences), with a specified raw
classpath, boot path, program arguments, VM arguments, and a main type name.
At the highest level, the Java launching plug-in provides Java launch configurations.
Java launch configurations leverage the debug platform's launching framework,
providing persistence and visibility in the Eclipse user interface - i.e. processes
appear in the debug view, have console I/O, and launched applications appear
in the launch history and launch configuration dialog. Java launch configurations
use high-level abstractions that insulate developers from many of the tedious
details involved in the lower level APIs.</p>
<h2>Launching a Web Server</h2>
<p>To illustrate the use of Java launch configurations, this article steps through
an example of translating a command line used to start Tomcat into an equivalent
launch configuration. To run the example you need the following.</p>
<li>a local installation of Tomcat, version 4.1.24 (available <a href="">here</a>)</li>
<li>a Java Development Kit (JDK, version 1.3.1 or higher, available <a href="">here</a>)</li>
<li>an environment variable, <code>JAVA_HOME</code>, set to the installation
location of your JDK</li>
<li>an Eclipse SDK, with <a href="">this
example plug-in</a> unzipped into its plugins directory</li>
<li>a classpath variable (Preferences &gt; Java &gt; Classpath Variables) named
<code>TOMCAT_HOME</code>, that points to your Tomcat installation directory</li>
<h3>First a Disclaimer</h3>
<p>The example used in this article is <b>not</b> <b>intended to be a style guide</b>
for integrating server or application launching into the Eclipse IDE. The sole
intent is to demonstrate the Java launch API.</p>
<h3>Launching Tomcat from the Command Line</h3>
<p>The simplest way to launch Tomcat is to use the <code>startup</code> command
provided with the sever. For example, from a DOS prompt, in the <code>bin</code>
directory of your Tomcat installation, type <code>startup</code>. This will
execute the batch file which starts the server. A second DOS shell will appear,
labeled Tomcat, and output messages will appear in the shell as the server starts.
To ensure the server has started properly, you can open a Web browser on this
address <code><a href="http://localhost:8080/">http://localhost:8080</a></code>.
The server can be shut down by using the <code>shutdown</code> command from
the bin directory of the Tomcat installation. The server will be stopped, and
the associated DOS window will close.</p>
<p>Examining the <code>startup</code> batch file reveals that Tomcat is ultimately
started by launching a Java application. </p>
<p><img src="images/tryit.gif" width="61" height="13"> From the <code>bin</code>
directory of your Tomcat installation, enter a command line similar to the following.
You will need to substitute the proper location for <code>tools.jar</code> specified
in the classpath parameter, based on the location of your JDK (in this example,
it is found in <code>d:\jdk1.4.1_02\lib\tools.jar</code>).</p>
<pre>java -Djava.endorsed.dirs=&quot;..\common\endorsed&quot;<br> -classpath &quot;d:\jdk1.4.1_02\lib\tools.jar;..\bin\bootstrap.jar&quot;<br> -Dcatalina.base=&quot;..&quot;<br> -Dcatalina.home=&quot;..&quot;<br>;..\temp&quot;<br> org.apache.catalina.startup.Bootstrap start
<p>This has the same effect as running the <code>startup</code> batch file, except
this time, the startup messages appear in the same DOS window. Once again, we
can verify the server has started properly by opening a Web browser on this
address <code><a href="http://localhost:8080/">http://localhost:8080</a></code>.
Examining the command line that was entered, we notice the following.</p>
<li>a Java VM is launched</li>
<li>the main type is <code>org.apache.catalina.startup.Bootstrap</code></li>
<li>the main type is passed one program argument - <code>start</code></li>
<li>the classpath includes <code>tools.jar</code> from the JDK installation,
and <code>bootstrap.jar</code> from the Tomcat installation</li>
<li>several system properties are set - <code>java.endorsed.dirs</code>, <code>catalina.base</code>,
<code>catalina.home</code>, and <code></code></li>
<p>The server can be shut down by using the <code>shutdown</code> command (from
another DOS shell). Note that the <code>shutdown</code> command actually results
in the same Java application being launched, with a different program argument
- i.e. <code>stop</code>. Thus, you can also stop the server by entering a command
line similar to the following, from the <code>bin</code> directory of the Tomcat
installation. Once again, you need to substitute the proper location of <code>tools.jar</code>.</p>
<pre>java -Djava.endorsed.dirs=&quot;..\common\endorsed&quot;<br> -classpath &quot;d:\jdk1.4.1_02\lib\tools.jar;..\bin\bootstrap.jar&quot;<br> -Dcatalina.base=&quot;..&quot;<br> -Dcatalina.home=&quot;..&quot;<br>;..\temp&quot;<br> org.apache.catalina.startup.Bootstrap stop</pre>
<h3>Launching Tomcat from Eclipse</h3>
<p>Now let's translate the command line used to start Tomcat from the system command
prompt into a launch configuration that can be used to launch Tomcat from within
Eclipse. To do this, we will create an instance of a local Java application
launch configuration, set various attributes on the configuration corresponding
to our command line, and then launch the configuration.</p>
<p>The example plug-in provides sample actions to start and stop Tomcat, available
on a Tomcat menu (on window menu bar). The <b>Start Tomcat</b> action provides
a cascading menu of all JREs defined in the workspace. When a JRE is selected,
Tomcat is launched on that JRE. The code snippets below refer to code in the
sample action <code>org.eclipse.jdt.launching.examples.tomcat.StartAction</code>,
which launches Tomcat on a specific JRE.</p>
<h4>Creating a Launch Configuration</h4>
<p>The first step is to create an instance of a launch configuration, used for
launching local Java applications.</p>
<img src="images/tag_1.gif" width=24 align=CENTER>ILaunchManager manager = DebugPlugin.getDefault().getLaunchManager();<br> ILaunchConfigurationType type =<br> manager.getLaunchConfigurationType(ID_JAVA_APPLICATION);<br><img src="images/tag_2.gif" width=24 align=CENTER>ILaunchConfiguration[] configurations =<br> manager.getLaunchConfigurations(type);<br> for (int i = 0; i &lt; configurations.length; i++) {<br> ILaunchConfiguration configuration = configurations[i];<br> if (configuration.getName().equals(&quot;Start Tomcat&quot;)) {<br> configuration.delete();<br> break;<br> }<br> }<br><img src="images/tag_3.gif" width=24 align=CENTER>ILaunchConfigurationWorkingCopy workingCopy =<br> type.newInstance(null, &quot;Start Tomcat&quot;);<p></p>
<li>The Java Application launch configuration type is retrieved. A launch configuration
type represents a class of launch configurations (much like a type in Java
represents a class of objects, also known as the Type Object pattern). Launch
configuration types are stored with the launch manager in the debug platform.
Each launch configuration type is defined as an extension in plug-in XML,
and has a unique identifier which can be used to access it. The constants
associated with the Java Application launch configuration are defined in <code>org.eclipse.jdt.launching.IJavaLaunchConfigurationConstants</code>.</li>
<li>This example deletes any existing launch configuration with the name &quot;<code>Start
Tomcat</code>&quot;. This is done by iterating through all Java application
launch configurations, in search of a configuration with that name, and deleting
it if one is found. A real application might reuse an existing launch configuration,
but for the purposes of this example, we simply delete any previously created
<li>An instance of a Java Application launch configuration is created and named
&quot;<code>Start Tomcat</code>&quot;. Instances are created as working copies,
which are read-write. In this example, the launch configuration will be persisted
with the workspace metadata. The <code>newInstance</code> method accepts an
<code>IContainer</code> in which to create the launch configuration, and the
name of the configuration to create. When null is specified as the container,
the configuration will be persisted with the workspace metadata. Alternatively,
a workspace project or folder could be specified - in which case the configuration
would be stored as a file in the workspace.</li>
<p>Launch configurations are simply containers of attribute-value pairs that can
be persisted. Each launch configuration type extension provides a launch delegate
that is capable of interpreting the attributes of a launch configuration and
launching an associated process. </p>
<h4>Specifying a JRE</h4>
<p>The JRE used to execute a Java application is, by default, the JRE on the build
path of the project being launched. If a launch configuration is not associated
with a project (as in this example), the workspace default JRE is used. A specific
JRE may be specified on a Java launch configuration, to refer to one of the
JREs defined in the workspace. A workspace may have any number of JREs defined,
which can be configured and displayed on the <b>Java &gt; Installed JREs</b>
preference page.</p>
<p>The Java launching plug-in allows for different types of JREs, as there are
many vendors and versions of JREs. A type of JRE is represented by the interface
<code>IVMInstallType</code>. For example, VMs which conform to the standard
Sun command line options are represented by one type of JRE. A specific instance
or installation of a type of JRE, is represented by the interface <code>IVMInstall</code>.
(Once again, we see the Type Object pattern).</p>
<p>The VM install types defined in a workspace can be retrieved from the <code>JavaRuntime</code>
class in the Java launching plug-in (<code>org.eclipse.jdt.launching</code>).
The instances or installations of each VM type, are retrieved from the VM type.
Our cascading sample menu <b>Start Tomcat, </b>loops through each VM install
within each VM type, and populates a submenu of actions - one for each VM install
in the workspace, as shown in the following code snippet from <code>StartMenuAction</code>.</p>
<pre>IVMInstallType[] types = JavaRuntime.getVMInstallTypes();<br>for (int i = 0; i &lt; types.length; i++) {<br> IVMInstallType type = types[i];<br> IVMInstall[] jres = type.getVMInstalls();<br> for (int j = 0; j &lt; jres.length; j++) {<br> IAction action = new StartAction(jres[j]);<br> ActionContributionItem item = new ActionContributionItem(action);<br> item.fill(menu, -1);<br> }<br>}</pre>
<p>Thus, each <code>StartAction</code> is created to launch Tomcat with a specific
JRE, and uses the following code to specify the JRE on the launch configuration.</p>
<pre>workingCopy.setAttribute(ATTR_VM_INSTALL_NAME, jre.getName());
workingCopy.setAttribute(ATTR_VM_INSTALL_TYPE, jre.getVMInstallType().getId());</pre>
<p>The JRE name and type are specified via the attributes <code>ATTR_VM_INSTALL_NAME</code>
and <code>ATTR_VM_INSTALL_TYPE</code>, respectively. Each VM install type has
an associated identifier that uniquely identifies it among other VM install
types, and this identifier is used to specify the VM type. The actual VM installation
is specified by the name of the JRE. Although a JRE also has a unique identifier,
the name of a JRE is used to identify it instead. The identifier for a specific
VM install may be different between workspaces, and has little meaning to a
user (as it is simply a number). Thus, the name is more descriptive and portable
when sharing a launch configuration with other users.</p>
<h4>Specifying a Main Type and Program Arguments</h4>
<p>The next step is to specify the main type we want to launch and the arguments
to pass to the main type.</p>
<pre><img src="images/tag_1.gif" width=24 align=CENTER>workingCopy.setAttribute(ATTR_MAIN_TYPE_NAME,<br> &quot;org.apache.catalina.startup.Bootstrap&quot;);<br><img src="images/tag_2.gif" width=24 align=CENTER>workingCopy.setAttribute(ATTR_PROGRAM_ARGUMENTS, &quot;start&quot;);</pre>
<li>To specify a main type, we simply set the main type attribute - <code>ATTR_MAIN_TYPE_NAME</code>.
The value is a string containing the fully qualified name of the main type.</li>
<li>To specify program arguments, the <code>ATTR_PROGRAM_ARGUMENTS</code> attribute
is used. Its value is a string containing the raw command line arguments to
pass to the main type.</li>
<h4>Specifying a Classpath</h4>
<p>By default, the project associated with a Java application launch configuration
is used to determine a runtime classpath for the application (which is specified
by the <code>ATTR_PROJECT_NAME</code> attribute). Generally, the build path
specified for a project in the workspace corresponds to the desired runtime
classpath. Thus, when a classpath is not explicitly specified on a launch configuration,
a default runtime classpath is computed from the associated project's build
path. However, our example launch configuration is not associated with a project
in the workspace - we are launching an application external to the workspace.
Thus, we must specify the runtime classpath to use.</p>
<p><img src="images/tip.gif" width="62" height="13"> In the Eclipse SDK, the command
line used to launch a Java application can be viewed by selecting the associated
process or debug target in the <b>Debug View</b>, and selecting <b>Properties</b>
from the context menu. This displays a dialog containing the command line (including
the classpath option) generated to launch a Java application. Examining the
command used to launch a process can be useful when diagnosing launch problems.</p>
<p>In the Eclipse SDK, the runtime classpath can be configured via the <b>Classpath</b>
tab of a Java application launch configuration. On this tab, the user can specify
the order of projects, system libraries, jars, folders, and variables to be
placed on the classpath. Entries can be added to the user application classpath
or the boot path. Similarly, a classpath can be programmatically specified on
a Java application launch configuration as an ordered list of classpath entries.
The attribute used to specify a classpath is <code>ATTR_CLASSPATH</code>,
and its value is a list of <code>String</code>s,
each of which is a memento for an <code>IRuntimeClasspathEntry</code>.</p>
<p>An <code>IRuntimeClasspathEntry</code> can
be used to describe any of the following:</p>
<li>a project in the workspace</li>
<li>an archive (jar or zip file) in the workspace</li>
<li> an archive in the local file system</li>
<li>a folder in the workspace</li>
<li>a folder in the local file system</li>
<li>a classpath variable with an optional extension</li>
<li>a system library (also known as a classpath container, which is a related
group of archives, such as the jars associated with a JDK)</li>
<p>The classpath specified on a launch configuration is specified in an unresolved
format, and is resolved by the launch delegate at run time. For example, a project
entry on the classpath is resolved to the output locations of that project (i.e.
the folder or folders that contain the compiled class files for the project).
Specifying an unresolved classpath on the launch configuration makes the classpath
portable between workspaces and shareable among users. When a classpath is specified
on a launch configuration, it must be specified completely - that is, including boot path
and user classpath entries.</p>
<p>Our example requires two entries on the user application classpath - <code>tools.jar
</code>and <code>bootstrap.jar</code>.</p>
<pre><img src="images/tag_1.gif" width=24 align=CENTER>IVMInstall jre = JavaRuntime.getDefaultVMInstall(); <br> File jdkHome = jre.getInstallLocation();<br> IPath toolsPath = new Path(jdkHome.getAbsolutePath())<br> .append(&quot;lib&quot;)<br> .append(&quot;tools.jar&quot;);<br> IRuntimeClasspathEntry toolsEntry =<br> JavaRuntime.newArchiveRuntimeClasspathEntry(toolsPath);<br> toolsEntry.setClasspathProperty(IRuntimeClasspathEntry.USER_CLASSES);<br><img src="images/tag_2.gif" width=24 align=CENTER>IPath bootstrapPath = new Path(&quot;TOMCAT_HOME&quot;)<br> .append(&quot;bin&quot;)<br> .append(&quot;bootstrap.jar&quot;);<br> IRuntimeClasspathEntry bootstrapEntry = <br> JavaRuntime.newVariableRuntimeClasspathEntry(bootstrapPath);<br> bootstrapEntry.setClasspathProperty(IRuntimeClasspathEntry.USER_CLASSES); <br><img src="images/tag_3.gif" width=24 align=CENTER>IPath systemLibsPath = new Path(JavaRuntime.JRE_CONTAINER);<br> IRuntimeClasspathEntry systemLibsEntry =<br> JavaRuntime.newRuntimeContainerClasspathEntry(systemLibsPath,<br> IRuntimeClasspathEntry.STANDARD_CLASSES);<br><img src="images/tag_4.gif" width=24 align=CENTER>List classpath = new ArrayList();<br> classpath.add(toolsEntry.getMemento());<br> classpath.add(bootstrapEntry.getMemento());<br> classpath.add(systemLibsEntry.getMemento());<br> workingCopy.setAttribute(ATTR_CLASSPATH, classpath);<br> workingCopy.setAttribute(ATTR_DEFAULT_CLASSPATH, false);</pre>
<li>The first entry on our classpath is <code>tools.jar</code> from the JDK
install. (This example assumes you have set your workspace default JRE to
a JDK install containing <code>tools.jar</code> in the <code>lib</code> directory).
We create a classpath entry that points to an archive in the local file system,
with an absolute path. We build the path relative to the install location
of the workspace default JRE. The entry's classpath property is set to <code>USER_CLASSES</code>,
to indicate that the classpath entry is to appear on the user application
portion of the classpath.</li>
<li>Next, a classpath entry for Tomcat's <code>bootstrap.jar</code> is created.
(This example assumes you have defined a classpath variable, <code>TOMCAT_HOME</code>,
that points to the install location of Tomcat). This entry is created relative
to the Tomcat install location, by creating a variable entry with an extension
of &quot;<code>bin\bootstrap.jar</code>&quot;. This entry is also set to appear
on the user application portion of the classpath.</li>
<li>When launching Tomcat from the command line, we did not specify a boot path
(the default boot path was used). However, when specifying a classpath on
a Java launch configuration, the complete path must be specified. Thus, an
entry is created that refers to the system libraries associated with the default
JRE. The classpath property of this entry is set to <code>STANDARD_CLASSES</code>,
indicating that the entry refers to a set of archives that normally appear
on the boot path by default. The Java application launch delegate only generates
a boot path argument when non-default entries appear on the boot path. However,
we must still specify all entries.</li>
<li>The classpath attribute is created and set - an <b>ordered</b> list of runtime
classpath entry <b>mementos</b>. It is also important to note that the <code>ATTR_DEFAULT_CLASSPATH</code>
attribute is also set to <code>false</code>. When this attribute is omitted
or set to <code>true</code>, a default classpath is used, rather than the
classpath specified on the launch configuration.</li>
<h4>Specifying System Properties</h4>
<p>Next we specify system properties.</p>
<pre><img src="images/tag_1.gif" width=24 align=CENTER>workingCopy.setAttribute(ATTR_VM_ARGUMENTS,<br> &quot;-Djava.endorsed.dirs=\&quot;..\\common\\endorsed\&quot;&quot;<br> + &quot;-Dcatalina.base=\&quot;..\&quot;&quot;<br> + &quot;-Dcatalina.home=\&quot;..\&quot;&quot;<br> + &quot;\&quot;..\\temp\&quot;&quot;);</pre>
<li>System properties are specified as VM arguments, using the <code>ATTR_VM_ARGUMENTS</code>
attribute. The value is a string of raw arguments, as they would appear on
the command line.</li>
<h4>Specifying a Working Directory</h4>
<p>The working directory associated with a Java runtime can be retrieved at run
time via the system property <code>user.dir</code> (that is, <code>System.getProperty(&quot;user.dir&quot;)</code>).
At run time, file operations are performed relative to the working directory
when absolute paths are not specified. When launching a Java program from the
command line, the working directory is initialized to the location in the file
system from which the VM is launched. When launching a Java program from within
Eclipse, the working directory must be specified. When a working directory is
not specified, it is, by default, the location in the local file system that
corresponds to the directory of the project being launched. When a project is
not associated with a launch configuration, the default working directory is
the directory from which the Eclipse SDK was started.</p>
<p>When we launched Tomcat from the command line, the working directory was the
<code>bin</code> directory of the Tomcat install - i.e. the directory from which
the command was given. Since we have specified system properties relative to
the working directory, we must also specify the working directory that should
be used on our launch configuration.</p>
<pre><img src="images/tag_1.gif" width=24 align=CENTER>File workingDir = JavaCore.getClasspathVariable(&quot;TOMCAT_HOME&quot;)<br> .append(&quot;bin&quot;).toFile();<br> workingCopy.setAttribute(ATTR_WORKING_DIRECTORY,<br> workingDir.getAbsolutePath());</pre>
<li>The value of the working directory attribute is a string representing a
path. If the path is absolute (that is, begins with a device or path separator),
the path is interpreted as a location in the local file system. If the path
is relative (does not begin with a device or path separator), the path is
interpreted as relative to the workspace root. Our example specifies an absolute
path in the local file system - the <code>bin</code> directory of the Tomcat
<h4>Launching a Configuration</h4>
<p>Now we are ready to launch our configuration.</p>
<pre><img src="images/tag_1.gif" width=24 align=CENTER>ILaunchConfiguration configuration = workingCopy.doSave();<br><img src="images/tag_2.gif" width=24 align=CENTER>DebugUITools.launch(configuration, ILaunchManager.RUN_MODE);</pre>
<li>First, the working copy launch configuration is saved. This persists the
launch configuration locally with the workspace metadata.</li>
<li>Next, the configuration is launched. This example launches the configuration
in run mode, using the launch API provided by the debug UI plug-in. This convenience
API has several advantages. According to workspace preferences any unsaved
editors are saved, the workspace is built, and then the configuration is launched,
all while displaying a progress dialog.</li>
<p><img src="images/tip.gif" width="62" height="13"> You can also launch a configuration
via the API <code>ILaunchConfiguration.launch(String mode, IProgressMonitor
monitor)</code>. This avoids saving editors and building the workspace, but
it requires you to provide a progress monitor.</p>
<p><img src="images/tryit.gif" width="61" height="13"> Display the <b>Tomcat </b>action
set by selecting <b>Window &gt; Customize Perspective</b>, and then checking
the <b>Tomcat Example</b> action set. Run the example by selecting the <b>Start
Tomcat</b> action from the <b>Tomcat</b> menu our example plug-in provides,
and selecting a JRE from the cascading menu. Note that you must choose a JRE
that is a JDK containing a <code>tools.jar</code>. Output will appear in the
console as the server is launched. You can verify the server is up and running
by opening a Web browser on this address <code><a href="http://localhost:8080/">http://localhost:8080</a></code>.
Notice that the launch configuration we created also appears in the launch history
(drop down <b>Run</b> and <b>Debug</b> menus), and the launch configuration
also appears in the launch configuration dialog.</p>
<p><img src="images/tip.gif" width="62" height="13"> We could avoid having the
launch configuration appear in the launch dialog and launch history by marking
our launch configuration as private. The debug plug-in defines an attribute
common to all launch configurations to control this - <code>IDebugUIConstants.ATTR_PRIVATE</code>.
The value is a boolean indicating if the launch configuration is private, and
the default value is <code>false</code> (i.e. when unspecified).</p>
<h3>Stopping the Server</h3>
<p>A <b>Stop Tomcat</b> action is provided to shut down Tomcat as well - available
from the <b>Tomcat</b> menu. This action is almost identical to the start action,
except it creates a launch configuration with a different name (<code>Stop Tomcat</code>),
and specifies the <code>stop</code> argument in place of <code>start</code>.</p>
<p><img src="images/tryit.gif" width="61" height="13">Shut down the server by
selecting the <b>Stop Tomcat</b> action. You will notice another process is
launched and then both processes (the Tomcat server and the newly launched process)
eventually terminate. </p>
<h3>Debugging the Server</h3>
<p>The example has shown how to launch Tomcat in run mode. The VM used to run
Tomcat can also be launched in debug mode, simply by changing the mode specified
in the following line.</p>
<pre>DebugUITools.launch(configuration, ILaunchManager.DEBUG_MODE);</pre>
<p><img src="images/tryit.gif" width="61" height="13"> Another way to launch Tomcat
in debug mode is to re-launch Tomcat from the debug drop down menu, or from
the launch configuration dialog when opened in debug mode. Tomcat will launch,
and its process, debug target, and threads will be displayed in the debug view.</p>
<h2>Other Launch Options</h2>
<p>Our Tomcat example demonstrates many of the common features/attributes required
for launching Java applications programmatically. However, there are other aspects
of the launch that can be controlled by attributes that were not used in our
example. The following list provides a summary of the options not covered by
the example, and when you might want to use them.</p>
<li><code>ATTR_PROJECT_NAME</code> - This attribute specifies the name of a
Java project associated with a launch configuration. When this attribute is
specified, the launch delegate uses the associated project to compute default
values for a launch - such as runtime classpath, working directory, JRE, and
source lookup path.</li>
<li><code>ATTR_STOP_IN_MAIN</code> - This attribute is a boolean indicating
whether an application should suspend when the <code>main</code> method is
entered on startup. The default value is <code>false</code>, and this attribute
is only effective when a configuration is launched in debug mode.</li>
<li><code>ATTR_VM_INSTALL_TYPE_SPECIFIC_ATTRS_MAP</code> - This attribute is
a map of attribute-value pairs. The interpretation of the attributes is specific
to a VM install type. For example, the Standard VM install type supports the
specification of the name of the executable used to launch a VM - i.e. java,
javaw, etc. This value is specified by the <code>ATTR_JAVA_COMMAND</code>
attribute with in this attribute map. An extension point (<code>org.eclipse.jdt.debug.ui.vmInstallTypePage</code>)
exists for clients to contribute a user interface control to the JRE tab of
a Java application launch configuration, to display and edit JRE specific
<li><code>ATTR_SOURCE_PATH</code> - This attribute is analogous to the classpath
attribute, except that it specifies where source should be be located. The
value is an ordered list of runtime classpath entry mementos. This attribute
is used mostly in debug mode when stepping through source code, but is also
useful in run mode when navigating from stack traces in the console to corresponding
<li><code>ATTR_DEFAULT_SOURCE_PATH</code> - This boolean attribute (analogous
to <code>ATTR_DEFAULT_CLASSPATH</code>) indicates whether a default source
path should be used, based on the default classpath. When unspecified or <code>true</code>,
any explicitly specified source path is ignored.</li>
<li><code>ATTR_CLASSPATH_PROVIDER</code> - This attribute specifies an identifier
of a classpath provider extension (extensions of type <code>org.eclipse.jdt.launching.classpathProviders</code>).
When specified, the associated classpath provider is consulted to compute
and resolve a runtime classpath for a launch configuration. This provides
clients with a hook for generating and resolving runtime classpaths.</li>
<li><code>ATTR_SOURCE_PATH_PROVIDER</code> - This attribute is analogous to
<code>ATTR_CLASSPATH_PROVIDER</code>, except that it specifies an extension
used to compute and resolve the source lookup path.</li>
<p>Launch configurations provide a high-level API for programmatically launching
Java applications. Just as a user can create, modify and launch an application
from the Eclipse user interface, configurations can be created, modified, and
launched programmatically. Java VM command line options correspond to Java launch
configuration attributes. Launch configurations leverage features of the debug
platform launching framework - persistence, launch history, console I/O, and
visibility in the launch configuration dialog.</p>
<p><small>Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries,
or both.</small></p>
<p><small>Other company, product, and service names may be trademarks or service marks
of others.</small></p>