maven

the picture

think of an assembly line in a factory. the stations are bolted to the floor in a fixed order: cut, weld, paint, inspect, ship. you don't design the line, you hand over a parts list and say "run it up to paint". every station before paint runs, in order, every time. that's maven: the stations are phases, the machines at each station are plugin goals, and the parts list is the pom.

the floor plan is fixed too. maven doesn't ask where your code is, it assumes:

the pom

here's a complete pom.xml: the one for the demo app later in this chapter, minus one dependency (that one is where the trouble starts). everything in this chapter ran on maven 3.10.0 and jdk 25.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>com.acme</groupId>           <!-- who: usually a reversed domain -->
  <artifactId>app</artifactId>          <!-- what -->
  <version>1.0-SNAPSHOT</version>       <!-- which. SNAPSHOT = still changing -->
 
  <properties>
    <maven.compiler.release>25</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
 
  <dependencies>
    <dependency>
      <groupId>com.acme</groupId>
      <artifactId>json-lib</artifactId>
      <version>1.0</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>6.1.3</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

groupId:artifactId:version is the artifact's address, its coordinates. maven turns it into a path (com/acme/json-lib/1.0/json-lib-1.0.jar), looks in ~/.m2/repository first, then downloads from maven central. maven.compiler.release becomes javac --release 25 (the safe way to target a version, see the jdk toolbox).

the lifecycle

this is the part people get wrong. you never run a plugin's "compile step" directly. you ask for a phase, and maven runs every phase before it.

$ mvn package
[INFO] --- resources:3.5.0:resources (default-resources) @ app ---
[INFO] --- compiler:3.16.0:compile (default-compile) @ app ---
[INFO] --- resources:3.5.0:testResources (default-testResources) @ app ---
[INFO] --- compiler:3.16.0:testCompile (default-testCompile) @ app ---
[INFO] --- surefire:3.6.0:test (default-test) @ app ---
[INFO] --- jar:3.5.1:jar (default-jar) @ app ---
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

so mvn package compiles, compiles tests, runs them, and only then builds the jar. a failing test stops it at test, and no jar gets made. mvn install does all of that and copies the jar into your local repository so your other projects can depend on it. there are two more, separate lifecycles: clean (deletes target/) and site (generates a report site). that's why the classic incantation is mvn clean install: two lifecycles, one command.

plugins do the work

maven core knows almost nothing about java. compiling is maven-compiler-plugin, testing is maven-surefire-plugin, jarring is maven-jar-plugin. a goal is one task a plugin can do (compiler:compile, compiler:testCompile). the packaging type (jar, war, pom) decides which goals are bound to which phases by default. you add more by declaring an execution:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-enforcer-plugin</artifactId>
      <version>3.6.2</version>
      <executions>
        <execution>
          <id>enforce</id>
          <goals><goal>enforce</goal></goals>   <!-- binds to validate by default -->
          <configuration>
            <rules><dependencyConvergence/></rules>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

mvn dependency:tree works without any of that: naming plugin:goal on the command line runs that goal once, outside the lifecycle. you'll use that one a lot. (and pin plugin versions like above. if you don't, they come from maven's own defaults, which change between maven releases.)

scopes: which classpath gets what

a dependency doesn't just "get added". its scope decides which classpaths it lands on.

scopes also filter what flows in transitively: your dependencies' test and provided dependencies never reach you.

when versions collide

every library brings its own dependencies, and sooner or later two of them want different versions of the same thing. maven only puts one version on the classpath, and it picks with a rule called dependency mediation:

1. the version nearest to your project in the tree wins.
2. if two are equally near, the one declared first wins.

that's it. there's no "newest wins". here's a real project where that bites:

pom.xml<!-- json-lib 1.0 and http-lib 2.0, nothing else -->

$ mvn package
[INFO] Running com.acme.app.AppTest
[ERROR] com.acme.app.AppTest.runs -- Time elapsed: 0.087 s <<< ERROR!
java.lang.NoSuchMethodError: 'java.lang.String com.acme.Text.whisper(java.lang.String)'
	at com.acme.Core.quiet(Core.java:3)
	at com.acme.Http.get(Http.java:3)
	at com.acme.app.App.run(App.java:8)
[ERROR] BUILD FAILURE

notice the build compiled. App never calls whisper() itself, core-lib does, and core-lib was compiled long ago against 2.0. javac had no way to know. this is why dependency conflicts surface as NoSuchMethodError, NoClassDefFoundError or AbstractMethodError in production instead of compile errors.

the enforcer plugin from the previous section makes maven refuse to build when versions diverge:

[ERROR] Dependency convergence error for com.acme:text-utils:jar:1.0. Paths to dependency are:
[ERROR] +-com.acme:app:jar:1.0-SNAPSHOT
[ERROR]   +-com.acme:json-lib:jar:1.0:compile
[ERROR]     +-com.acme:text-utils:jar:1.0:compile
[ERROR] and
[ERROR] +-com.acme:app:jar:1.0-SNAPSHOT
[ERROR]   +-com.acme:http-lib:jar:2.0:compile
[ERROR]     +-com.acme:core-lib:jar:2.0:compile
[ERROR]       +-com.acme:text-utils:jar:2.0:compile