Maven is a project management framework hosted by the Apache Software Foundation (ASF) at http://maven.apache.org. The Maven project started as the result of build process needs inside ASF projects. Before Maven each Apache project had its own methods of compilation, distribution, web site generation, and etc. As a developer, one had to deal with each project’s build separately. In addition, people weren’t contributing enough to Apache projects since it was a hassle to get each one running on their locals.  So, there was a need for a uniform build system, and with the Apache Turbine project Maven took the scene.

Maven tries to make builds as easy as possible in a uniform way — if you know how to build one Maven project, you can build all of them. As Maven becomes more widely used, we believe that this will be the first thing that comes to mind any time someone mentions Maven.

Before You Start

You need to install Maven on your computer. You can either use the Maven that ships with IDEs / plugins, or you can download it from http://maven.apache.org/download.html.  Follow the installation instructions that are available for MacOs, Windows and Linux.

Meat & Potatoes

Probably the most important key concept of Maven is that it favors convention over configuration. With six lines of XML you can create a Maven project and build a jar file out of it. Maven offers common interfaces for building projects. You don’t need to deal with all the necessary libraries, the tasks to run to build the project, and etc.  There’s a good saying for this: before Maven, it was the era of build engineers.  Maven stops you from building the build, instead letting you focus on development to produce high quality code.  Maven has a detailed dependency management mechanism, so to get a project running on your local you don’t need to deal with jar files or the files that those jar files depend on — a la transitive dependency. Maven uses third-party public repositories for fetching all those artifacts, and there’s a good deal of them around.

Maven has a pluggable architecture, and the Maven core is actually very lightweight. It doesn’t even know about compiling code. It is just a matter of adding a compiler plugin. For Maven, a plugin is just another artifact to be fetched from a repository. Since the architecture is very pluggable, you can implement your own plugin and hook it into the build system easily.

In the sections below we’ll cover the core concepts of Maven in detail and discuss how you can begin using Maven in your own development projects.

The POM

POM stands for Project Object Model, and it’s what makes your project a Maven project. POM is an XML file that has the same declarative approach as in build.xml of Ant, or web.xml in Java web applications. POM describes the project with metadata for build processes, but it also contains data besides that which is needed for building, such as:

• the project’s relationship between Maven projects
• the list of team members, contributors, and developers
• source control management information
• the license of the project
• site generation information

So, it is a conceptual model that tries to cover nearly all the definitions of a software project. POM has a seamless integration with Java, but it is not just for Java projects. For instance, you can build FLEX distributable artifacts with israfil plugins, or you can create Microsoft binaries from C# codes, so it’s just a matter of plugins as we stated before. The best way to learn about the details of an XML file is to examine its XSD. Since XSD files are not human-readable, you can check out the XSD document of a Maven POM file that we shared at http://www.tinyurl.com/maven-xsddoc so you can easily see the tags that can be used inside POM.

Here is a sample skeleton for Project Object Model.

<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">
   <parent />
   <groupId />
   <artifactId />
   <version />
   <packaging />
   <developers /> <contributors />
   <scm>...</scm>
   <build>
      <plugins>...</plugins>
   </build>
   <dependencies>...</dependencies>
   <repositories>...</repositories>
   <pluginRepositories>...</pluginRepositories>
   <profiles>...</profiles>
</project>

As you can see, all tags reside inside the project tag of POM.  Let’s go through the tags briefly. With the parent tag you can create parent-child relationships between your Maven projects.  The groupId,  artifactId and the version tags uniquely define a project coordinate.  With the packaging tag, project-specific packaging can be determined such as jar, war, and ear bundling.  The list of developers and contributors can be found inside the developers and contributors tags.  The source control definitions can be provided with the SCM tag, and the build tag allows you can hook in plugins needed for execution and configure them according to your needs.  With the repositories and pluginRepositories definitions you can tell Maven where to look to download the needed dependencies and plugins.  And finally, the profile tag allows you to generate different builds of a project like development, staging or production.

Here is the simplest POM. It’s just six lines of XML to define a Maven project.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>myapp</artifactId>
    <version>1.0.0</version>
</project>

When we run the mvn install command on this project Maven will try to compile the code, run the tests against that code, package the project as a jar file, and deploy it to the local repository. You may ask how that’s possible with just six lines of XML — after all, we haven’t defined any source folders, test folders, or the target folder that will contain the compiled classes.  Well, those are all coming from the convention.  And they are all defined in the Super POM.

