Maven from Scratch: Coordinates, Dependency Mediation and Build Lifecycles

Maven does exactly one job: you write down what you need in a shopping list (pom.xml), and it fetches, processes and packs accordingly. You never need to know which corner of the disk a jar lives in, nor hand-assemble a compile command — you just write a coordinate (organization + module + version) and let it handle the rest. This article covers four things: who you are (coordinates) → what you need (dependencies and scopes) → where to fetch (repositories and mirrors) → how to process (lifecycles and multi-module builds).

After this article you should be able to answer:

• Why does one pom.xml rebuild the project on another machine, while a hand-copied javac -cp line cannot?
• If two paths drag in two versions of the same library, which one wins — and can I overrule it?
• What does each of the five words in mvn clean package -DskipTests actually trigger? Is test code still compiled?

Start with the world before build tools. You write three classes and compile them with one line:

javac follows the imports and compiles the classes it depends on. But a real project has two hundred source files and a dozen third-party libraries, and the command balloons into this:

And that is only "compile". "Run the tests", "build the jar", "deploy to the server" each repeat this manual work. This is exactly what a build tool fixes: turning resolve, compile, test, package and deploy into one repeatable, declarative, machine-independent pipeline.

Maven is the most classic and most widely used tool on that pipeline. The fundamental difference from raw javac is what it trusts:

• Raw javac trusts a local path — lib/xxx.jar must physically exist on disk
• Maven trusts a coordinate — you declare org.springframework:spring-core:6.1.0 and it fetches the file from a repository itself
• So moving machines needs only one pom.xml, with no dependence on anyone's local setup

That diagram is the skeleton of this article: top-left is the coordinate (GAV) used to identify one artifact; bottom-left is the repository system that decides where to fetch it; the two columns on the right are lifecycles and plugins, which decide what happens to it afterwards. Every section below just zooms into one of those boxes.

Maven itself is a zip: unzip it and add bin to PATH; it also needs a JAVA_HOME pointing at a JDK:

mvn -v prints the Maven version, the JDK it actually uses, and the OS — the first thing to check when "Maven is using the wrong JDK".

By default Maven downloads from the overseas central repository (repo.maven.apache.org), which is often slow enough to time out inside China. The fix is a mirror. Here is the point beginners confuse most: settings.xml has two locations, with completely different scopes.

Here is a complete user-level ~/.m2/settings.xml, ready to copy:

Once downloaded, dependencies are cached locally, so builds work offline. Three switches are worth memorizing:

• -o (offline): force offline, using only the local repo — good for air-gapped machines or checking cache completeness
• -U (update-snapshots): force a check for SNAPSHOT updates, essential for team work
• -X (debug): print full debug logs; turn it on and you see exactly which URL Maven is requesting

That "once a day" is the only number here you can actually drag, and it is the most common invisible time lag in a team. Treat it as a knob: on the left you change the repository's <updatePolicy> (expressed in minutes), on the right you get the symptoms that setting produces in a real project:

Every artifact in Maven is uniquely located by a coordinate set, GAV for short:

Resolution order is: local repository → private repo (if configured) → central. Each hit back-fills the cache layer by layer: the private repo caches the public artifact, then your local repo caches the private one. The second build barely touches the network.

The easiest field to misuse, and the one that plants the nastiest mines, is scope. It determines whether a dependency is visible when compiling main code, compiling tests, and at runtime.

Here is the full six-scope table — worth bookmarking:

This sandbox links all three dimensions live — switch the scope to see the difference:

That table has six rows, and the one thing everybody forgets while copying a pom is the scope itself. Do not copy — tick it out. Every checkbox in this generator emits the scope its dependency actually belongs to, and explains below why that one:

What you declare directly is a direct dependency; what it declares gets passed on to you as a transitive dependency. The trouble is that several paths can pull in different versions of the same library, and Maven must pick one — this is dependency mediation.

The "only one may stay" clause bites hardest when both candidates sit at the same depth. Switch to "version conflict" and you can swap the order in which two dependencies are written in pom.xml and watch the winner flip — which is why "I added a dependency, touched no code, and everything broke":

For example, the project declares A and C:

That is the entire heart of Maven mediation. Understand it and you can predict the result of mvn dependency:tree before running it.

To knock a transitive version out, use <exclusions>:

Conversely, a library author who wants to stop one of its dependencies from propagating uses <optional>true</optional>:

Pick the wrong version and the code usually blows up at runtime, not compile time. Two commands are the main tools:

A typical dependency:tree output, where indentation is path depth:

Here is a real NoSuchMethodError: you call a writeValueAsBytes overload that only Jackson 2.16 has, but the runtime classpath actually holds 2.15:

