Maven Tutorial - Maven POM File








POM stands for Project Object Model. It is a core concept in Maven.

A POM file is using XML format to declare the project resources like dependencies.

The dependencies are JAR files which are used as library in the project.

The pom.xml located in the root directory of the project contains references to all of these resources.

Since Maven is Convention over Configuration, most of time we only need to declare the name of the artifacts, we don't need to specify the absolute or relative path for Maven to locate the resource. Maven uses a default directory/folder layout. All mavenized projects uses the same directory/folder to organize their source files, resource files.





How Maven uses the POM file

Maven uses the pom.xml file in the following steps.

  • Read the pom.xml file, parse the content.
  • Download dependencies to local dependency repository.
  • Execute life cycle/build phase/goal.
    For example, mvn compile will do the compile
    mvn test will execute all unit test cases
    mvn package will do compile, then execute all unit test cases, finally zip the classes file to a jar/war/ear file.
  • Execute plugins. Maven plugins are extensions for Maven core. Sometime we need to use plugins to do custom-project specific tasks.




What is in pom.xml file

A Maven POM file (Project Object Model), pom.xml, is an XML file that describe the resources of the project.

Each project has a POM file. The POM file is named pom.xml and should be located in the root directory of the project.

The pom.xml has declaration about the project and various configurations.

The pom.xml file also has the goals and plugins.

The POM file describes what to build, but not how to build it. How to build it is up to the Maven build phases and goals.

We can add custom actions (goals) into the Maven build phase.

The following tables lists some of the configuration that can be specified in the POM.

Item Description
project dependencies Library JAR files
plugins Extension needed
build profiles Custom setting for project
project version A version number for the project. If the pom.xml is for a library, the version number is used as the library version number.
developers Provide the information for developers who builds the software
mailing list Email address

A project divided into sub projects will typically have one POM file for the parent project, and one POM file for each subproject.

By using this structure we can build the whole project in one step, or if necessary we can build sub projects separately.

Example

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>groupID</groupId>
    <artifactId>artifactId</artifactId>
    <version>1.0.0</version>
</project>

Before creating a POM, we should decide the project group (groupId), the project name(artifactId) and its version(version).

These attributes help us in uniquely identifying the project in repository.

In the following code we fill the groupId which is the project group name, the artifactId which is the project name, and the project version.

<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.companyname.project-group</groupId>
   <artifactId>feeCalculation</artifactId>
   <version>1.0</version>
 
</project>

Note

All POM files require the project XML element and three mandatory fields: groupId, artifactId,version.

Projects notation in repository is groupId:artifactId:version.

The modelVersion element sets what version of the POM model. It has to match 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.

Normally we use a group ID similar to the root Java package name of the project.

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.yourCompany would then be located in a directory called MAVEN_REPO/com/yourCompany.

The MAVEN_REPO is the directory path of the Maven repository.

The artifactId element contains the name of the project.

The artifact ID is used as name for a sub directory under the group ID directory in the Maven repository and as part of the name of the JAR file produced when building the project.

The build result, a JAR, WAR or EAR file, is called an artifact in Maven.

The versionId element contains the version number of the project.

The users of your project can refer to a specific version of your project by using the version number in versionId element.

The version number is used as a name for a subdirectory under the artifact ID directory. and 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/companyname/project-group/feeCalculation/1.0.0/feeCalculation-1.0.0.jar

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.

Super POM

All Maven POM files inherit from a super POM regardless explicitly defined or not.

This base POM is known as the Super POM, and contains values inherited by default.

It helps developer to specify minimum configuration detail in pom.xml.

If no super POM is specified, the POM file inherits from the base POM.

Here is a diagram illustrating that:

Base POM
 |
 +---POM
 |
 |
 +---POM
 |    |
 |    +---POM
 |    |
 |    +---POM
 |    |
 |    +---POM
 |
 |
 +---POM

We can set a super POM file explicitly in POM file to 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.oneproject.fee</groupId>
        <artifactId>my-parent</artifactId>
        <version>2.0</version>
        <relativePath>../my-parent</relativePath>
        </parent>
    

    <artifactId>my-project</artifactId>
    ...
</project>

An inheriting POM file can override settings from a super POM by specifying new settings in the inheriting POM file.

Effective pom

Maven use the effective pom from super pom plus project configuration to execute relevant goal.

We can look at the default configurations of the super POM by running the following command:

mvn help:effective-pom