Checkpoint Lab — Maven Dependencies, Scopes, Transitive Resolution, Exclusions, Optional Dependencies, and Classpaths

1. Checkpoint scenario and acceptance contract

You are preparing scope-app for a production-style CI handoff. The build must explain every dependency edge and every runtime assumption. Reuse the producer/consumer model from Lesson 2 or recreate it from the supplied files. No hosted repository or paid service is required.

CHECKPOINT ACCEPTANCE
[ ] wrapper/Maven/JDK identities recorded
[ ] isolated local repository recorded
[ ] >= 4 ordinary scopes represented: compile, runtime, provided, test
[ ] >= 1 transitive exclusion represented
[ ] >= 1 optional producer edge represented
[ ] dependency tree captured
[ ] compile/runtime/test classpaths captured
[ ] two predictions written before changes
[ ] runtime-only H2 probe verified
[ ] one deliberate scope-related runtime failure captured
[ ] failure diagnosed from graph/classpath evidence
[ ] least-destructive repair verified
[ ] unnecessary coupling reviewed/removed
[ ] cleanup affects only disposable lab state

2. Preflight — record identities before the graph

Do not start by editing the POM. Record the execution environment and wrapper state first.

cd maven-scope-lab
REPO="$PWD/.lab-m2/repository"
DEP=org.apache.maven.plugins:maven-dependency-plugin:3.11.0
mkdir -p checkpoint-evidence

./mvnw --version | tee checkpoint-evidence/maven-version.txt
java -version 2> checkpoint-evidence/java-version.txt
cp .mvn/wrapper/maven-wrapper.properties checkpoint-evidence/wrapper.properties
sha256sum optional-feature-lib/pom.xml scope-app/pom.xml   > checkpoint-evidence/pom-input-sha256.txt
printf 'localRepository=%s
' "$REPO" > checkpoint-evidence/repository.txt

Assumptions: Maven 3.9.16, Wrapper 3.3.4, Dependency Plugin 3.11.0, JDK 21, Java release 17. If your wrapper or Maven runtime differs, stop and update the evidence/compatibility analysis rather than pretending the version does not matter.

3. Draw and predict the graph before resolving

The intended graph is:

flowchart LR
  A[scope-app]
  F[optional-feature-lib 1.0.0]
  C[commons-codec 1.17.1]
  T[commons-text 1.10.0]
  L1[commons-lang3 transitive request]
  L2[commons-lang3 3.17.0 direct]
  H[H2 2.3.232 runtime]
  S[Servlet API 6.1.0 provided]
  J[JUnit Jupiter 5.13.4 test]
  A -->|compile| F
  F -. optional .-> C
  A -->|compile| T
  T -. excluded .-> L1
  A -->|compile| L2
  A -->|runtime| H
  A -->|provided| S
  A -->|test| J

Prediction A:
  commons-codec will NOT appear in scope-app's resolved consumer tree,
  because optional-feature-lib marks that dependency optional.

Prediction B:
  jakarta.servlet-api will appear in compile/test classpath evidence,
  but NOT in the Maven runtime classpath.

Prediction C:
  H2 will appear in runtime/test classpath evidence but not compile.

Prediction D:
  commons-lang3 3.17.0 will be the intentional direct edge;
  the commons-text -> commons-lang3 transitive path is excluded.

At least two predictions are mandatory. Writing them first prevents post-hoc explanations that merely restate whatever Maven happened to print.

4. Install the producer into only the isolated repository

The optional producer must exist as an ordinary Maven coordinate so the consumer reads its installed POM metadata.

./mvnw -Dmaven.repo.local="$REPO" -f optional-feature-lib/pom.xml clean install   | tee checkpoint-evidence/producer-install.log

find "$REPO/dev/academy/optional-feature-lib/1.0.0" -maxdepth 1 -type f -print   | tee checkpoint-evidence/producer-installed-files.txt

grep -n -A5 -B3 '<optional>true</optional>'   "$REPO/dev/academy/optional-feature-lib/1.0.0/optional-feature-lib-1.0.0.pom"   | tee checkpoint-evidence/optional-metadata.txt