"Confirm the version first" is far too easy to turn into a slogan. Spread that dependency tree out as a single-step run: on the left, the candidates Maven collects; on the right, the depth table as it fills in and who brought whom. Step through it and watch step 4 — Maven picks the closest, not the newest:

Maven has three independent lifecycles, each made of ordered phases; running a later phase automatically runs the earlier ones:

A phase itself is an empty shell; the work is done by plugin goals bound to it — Maven's single most important design:

Those two tables add up to eleven rows, but reading and knowing are different things: you have to click. This diagram splits one mvn package into five boxes — each one says who is doing the work and what breaks if you skip it:

Those two facts — "a later phase drags the earlier ones" and "calling a goal directly skips steps" — are the parts Maven interviews get wrong most often. This lab is built for exactly that; cycle through the four modes in order:

A common command is really a combination of phases; unpack it one flag at a time:

As a project grows, a single pom becomes thousands of lines. Maven splits it with two orthogonal ideas: aggregation builds everything together, inheritance shares configuration.

The parent POM does both aggregation and inheritance:

A child module simply inherits the parent and declares its dependencies (versions come from the parent):

Aggregation is often mistaken for "build in directory order"; in reality Maven sorts by the dependency graph. This animation splits one mvn install into six frames — look at frames 5 and 6: downstream modules read what was just installed into the local repository, so "I changed common but web still behaves the old way" is never cache superstition. It simply never read your new class:

Section 7 listed the three lifecycles, but "phases" stay abstract. This animation walks one dependency from being written into pom.xml all the way to sitting on the runtime classpath. Watch step 4 (mediation) and step 6 (scope decides whether it ships) — they correspond to Sections 5 and 4:

The second lab here answers "what actually changes when I edit a scope". Press the four buttons and watch the same jar's visibility across "compiling main code / compiling tests / packaging", including why a JDBC driver marked provided looks perfectly fine locally and collapses the moment it reaches production:

The third lab answers a question every beginner asks: why does the plain jar produced by mvn package refuse to run with java -jar. A fatjar puts dependencies under BOOT-INF/lib and reads them with a custom class loader — which ties straight back to the classpath lesson in article #1:

The fourth lab goes back to the two most treacherous rules of Section 7. Calling a goal directly skips every earlier phase (so you package stale classes), and several goals bound to one phase queue up in the order they are written in the pom. Press all four modes, but especially the third:

One last cross-article trap: the JDK Maven uses is not necessarily the java on your terminal. The Java version printed by mvn -v is the one your build really runs on, and this mode shows how it gets picked on a machine with several JDKs:

Enough buttons — time to type. This console is wired to the same in-browser kernel and every reply is computed there. Start with lab mvnlife phases, then work down the list:

You already know the rules (nearest wins, then first declared). What is hard is what to do after the verdict. Pick the shape of the conflict on the left, pick your remedy on the right, and the panel shows the resulting dependency:tree plus a risk rating:

That NoSuchMethodError row is the chapter's signature "Maven did nothing wrong and you still broke" scene. The stack below is real — do not read the answer, just click the frame you believe is guilty:

Goal: manufacture a version conflict deliberately, then resolve it three different ways and feel the difference.

Run it and record the output:

Expected shape (indentation is depth; the loser is marked omitted):

Now add code using an API that only 1.2 has, and observe what breaks at compile time versus runtime. Then try each remedy in turn: declare the version directly, add an <exclusion> to the first dependency, pin it in dependencyManagement — verifying every attempt with the same dependency:tree command.

Done when: you can explain in your own words what each of the three fixes actually changed, and why the third one suits a team.

1. Swap the declaration order of the two dependencies and arrange them at equal depth (add one more intermediate dependency). You will observe the winning version flipping with the order — the fragility of letting line order decide runtime behaviour.
2. Change commons-logging's scope to provided, run mvn package, then java -jar. You will observe NoClassDefFoundError at startup while the build stays completely green.
3. In ~/.m2/settings.xml, change mirrorOf from central to * and build a project that needs a private repo. You will observe Could not find artifact ... (without a private repo, reproduce the request-path change with an obscure Central-only coordinate).

Tip: after variant 1, revisit the "equal depth" column of the Section 12 sandbox — the conclusion becomes obvious.

Create a three-module project that exercises every concept in this article:

Requirements: ① the parent manages versions in dependencyManagement and children never write <version>; ② at least one child uses <exclusions> with a comment saying why; ③ mvn clean install at the root passes; ④ mvn dependency:tree contains no omitted for conflict; ⑤ lab-web configures spring-boot-maven-plugin and produces a jar that java -jar runs directly.

Acceptance checklist: on a fresh machine (or after deleting the entire ~/.m2/repository), a single mvn clean install rebuilds everything identically — that, and only that, is a reproducible build.