Goodbye Maven 3: How Maven 4 Redefines Java Builds After 15 Years

POM Model Evolution

Maven 4 introduces POM model version 4.1.0. The schema can infer the version, so the modelVersion element may be omitted. Maven 4 can build existing 4.0.0 POMs unchanged; all new capabilities are activated only when the model version is 4.1.0.

Build POM vs Consumer POM (Flattening)

In Maven 3 a published POM served both as the project's own build description and as the dependency descriptor for downstream consumers, causing downstream projects to parse plugin configurations, lifecycle details, parent hierarchy and unused dependencies. Maven 4 splits the POM into two artifacts:

Build POM – used only for the project's own build.

Consumer POM – consumed by downstream projects; it omits plugin configuration, parent references and unused dependencies, retaining only real transitive dependencies with deterministic values.

Consumer POMs are generated automatically with:

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

In Maven 3 this required the external Flatten Maven Plugin; in Maven 4 it is built‑in. Benefits observed are faster dependency resolution, more stable build results and predictable behavior.

Explicit Artifact Types for Classpath and Module Path

Java’s module system makes the distinction between classpath and module‑path critical. Maven 3 inferred the path from the presence of module-info.class, which could be unreliable. Maven 4 adds explicit types:

<type>classpath-jar</type>

<type>module-jar</type>

Developers declare the intended location directly.

Annotation Processor Modeling

Maven 4 defines dedicated processor types:

processor

classpath-processor

modular-processor

Example for Lombok:

<dependencies>
  <!-- Annotation processor, compile‑time only -->
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>${lombok.version}</version>
    <type>classpath-processor</type>
  </dependency>

  <!-- API dependency -->
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>${lombok.version}</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

This separates the processor classpath from the API classpath, improving IDE support, build caching and incremental compilation.

Modules Renamed to Subprojects

To avoid confusion with Java 9 modules, Maven 4 deprecates the modules element and replaces it with subprojects:

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

Additional enhancements include automatic parent inference ( <parent /> when omitted), automatic subproject discovery, unified build timestamps, and a safe release mechanism that aborts the whole release if any module fails.

Tree‑Based Lifecycle for Parallel Builds

Maven 3’s linear lifecycle limited parallelism in multi‑module builds. Maven 4 introduces a tree‑based lifecycle where each subproject progresses independently once its dependencies are satisfied, fully exploiting multi‑core servers. Enable it with: mvn -b concurrent verify Large multi‑module projects observe visibly reduced build times.

Rich Conditional Profiles

Profiles now accept full expressions. Example:

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

This goes beyond simple os.name or jdk.version checks, allowing sophisticated activation logic.

Unified sources Model

Maven 3 required separate sourceDirectory and testSourceDirectory. Maven 4 consolidates them under a sources container, supporting multiple source entries with explicit scopes:

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

This model better fits multi‑directory, multi‑version and modular projects, and also works in environments without plugins.

Official Upgrade Assistant mvnup

The tool analyses POM structure, plugin usage and project layout, then generates executable upgrade suggestions:

mvnup check   # generate analysis report
mvnup apply   # apply changes automatically

Overall Impact

Maven 4 is a systematic reconstruction of the Java build model. It delivers clearer build semantics, clean separation between build and consumer descriptors, explicit handling of classpath vs module‑path, dedicated annotation‑processor modeling, renamed subprojects, a tree‑based lifecycle that unlocks parallelism, expressive profile conditions, and a unified sources definition. These changes align the build tool with modern Java engineering practices.