Post#79.Maven POM Files

Maven POM Files

A Maven POM file (Project Object Model) is an XML file that describe the resources of the project. This includes the directories where the source code, test source etc. is located in, what external dependencies (JAR files) your projects has etc.

The POM file describes what to build, but most often not how to build it. How to build it is up to the Maven build phases and goals. You can insert custom actions (goals) into the Maven build phase if you need to, though.

Each project has a POM file. The POM file is named pom.xml and should be located in the root directory of your project. A project divided into subprojects will typically have one POM file for the parent project, and one POM file for each subproject. This structure allows both the total project to be built in one step, or any of the subprojects to be built separately.

Throughout the rest of this section I will describe the most important parts of the POM file. For a full reference of the POM file, visit http://maven.apache.org/pom.html

Here is a minimal POM 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/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.igt</groupId>

    <artifactId>java-web-crawler</artifactId>

    <version>1.0.0</version>

</project>

The modelVersion element sets what version of the POM model you are using. Use the one matching the Maven version you are using. Version 4.0.0 matches Maven version 2 and 3.

The groupId element is a unique ID for an organization, or a project (an open source project, for instance). Most often you will use a group ID which is similar to the root Java package name of the project. For instance, for my java project I may choose the group ID com.igt. If the project has many independent contributors, perhaps it would make more sense to use a group ID. Thus, com.igt could be used.

Note:

The group ID does not have to be a Java package name, and does not need to use the . notation (dot notation) for separating words in the ID. But, if you do, the project will be located in the Maven repository under a directory structure matching the group ID. Each . is replaced with a directory separator, and each word thus represents a directory. The group ID com.igt would then be located in a directory called MAVEN_REPO/com/igt. The MAVEN_REPO part of the directory name will be replaced with the directory path of the Maven repository.

The artifactId element contains the name of the project you are building. In case of my Java Web Crawler project, the artifact ID would be java-web-crawler. The artifact ID is used as name for a subdirectory under the groupID directory in the Maven repository. The artifactID is also used as part of the name of the JAR file produced when building the project. The output of the build process ( the build result) is called an artifact in Maven. Most often it is a JAR, WAR or EAR file.

The versionId element contains the version number of the project. If your project has been released in different versions, for instance an open source API, then it is useful to version the builds. That way users of your project can refer to a specific version of your project. The version number is used as a name for a subdirectory under the artifact ID directory. The version number is also used as part of the name of the artifact built.

The above groupId, artifactId and version elements would result in a JAR file being built and put into the local Maven repository at the following path (directory and file name):

MAVEN_REPO/com/igt/java-web-crawler/1.0.0/java-web-crawler-1.0.0.jar

Note: If your project uses the Maven directory structure, and your project has no external dependencies, then the above minimal POM file is all you need to build your project.

If your project does not follow the standard directory structure, has external dependencies, or need special actions during building, you will need to add more elements to the POM file.

In general you can specify a lot of things in the POM which gives Maven more details about how to build your projects.

Super POM

All Maven POM files inherit from a super POM. If no super POM is specified, the POM file inherits from the base POM. Here is a diagram illustrating that:

You can make a POM file explicitly inherit from another POM file. That way you can change the settings across all inheriting POM's via their common super POM. You specify the super POM at the top of a POM file like this:

<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/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

   

        <parent>

        <groupId>org.codehaus.mojo</groupId>

        <artifactId>my-parent</artifactId>

        <version>2.0</version>

        <relativePath>../my-parent</relativePath>

        </parent>

   

    <artifactId>my-project</artifactId>

    ...

</project>

Note: An inheriting POM file may override settings from a super POM. Just specify new settings in the inheriting POM file.

Effective POM

With all this POM inheritance it may be hard to know what the total POM file looks like when Maven executes. The total POM file (result of all inheritance) is called the effective POM. You can get Maven to show you the effective POM using this command:

mvn help:effective-pom

This command will make Maven write out the effective POM to the command line prompt.