Maven is - at its heart - a plugin execution framework; all work is done by plugins. Looking for a specific goal to execute? This page lists the core plugins and others.

To see the most up-to-date list browse the Maven repository at http://repo1.maven.org/maven2/, specifically the org/apache/maven/plugins subfolder. (Plugins are organized according to a directory structure that resembles the standard Java package naming convention)

There are also many plug-ins available at the Mojo project at Codehaus. To see the most up-to-date list browse the Codehaus repository at http://repository.codehaus.org/, specifically the org/codehaus/mojo subfolder. Here are a few common ones:

A number of other projects provide their own Maven2 plugins. This includes:

Creating an archetype is a pretty straight forward process. An archetype is a very simple plugin, that contains the project prototype you wish to create. An archetype is made up of:

• an archetype descriptor ( archetype.xml in directory: src/main/resources/META-INF/). It lists all the files that will be contained in the archetype and categorizes them so they can be processed correctly by the archetype generation mechanism.
• the prototype files that are copied by the archetype (directory: src/main/resources/archetype-resources/)
• the prototpye pom ( pom.xml in: src/main/resources/archetype-resources)
• a pom for the archetype ( pom.xml in the archetype's root directory).

To create an archetype follow these steps:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>my.groupId</groupId>
  <artifactId>my-archetype-id</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>
</project>

<archetype>
  <id>quickstart</id>
  <sources>
    <source>src/main/java/App.java</source>
  </sources>
  <testSources>
    <source>src/test/java/AppTest.java</source>
  </testSources>
</archetype>

archetype
|-- pom.xml
`-- src
    `-- main
        `-- resources
            |-- META-INF
            |   `-- archetype.xml
            `-- archetype-resources
                |-- pom.xml
                `-- src
                    |-- main
                    |   `-- java
                    |       `-- App.java
                    `-- test
                        `-- java
                            `-- AppTest.java

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>${groupId}</groupId>
  <artifactId>${artifactId}</artifactId>
  <packaging>jar</packaging>
  <version>${version}</version>
  <name>A custom project</name>
  <url>http://www.myorganization.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

mvn install 

mvn archetype:create                                    \
  -DarchetypeGroupId=<archetype-groupId>                \
  -DarchetypeArtifactId=<archetype-artifactId>          \ 
  -DarchetypeVersion=<archetype-version>                \
  -DgroupId=<my.groupid>                                \
  -DartifactId=<my-artifactId>   

mvn archetype:create 
  -DgroupId=[your project's group id]
  -DartifactId=[your project's artifact id]
  -DarchetypeArtifactId=maven-archetype-archetype

• Contents
• Getting Started
• Maven 2 Commands
• Maven 2 Versus Ant?
• Adding Some Business Logic
• Creating the WAR file
• Tying Together the Logic and Web Application
• Repositories
• Summary
• Resources

You may have heard of Maven 2--it's often touted by technologists as a replacement for Ant. You may have even taken some time to browse around on the Maven 2 site, but maybe the documentation has left you a little bit unclear on where and how to go about getting started.

In this article, we will take a look at using Maven 2 to help build a simple web application (a bit of business logic in a JAR and a JSP-based web application). By the end of this article, you should feel comfortable working with Maven 2, and ready to start using it as a much more satisfactory tool than Ant (or even your IDE).

Getting Started

These instructions assume that you have installed Java 5 and Maven 2. The following two commands shown should work at your command line:

C:\>java -version
 java version "1.5.0_06"
 Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
 Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)

C:\>mvn -v
Maven version: 2.0.5

Everything else required for this project will be downloaded for you automatically by Maven 2 (obviously, a working internet connection is also required). I used my Windows system to write this article, but everything here should work fine on Mac OS X, Linux, Solaris, etc.

From a high level, the project will be organized into two subprojects (one for the JAR and one for the WAR). Let's start by creating the base directory for the project. This directory serves as the base for the other folders.

C:\>mkdir maven2example
C:\>cd maven2example
C:\maven2example>

Now, let's create the two subprojects. Maven 2 supports the notion of creating a complete project template with a simple command. The project templates (called “archetypes” in Maven) shown below are a subset of the full list of archetypes built in to Maven 2.

These archetypes are analogous to the sample projects you might find in your IDE as defaults for standard "New Project…" options.

To create a simple Java project, you simply execute the command as shown.

mvn archetype:create
   -DgroupId=[your project's group id]
   -DartifactId=[your project's artifact id]

The mvn command invokes the Maven 2 system, in this case a request to run the archetype plugin with the create command. The -D commands are simply setting Java system properties, thereby passing configuration information to Maven 2. Per the Maven 2 FAQ, the groupID should follow the package name (reversed DNS of your website), and can contain subgroups as appropriate. For example, the sample code for my books might use com.cascadetg.hibernate or com.cascadetg.macosx. In this case, let's use the com.attainware.maven2example.

The artifactID is specific to each artifact and by convention should be the filename, excluding extension. In this case, we would like to create two artifacts, a JAR file containing the logic and a WAR file containing the web application. First, let's create the JAR file using the command as shown below. Maven 2 tends to be quite verbose, and so I have trimmed the output shown here and and many of the other listings in this article to focus on the elements of interest.

 C:\maven2example>mvn archetype:create
       -DgroupId=com.attainware.maven2example
     -DartifactId=maven2example_logic

 [INFO]   Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO]   -----------------------------------------------------
[INFO] Building Maven Default Project
    <snip>
 [INFO] Archetype created in dir:   
                        C:\maven2example\maven2example_logic
[INFO]   -----------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO]   -----------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Sun Feb 04 10:42:33 PST 2007
[INFO] Final Memory: 4M/8M
[INFO]   -----------------------------------------------------

C:\maven2example>

Looking at the resulting file structure, we can see that Maven 2 has done several things for us. It's created a fairly complete directory structure, following many best practices for organizing code. The source code is broken into two directories, one for the code itself and one for the test cases. The package structure is taken from the groupId, and is mirrored in both the main code and the test case directory structure.

Figure 1. Source for JAR project layout

Clicking through the results, you will see folders and two Java source files--so far, nothing surprising.

In the root folder, however, we notice a file called pom.xml .

Figure 2. Maven 2 project file for JAR project

This file is essentially analogous to an IDE project file: it contains all of the information about a project, and is the file that Maven 2 uses to act upon to execute commands. The contents of pom.xml :

<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>
     <groupId>com.attainware.maven2example</groupId>
        <artifactId>maven2example_logic</artifactId>
     <packaging>jar</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>maven2example_logic</name>
     <url>http://maven.apache.org</url>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
           <version>3.8.1</version>
         <scope>test</scope>
       </dependency>
     </dependencies>
 </project>

There really isn't a lot in the standard pom.xml file. We can see the groupId and artifactId, that the project is intended to build a JAR, and that the current version is to 1.0-SNAPSHOT. The project uses JUnit 3.8.1 for unit tests. We could change the URL to point to our company or project website and/or update the version number to something more appropriate, but for now this is fine. If you are curious, you can review the schema for Maven pom.xml files.

Maven 2 makes heavy use of standard directory layouts to reduce clutter. It assumes that the source code and test code will be found in the directory created by the project template. By specifying standard directory layouts, it easier to immediately start work on a project with spending a lot of time relearning the build process. While it is possible to reconfigure Maven 2 to use custom directory layouts, I have found that it's generally less work to simply use the Maven 2 layout. I have converted several projects of small to medium size from Ant to Maven 2, and found that the size and complexity of my build files (from custom Ant build.xml files to Maven 2 pom.xml files) dropped by an order of magnitude. By using Maven 2 templates (archetypes) and simply copying source files into the proper locations, I found that I wound up with much more comprehensible project structures than the slowly accreted, custom Ant build.xml projects. While it is possible to force Maven 2 to fit into arbitrary directory structures, that's probably not the place to start.

Maven 2 Commands

Maven 2 supports two kinds of commands that can be run on projects ( pom.xml files). The first type of command is a plugin command. Plugin commands include things like "copy a set of files," "compile a source tree," etc. The other type of command is a lifecycle command. A lifecycle command is a series of plugin commands strung together. For example, the test lifecycle command might include several plugin commands in a series.

Let's execute the lifecycle command mvn test on our pom.xml file. As can be seen in the following listing, this command executes several plugins (additional output omitted for readability).

C:\maven2example\maven2example_logic>mvn test

[INFO] Scanning for projects...
[INFO]   -------------------------------------------------------
[INFO] Building maven2example_logic
[INFO]    task-segment: [test]
[INFO]   -------------------------------------------------------
 [INFO] [resources:resources]
[INFO] [compiler:compile]
[INFO] [resources:testResources]
[INFO] [compiler:testCompile]
[INFO] [surefire:test]
 [INFO]   ------------------------------------------------------
[INFO] BUILD SUCCESSFUL

C:\maven2example\maven2example_logic>

What we can see is that the mvn test lifecycle command is bound to several plugins, including resources, compiler, and surefire. These plugins in turn are called with different goals, such as compile or testCompile. So, by simply calling mvn with a single lifecycle command, we execute a number of plugins--no additional configuration necessary. If you want to specify a plugin directly, that's fine. For example:

C:\maven2example\maven2example_logic>mvn compiler:compile

[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'compiler'.
[INFO] --------------------------------------------------------
[INFO] Building maven2example_logic
[INFO]    task-segment: [compiler:compile]
[INFO] --------------------------------------------------------
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] --------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] --------------------------------------------------------

C:\maven2example\maven2example_logic>

Now that we have seen both lifecycle commands and plugin commands in action, let's look at some of the typical lifecycle commands.

A complete list of lifecycle commands can be found at on the Maven 2 site.

Similarly, here is a list of some of the more popular plugin commands, analogous to the popular tasks in Ant or commands in an IDE. Note that a lifecycle command name is a single word, whereas a plugin command name is broken into a plugin and a specific goal with a colon:

You may want to take some time perusing the list of plugins that are available to Maven 2 by default. It is possible to add additional plugins by either writing them yourself or by grabbing them from a repository (repositories are discussed later in this article).

You can configure plugins on a per-project basis by updating your pom.xml file. For example, if you wish to force compilation on Java 5, simply pass in the following option under the build configuration in the pom.xml file:

<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">
       <build>
         <plugins>
           <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              <configuration>
                   <source>1.5</source>
                   <target>1.5</target>
              </configuration>
           </plugin>
         </plugins>
       </build>
 </project>

Each plugin listed on the Maven 2 site includes documentation on the various configuration options available.

Maven 2 Versus Ant?

If you are familiar with Ant, you may be wondering why lifecycles and plugins are an improvement over targets and tasks. While you can cleanly separate your Ant targets from the various directories and artifacts, it's surprisingly difficult to do. For example, let's say that you have several directories, with several artifacts (multiple JAR files, which get combined into a WAR, for example). Every command that you write for each Ant target will require properties for the source, and various dependencies, typically passed around via a combination of Ant variables. Dependencies in particular require a lot of custom handholding, with JAR files downloaded and managed by hand.

Maven 2, on the other hand, assumes that given a pom.xml file, you are probably always going to be doing the same general kind of things with your code. You are probably going to want to build a JAR file from that lump of code over there . You are probably going to want to build a WAR file from that set of files over there . So those actions (or goals) are written in Java as reusable chunks of code (plugins). Instead of complicated lumps of thousands of lines of custom build.xml files, you just call a plugin with a specific goal.

There are several advantages to this approach. For one, the Maven 2 Java-based plugins are a lot smarter than the lower-level commands found in Ant tasks. You don't have to write custom tasks that handle compilation, and then have to worry about keeping your clean task in sync with your compile and packaging tasks; Maven 2 just takes care of this stuff for you.

Another advantage of this model is that it encourages reuse of plugins in a much more robust way than Ant tasks. Later in this article, we will show how simply adding a few lines to a pom.xml file will automatically download and launch Jetty (a lightweight servlet/JSP container), seamlessly installing and running the WAR file.

Adding Some Business Logic

Let's add a tiny bit of pseudo-business logic to our application. First, we write a simple test cast that looks for a String, updating C:\maven2example\maven2example_logic\src\test\java\com\attainware\maven2example\AppTest.java .

 package com.attainware.maven2example;
 import junit.framework.Test;
 import junit.framework.TestCase;
 import junit.framework.TestSuite;
 import com.attainware.maven2example.App;
 
 public class AppTest extends TestCase
 {
       public void testApp()  
       {
           assertTrue( App.now().length() > 0 );
       }
 }

Opening the file C:\maven2example\maven2example_logic\src\main\java\com\attainware\maven2example\App.java , we update the contents to:

package com.attainware.maven2example;

public class App
{
       public static String now()
       {
            return new java.util.Date().toString();  
       }
 }

Running the command mvn install, as shown below, causes several plugins to run (status messages omitted for readability).

 C:\maven2example\maven2example_logic>mvn install

 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
 [INFO] [surefire:test]
 [INFO] [jar:jar]
 [INFO] [install:install]
 [INFO] BUILD SUCCESSFUL

 C:\maven2example\maven2example_logic>

By running the mvn install lifecycle command, Maven 2 finishes by installing the JAR file into the local repository, making this resulting JAR file available to other projects on this system. This allows this JAR file to be available for inclusion in our WAR file.

Creating the WAR file

Now that we have created our JAR file, creating the WAR file is straightforward--we just pass in a different archetype ID.

C:\maven2example> mvn archetype:create
   -DgroupId=com.attainware.maven2example
   -DartifactId=maven2example_webapp
   -DarchetypeArtifactId=maven-archetype-webapp 

[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ---------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] [archetype:create]
[INFO] Archetype created in dir: 
                        C:\maven2example\maven2example_webapp
[INFO] ---------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ---------------------------------------------------------

C:\maven2example>

As shown in Figure 3, we now have a directory structure you would expect to see for a WAR. Note that the JAR file is automatically pulled into the WAR file from the local repository.

Figure 3. WAR project directory structure

Simply executing the command mvn package creates our WAR file (again, omitting most of the status messages besides the plugin list).

In this case, the mvn package command builds the WAR file but does not install it into the local repository (repositories will be discussed later). As you build larger, more sophisticated projects with more complex dependencies, you may wish to be more deliberate about using the mvn package and mvn install commands to control inter-project dependencies. Because the WAR file is the final artifact we are creating, we can save a few compute cycles merely by packaging the WAR file in the local target directory.

 C:\maven2example\maven2example_webapp>mvn package

 [INFO] Scanning for projects...
 [INFO] --------------------------------------------------------
 [INFO] Building maven2example_webapp Maven Webapp
 [INFO]    task-segment: [package]
 [INFO] --------------------------------------------------------
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
 [INFO] [surefire:test]
 [INFO] [war:war]
 [INFO] Building war: 
         C:\maven2example\maven2example_webapp\
             target\maven2example_webapp.war
 [INFO] -------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] -------------------------------------------------------

 C:\maven2example\maven2example_webapp>

As we can see in Figure 4, we now have a WAR file.

Figure 4. Resulting WAR file

Now that we have a WAR file, we would like to be able to run the application. To do this, we simply add the Jetty plugin to the pom.xml for this web application as shown:

<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>
     <groupId>com.attainware.maven2example</groupId>
     <artifactId>maven2example_webapp</artifactId>
     <packaging>war</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>maven2example_webapp   Maven Webapp</name>
     <url>http://maven.apache.org</url>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
           <version>3.8.1</version>
         <scope>test</scope>
       </dependency>
     </dependencies>
     <build>
       <finalName>maven2example_webapp</finalName>
          <plugins>
             <plugin>
                  <groupId>org.mortbay.jetty</groupId>
                  <artifactId>maven-jetty-plugin</artifactId>
             </plugin>
         </plugins>
    </build>
 </project>

By adding the plugins entry with the Jetty information, we can now run our web application by simply typing the command as shown below.

 C:\maven2example\maven2example_webapp> mvn jetty:run
 
 [INFO] Scanning for projects...
 [INFO] Searching repository for plugin with prefix: 'jetty'.
 [INFO]   ----------------------------------------------------
 [INFO] Building maven2example_webapp Maven Webapp
 [INFO]    task-segment:   [jetty:run]
 [INFO]   ----------------------------------------------------
 [INFO] Preparing jetty:run
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [jetty:run]
 [INFO] Starting jetty 6.1.0pre0   ...
 [INFO] Classpath =   
   [file:/C:/maven2example/maven2example_webapp/target/classes/]
   2007-02-04 12:41:24.015::INFO:
    Started SelectChannelConnector @   0.0.0.0:8080
 [INFO] Started Jetty Server

We can now open our web browser to localhost:8080/maven2example_webapp to see our web application (as shown in Figure 5). Type Ctrl-C in the console window to shut down the server. Note that we didn't have to download and install Jetty separately--Maven 2 automatically downloads and configures Jetty.

Figure 5. Hello World Web Application

Tying Together the Logic and Web Application

Now, we simply have to tie together the logic in our JAR file and the web application. First, we want to set up a dependency between our JAR and the web application. This will tell Maven 2 that we want to use this JAR file in our WAR, which will cause Maven 2 to automatically copy the JAR file when we package our WAR file.

First, we add the dependency on this other JAR file to our pom.xml for the web application as shown below.

<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>
     <groupId>com.attainware.maven2example</groupId>
     <artifactId>maven2example_webapp</artifactId>
     <packaging>war</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>maven2example_webapp   Maven Webapp</name>
     <url>http://maven.apache.org</url>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
           <version>3.8.1</version>
         <scope>test</scope>
       </dependency>
        <dependency>
           <groupId>com.attainware.maven2example</groupId>
            <artifactId>maven2example_logic</artifactId>
           <version>1.0-SNAPSHOT</version>
       </dependency>
      </dependencies>
     <build>
       <finalName>maven2example_webapp</finalName>
         <plugins>
              <plugin>
                <groupId>org.mortbay.jetty</groupId>
                <artifactId>maven-jetty-plugin</artifactId>
              </plugin>
         </plugins>
     </build>
 </project>

We then update our JSP file to use our fancy new business logic.

<html>
 <body>
 <h2>Fancy Clock</h2>
 <%= com.attainware.maven2example.App.now() %>
 </body>
</html>

Next, we run the command mvn package to rebuild the WAR file.

 C:\maven2example\maven2example_webapp>mvn package

 [INFO] Scanning for projects...
 [INFO]   ---------------------------------------------------
 [INFO] Building maven2example_webapp Maven Webapp
 [INFO]    task-segment:   [package]
 [INFO]   ---------------------------------------------------
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
 [INFO] [surefire:test]
 [INFO] [war:war]
 [INFO] Building war:   
     C:\maven2example\maven2example_webapp\
          target\maven2example_webapp.war
 [INFO]   ---------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] -----------------------------------------------------

Notice that the JAR file is now copied into WAR file, as shown in Figure 6.

Figure 6. Verifying the JAR copied into the WAR

When we execute the mvn jetty:run command and view the results in our browser, we see the results as shown in Figure 7.

Figure 7. WAR running with business logic from JAR

To recap, we now have two independent projects running on our system. When we run mvn install on the logic, the JAR file installed in the local repository will be updated. When we run mvn package on the web application, it will pick up the latest copy installed into the local repository.

We would like to be able to run a single command to update both the JAR file and the WAR file. To do this, we create another pom.xml file that invokes both projects.

<project>
     <name>Maven 2 Example</name>
         <url>http://www.attainware.com/</url>
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.attainware.maven2example</groupId>
        <version>1.0</version>
     <artifactId>maven2example_package</artifactId>
     <packaging>pom</packaging>
   
     <modules>
       <module>maven2example_logic</module>
       <module>maven2example_webapp</module>
     </modules>
 </project>

This pom.xml file lives right above the other projects and serves as a "master" project file.

Figure 8. Location of master project file

Now, we can simply execute a single command, mvn install, and do a full build on both projects.

 C:\maven2example>mvn install
 
 [INFO] Scanning for   projects...
 [INFO] Reactor build order:
 [INFO]   maven2example_logic
 [INFO]   maven2example_webapp Maven Webapp
 [INFO]   Maven 2   Example
 [INFO]   -----------------------------------------------------
 [INFO] Building maven2example_logic
 [INFO]    task-segment: [install]
 [INFO]   -----------------------------------------------------
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
 [INFO] [surefire:test]
 [INFO] [jar:jar]
 [INFO] [install:install]
 [INFO]   -----------------------------------------------------
 [INFO] Building maven2example_webapp Maven Webapp
 [INFO]    task-segment:   [install]
 [INFO]   -----------------------------------------------------
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
 [INFO] [surefire:test]
 [INFO] [war:war]
 [INFO] [install:install]
 [INFO] [site:attach-descriptor]
 [INFO] [install:install]
 [INFO]   -----------------------------------------------------
 [INFO] Reactor Summary:
 [INFO]   -----------------------------------------------------
 [INFO] maven2example_logic   ................ SUCCESS [2.281s]
 [INFO] maven2example_webapp Maven Webapp .... SUCCESS [0.563s]
 [INFO] Maven 2 Example   .................... SUCCESS [1.156s]
 [INFO]   -----------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] -------------------------------------------------------

To summarize, we now have a project that now compiles and tests a JAR, which is then built and installed into a WAR, which is then in turn installed into a local web server (which is downloaded and automatically configured). All of this with a few tiny pom.xml files.

Repositories

You may be wondering about the use of the term "repository." We have glossed over the use of the term, but in brief, Maven 2 makes use of two kinds of repository: local and remote. These repositories serve as locations for Maven 2 to automatically pull dependencies. For example, our pom.xml file above makes use the local repository for managing the dependency on the JAR file, and the default Maven 2 remote repository for managing the dependencies on JUnit and Jetty.

Generally speaking, dependencies come from either the local repository or remote repositories. The local repository is used by Maven 2 to store downloaded artifacts from other repositories. The default location is based on your system. Figure 9 shows the local repository on my laptop as of the writing of this article.

Figure 9. Local repository example

If Maven 2 can't resolve a dependency in the local repository, it will try to resolve the dependency using a remote repository.

The default remote repository, known as Ibiblio, includes many of the most popular open source packages. You can browse the wide range of packages on Ibiblio with the URL above and add dependencies as needed. For example, let's say that you would like to use Hibernate in your project. Navigating to www.ibiblio.org/maven/org.hibernate/poms, we can see there are a wide number of releases of Hibernate available. Opening up a sample Hibernate pom file, we can see that we simply need to add the appropriate groupId, artifactId, and version entries to our business logic pom.xml file (the scope flag tells Maven 2 which lifecycle is interested in the dependency).

<dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate</artifactId>
        <version>3.2.1.ga</version>
        <scope>compile</scope>
 </dependency>

Simply adding this dependency to the pom.xml file will cause Maven 2 to automatically download Hibernate and make the appropriate JAR files available to both the business logic JAR file and the WAR file.

You can set up your own remote repository, and add an entry to the pom.xml file to look in that repository for artifacts. This is extremely useful for enterprises that make use of shared resources (for example, one group may wish to publish JAR files that are used to access a particular piece of middleware).

Finally, you may instead wish to install your own JARs into the local repository. For example, if you have a Simple.jar file that someone gave you, use the command shown below (choosing groupId and artifactId values that are highly likely to be unique to avoid a namespace collision).

mvn install:install-file
     -Dfile=Sample.jar
     -DgroupId=uniquesample
     -DartifactId=sample_jar
     -Dversion=2.1.3b2
     -Dpackaging=jar
     -DgeneratePom=true

Summary

In this article, we looked at how a few commands and some tiny XML files allow us to create, compile, test, bundle, and manage project dependencies. We built a simple web application and deployed it to a web server with just a few commands, and we still haven't touched on many of the features of Maven 2. For example, additional commands generate integrated Javadocs across multiple projects, code coverage reports, or even a complete website with documentation. With luck, this orientation to Maven 2 has given you enough information to begin the transition. Eventually, tools such as Eclipse and NetBeans will almost certainly support Maven 2 (or something like it) natively. In the meantime, you can dramatically reduce your use of raw Ant (and spend a lot less time fighting XML build scripts) by switching even small projects over to Maven 2.

Resources

• Source code shown in this article is available for download from www.cascadetg.com/maven.
• The main Maven 2 site

Will Iverson is the practice director, Software Development for SolutionsIQ, a Pacific Northwest service provider.

Kent Beck, Erich Gamma

Here is a short cookbook showing you the steps you can follow in writing and organizing your own tests using JUnit.

Simple Test Case

How do you write testing code?

The simplest way is as an expression in a debugger. You can change debug expressions without recompiling, and you can wait to decide what to write until you have seen the running objects. You can also write test expressions as statements which print to the standard output stream. Both styles of tests are limited because they require human judgment to analyze their results. Also, they don't compose nicely- you can only execute one debug expression at a time and a program with too many print statements causes the dreaded "Scroll Blindness".

JUnit tests do not require human judgment to interpret, and it is easy to run many of them at the same time. When you need to test something, here is what you do:

1. Annotate a method with @org.junit.Test
2. When you want to check a value, import org.junit.Assert.* statically, call assertTrue() and pass a boolean that is true if the test succeeds

For example, to test that the sum of two Moneys with the same currency contains a value which is the sum of the values of the two Moneys, write:

@Test public void simpleAdd() {

    Money m12CHF= new Money(12, "CHF"); 

    Money m14CHF= new Money(14, "CHF"); 

    Money expected= new Money(26, "CHF"); 

    Money result= m12CHF.add(m14CHF); 

    assertTrue(expected.equals(result));

}

If you want to write a test similar to one you have already written, write a Fixture instead.

Fixture

What if you have two or more tests that operate on the same or similar sets of objects?

Tests need to run against the background of a known set of objects. This set of objects is called a test fixture. When you are writing tests you will often find that you spend more time writing the code to set up the fixture than you do in actually testing values.

To some extent, you can make writing the fixture code easier by paying careful attention to the constructors you write. However, a much bigger savings comes from sharing fixture code. Often, you will be able to use the same fixture for several different tests. Each case will send slightly different messages or parameters to the fixture and will check for different results.

When you have a common fixture, here is what you do:

1. Add a field for each part of the fixture
2. Annotate a method with @org.junit.Before and initialize the variables in that method
3. Annotate a method with @org.junit.After to release any permanent resources you allocated in setUp

For example, to write several test cases that want to work with different combinations of 12 Swiss Francs, 14 Swiss Francs, and 28 US Dollars, first create a fixture:

public class MoneyTest { 

    private Money f12CHF; 

    private Money f14CHF; 

    private Money f28USD; 

    @Before public void setUp() { 

        f12CHF= new Money(12, "CHF"); 

        f14CHF= new Money(14, "CHF"); 

        f28USD= new Money(28, "USD"); 

    }

}

Once you have the Fixture in place, you can write as many Test Cases as you'd like. Add as many test methods (annotated with @Test) as you'd like.

TestRunner

How do you run your tests and collect their results?

Once you have tests, you'll want to run them. JUnit provides tools to define the suite to be run and to display its results. To run tests and see the results on the console, run:

org.junit.runner.TextListener.run(TestClass1.class, ...); 

You make your JUnit 4 test classes accessible to a TestRunner designed to work with earlier versions of JUnit, declare a static method suite that returns a test.

public static junit.framework.Test suite() { 

    return new JUnit4TestAdapter(Example.class); 

}

Expected Exceptions

How do you verify that code throws exceptions as expected?

Verifying that code completes normally is only part of programming. Making sure the code behaves as expected in exceptional situations is part of the craft of programming too. For example:

new ArrayList<Object>().get(0); 

This code should throw an IndexOutOfBoundsException. The @Test annotation has an optional parameter "expected" that takes as values subclasses of Throwable. If we wanted to verify that ArrayList throws the correct exception, we would write:

@Test(expected= IndexOutOfBoundsException.class) public void empty() { 

    new ArrayList<Object>().get(0); 

}