Super POM has the same analogy with Java as in java.lang.Object.  Every Maven project extends this super POM.  It resides under the Maven uber jar.  Super POM defines the standard directory layout.  With Maven 2.0.9, super POM also locks the versions of common plugins to have stable builds.  So it’s best to use the latest Maven in order to have stable and better builds.  Super POM also contains the central Maven repository definition, http://repo1.maven.org/maven2. Note that there could be more than one POM through your project hierarchy.  Your project can have a parent project, and that parent project will extend the super POM.  Inside the child project, the elements of parent POM are inherited.  So, if you want to see the merged version of the POM, just run the command mvn help:effective-pom goal.

Build LifeCycle

We declared the project with the model, but we need a process for building the project out of this metadata.  To achieve this, Maven introduces the concept of lifecycles.  A lifecycle is a process for building and distributing an artifact, and it is clearly defined.  There are three built-in lifecycles of Maven: the default, which handles project deployment; the clean, which handles the cleaning of all project files generated by a previous build; and the site, which generates the project’s site documentation.  Each lifecycle contains phases in a specific order, and zero or more goals are attached to each phase.  So the atomic part here is the goal, and when we gather goals together we have the phases, and when phases are registered in specific order we have the lifecycle.  The illustration below shows the list of phases for the default lifecycle.

The default lifecycle of Maven first validates the project, like checking the consistency of pom.xml file, and then it tries to compile the code. If the compile is successful, it then tries to run the test against the compiled code, package the project in the specified format, run the integration tests against that package, verify the package by checking for the validity, install the verified package to the local repository, and finally deploy the package in the specified environment.

To execute phases/goals we can follow the notation below in the command line:

mvn phase
mvn phase:goal

We can also invoke multiple phases/goals within one command line, like:

mvn phase phase:goal
mvn phase:goal phase:goal

When we invoke the mvn integration-test command, Maven executes all the phases that are registered before that phase.  So the validate, compile, and package phases get executed before the integration-test phase.

Dependency Management

Maven is very capable of handling dependencies as the build tool.  If you’re still using the old-fashioned method of copying the necessary artifacts by hand to your lib folder,  believe us — it’s the beginning of the end for your project. You will find yourself in jar hell very soon.  So how can you avoid this?  The answer is Maven and its dependency mechanism.

If you specify a dependency by giving the coordinates of some third party project, which is the group identifier, artifact identifier, and the version, Maven will look for that artifact inside the defined repositories and fetch to the local repository.  Since everything is a plugin to Maven in the ecosystem, Maven-dependency-plugin is responsible for those actions.

Here is a sample dependency declaration for the project JUnit.  The dependency is defined by its coordinates, groupId, artifactId, and version.

<dependency>
     <groupId>junit</groupId>
     <artifactId>junit</artifactId>
     <version>4.8.1</version>
     <scope>compile</scope>
</dependency>

Scopes can also be provided while defining the dependency. There are six kinds of scopes.  The default scope is the compile.  All dependencies scoped as compile are in the project’s compile, test, and runtime classpaths by default.  Provided is a similar scope to compile, but it is expected that the dependency should be provided by JDK or the container at runtime.  For instance, servlet.jar is one of the dependencies that is usually scoped like this.  Because it will be provided by the web container, provided scope affects the compile and test classpaths.  Runtime scope means that the dependency is not needed for compilation, but it is needed at test execution and runtime so it affects the test and runtime classpaths.  For instance we might need a JDBC driver implementation only at runtime, so artifact will be scoped as provided.  Test scope means that dependency is only needed for test compilation and execution and not for the application itself.  It affects the test classpath.  System scope is the same as provided, but the dependency should be explicitly specified since it won’t be looked up in the repository.  It affects the compile and test classpaths. To declare the path of the dependency there is the <systemPath> tag that you can use.  Actually, we don’t recommend using this, because in our opinion every dependency should be “Mavenized” and go into the repository.  The last scope is import, which is introduced with Maven 2.0.9.  With import scope it is stated that the specified POM should be replaced with the dependencies in that POM’s <dependencyManagement> section.

Versions and Ranges on Dependencies

Maven follows this notation for versioning artifacts:

<major>.<minor>.<incremental> - <qualifier>

