mandelbr0t's Journal: Maven, Eclipse+WTP+Spring, and Tomcat

The main problem with the J2EE development environment is that it's a lot less standardized than a .NET one. However, there's some really excellent software out there to help manage all of the issues with J2EE development. This article will focus specifically on Eclipse since it is available for free, and works well with all other required components.

I'm going to walk through the introduction to the SpringSource MVC Tutorial using instructions specific to Eclipse. Once you've run through this introduction, you'll understand how the project setup differs in Eclipse, but you'll still be able to follow along with the tutorial. I'm assuming a fresh install of Eclipse. I downloaded Eclipse for Java EE Developers. I'll leave the setup of Eclipse as an exercise for the reader. I would recommend that you use the 32-bit JVM to run Eclipse, as there are many issues with 64-bit Java, and 32-bit Java works fine for J2EE applications (which still run on 32-bit machines here anyway).

OK, once you've got Eclipse up and running, go to Help -> Install New Software... Add the following update site: Maven 2.x Integration for Eclipse. Install the Maven Integration (it's the only update available from this site). I also installed Maven WTP Integration from Maven Integration Extras. Finally, I installed Spring IDE.

Next, we'll create the project. Right-click in the Project Explorer, and select New -> Dynamic Web Project. Call the project springapp, remove src from the source folders path (we'll configure that in a minute) and change the default output folder to be target/classes. Create a Tomcat 6 server runtime or use an existing one. Change the WebContent directory to be src/main/webapp. Right-click on the springapp project, and select Build Path -> Configure Build Path. Select the Source Folders tab, and check the "Allow Output Folders for Source Folders" option. Make sure the default output folder is set to springapp/target/classes. Click the Add... button and add two source folders: src/main/java and src/test/java. You will have to create the source folders in the Add dialog. For src/test/java, expand and select Output folder. Click Edit... and select the Specific output folder radio button, and enter target/test-classes. We don't need the resource folders for this project. Now your project is created, and we'll add the remaining parts of the project, Maven and Spring.

First, start with Maven. Right-click on the springapp project, and select Maven -> Enable Dependency Management. This will prompt you to fill in the information for your springapp project. I used org.springsource for the group Id and springapp as the artifact name. I changed the packaging to war. You can change these options later by double-clicking on pom.xml once Maven Dependency Management has been enabled. Next, M2Eclipse will prompt you to add any Maven artifacts you need to the project. We only need one for now, spring-webmvc. Entering this in the quick-search box will find the artifact org.springframework.spring-webmvc very quickly. I used version 3.0. The remaining Spring components will be automatically imported as spring-webmvc depends on them.

There's one last problem that may need to be addressed. When I added Maven Dependency Management, I noticed that JRE System Library in the Libraries node was set to J2SE 1.4. Since I use the Tomcat 6 server runtime in this example, there will be a build error, since Tomcat 6 needs Java 1.5 at a minimum. You should have installed J2SE 1.6 prior to installing, Eclipse, but if you didn't, now is probably a good time. Make sure you have at least Java 1.5 if you don't upgrade to the latest version. Now, right-click on the JRE System Library and select Properties. Make sure the Execution Environment radio button is selected, and select J2SE-1.6 from the drop-down next to it. If J2SE 1.6 (or 1.5) isn't in the list, click the Execution Environments... button, and add a J2SE 1.5 or greater home directory. When you change the version of the JRE System Library, the build error should disappear in a few seconds.

By default, however, Eclipse WTP does not export the Maven artifacts to your WEB-INF/lib directory. This will lead to many error messages like "Wrapper could not find class org.springframework.web.servlet.DispatcherServlet", and other ClassNotFoundExceptions when trying to execute your Controller. So, to fix this problem, first delete the lib folder from src/main/webapp/WEB-INF (it will be created automatically by Maven). Then, right-click on the springapp project, and select Properties. In the left pane, select Java EE Module Dependencies, and check the box next to Maven Dependencies. This will now cause your Maven dependencies to be packaged in the project WAR, and eliminate the corresponding ClassNotFoundExceptions. The project is almost complete, but the Spring Project Nature has not yet been added. There are two ways to do so. We'll use the first and discuss the second later. Right-click on the springapp project, and select Spring -> Add Spring Project Nature. There's now a new node marked Spring Elements in your Project, but it's currently empty. That's it! The project is prepared.

