Developing Web applications with Maven and Eclipse: You *can* have it all

When developing applications using Eclipse or a similar IDE, you quickly get used to being able to test your software immediately after making a change. Plugins like MyEclipseIDE enable that kind of instant edit/compile/test cycle for web applications as well.

But if you’re building web applications with Maven, it’s not so easy. Maven is a fantastic tool for building applications and managing dependencies, but it lends itself to a more batch-oriented mode of operation in which you build and deploy war files from the command line. I found myself wishing I could have the best of both worlds; building my web applications using Maven, but with a seamless edit/compile/test cycle when using Eclipse. Then I discovered the WTP (Web Tools Platform) project. Hallelujah!

WTP extends the Eclipse platform with tools for developing Web and Java EE applications. Not only does that include a way to incrementally deploy applications to an application server, it’s supported by Maven – so you can have your cake and eat it too. The trick is to add a clause to your Maven pom.xml file which causes Maven’s eclipse:eclipse target to emit the proper WTP configuration information. Then when you open the project in Eclipse, you can use WTP’s seamless deployment capabilities.

Here’s a step by step explanation of how to set this up:

1. First you need to have your web application working with Maven. There are plenty of tutorials on the web explaining how to do this. If you just want to create a simple example quickly, you can build a skeleton web application using this command (after you have Maven installed and working on your PC). This should be typed all on one line:

mvn archetype:create -DgroupId=com.lab49.example -DartifactId=myWebApp
     -DarchetypeArtifactId=maven-archetype-webapp

This will create a skeleton hello, world web application that can be built with Maven, which you can extend with JSP pages, classes, etc.

2. Add the following two clauses within the build element in the pom.xml file:

<!-- add support for Jetty testing -->
<plugins>
    <plugin>
        <groupId>org.mortbay.jetty</groupId>
        <artifactId>maven-jetty-plugin</artifactId>
    </plugin>
</plugins>

<!-- add Eclipse WTP support -->
<pluginManagement>
    <plugins>
        <plugin>
            <artifactId>maven-eclipse-plugin</artifactId>
            <configuration>
                <wtpversion>2.0</wtpversion>
                <wtpapplicationxml>true</wtpapplicationxml>
                <wtpmanifest>true</wtpmanifest>
                <downloadSources>true</downloadSources>
                <downloadJavadocs>true</downloadJavadocs>
                <projectNameTemplate>[artifactId]-[version]</projectNameTemplate>
                <manifest>${basedir}/src/main/resources/META-INF/MANIFEST.MF</manifest>
            </configuration>
        </plugin>
    </plugins>
</pluginManagement>

The Jetty support is not what this article is about, but it’s a nice thing to include. It enables you to test your code using the Maven command:

mvn jetty:run

to compile your application, start up a web server (based on the Jetty web server library), and deploy itself so you can access it via a URL something like:

http://localhost:8080/myWebApp/

Having to test your application by starting a web server from the command line is still a batch mode of operation and doesn’t perfectly fit the Eclipse model of development, but nonetheless it’s very convenient.

3. Now let’s enable the WTP support. Generate a set of Eclipse project files for your Maven project. If you had previously generated them without WTP support you should delete them and recreate them, i.e.

mvn eclipse:clean
mvn eclipse:eclipse

4. Make sure you have WTP support in your version of Eclipse. The easiest way to do that is to use the version Eclipse IDE for Java EE Developers which already includes WTP support. If you weren’t using that version before, you can download it, then open your original Eclipse workspace to migrate seamlessly. Otherwise you’ll have to follow these instructions to add WTP support to your existing version of Eclipse.

5. Set up your Maven web application as a Java project within Eclipse (i.e. create a new Java Project from existing source, and select the root Maven web application directory with the generated Eclipse config files). At that point you should see your Maven project in Eclipse, be able to edit JSPs, Java classes and so on.

6. Install an application server on your PC if you don’t already have one set up, e.g. Tomcat.

7. The next step is to link Eclipse to your Tomcat installation (or other application server). The WTP platform refers to this as setting up a Server Runtime Environment. To do this, go to Eclipse / Window / Preferences / Server / Installed Runtimes (this option will only be available if WTP support has been installed), click Add, select your application server type and version (e.g. Tomcat 6.0), and select the installation directory of the application server along with any other required options e.g. which JRE to use.

Then go to the Server View in Eclipse (Window / Show View/ Other… / Server / Servers). Right click in the window and select New / Server. Choose the server runtime you just configured. Click Finish.

The Servers view should now display an entry for your application server. Select it and click the green triangle icon to start the server. (Make sure the server was not running beforehand.) If everything is set up properly, Eclipse will launch the server, the console will show the startup log, and the server state in Eclipse will change to Started.

8. Finally, tell Eclipse to add your web application project to the application server. From the Servers View, right click on your application server and select Add and Remove Projects. Your Eclipse web application project should show up on the left hand side of the window as an available project (since Maven added the WTP configuration when generating the Eclipse project files). Click Add to move it over to the right hand side (configured projects) and click Finish.

If everything has been configured properly, the Server View will show your web application project listed under the application server, and the status will show as Synchronized. Your project will be live and accessible via a URL like:

http://localhost:8080/myWebApp/

Now you can leave your application server running all the time. You can edit JSPs, Java code, etc. in your web project and whenever you save a change, it will instantly be published to the application server. (If you look at the Servers View window, you’ll see it temporarily change to status republish then back to synchronized whenever you save a change).

Now you have an instant edit/compile/test cycle, but you can also rebuild your application at any time from the command line using Maven. You can have it all.

p.s. I’ve found Eclipse sometimes gets carried away validating various elements of web projects. This can be so slow as to make the IDE unusable. You can disable validation by selecting Window / Preferences / Validation. From this window you can disable validation globally, for specific projects, or for specific types of files.

p.p.s. If you are using Java 5 or Java 6, Eclipse may also highlight your web project in red with the error Java compiler level does not match the version of the installed Java project facet. To fix this, right click on the web project and select Properties. Select Project Facets. Click Modify Project. A list of Project Facets will be displayed. Correct the Java Version (e.g. from 1.4 to 5.0). Click Finish.