Understanding Maven

Get started with the fundamentals of developing Java projects with Apache Maven

(For more resources related to this topic, see here.)

A Maven project

A Maven project is simply a folder in your filesystem (also known as the project root folder) that contains a file called pom.xml, the XML representation of your Project Object Model (POM); this is the first—and most important—Maven convention.

This minimal structure allows you to run a mvn command from the project root folder. By default, the mvn command searches for a pom.xml file in the local folder and it stops immediately if it is not able to find it.

By convention, all artifacts generated by the build are delivered in a folder—relative to the pom.xml location—known as Build Directory (the target by default). Since the target is generated on each build, it is:

  • Safe to delete it anytime

  • Crucial to ignore it when sharing the project using a Version Control System software

A Maven project defines a packaging, which identifies the main objective of the build, which in turn specifies the artifact that is going to be produced by the invocation of the build.Default JAR (other values are EAR, EJB, RAR, PAR, WAR, and POM).

POM packaging is an exception, since:

  • The Maven build does not produce an artifact

  • The Maven build considers—as the only artifact—the main pom.xml file of the Maven project

A POM Maven project can be useful for the following activities:

  • Aggregate dependencies (for more information, you can navigate to Lifecycle | Dependency Management)

  • Parent POM (for more information, you can navigate to Lifecycle | Multi-module project)

Super POM

