Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 41 ยท The POM

The POM File

Understand the Maven pom.xml: the project root, modelVersion, coordinates, packaging, name and description, dependencies and the idea of an effective POM.

Every Maven project has one file at its root named pom.xml. POM stands for Project Object Model: it is an XML description of the project that Maven reads before it does anything else. It says what the project is called, how it is packaged, which libraries it needs and how its build should differ from the defaults.

A POM is declarative. It does not list build steps; it states facts about the project, and Maven combines those facts with its built-in conventions. In this lesson you learn the structure of the file, the handful of elements you will write in nearly every project, and the idea of the effective POM, which is what Maven actually uses after merging defaults. The runnable examples are stand-ins that read a POM with Java's own XML API.

The skeleton of a POM

Coordinates groupId, artifactId, version.
Packaging jar, war or pom.
Dependencies The libraries you need.
Build Plugins and settings.
1 / 2

A minimal POM

Here is a small but realistic POM:

XML
<?xml version="1.0" encoding="UTF-8"?>
<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
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>greeter</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <name>Greeter</name>
  <description>A tiny library that says hello.</description>
  <url>https://example.com/greeter</url>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.11.0</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Take it from the top.

  • <project> is the root element. The xmlns and xsi:schemaLocation attributes name the XML schema; they let editors validate and autocomplete the file. They are boilerplate: copy them and move on.
  • <modelVersion> is the version of the POM format itself. It has been 4.0.0 for all of Maven 2 and 3 and it is required. Maven 4 can also read a newer model version for projects that use its new features, but 4.0.0 still works everywhere.
  • groupId, artifactId and version are the project's coordinates, its unique identity. The next lesson is entirely about them.
  • <packaging> says what kind of artifact the project produces. If you leave it out, the default is jar.
  • <name>, <description> and <url> are human-readable metadata. They do not affect the build, but they appear in logs, generated sites and published listings, and Maven Central requires some of them when you publish.
  • <dependencies> lists the libraries the project needs. See Adding Dependencies.

Elements inside <project> can appear in any order, but most teams keep the order above, which reads naturally from "who am I" to "what do I need" to "how do I build".

Packaging

The <packaging> element decides which lifecycle bindings apply, that is, which goals run in each phase.

Packaging Produces Typical use
jar a JAR archive (default) libraries and command-line apps
war a web archive classic servlet container deployments
pom no code, just the POM itself parent POMs and multi-module roots
maven-plugin a Maven plugin writing plugins

The pom packaging is special: a project with pom packaging has nothing to compile. It exists to hold shared configuration or to group modules, which you will use in Parent POMs and the Effective POM and Multi-Module Builds.

Where the build lives

Inside <project>, two optional sections hold the build's behavior.

XML
<properties>
  <maven.compiler.release>21</maven.compiler.release>
</properties>

<build>
  <plugins>
    <plugin>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.2.5</version>
    </plugin>
  </plugins>
</build>

<properties> defines reusable values (see Properties and Build Settings). <build> configures plugins and folders. In a small project you may need neither.

The effective POM

You write a short POM, but Maven needs a lot more information to build: where the source folders are, which plugin versions to use, where Maven Central lives. That all comes from a built-in parent called the Super POM, which every POM inherits from. Maven merges the Super POM, any parent POMs you declare, and your own file, and the result is the effective POM.

You can see it with a command:

TEXT
mvn help:effective-pom

The output is long and shows every default made explicit, including the standard repository and the src/main/java directory. When a build does something you did not expect, the effective POM is the place to look, because it shows what Maven really sees. You will use this command heavily in Parent POMs and the Effective POM.

flowchart LR
    S["Super POM<br/>(built in)"] --> E["Effective POM"]
    P["Parent POM<br/>(optional)"] --> E
    Y["Your pom.xml"] --> E
    E --> B["The build"]

Your file is only one layer; the effective POM is what drives the build.

Common mistakes

  • Forgetting modelVersion. Maven refuses to read the POM.
  • Putting <dependency> directly in <project>. Dependencies belong inside <dependencies>.
  • Typos in element names. Maven reports "Unrecognised tag" or ignores the element in some positions; read the first error line.
  • Mixing up name and artifactId. artifactId is the machine identity (no spaces, lowercase); name is for people and may contain spaces.

IDEs validate the POM against the schema as you type. If your editor shows a red squiggle, believe it; XML mistakes are easy to make and easy to fix.

Stand-in: reading a POM with Java

The real thing, Maven, uses its own model classes to read a POM. The stand-in below uses the XML parser built into Java to extract the same facts and fill in the default packaging, much like Maven does. The POM is a text block inside the program, so nothing is read from disk.

Java Parse a tiny POM

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The model skips namespaces, inheritance, interpolation and validation. Notice the two defaults it applies: no <packaging> means jar, and no <scope> means compile. Both match what Maven does.

The second stand-in is a tiny validator that checks the required elements, which is the first thing Maven does when it reads your file. Try deleting a line from the POM text and running it again.

Java Check the required elements

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

This sample POM has no <version>, so the model reports it. Real Maven allows a missing groupId or version when a parent POM supplies them, which this simple check does not know about; that is one of the topics of Parent POMs and the Effective POM.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the default packaging when <packaging> is omitted?

    A POM without a packaging element produces a jar.
  2. 2. What is the effective POM?

    Maven combines the built-in Super POM, parent POMs and your file. The merged result is what drives the build, and mvn help:effective-pom prints it.
  3. 3. Which element is a human-readable label that does not identify the project?

    name is for people. Identity comes from the coordinates groupId, artifactId and version.
  4. 4. A project with packaging pom is typically used for what?

    pom packaging produces no code. It is used for parent POMs and multi-module aggregators.

Summary

  • pom.xml is a declarative XML description of the project: coordinates, packaging, metadata, dependencies and build settings.
  • modelVersion is required; packaging defaults to jar; a dependency's scope defaults to compile.
  • name and description are for humans; the coordinates identify the project.
  • Every POM inherits from the Super POM; Maven works with the merged effective POM, shown by mvn help:effective-pom.

Next, the three values that identify every project: Coordinates: groupId, artifactId, version.