Creating a Maven Web Project in Eclipse

My development platform of choice has been Eclipse for many years now and, more recently, I have really started to enjoy the library management that Maven provides me in development, testing and production.  Although there are very nice plugins available for integrating Maven and Eclipse together, it is not always the most straight forward process to setup a WTP project in Eclipse that can utilize Maven.  I have also found that since creating new projects is not something that we do on a daily or even monthly basis, it can easily become a trial and error episode chewing up a couple of hours of precious development time.  I hope that walking through it here will help save you some time on your next project.
Let's assume a fresh install of Eclipse.  I am using Eclipse 3.6 Helios for Java EE developers which you can download from eclipse.org.  You will also need to download and extract Apache Tomcat 6.  We will point to this Tomcat directory later when we go to test our project setup.

Our fresh install of Eclipse does not come with the necessary Maven plugins, so we will need to install them first.  In Eclipse, navigate to your Help menu and select "Install New Software...".

In the top right hand corner, click on the "Add..." button and a dialog will appear that will allow you to add an new update site for the M2 Eclipse plugin.  The Location is: http://m2eclipse.sonatype.org/sites/m2e .  You can name the site anything that you like, but  you will want it to reflect the name so that you will recognize it later if you come back to scan through your plugins.  I have named mine M2Eclipse.

Clicking OK here will take you to a screen so that you can choose the pieces that you want to download.  For this site, you only have one choice so it is easy.  Check it and click finish and the plugin will start to install.

You will have to navigate and agree to the license.  It will also ask you to restart eclipse after the install.  You should go ahead and do this and return back to the "Install New Software..." screen after the restart.  You will also need to install the M2 Eclipse Extras in the same way.  The repository location for the extras is: http://m2eclipse.sonatype.org/sites/m2e-extras

This update site contains more than one item to install.  You will not need to check the M2Eclipse Extensions Develop Support or the Project configurators for commonly used maven plugins.  I do like to use Mylyn and the integration with CVS is nice to have, but they are not necessary.  You can choose the ones that you feel you need for your development environment.  The only one that you must pull down is the Maven Integration for WTP.

Clicking Finish here will take you through the license agreement again and then ask you to restart.

After restarting, let's continue by installing the Apache Tomcat runtime environment in Eclipse.  Under Eclipse "Preferences..." navigate down to "Server > Runtime Environments".  Click on "Add..." and select "Apache Tomcat v6.0" and click Next.

You will need to enter the Tomcat installation directory.  This will be the directory where you extracted Tomcat.  You can use "Browse..." to locate and populate that location.

We are now ready to create our Web project.  Return to the Project Explorer in the Java EE perspective and choose File > New > Dynamic Web Project

Simply name your project and make sure that your Target runtime is set to Apache Tomcat 6.0 and your Dynamic web module version is 2.5

Click Next >

This screen will allow you to configure your folders for building the application.  We are going to modify these folders to match the Maven hierarchy.  This can be done later as well, but doing it now will avoid some copy and paste as well as some deleting cleanup.  You will need to remove the "src" folder that is listed by default and add the following source folders:

• src/main/java
• src/main/resources
• src/test/java
• src/test/resources

You should also change the Default output folder to "target/classes"

Click Next >

We are also going to change the Web Module settings to match the Maven packaging.  You will need to change the Content directory on this page from WebContent to "src/main/webapp".

Click Finish.

This completes the setup of the Dynamic Web Project.  We now need to make it a Maven project as well.  This can be done by right clicking on the project in the Project Explorer and choosing "Maven > Enable Dependency Management"

In this wizard, you will only need to change the Packaging to "war" instead of "jar". and click "Finish"

You should now see the POM editor in Eclipse.  We need to add a compiler plugin for 1.6 that will help keep things building cleanly.  Click on the Plugins tab at the bottom of the editor and then Click on "Add..." in the Plugins section at the top left.  Search for the groupId of "org.apache.maven.plugins" and then choose the "maven-compiler-plugin" artifact from the list.

Click on OK and then navigate to the "pom.xml" tab in the editor.  We need to add the configuration for 1.6 which we cannot do through the GUI.  All that is needed is the configuration XML that is selected below.

Save and close the POM editor.

When that completes building, you may notice that the Java Runtime is giving you a warning in your "Markers" tab.

This can be remedied by changing your build path.  You can right click on the project and select "Properties" and then change the build path JRE System Library to point to the 1.6 Execution Environment.  If you do not have your Execution Environments set, you can simply click on the "Environments..." button on this dialog and point them to the JDK installation on your machine.

Clicking Finish here will rebuild the project and you should be error free in your Markers tab.

Now for some simple cleanup of your project.  You can expand your project in the Project Explorer and navigate down to Web Resources > WEB-INF  and delete the lib directory.  We are going to let Maven and WTP work together to manage this.

You will also notice that you have a Classpath Dependency warning in your Markers tab.  This is very important and will have to be addressed if you want your Maven managed dependencies to be available to your local test server.

Simply right click on the warning and choose the "Quick Fix" option.

Then you will be prompted with a popup explaining the suggested remedies to your problem.  We need the classpath to be available to our server, so we need it to be added as a dependency.  Choose that option and then click "Finish".

The setup is now complete.  All that is left now is to test our new project and configuration.  This is easily done by creating an index JSP in our webapp directory.

 After saving the JSP, you can test your application by right clicking on the project and choosing "Run As > Run on Server"

Choose the Tomcat v6.0 Server and then click Finish.  This will push your project to deploy on startup of that server and it will start the server.

When the startup is done, a browser window should appear in Eclipse with your index.jsp content displayed.

You are now off to the races on your new web project using Maven.  All of the dependencies that you add to the pom file will be included in the classpath each time you start the server.

I hope that you found this useful.  Let me know your experience.