Using Apache Maven

Page content

Notes on using the Maven tool for Java projects.

Concepts

Maven uses a Project Object Model (POM) to describe the project that it manages. This is stored as an XML file in the root directory of the project. The POM file will have the name pom.xml.

Maven supports project templates, known as archetypes. This means that you can create a POM file for your project from an existing template.

Phases, Lifecycles and Goals

A phase is a step in a lifecycle, which is an ordered sequence of phases. If you specify a phase with the mvn command, Maven will execute every phase in the sequence up to and including the one defined.

The default lifecycle has these phases:

  • validate: validate the project is correct and all necessary information is available
  • compile: compile the source code of the project
  • test: test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
  • package: take the compiled code and package it in its distributable format, such as a JAR.
  • integration-test: process and deploy the package if necessary into an environment where integration tests can be run
  • verify: run any checks to verify the package is valid and meets quality criteria
  • install: install the package into the local repository, for use as a dependency in other projects locally
  • deploy: done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.

There are two other standard Maven lifecycles. These are:

  • clean: cleans up artifacts created by prior builds
  • site: generates site documentation for this project

Goals are tasks or targets. Each goal is associated with one or more phases of a lifecycle. Maven plugins are collections of goals.

Profiles

A build profile is a set of configuration values, which can be used to set or override default values.

Repositories

Maven downloads dependencies from the central repository, and from your remote repository. The central repository is the Maven public repository. Use the Maven Package Search page to see what is available. Downloads are cached in a local repository directory. This means that Maven looks for dependencies in the local repository first, then the central repository, and then the remote repository.

You may also specify external dependencies in the POM. These are dependencies that are not available from any repository. The files for external dependencies should be in the lib directory of your project.

SNAPSHOT is a special version that indicates a current development copy. Maven checks for a new SNAPSHOT version in a remote repository for every build.

Documentation Generation

Maven includes Doxia, a framework for generating documentation from a set of plain-text files. It supports various formats, including Markdown. Doxia is mainly for maintaining project Websites, rather than API documentation from JavaDoc annotations in the source code.

Setup

Maven is a Java tool, so the same package will run on any operating system that has a JDK installed.

  1. Download the latest version of Maven
  2. Unzip the download
  3. Copy the Maven directory to /usr/local/lib
  4. Add /usr/local/lib/<MAVEN_DIRECTORY> to your PATH environment variable

Project Structure

Maven assumes a specific project structure:

  • Source code: src/main/java/
  • Resources: src/main/resources/
  • Tests: src/test/
  • Compiled byte code: target/
  • Distributable JAR: target/classes/

Project Object Model (POM)

Each POM file must have these properties defined:

  • modelVersion - The version of the POM that the file uses
  • groupId - The identifier for the team or group that maintains the project
  • artifactId - The identifier for the project
  • version - The version of the project

Maven 2 and Maven 3 both use modelVersion 4.0, which means that every POM file should use this version.

Maven always uses an effective POM. This is a combination of the settings from:

  • The project pom.xml
  • All parent POMs
  • The Super POM
  • Any user-defined settings
  • The active profiles

To see the effective POM for a project, run this command:

mvn help:effective-pom

Each POM uses the Super POM that is provided by Maven, unless you declare a different Super POM.

Maven Plugins

  • Assembly - Packs multiple outputs into a single compressed archive, such as a JAR, WAR, or ZIP file
  • FMT - Reformats Java code to Google Java Style
  • Jib - Container builder

Online Resources