install is deliberately local. It proves consumer metadata behavior without remote repository credentials or mutable publishing infrastructure.

5. Build and capture dependency/classpath evidence

Run tests, capture the resolved tree, then generate classpath projections. Store evidence outside scope-app/target when you want it to survive clean.

./mvnw -Dmaven.repo.local="$REPO" -f scope-app/pom.xml clean test   | tee checkpoint-evidence/app-test.log

./mvnw -Dmaven.repo.local="$REPO" -f scope-app/pom.xml "$DEP":tree   -DoutputFile=target/dependency-tree.txt
cp scope-app/target/dependency-tree.txt checkpoint-evidence/dependency-tree.txt

for scope in compile runtime test; do
  ./mvnw -Dmaven.repo.local="$REPO" -f scope-app/pom.xml     "$DEP":build-classpath -DincludeScope="$scope"     -Dmdep.outputFile="target/${scope}.cp"
  cp "scope-app/target/${scope}.cp" "checkpoint-evidence/${scope}.cp"
done

# POSIX-only display helper:
for f in checkpoint-evidence/{compile,runtime,test}.cp; do
  echo "--- $f ---"
  tr ':' '
' < "$f"
done

6. Verify the predictions independently

grep -q 'optional-feature-lib' checkpoint-evidence/dependency-tree.txt
grep -q 'commons-codec' checkpoint-evidence/dependency-tree.txt   && echo 'FAIL: optional dependency unexpectedly propagated'   || echo 'PASS: optional dependency absent'

grep -q 'jakarta.servlet-api' checkpoint-evidence/compile.cp
grep -q 'jakarta.servlet-api' checkpoint-evidence/runtime.cp   && echo 'FAIL: provided dependency in runtime CP'   || echo 'PASS: provided dependency absent from runtime CP'

grep -q '/h2-' checkpoint-evidence/runtime.cp
grep -q '/h2-' checkpoint-evidence/compile.cp   && echo 'FAIL: runtime dependency in compile CP'   || echo 'PASS: H2 absent from compile CP' 

7. Verify normal and runtime-only behavior

Run the normal application and H2 runtime probe using only target/classes plus the generated runtime dependency classpath.

CP="scope-app/target/classes:$(cat checkpoint-evidence/runtime.cp)"
java -cp "$CP" dev.academy.App Academy   | tee checkpoint-evidence/app-runtime.txt
java -cp "$CP" dev.academy.DbProbe   | tee checkpoint-evidence/h2-runtime.txt

hello Academy / feature-core
h2-runtime-present

8. Inject one scope-related runtime failure

The application contains ContainerOnlyEndpoint, compiled against the Servlet API in provided scope. A plain JVM is intentionally not a servlet container. Try to load that class with the Maven runtime classpath and preserve the failure.

set +e
java -cp "$CP" dev.academy.ContainerOnlyEndpoint   > checkpoint-evidence/provided-failure.out   2> checkpoint-evidence/provided-failure.err
status=$?
set -e
printf 'exit=%s
' "$status" | tee checkpoint-evidence/provided-failure.status
sed -n '1,20p' checkpoint-evidence/provided-failure.err

# Confirm the missing provider is consistent with the runtime CP:
grep -q 'jakarta.servlet-api' checkpoint-evidence/runtime.cp   && echo 'unexpected: servlet API present'   || echo 'expected: servlet API absent' 

Diagnosis: this is not a broken Maven build. The class was compiled under a provided-dependency contract and then launched outside the provider environment. The correct repair depends on architecture: either run/test it inside the compatible servlet container that owns the API, or—if the component is actually standalone—change the application dependency/packaging model so it supplies the required runtime library.

9. Repair deliberately and verify the changed contract

For this training checkpoint, choose the architectural statement explicitly. Assume the component is intended to be standalone, not container-hosted. Change only the Servlet API dependency from provided to ordinary compile scope (remove the <scope>provided</scope> element). Then predict: the runtime classpath will gain jakarta.servlet-api; the dependency tree coordinate/version will remain; a plain JVM will get past the missing-superclass failure and then report that the class has no main method.

