skip to content

What does the maven-build-cache-extension do, and how does it decide whether to skip rebuilding a module?

level: seniorimportance: nice to knowfreq 20%

answer

  1. content hash of inputs → cache key
  2. hit = restore outputs, skip goals
  3. upstream hashes ripple downstream
  4. config in maven-build-cache-config.xml
  5. false hits from untracked inputs = main risk

basics

~20 s

It caches the outputs of each module keyed by a hash of that module's inputs (source files, POM, dependencies, plugin config). If the hash matches a prior build, Maven restores the cached output (e.g. the jar) instead of recompiling and re-running goals.

solid answer

~50 s

The Apache `maven-build-cache-extension` is a core extension that adds incremental, content-addressed caching to the reactor. For each module it computes a hash over its declared inputs — source/resource files, the effective POM, plugin configurations, and the hashes of upstream modules' outputs. On a build it looks up that key in a local (and optionally shared/remote) cache; on a hit it restores the saved artifacts and skips executing the module's goals entirely, logging a cache hit. On a miss it builds normally and saves the result. You configure what counts as input and which goals are cacheable via `maven-build-cache-config.xml`. Big wins on large multi-module repos and CI where most modules are unchanged. Risks: an incomplete input definition causes false cache hits (stale outputs), so non-deterministic plugins or untracked inputs must be excluded or marked. It complements -T and mvnd.

code

xml · 8 lines
xml
<!-- .mvn/extensions.xml -->
<extensions>
  <extension>
    <groupId>org.apache.maven.extensions</groupId>
    <artifactId>maven-build-cache-extension</artifactId>
    <version>1.2.0</version>
  </extension>
</extensions>

go deeper

for a junior

Knows it skips rebuilding unchanged modules by caching their outputs.

for a middle

Can describe input-hash keys, hits vs misses, and the .mvn/extensions.xml setup.

for a senior

Reasons about false hits, input completeness, and remote/shared caches for CI.

for a principal

Designs cache governance — shared remote cache, what's cacheable, guarding determinism across the org.

## The idea: skip work whose inputs didn't change Maven by itself re-executes a module's goals (compile, test, package…) every build, even if nothing changed. The **maven-build-cache-extension** (an official Apache extension) adds *content-based incremental caching*: if a module's inputs are identical to a previous build, restore the previous outputs instead of redoing the work. ## How the cache key is computed For each module the extension builds a hash from: - the module's **source and resource files** (their content), - the **effective POM** and **plugin configuration**, - the **hashes of upstream modules** it depends on (so a change ripples downstream), - selected **input parameters**. This produces a content-addressed key. Same inputs → same key → cache hit. ## Hit vs miss - **Hit:** the saved artifacts (jar, classes, etc.) are restored and the module's goals are *not run*; the log shows a cache hit. - **Miss:** the module builds normally and its outputs are stored under the new key. ## Local and remote caches The cache can live on the local disk and/or a **shared/remote** store (e.g. an HTTP endpoint or repository), so CI runners and teammates reuse each other's results. ## Configuration You register it as an extension and tune it with `maven-build-cache-config.xml`: which input globs to include/exclude, which goals are cacheable, and how to handle volatile inputs. ```xml <!-- .mvn/extensions.xml --> <extensions> <extension> <groupId>org.apache.maven.extensions</groupId> <artifactId>maven-build-cache-extension</artifactId> <version>1.2.0</version> </extension> </extensions> ``` ## Risks The correctness hinges on the **input definition being complete**. If an input that affects output is not tracked (an env var, generated file, non-deterministic plugin), you get a *false hit* — stale outputs. Exclude or properly model such inputs. Tests with external side effects may also need to be marked non-cacheable. ## How it relates to other tools - **-T:** parallelizes the modules that *do* run. - **mvnd:** reuses the JVM process. - **build cache:** avoids running unchanged modules at all. All three stack.

  • What causes a dangerous 'false cache hit'?
    An input that affects the output but isn't part of the hash — an untracked generated file, an environment variable, or a non-deterministic plugin. Maven restores stale outputs because the key matched. You fix it by adding the input to the config or marking the goal non-cacheable.
  • Why does changing one base module invalidate downstream modules' cache?
    Each module's key includes the hashes of its upstream dependencies' outputs, so a change to a base module changes its hash, which changes every dependent module's key — a correct cache miss cascade.

Like a memoized function: same arguments (inputs) return the stored result instead of recomputing — but only correct if you actually pass every argument that affects the answer.

saying these in an interview costs you the question

  • Confusing the build cache with the ~/.m2 local repository (one caches build outputs by input hash; the other stores downloaded artifacts)
  • Assuming it's safe with non-deterministic builds without configuring inputs
  • Thinking it's enabled by default — it's an opt-in extension

context

resolving links…