It starts with a major version and follows up with a minor one, and then an incremental version comes up.  At the end you can also add a qualifier in free-text format.  For example, both of these examples are valid artifact versions:

1.2.3
1.2.3-alpha-01

Be careful about qualifier notation since Maven uses string comparison while comparing two artifacts.  For example, 1.2.3-alpha-2 would be a later version than 1.2.3-alpha-10.  Zero left padding is needed on the alpha-2 qualifier to make it the earlier version.  You can also define ranges on versions while adding dependencies to your project, and you can define exclusion or inclusion on the range with the bracket notation like this:

<dependency>
     <groupId>junit</groupId>
     <artifactId>junit</artifactId>
     <version>[3.8,4.0)</version>
</dependency>

The version tag here states that it should be 3.8 at least, and it should be below 4.0.

Snapshot Qualifier

Maven also has a special qualifier, the SNAPSHOT, which indicates the artifact is created while the project is under active development.  When you install/release an artifact or fetch one from a remote repository, Maven expands this SNAPSHOT suffix with a date (UTC format)-time-buildnumber pattern.  So for an artifact such as myjar-1.0.0-SNAPSHOT.jar the result would be something like myjar-1.0.0-20100219.141012-1.jar.  And if you install a SNAPSHOT artifact to your local repository, it will not get converted to the date-time format in order to avoid filling your hard disk with snapshot versions.

By default Maven will periodically (on a daily basis) attempt to download the latest version of the snapshot.  You can change it to “always” or an “interval” specified in minutes by adjusting the setting in your repository configuration.

<releases>
      <updatePolicy>interval:30</updatePolicy>
</releases>

Managing Projects and Dependencies

Maven supports parent-child relationships between projects.  To declare a project as a parent, add the parent tag in your project’s pom.xml like this:

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.openglogic.wazi</groupId>
        <artifactId>parentapp</artifactId>
        <version>1.0.0</version>
    </parent>
    <artifactId>sampleapp</artifactId>
</project>

Just add the groupId, artifactId, and version of your parent project.  Maven will look into the parent folder and the local repository to locate that parent project.  It’s not mandatory to define groupId and version in your subproject, as Maven could inherit those fields from the parent.  Your project will also inherit dependencies that are declared in the parent project’s POM.  To see the merged version of the child project’s POM we can use mvn help:effective-pom command.  Actually, the most likely problem that you might encounter here is this: if you have a good number of child projects extending one parent POM, changing one dependency in the parent causes all child projects to face the consequences of that change.  Thus, it might be better to use the dependencyManagement feature.  Here’s the parent POM of a project that defines Commons-Logging with dependencyManagement at version 1.1.1:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>parentapp</artifactId>
    <packaging>pom</packaging>
    <version>1.0</version>
    <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>commongs-logging</groupId>
               <artifactId>commongs-logging</artifactId>
               <version>1.1.1</version>
           </dependency>
       </dependencies>
    </dependencyManagement>
</project>

And here’s the POM of a child application.  As you can see, we didn’t define the version of Commons-Logging.  Instead, the version that we declared in the parent POM will be used.  And if we don’t define the Commons-Logging dependency in the child, it won’t be inherited from parent as in the previous case.

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.openlogic.wazi</groupId>
        <artifactId>parentapp</artifactId>
        <version>1.0</version>
    </parent>
    <artifactId>sampleapp</artifactId>
    <dependencies>
       <dependency>
           <groupId>commongs-logging</groupId>
           <artifactId>commongs-logging</artifactId>
       </dependency>
    </dependencies>
</project>

You may also have a project dependency hierarchy like this:

Here projectA depends on projectB and projectB depends on projectC.  So to compile projectA we need to compile projectB, but in order to compile projectB we need to compile projectC.  And that results to eight lines of Maven commands for just compiling projectA.

To overcome this, Maven supports a project modules approach.  We can create a modules project and have that project to point to the submodules. Here is the POM of modulesapp:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.openlogic.wazi</groupId>
    <artifactId>modulesapp</artifactId>
    <packaging>pom</packaging>
    <version>1.0</version>
    <name>modulesapp</name>
    <modules>
        <module>projectA</module>
        <module>projectB</module>
        <module>projectC</module>
    </modules>
</project>

By just compiling the modulesapp, we’ll have three submodules compiled automatically since they’re declared as modules inside the project. Maven-reactor-plugin will take the stage here and analyze the dependency hierarchy to define the order of compile.