Create the index.jsp by right-clicking on the springapp project and adding a JSP. Notice that by default, the JSP will be created in src/main/webapp, exactly where it is supposed to be. Copy and paste the code from the tutorial and save. Select index.jsp from the Web Content node in your project, and click the run button. It should automatically deploy to Tomcat and display in a new tab in Eclipse. Now, add the HelloController class by right-clicking on src/main/java under Java Resources, and adding a new class. Use springapp.web for the package and call it HelloController. Add the Controller interface from org.springframework (if it doesn't appear under Libraries -> Maven Dependencies, edit pom.xml and ensure that spring-webmvc is added in compile scope in the Dependencies tab. Copy the code for HelloController from the tutorial.

Now, we'll create the HelloControllerTests. First, however, we'll need to add junit in test scope. Double-click on pom.xml and select the Dependencies tab. Next to the Dependencies pane (which should have only spring-webmvc listed), click Add... and search for junit. Make sure the test scope is selected before adding it. Now, right-click on the src/test/java folder and create the class springapp.web.HelloControllerTests. Change it to inherit from junit.framework.TestCase. Copy the single test method from the tutorial into the HelloControllerTests class. You should now be able to Run As JUnit Test, and see the lovely green bar in your JUnit tab in Eclipse.

Finally, we'll create the hello.html bean. First, however, we need to configure the DispatcherServlet. Right-click on the springapp project, and select Add New Servlet. Notice that you can add an existing class instead of one of yours. Choose the org.springframework.web.servlet.DispatcherServlet, add a URL mapping *.html, and remove the "/springapp" URL mapping. Next, you need to configure HelloController to respond to the URL hello.html. Adding a new Spring Bean Definition springapp-servlet.xml from the project context menu to your project in src/main/webapp/WEB-INF will create the servlet configuration for you. This is the second way to add the Spring Project Nature, as there is an option which adds it if required when you create your first Spring Bean Definition. Choose only the beans namespace, and add the bean definition from the website to your springapp-servlet.xml. Lastly, the hello.jsp referred to by HelloController needs to be created. Create hello.jsp in src/main/webapp and copy the code from the tutorial. Your project is now ready for deployment. Start the project by clicking Run on index.jsp. When the browser opens up in Eclipse, simply change /springapp/index.jsp to /springapp/hello.html, and the contents of hello.jsp should display. You should now be able to follow the rest of the tutorial without a problem.

The purpose of this guide was to introduce an experienced Java programmer to the true power of Eclipse. While the above may seem to be overly difficult compared to other IDEs, that is the cost of the flexibility of Eclipse. This guide has shown how to configure a very specific J2EE configuration, using very specific tools. However, other toolkits may use different project layouts and build tools. The Eclipse integration of major tools, however, has allowed for a truly visual experience. I did not type a single line of XML during the course of this guide, nor did I configure a single build property in an XML file or require building from a command line. The difficult administration tasks of managing dependencies (and versions!!) and packaging for deployment are handled professionally by Maven. Maven also lends itself well to test-driven development, by specifying a project layout that includes test source and resource folders, and allowing dependencies to be added in test scope without changing the deployment. Spring IDE combines all of your Spring elements in a single node for easy access, and is capable of validating your Spring components prior to deployment. And, the Dynamic Web Project from Eclipse WTP provides an easy way of managing your Web Project visually, allowing you to add Servlet, Filter and Listener classes without directly editing web.xml. While this project targeted Tomcat 6 running on Java 1.6 (32-bit), it would be equally easy to target a different J2EE platform. YMMV, but I hope that you find this to be as pleasant and productive a development environment as I do.

Just one final note: I've tried creating a Dynamic Web Project as a Maven Project and adding the Web Facet, but this no longer uses the Web Project layout in Project Explorer. I prefer the Web Project layout, as it makes it much easier to find components in a large project.