Building Java apps with Maven

In the previous parts of this series we've moved from developing a Swing application to moving to a hybrid Swing application with Web serving abilities. Now, we're going to go all the way, to making the code into a Web application which you can deploy into a running server.

The major change we are making will be in how we build the application. So far we've used Ant, but we are going to switch to the more lifecycle-oriented Apache Maven, now in its second release. Although we are replacing Ant with Maven, don't assume Maven is just a build tool; it is more about managing projects by applying best practice patterns. It's easier if we start by installing Maven and get the new ToDoTasks source code for this month.

The first thing you should notice is how much simpler the directory tree is. At the top level, there is a src directory and a pom.xml file, the Project Object Model (POM), which is where all the information about the project resides. A POM tells Maven how to build what it calls an artifact, which has a name, group and version and maps to a jar or war file. So the first thing the POM has information about is the artifact we are making;

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
		http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion> 

That's the mandatory preamble; we start a project element and then we have a required modelVersion element that says which version of POM we're using. Now onto our artifact information.

        <groupId>uk.builder</groupId>
        <artifactId>todotasks</artifactId>

The groupId is a unique identifier for a cluster of artifacts; in this case, it's uk.builder. The artifactId is a unique name for our artifact within the group. Together, they give our artifact a name, but not a version;

        <version>2.0-SNAPSHOT</version> 

Here's our version; the "-SNAPSHOT" is Maven practice for denoting "in development" versions. Now, although we have a working name for the project, we need a display name.

        <name>ToDoTasks</name> 

This name will be used by Maven when it needs to display the name of the artifact. Now we get to the really important part.

        <packaging>war</packaging> 

The packaging element can have the value jar,war or ear; we're making a Web application, so we use war. This isn't — as it appears at first glance — just saying how we package up the artifact; in fact it influences the entire lifecycle of the artifact.

Now, we'll pause here from looking at the POM file, and look at the src directory.

src -+-> main -+-> java -> com -> builder -> uk -> todotasks
     |         |
     |         +-> webapp -+-> META-INF
     |                     |
     |                     +-> WEB-INF
     |
     +-> test -+-> java -> com -> builder -> uk -> todotasks

The src directory in a Maven project holds all the source code, specifically under a main directory, and then another subdirectory, java for Java source code, webapp for the web application code. The only exception is test code which is held in a parallel tree under the test directory. You'll notice there's no library directory for jar files. That's because with Maven, you don't need one.

Maven thinks of the world in terms of repositories of jar/war/ear files, each with their own group id, artifact id and version; these files are called artifacts. Locally, you have your own repository, usually in a .m2 directory in your home directory. Maven's goal in building a project is to create an artifact that can be installed into this repository for other projects to be able to use it. There are also remote repositories, from which Maven can get copies of artifacts, to install them into the local repository, again so projects can use them.

Maven discovers what artifacts are required by another section in the pom.xml file, the dependencies section.

 <dependencies>
  <dependency>
   <groupId>jdbm</groupId>
   <artifactId>jdbm</artifactId>
   <version>1.0</version>
  </dependency>

Now this is a simple dependency to get jdbm. Maven, by default, refers to http://www.ibiblio.org/maven2/ for dependencies, and if you look there in the directory jdbm/jdbm/1.0/ you'll find the jdbm-1.0.jar file, which is what Maven will retrieve, along with a short pom.xml file for jdbm which can list any dependencies that the artifact has itself. You can manually browse the ibiblio repository or you can use a site such as MVN Registry which lets you search the repository.

Our next dependency is on dwr, but you won't find this on the ibiblio repository. We'll have to install this in our own local repository.

  <dependency>
   <groupId>dwr</groupId>
   <artifactId>dwr</artifactId>
   <version>2.0M3</version>
  </dependency>

Our next dependency is on the Java Servlet API. This is on ibiblio, but we only need it when our project is being built, because when we deploy to a Web server, the servlet API will already be there.

  <dependency>
   <groupId>javax.servlet</groupId>
   <artifactId>servlet-api</artifactId>
   <version>2.4-20040521</version>
   <scope>provided</scope>
  </dependency>

The scope element lets us say when this artifact is needed so "provided" means the artifact is provided by the run time environment. Another type of scope is "test" which means the artifact is needed for testing but not at other times. For example, this is how we include Junit;

  <dependency>
   <groupId>junit</groupId>
   <artifactId>junit</artifactId>
   <version>3.8.1</version>
   <scope>test</scope>
  </dependency>
 </dependencies>