Every Maven POM implicitly inherits from Super POM (more information is available at http://maven.apache.org/ref/3.0.5/maven-model-builder/super-pom.html), which contains all the default values that are needed to perform built-in Maven features, as we will see later in this book. Super POM is provided by the Maven installation.

It is not intended to be changed—as it would cause build portability issues (more information is available at http://www.devx.com/Java/Article/32386)–but it is definitely interesting to read and investigate it further (more information is available at http://maven.apache.org/ guides/introduction/introduction-to-the-pom.html) in order to be more confident when using/overriding values in your pom.xml file.

Artifact

An artifact–in a Maven context–is a file that is (or has been) produced by a build execution and represents an application binary (of a specific version) that is subject to a lifecycle.

An artifact can have diff erent purposes, listed as follows:

  • A project's library: JAR, WAR, EAR, ZIP, or any file extension you may want to integrate in your build.

  • Maven plugin: A JAR application containing the logic to execute build executions.

  • Maven archetype: A JAR application containing the logic to create a Maven project with a pre-defined file and folder content. Archetypes will be introduced in the next section.

  • Project descriptor: As we'll see shortly, a POM is itself an artifact.

The following coordinates uniquely identify an artifact:

  • groupId: This coordinate represents the group, company, team, organization, and/ or project related with the given artifact. The convention is the same as that of the Java packages (more information is available at http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html6). For example, projects from Apache Software Foundation would have a groupId coordinate that starts with org.apache. A good rule of thumb for deciding the granularity of groupId is by following the project's structure. For example, com.mycompany.myproject.persistence, com.mycompany.myproject.api, and so on.

  • artifactId: This coordinate represents the name of the project (or module) related with the given artifact. artifactId must not contain any version-related information; if the artifact is a module, it is advised to join the project name with the module one (that is, commons-logging). Using only lowercase letters and the dash (-) as a separator is a clear and consolidated strategy. Good examples for artifactID are maven-core, commons-math, and log4j-over-sl4j.

  • type: The extension (and filetype) of the artifact; the default type is JAR, but it can have any extension, such as WAR, EAR, or any other.

  • version: This coordinate is a specific release of a project. It consists of a group of literals separated by dots; for example, 1.0, 2.0.1-RC1, and 2.0.0.1-alpha-2. If the version ends with the –SNAPSHOT literal, it means that the artifact is a nightly build and therefore not released yet. In order to take full advantage of Maven's version management, every work in progress project should have a –SNAPSHOT version; we will discuss this later.

  • classifier: This is an additional coordinate to handle two (or more) artifacts having the same coordinates but containing a diff erent content; empty by default. For example, Maven identifies binary and source (source artifacts are archives containing the source code of your application, for more on this you can visit http://maven.apache.org/ plugin-developers/cookbook/attach-source-javadoc-artifacts.html) artifacts using the same coordinates, but with diff erent classifiers.

For more information about naming conventions, check the official Maven documentation available at http://maven.apache.org/guides/mini/guide-naming-conventions.html

Minimal pom.xml

An example of a minimal pom.xml file is as follows:

<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany.app</groupId>
<artifactId>app-web</artifactId>
<version>1.0-SNAPSHOT</version>
<type>war</type>
</project>

The pom.xml file is the central configuration file for a Maven project, and it is fundamental to understand it deeply; it contains information about the project structure, metadata, and confi guration related with the plugin's executions.

The modelVersion element is in every pom.xml; it represents the pom.xml XML schema version and is set to 4.0.0 for all Maven 2.x and 3.x-based builds.

The–SNAPSHOT suffix in a pom.xml file specifies that the artifacts produced by this build are unreleased, and therefore they considered nightly builds.

In this section we will introduce the most important elements of a POM; some will not be mentioned, while some others will be briefl y introduced.

Parent (also known as POM Inheritance)

A pom.xml file can define a parent as a pointer to a POM artifact. As a result, all parent's Maven configurations will be inherited.

<parent>
<groupId>com.mycompany.myproject</groupId>
<artifactId>my-parent-pom</artifactId>
<version>1.0-SNAPSHOT</version>
</parent>

Plugin

A Maven plugin is a JAR Maven artifact containing Java classes that implement one or more goals using the Maven Plugin API (more information is available at http://maven.apache. org/ref/3.0.5/maven-plugin-api), and declares a public short name (that is, tomcat7x).

<build>
<plugins>
<plugin>
<groupId>org.apache.tomcat.maven</groupId>
<artifactId>tomcat7-maven-plugin</artifactId>
<version>2.1</version>
<configuration>
<url>http://127.0.0.1:8080/manager</url>
<server>Tomcat</server>
<path>/app-web</path>
</configuration>
</plugin>
</plugins>
</build>

The goal identifies a build task; it has a unique name (that is, run) within the same plugin. It can access and change the POM and provide a wide range of operations, from zipping a folder to performing a remote deployment on a Tomcat server.

A goal can be executed by the mvn command using the following syntax:

<plugin_shortname>:<goal_name>, for example mvn tomcat7x:run

A goal can be invoked by the lifecycle phase; you will read more about it in the Maven lifecycle section.

All plugins having an artifactId coordinate starting with maven- are directly supported by Maven projects (more information is available at http://maven.apache.org/plugins/).

In order to understand how to use a Maven Plugin, search for its official documentation page; the Usage page (available at http://tomcat.apache.org/maven-plugin-2.0/tomcat7- maven-plugin/usage.html) explains how to add the plugin to your build; the Goals page (available at http://tomcat.apache.org/maven-plugin-2.0/tomcat7-maven-plugin/plugin-info.html) lists all goals and parameters that you can set.

Repository

A Maven Repository is a folder with a specific layout that can optionally be located remotely:

<repositories>
<repository>
<id>my-custom-repo</id>
<url>http://artifacts.mysite.com/repository</url>
</repository>
</repositories>

The Repository layout is a key convention in Maven that allows you to uniquely locate an artifact:

<repository_url>/<groupId>/<artifactId>/<version>/<artifactId>-
<classifier>-<version>.<type>

For example, you can have the following coordinates for the preceding artifact:

  • groupId: org.apache.solr

  • artifactId: solr

  • version: 4.3.0

  • type: .war

For a remote URL, the Repository URL can be:

The layout key will hence be:

For a local URL, the Repository URL can be:

  • file: ///Users/mau/.m2/repository

The layout key will hence be:

  • file: ///Users/mau/.m2/repository/org/apache/solr/solr/4.3.0/ solr-4.3.0.war

A Maven Repository is the source and the destination of artifacts in the following scenarios:

  • Source: When a Maven build depends on one or more artifacts, the Maven Repository is the place where these fi les are resolved and downloaded from

  • Destination: When a Maven build produces one or more artifacts, it may be— optionally—deployed on a Maven Repository

A Maven Repository can restrict the download/upload artifact operations depending whether the artifact's version is a -SNAPSHOT literal or not. This way, you can easily defi ne nightly builds, repositories, and defi ne tailored maintenance operations (that is, remove -SNAPSHOT artifacts after 30 days).

-SNAPSHOT artifacts are a special case for Maven Repositories:

  • When uploaded, the -SNAPSHOT literal of the artifact name will be replaced with the current timestamp (more information is available at http://docs.oracle.com/javase/6/docs/api/java/sql/Timestamp.html)

  • When downloaded, the revolved artifact will be the one with the highest timestamp (most recently uploaded amongst all other –SNAPSHOT artifacts having the same coordinates)

The Super POM defines two very special repositories:

  • Local Repository: This repository is a local folder located in ~/.m2/repository (~ means user home in Linux, Unix, and OS X environments). The Local Repository works as a cache for all remotely-fetched artifacts: every time Maven downloads an artifact for you, it will do it only once. This rule does not apply to -SNAPSHOT artifacts, since these versions are supposed to change frequently; in this case, the build will ask the Maven Repository whether the -SNAPSHOT artifact was updated since the last fetch.

  • Maven Central Repository: This is a remote Maven repository containing the official releases of Maven core plugins—which deliver all built-in functionalities of Apache Maven—and the biggest collection of Java artifacts in the world (Java.net and Oracle are hosted here, and many other companies, projects, and communities). Maven Central is open (more information is available at http://www.sonatype.org/central/participate ) to the contribution of anyone who wants to share their artifacts with the rest of the world.You can browse Maven Central using http://search.maven.org (shown in the following screenshot). Maven Central is hosted by Sonatype (more information is available at http://www.sonatype.org/).

Summary

Thus this article helps us understand Maven vocabulary more closely as it is very important to have all the concepts clear in order to gain a complete understanding of Maven.

Resources for Article :


Further resources on this subject:


Books to Consider

comments powered by Disqus