How Maven 4’s New POM Model and Flattening Transform Java Build Automation

Background

Since Maven 3 was released in 2010 its core model has changed little, while the Java ecosystem has moved to modularization, parallel builds, cloud‑native containers and rapid JDK releases. Maven 4 is designed to address these accumulated gaps and is currently at release candidate 5 (RC5), close to a stable GA.

POM Model Upgrade

Maven 4 introduces POM model version 4.1.0. Existing POMs with modelVersion 4.0.0 remain buildable, but the new capabilities are only active for 4.1.0. The modelVersion element can be omitted; Maven derives it from the schema.

<project xmlns="http://maven.apache.org/POM/4.1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.1.0
                             http://maven.apache.org/xsd/maven-4.1.0.xsd">
  <modelVersion>4.1.0</modelVersion>
</project>

Build POM / Consumer POM Separation (Flattening)

Maven 3 publishes a single POM that mixes build configuration, parent references and unused properties, forcing consumers to parse irrelevant data. Maven 4 separates the artifact that is built (Build POM) from the artifact that is consumed (Consumer POM). The Consumer POM contains only the real transitive dependencies, concrete property values and no plugin configuration, parent POM or unused dependencies.

No plugin configuration.

No parent POM.

No unused dependencies.

Only actual transitive dependencies remain.

All properties are resolved to concrete values.

Enable flattening with the following command:

mvn clean install -Dmaven.consumer.pom.flatten=true

In Maven 3 this required the flatten-maven-plugin; Maven 4 provides the functionality natively, resulting in faster and more predictable dependency resolution.

Explicit Artifact Types for Classpath / Module‑Path Control

Maven 3 inferred the classpath/module‑path based on the presence of module‑info.class. Maven 4 adds explicit types so developers can declare the intended location of a dependency.

<type>classpath-jar</type>
<type>module-jar</type>

Dedicated annotation‑processor types are also introduced:

processor

classpath-processor

modular-processor

Example with Lombok:

<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <version>${lombok.version}</version>
  <type>classpath-processor</type>
</dependency>

Modules Renamed to Subprojects (Java 9 Alignment)

To avoid confusion with Java 9 modules, Maven 4 deprecates the term “modules” and uses “subprojects”. Parent inference and automatic subproject discovery are built‑in.

<subprojects>
  <subproject>project-a</subproject>
  <subproject>project-b</subproject>
</subprojects>

Parent inference – an empty <parent/> is automatically resolved.

Subproject auto‑discovery – no explicit listing required.

Unified build timestamps.

Safe publishing – a failure in any subproject aborts the whole release.

Tree‑Based Lifecycle – Parallel Builds

Maven 3’s linear lifecycle limits parallelism in large multi‑module builds. Maven 4 introduces a tree‑based lifecycle where each subproject progresses independently once its dependencies are ready, dramatically reducing build time for complex projects.

mvn -b concurrent verify

Configuration Enhancements

Profile Condition Expressions

Profiles can now use full boolean expressions instead of simple OS or JDK checks.

<condition>
  exists('${project.basedir}/src/**/*.xsd') && length(${user.name}) > 5
</condition>

Unified sources Model

Maven 3 required separate sourceDirectory and testSourceDirectory. Maven 4 consolidates them into a single sources element, supporting multiple directories, versions and modular projects without additional plugin configuration.

<sources>
  <source>
    <scope>main</scope>
    <directory>my-custom-dir/foo</directory>
  </source>
  <source>
    <scope>test</scope>
    <directory>my-custom-dir/bar</directory>
  </source>
</sources>

Official Upgrade Assistant (mvnup)

Maven 4 ships with mvnup to help migrate existing projects.

mvnup check   # generate migration report
mvnup apply   # automatically apply suggested changes

The tool analyses POM files, plugins and project structure, then provides executable upgrade recommendations.