# Edit only scope-app/pom.xml: remove the servlet dependency's provided scope.
./mvnw -Dmaven.repo.local="$REPO" -f scope-app/pom.xml clean compile
./mvnw -Dmaven.repo.local="$REPO" -f scope-app/pom.xml "$DEP":build-classpath   -DincludeScope=runtime -Dmdep.outputFile=target/runtime-repaired.cp
cp scope-app/target/runtime-repaired.cp checkpoint-evidence/runtime-repaired.cp

grep 'jakarta.servlet-api' checkpoint-evidence/runtime-repaired.cp

CP2="scope-app/target/classes:$(cat checkpoint-evidence/runtime-repaired.cp)"
set +e
java -cp "$CP2" dev.academy.ContainerOnlyEndpoint   > checkpoint-evidence/repaired-load.out   2> checkpoint-evidence/repaired-load.err
status=$?
set -e
printf 'exit=%s
' "$status"
sed -n '1,12p' checkpoint-evidence/repaired-load.err

# Expected change: no NoClassDefFoundError for HttpServlet.
# A "main method not found" message is acceptable evidence that class loading passed.

In a real servlet application, the opposite repair could be correct: keep provided and fix the deployment/test environment. The checkpoint scores the reasoning and evidence, not a universal preference for compile scope.

10. Remove unnecessary coupling while preserving behavior

Review the graph rather than deleting random dependencies. Two examples:

• If scope-app never uses DigestFeature, leave Commons Codec absent. Do not add it “just in case.”
• If source no longer imports Commons Lang after refactoring to only Commons Text APIs, remove the direct Lang declaration and re-evaluate whether the exclusion is still necessary. If source still imports StringUtils, keep the direct dependency.

Every removal must be followed by clean test, dependency-tree comparison, runtime probes, and—where relevant—artifact/security evidence. A smaller graph is valuable only when behavior remains correct.

11. Verification checklist

12. Cleanup and rollback

Keep checkpoint-evidence only if you want the learning record. Cleanup must not touch normal Maven settings, wrapper distributions outside the lab, or ~/.m2/repository.

cd ..
pwd
ls -la maven-scope-lab

# Optional: copy maven-scope-lab/checkpoint-evidence somewhere safe.
rm -rf maven-scope-lab

Knowledge check

13. What Chapter 06 adds to a production build-engineering model

• Dependency ownership: direct source/API requirements are declared directly.
• Classpath contracts: compile, runtime, provided, and test visibility are independently inspectable.
• Graph governance: exclusions are path-specific and optional edges are consumer-boundary decisions.
• Deployment awareness: provided scope moves responsibility to an external runtime that must be tested.
• Diagnostic discipline: model → tree → classpath → runtime evidence precedes corrections or cache experiments.
• Supply-chain discipline: repository/cache availability is distinct from trust, vulnerability, and provenance.

Chapter 07 builds on this resolved model by examining Maven plugins, lifecycle bindings, plugin configuration/executions, and plugin management—the executable code that turns Maven phases into concrete work.

Official references and version notes

Version-sensitive statements in this lesson were checked against Apache Maven primary documentation on 2026-08-23. Required labs use Maven 3.9.16 through Maven Wrapper 3.3.4, Maven Dependency Plugin 3.11.0 for graph/classpath inspection, JDK 21 to run Maven, and Java 17 as the application release target. Maven 4.0.0-rc-6 remains preview-stage and is not required here.

Checkpoint scope projections use Maven Dependency Plugin 3.11.0. Maven’s dependency documentation is the authority for transitivity/scope behavior; plugin includeScope is used only to materialize classpath views.

• Maven — Introduction to the Dependency Mechanism
• Maven — Optional Dependencies and Dependency Exclusions
• Maven — Dependency and Repository Model
• Maven — POM Reference
• Maven Dependency Plugin 3.11.0 — Usage
• Maven Dependency Plugin 3.11.0 — Plugin Details
• Maven Dependency Plugin — dependency:tree
• Maven Dependency Plugin — dependency:build-classpath
• Maven Releases History
• Apache Maven Wrapper