Repositories

At some point each Java project that we’ve been developing heavily depends on other artifacts. For instance, a simple web application using the stack JSF, PrimeFaces, Seam, JPA, and Hibernate will have 40 dependencies like:

REPO/javax/activation/activation/1.1/activation-1.1.jar
REPO/antlr/antlr/2.7.6/antlr-2.7.6.jar
REPO/asm/asm/3.1/asm-3.1.jar
REPO/cglib/cglib/2.2/cglib-2.2.jar
REPO/commons-beanutils/commons-beanutils/1.7.0/commons-beanutils-1.7.0.jar
REPO/commons-codec/commons-codec/1.3/commons-codec-1.3.jar
REPO/commons-collections/commons-collections/3.2.1/commons-collections-3.2.1.jar
REPO/commons-lang/commons-lang/2.4/commons-lang-2.4.jar
REPO/commons-logging/commons-logging/1.1.1/commons-logging-1.1.1.jar
REPO/dom4j/dom4j/1.6.1/dom4j-1.6.1.jar
REPO/javax/el/el-api/1.0/el-api-1.0.jar
REPO/org/hibernate/hibernate-annotations/3.5.0-Beta-2/hibernate-annotations-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-commons-annotations/3.2.0.Beta1/hibernate-commons-annotations-3.2.0.Beta1.jar
REPO/org/hibernate/hibernate-core/3.5.0-Beta-2/hibernate-core-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-entitymanager/3.5.0-Beta-2/hibernate-entitymanager-3.5.0-Beta-2.jar
REPO/org/hibernate/hibernate-validator-legacy/4.0.2.GA/hibernate-validator-legacy-4.0.2.GA.jar
REPO/hsqldb/hsqldb/1.8.0.2/hsqldb-1.8.0.2.jar
REPO/javassist/javassist/3.10.0.GA/javassist-3.10.0.GA.jar
REPO/org/jboss/el/jboss-el/1.0_02.CR4/jboss-el-1.0_02.CR4.jar
REPO/org/jboss/seam/jboss-seam/2.2.0.GA/jboss-seam-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-jul/2.2.0.GA/jboss-seam-jul-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-mail/2.2.0.GA/jboss-seam-mail-2.2.0.GA.jar
REPO/org/jboss/seam/jboss-seam-ui/2.2.0.GA/jboss-seam-ui-2.2.0.GA.jar
REPO/org/hibernate/java-persistence/jpa-api/2.0-cr-1/jpa-api-2.0-cr-1.jar
REPO/javax/faces/jsf-api/1.2_13/jsf-api-1.2_13.jar
REPO/com/sun/facelets/jsf-facelets/1.1.14/jsf-facelets-1.1.14.jar
REPO/javax/faces/jsf-impl/1.2_13/jsf-impl-1.2_13.jar
REPO/jstl/jstl/1.2/jstl-1.2.jar
REPO/javax/transaction/jta/1.1/jta-1.1.jar
REPO/junit/junit/3.8.1/junit-3.8.1.jar
REPO/javax/mail/mail/1.4.1/mail-1.4.1.jar
REPO/postgresql/postgresql/8.4-701.jdbc3/postgresql-8.4-701.jdbc3.jar
REPO/org/primefaces/primefaces/1.0.0/primefaces-1.0.0.jar
REPO/quartz/quartz/1.6.0/quartz-1.6.0.jar
REPO/javax/servlet/servlet-api/2.5/servlet-api-2.5.jar
REPO/org/slf4j/slf4j-api/1.5.8/slf4j-api-1.5.8.jar
REPO/org/slf4j/slf4j-nop/1.5.6/slf4j-nop-1.5.6.jar
REPO/org/testng/testng/5.9/testng-5.9.jar
REPO/xpp3/xpp3_min/1.1.3.4.O/xpp3_min-1.1.3.4.O.jar
REPO/xstream/xstream/1.1.3/xstream-1.1.3.jar

Of course, we can store those jars in source control, but it will:

• increase the storage
• make it dreadful to checkout the  project
• force us to version our jars, and we certainly don’t need that

