Monday, August 9, 2010

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.


25 comments:

Paul said...

Thanks for the great tutorial. Saves hours of headaches.

Karim said...

best tutorial on maven ever...hi paul the pou, love your work

Anonymous said...

Thanks a lot !!!! This was really wonderful ... was struggling from last 4 days to figure my problems out...
Hare Krishna

Allemand said...

Hi!
Good post! But it isn't work for me.
The export (right click / export / war) works fine but when I deploy in my local Tomcat the Maven Dependencies is empty. So nothing that I describe in pom.xml don't go to my server. HELP!

PS: Sorry about my english, I'm brazilian!

Troy Tolle said...

Allemand,
Your WEB-INF/lib directory is where you will find your jar dependancies after you export your war file.

Allemand said...

Ok, I know that.
But when I publish the application on my Eclipse Server (Tomcat, like in your example) the lib folder is empty. All that I add as Dependency in pom.xml is ignored when I deploy in my local Tomcat.
For example, add Hibernate as dependency and create a Filter that only create a new org.hibernate.cfg.Annotationconfoguration and call your index.jsp.
Should appears a message like java.lang.ClassNotFoundException: org.hibernate.cfg.AnnotationConfiguration.

Troy Tolle said...

Allemand,
I am not sure why your lib directory is empty. I would try deleting your target directory and doing a Maven clean and then update dependancies and then building the project again so it creates the target directory again. I am including links here to a couple of screenshots of my export and the result.

http://imgur.com/3JAiE.png

http://imgur.com/7VOmP.png

Allemand said...

DONE!!!! uhuuu!
The error was on the version of the M2Eclipse plugin and the Eclipse Mac Version! Why? I don't know! I simply delete-install the plugin!
Sorry!

exac said...

Thank you very much for your great piece of work. I've read many tutorials how to join eclipse and maven features in web app. project, but none was so usefull and precise as yours. It really helped.

Troy Tolle said...

Thanks exac. Glad you found it useful.

Nagarajah Sujeevan. said...

Thanks, This is what I was looking for. You saved my time.

Troy Tolle said...

Nagarajah,
Glad to hear it. I hope your project is a success!

Anonymous said...

Awesome post. very clear explantion .

Thanks

Charles Chigoriwa said...

This is wonderful. What a concise and useful article!!!God bless you. Keep up the spirit

Troy Tolle said...

Thank you Charles!

Andrius Kurtinaitis said...

I have done all the steps, and the problem I am facing is that when I include Maven dependencies as a deployment assemblies, I get duplicate jar files in the application - Eclipse also copies 'provided' dependencies to WEB-INF/lib - which it should not. Have'nt you had such a problem?

Andrius Kurtinaitis said...

The Tomcat then gives various classloader problems, because it tries to some classes from load servlet-api or jas-api, which are already there and it gets conflicts...

Troy Tolle said...

Andrius, I have not had that problem. Please make sure that you are not adding any jar files manually to the classpath. If you are using maven, there is no need to do that as it will do exactly what you are saying and add them to the lib directory automatically for you based upon the dependency tree that is created.

Paul said...

good one

Jimmy Leo said...

Thank you so much.. Best tutorial on maven for eclipse ever.

So precise and clear.

Troy Tolle said...

Thank you Jimmy! I am glad you found it useful.

Anonymous said...

Thank you, your post helped me a lot.

papasani said...

Excellent article on integration of maven, tomcat, and eclipse.
Great help for us. Thank you

Nithin said...

Great one !!!
Thanks a lot... This was really helpful.

Fire Dragon said...

Bạn cần mua đồ mỹ? Bạn đang tìm nơi tin tưởng để bạn có thể nhờ mua hàng bên mỹ. Hãy đến với chúng tôi hiện chúng tôi đang cung cấp dịch vụ mua hàng mỹ và cùng nhiều dịch vụ khác có thể kể đến như nhận mua hàng trên amazon, ship hàng úc, mua hang ebay vn, ship hàng nhật bản, ... Nếu bạn đang cần nơi nhận order hàng ebay thì hãy đến với chúng tôi. Khi bạn đến với chúng tôi bạn sẽ thấy việc mua hàng trên ebay dễ dàng như có ebay vietnam vậy.