Jetty and Eclipse Integration

The Jetty web server is a standards compliant J2EE container that is regularly updated to conform with the latest servlet and JSP specifications. Because of its embeddable nature, it is a popular choice with developers who need to incorporate a servlet container /web server in their applications. It is also a natural choice to quickly debug and test web applications that are being developed using the Eclipse IDE.

Jetty Launcher as an Eclipse Plugin

Simplicity notwithstanding, setting up a Web application for debug and testing on Jetty server as a separate command line process can slow down the development cycle considerably. This is especially true for extremely short “change-build-view” cycles. The extra effort can be attributed to

• context switching between the Jetty console (command shell) and the Eclipse IDE
• establish visual traceability between console messages and the corresponding source codes.
• lack of visual debugging capabilities and step through of source code.

The obvious solution is to have a Jetty launcher as an Eclipse plugin for better IDE integration. Unfortunately, there are some practical issues with this scheme, the primary one being that of version mismatches.

As open-source products, both Eclipse and Jetty undergo a change in version quite frequently. For Jetty, the structure of the distribution, in terms of necessary files and folders, keep changing with every major release. Eclipse plugins, on the other hand, are well known for not being cross compatible (backward and forward) with different versions of the IDE.

By far, the most popular plugin for Eclipse and Jetty integration is the Jetty launcher (see Resources and Links at the bottom). Unfortunately, this plugin does not work with latest versions of Jetty (6.x) and Eclipse (3.2.x) due to changes in the structure of Jetty distribution.

A Simple Solution

A good thing about the Jetty distribution is that it uses a single bootstrap jar (start.jar) as the launcher and the entry point to the main servlet container. The location of different libraries and the necessary files and folders for configuration and logging are stored as metadata information in the file org/mortbay/start/start.config within the bootstrap jar. In a pinch, it is possible to extract this file, make modifications as necessary and update the bootstrap jar with the latest contents.

A simple solution to a universal integration would therefore involve setting up the Jetty server as a Java project and execute the start.jar as an external application from within Eclipse. The exact steps to perform this setup are as explained in the following sections.

Step-by-Step Integration

For the purpose of this article, we shall assume the target version of Eclipse to be 3.1.2 and that of Jetty to be 6.1.1. The process enumerated below should remain more-or-less the same for different versions of Jetty and Eclipse.

Step 1: Create Jetty Server Project

Create a Java project in Eclipse called “Jetty Server”. The name is not significant, you can name it anything as long as it makes sense. This project is the one that will be used to launch Jetty as an application from within Eclipse.

Copy the necessary files from the Jetty 6.1.1 distribution including sub-folders to the “Jetty Server” project. The project tree should now look somewhat like this:

Right-click on the project name, select Properties in the popup menu to get the properties dialog box. Add start.jar to the list of libraries in the Java build path.

Step 2: Create Web Application Project

Create your Web application as a separate project under the same Eclipse workspace. The folder structure of a sample Web application is as provided below:

You need to make sure that the Web application project defines a web root folder for setup with Jetty. In the example above it is the folder sampleapp_webroot.

Step 3: Putting it all Together

One nice thing about Jetty 6.x is the support for application context for hot-deployment of applications under development. To make use of this feature, create a file called sampleapp.xml under the folder contexts. The contents of this file should look somewhat like this:

<Configure class="org.mortbay.jetty.webapp.WebAppContext">
  <Set name="contextPath">/app</Set>
  <Set name="war">../sample_app/sampleapp_webroot</Set>
  <Set name="extractWAR">true</Set>
  <Set name="copyWebDir">false</Set>
  <Set name="defaultsDescriptor">
    <SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml
  </Set>
</Configure>

This essentially loads the expanded web application under the path contextPath and maps the same for access using the URL http://<server_name&gt;:<port>/app. Note that relative path names are allowed for the contextPath attribute.

Step 4: Running the Server

Select the “Jetty Server” project within Eclipse. From the main menubar select Run and Run … to bring up the configuration dialog box. Create a new run configuration under Java Application as shown below:

The main class to launch is org.mortbay.start.Main. Save the settings by clicking on the Apply button.

Now press Run to start the Jetty server. If everything goes fine, you will see the Jetty output in the Eclipse console pane. Next time you can start the Jetty server using the Ctrl+F11 shortcut key within Eclipse (Java perspective).

Distribution

For mid-sized development teams, repeating the above steps on multiple desktops can be a time consuming and error-prone process. Having a single distribution of a “Jetty Server” project should help.

Right click on the “Jetty Server” project in Eclipse and select Export from the popup menu. In the export dialog box choose the export destination to be of type “Archive File”. In the next screen, select the output archive file path and click Finish.

Note: Make sure that all items under the “Jetty Server” project are selected for export including the .project and .classpath entries under the root folder.

For installation on a fresh desktop, take the distribution archive and unzip the same in a suitable folder on the target machine. Under Eclipse, create a new Java project from existing source. For the source path, select the folder where you unzipped the distribution archive.

Eclipse Debugging

It is also possible to enable Eclipse debugging for the Web application under development in Jetty. To do so, select the “Jetty Server” project within Eclipse. From the main menubar select Run and Debug … to bring up the configuration dialog box. Creating a new run configuration for debugging is the same as that for a normal startup as explained in Step 4 above. Note that you can press F11 (shortcut key) to launch the previously executed debug session.

In case your Web application contains libraries (jar files) that are under active development as part of the overall application, you would need to step through the source of those libraries as well. To enable such debugging, right click on the library jar in Eclipse, select Properties from the popup menu and attach the corresponding source.

Resources and Links

[1] The Jetty Webserver homepage is at http://jetty.mortbay.org.

[2] The Jetty Launcher plugin for Eclipse can be obtained from http://jettylauncher.sourceforge.net.

reddit