Maven POM Structure, Coordinates, Packaging, Build Lifecycle, Phases, and Goals: Concepts, Architecture, and Mental Model

1. The practical problem — why did Maven run that goal?

Chapter 04 established which Maven runtime, settings, wrapper, repositories, and JDK are active. This chapter asks the next production question: when you run ./mvnw package, why do resources get copied, Java gets compiled, tests run, and a JAR appears even though your POM never named those goals?

The answer is not “because package means build a JAR.” Maven first builds an effective project model. That model contains your POM plus inherited/default state. The project’s packaging selects default goal-to-phase bindings. Maven then walks the chosen lifecycle through the requested phase and executes every bound plugin goal encountered on that path.

2. The model-to-execution pipeline

flowchart TD
  P[pom.xml] --> M[Model builder]
  S[Super POM] --> M
  R[Parent POMs + active profiles] --> M
  M --> E[Effective POM]
  E --> C[Coordinates + packaging + build configuration]
  C --> L[Selected lifecycle and requested phase]
  B[Packaging default bindings] --> L
  X[Explicit plugin executions] --> L
  L --> G[Ordered plugin goals]
  G --> O[target outputs]
  G --> I[local repository on install]

Read every arrow literally. pom.xml, the Super POM, parents, and active profiles feed the model builder. The resulting effective POM contributes coordinates, packaging, properties, dependencies, and plugin configuration. Packaging contributes default bindings. Explicit executions add more goals. The requested phase determines how far Maven walks the lifecycle. Goals then create observable files, reports, artifacts, or local-repository state.

3. Vocabulary that must stay separate

4. Minimal POM versus effective POM

<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>dev.academy</groupId>
  <artifactId>lifecycle-lab</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>17</maven.compiler.release>
  </properties>

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

This POM says less than Maven actually knows. All Maven 3 models implicitly inherit the Super POM, which supplies conventions such as target, src/main/java, src/test/java, resource directories, and Central. The effective model can also include parent inheritance and active profiles.

./mvnw --version
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:effective-pom \
  -Dverbose \
  -Doutput=target/effective-pom.xml

# Inspect, do not edit, the generated evidence file.
grep -nE '(<packaging>|<sourceDirectory>|<outputDirectory>|maven-.*-plugin)' \
  target/effective-pom.xml | head -80

5. Three built-in lifecycles; phases are ordered checkpoints

If you invoke install, Maven executes every earlier phase of the default lifecycle before install. It does not automatically run clean because clean belongs to a different lifecycle. That is why ./mvnw clean install contains two separate CLI phase requests.

A phase can have zero goals bound to it. In a minimal JAR project, validate is still a valid phase even if no default goal performs visible work there.

6. Packaging turns phases into concrete plugin goals

These versions come from Maven 3.9.16 core bindings. They are not a timeless promise. Changing the Maven runtime can change the default plugin versions even if pom.xml is unchanged. That is one reason the wrapper and effective-model evidence matter.

7. Packaging changes the lifecycle mapping

Packaging is not merely a filename extension. It participates in lifecycle mapping.

If a project says <packaging>pom</packaging> but an operator expects target/*.jar, the model and expectation disagree. Diagnose the POM before blaming the JAR plugin.

8. Inspect before mutating

./mvnw --version

# Effective model with source-line origins in comments.
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:effective-pom \
  -Dverbose -Doutput=target/effective-pom.xml

# Read a plugin goal description without executing the build lifecycle.
./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.2:describe \
  -Dplugin=org.apache.maven.plugins:maven-jar-plugin:3.5.0 \
  -Dgoal=jar -Ddetail

# Record declared coordinates/packaging from the source POM.
grep -nE '<(groupId|artifactId|version|packaging)>' pom.xml

This sequence proves Maven/JDK identity, declared model, effective model, and plugin capability before you add or move any execution. In CI, capture the same concise evidence near the beginning of a job when lifecycle behavior matters to incident diagnosis.

9. Build-state and trust boundaries

10. DevOps operating model

A production build should be explainable as a chain: declared POM → effective model → packaging/lifecycle bindings → ordered plugin goals → artifact/report/local-repository evidence. When CI only records “mvn package succeeded,” it hides the versions and model that produced the result. Record wrapper/Maven/JDK identity and retain enough lifecycle/artifact evidence to reproduce or diagnose the run.

Knowledge check

Summary

The POM is Maven’s declared project model; the effective POM is the model after inheritance, profiles, and defaults. Packaging selects default lifecycle bindings. Lifecycles contain ordered phases, and phases execute bound plugin goals. A phase request walks every earlier phase in that lifecycle; a direct goal invocation does not. The wrapper fixes the Maven runtime that supplies the Super POM and core bindings, so wrapper identity is part of lifecycle reproducibility.

Official references and version notes

Version-sensitive statements in this lesson were checked against Apache Maven primary documentation on 2026-08-23. The production teaching baseline is Maven 3.9.16 through Maven Wrapper 3.3.4, running on JDK 21 and compiling the lab project with maven.compiler.release=17. Maven 4 is intentionally outside this chapter’s required path because it remains preview-stage. Default lifecycle plugin versions are properties of the Maven runtime and can change when the Maven runtime changes; re-check the matching core reference after an upgrade.

• Maven — Introduction to the Build Lifecycle
• Maven 3.9.16 — Lifecycles Reference
• Maven 3.9.16 — Default Lifecycle Plugin Bindings
• Maven — POM Reference
• Maven 3.9.16 — Super POM
• Maven Help Plugin 3.5.2 — effective-pom
• Maven Install Plugin
• Maven JAR Plugin