To manage your project’s artifacts and dependencies Maven offers the repository mechanism. There are two types of repositories: a local one that caches the remote downloads your projects depends on and stores the build artifacts that you haven’t yet released; and the remote one that’s mostly hosted by a third party provider and is accessible with a variety of protocols like http. You can store artifacts with extensions like jars, wars, ears, ejbs, zips, and rar and resolve them through the Maven dependency management in your project. If there’s no external repository specified in the project’s POM, Maven looks for a local repository and the central Maven repository defined in the super POM. There are two types of repositories for hosting snapshot and release artifacts. Here’s a sample declaration for each. The first declaration is for a JBoss release repository. The id is uniquely identifying the repository, and it’s pointing to the given URL.

<repository>
    <id>jboss-repo</id>
    <name>The Release JBoss maven repo</name>
    <url>http://repository.jboss.org/maven2</url>
    <releases>
        <enabled>true</enabled>
    </releases>
</repository>

The second declaration is for snapshot artifacts. By default, Maven will not look into repositories for snapshot artifacts if the repository declaration is not tagged as snapshots with the enabled tag.

<repository>
    <id>jboss-snapshot-repo</id>
    <name>The Snapshot JBoss maven repo</name>
    <url>http://snapshots.jboss.org/maven2</url>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>

Searching for Artifacts Online

Searching for artifacts to add as dependencies to your projects can be a problem from time to time. You know that you need a specific jar, such as the Apache Jackrabbit core jar file, but you don’t know about its groupId, artifactId, or the latest version that is available. With the sites listed below, you can easily search for your artifacts online.

http://repository.apache.org
http://www.jarvana.com
http://mvnrepository.com
http://www.artifact-repository.org
http://www.mvnbrowser.com
http://mavensearch.net

Apache runs a Nexus at repository.apache.org. You can find all the Apache-related stuff in there. Another one of the sites above, Jarvana, is actually one of our favorites. It gives you the ability to search for an artifact based on the project name or even a class file name. Suppose you’re developing a web application and you came across a class not found problem that occurred at runtime. With Jarvana you can search for those classes and find the related Maven artifact. It also lists the Javadocs and other cool stuff if applicable.

IDE Support

For popular JAVA IDEs like NetBeans Eclipse or IDEA, you can find first-class support for Maven inside the IDEs. NetBeans and Intellij IDEA support Maven out of the box and ship with the latest version, Maven 3. For Eclipse there are two incubation projects at the moment. One of them is Eclipse Integration for Apache Maven, Eclipse IAM, which is also formerly known as the Q4E project. The other one is the m2eclipse plugin and it’s being maintained by Sonatype. m2eclipse is a must-have plugin if you’re developing on Eclipse. With m2eclipse you can check out Maven projects directly from source control as Maven projects. It supports source controls like Subversion, CVS, Git and many others. You can also create new projects by selecting archetypes.  It’ll take 30 seconds to get you started, for instance, with web applications. There’s also a nice POM editor bundled with the plugin so you don’t need to deal with the XML directly. We’ve includes some screenshots of the plugin below.

To checkout projects from source control:

To create a project with archetypes:

The pom.xml editor – the dependencies:

The Dependency Graph:

Finishing up

There’s no better way to learn the benefits of Maven than to give it a try.  If you’re starting from scratch or have a greenfield project, now is the perfect time to get started with Maven! Maven will ease the build process of your project, and it will be much simpler to manage the project with well-defined metadata. If you’re part of a group of developers working on the same project, you could also use Maven to create your own repository manager. (Nexus, Arcihva and Artifactory are other open source alternatives you can use for that.) Another way to get started with Maven is to create a company or project-specific POM to easily manage dependencies across your sub-projects.

Regardless of how you get started with Maven, here are a few tips to keep in mind:

• Keep your POM simple and readable.
• Use property references to avoid any hard coding.
• Use profiles to create different builds out of your project. Make it so that you can release early and release often — it’s a MUST in the land of agile/extreme programming.
• Follow the rule for Seperation of Concerns, or SoC. Arrange your Maven projects so that you have one artifact per project.
• Use IDE integrations for Maven — there’s a good deal of first class support for popular Java IDEs. Move yourself from stone age to iron age on that matter.
• And finally, do not use parameters for ignoring your tests, they’re evil!

Should you need additional resources on Maven, try the following books that you can find online for free:

http://www.sonatype.com/book

• Maven:The Complete Reference
• Maven By Example
• m2eclipse Book
• Nexus Book

http://www.maestrodev.com/better-build-maven

• Better Builds with Maven