Maven & Project Basics

A POM (Project Object Model) is declarative XML: it describes the project and its build inputs; it is not a shell script that runs from top to bottom. Maven combines this file with inherited parent settings, imported dependency management, plugin defaults, profiles, and repository metadata to create the effective POM that the build actually uses.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<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">
  <!-- The POM model schema, not the Maven version used to run the build -->
  <modelVersion>4.0.0</modelVersion>

  <!-- Project coordinates: group, artifact, and version (GAV) -->
  <groupId>com.example</groupId>
  <artifactId>task-api</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>

  <!-- Reusable values; a property matters only where a plugin or element reads it -->
  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.12.2</junit.version>
  </properties>

  <!-- Adds libraries to this project's classpath -->
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <!-- Plugins perform build work such as compiling and testing -->
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.2</version>
      </plugin>
    </plugins>
  </build>
</project>

The standard layout is part of this model: Maven compiles src/main/java, copies src/main/resources, compiles tests from src/test/java, and writes generated output under target/. A plugin can change these conventions, but changing them early makes every IDE, CI job, and example harder to follow.

A dependency coordinate points Maven to an artifact repository. That artifact may declare its own dependencies, producing a transitive graph. Maven selects versions using dependency mediation and dependency management; it does not load every version side by side. When runtime code reports NoSuchMethodError, inspect the resolved graph because compilation and runtime may have selected incompatible classpaths.

Each dependency entry contributes one declared edge to the graph. Its groupId and artifactId identify the artifact, version selects it unless dependency management supplies one, and scope controls which classpaths can see it.

Spring Boot adds a curated dependency platform to the plain Maven model. The spring-boot-starter-parent parent is a convenience option: its version is the Spring Boot release, and it contributes Boot dependency management plus useful Maven defaults and plugin management. A parent is inherited configuration; it is not a dependency placed on the application classpath.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.5.16</version>
  <relativePath/> <!-- resolve from repositories, not ../pom.xml -->
</parent>

<properties>
  <java.version>21</java.version>
</properties>

<dependencies>
  <!-- Version is intentionally omitted: Boot's managed set supplies it. -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
</dependencies>

<build>
  <plugins>
    <!-- The parent manages this plugin version; the declaration enables repackaging. -->
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

A project that already needs another parent can import the Boot BOM instead. This keeps Boot library version alignment while leaving parent inheritance available for the project’s own parent. In that arrangement, configure and pin build-plugin versions explicitly because a dependency BOM manages libraries, not Maven plugins.

1
2
3
4
5
6
7
8
9
10
11

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.5.16</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

1
2
3
4

./mvnw help:effective-pom > effective-pom.xml
./mvnw dependency:tree -Dverbose
./mvnw dependency:tree -Dincludes=org.springframework
./mvnw help:evaluate -Dexpression=spring-boot.version -q -DforceStdout

A lifecycle phase is a milestone. Invoking a later phase runs the preceding phases in order: verify includes compilation, test compilation, and tests before final verification. A plugin goal is a concrete task bound to a phase or invoked directly. dependency:tree is a goal; test and package are lifecycle phases. This distinction makes build output predictable.

Use the committed Maven Wrapper for these commands so the build tool is pinned in local development and CI. The wrapper pins Maven itself, not the JDK, dependency versions, or external services.

1
2
3
4

./mvnw --version
./mvnw clean verify
./mvnw dependency:tree
jar tf target/task-api-0.0.1-SNAPSHOT.jar | head

A classic production outage occurs when two transitive dependencies pull incompatible versions of the same core library, resulting in a runtime NoSuchMethodError.

1
2
3
4
5

[INFO] com.example:task-api:jar:0.0.1-SNAPSHOT
[INFO] +- com.lib.a:library-a:jar:1.0.0:compile
[INFO] |  \- com.fasterxml.jackson.core:jackson-databind:jar:2.14.0:compile
[INFO] \- com.lib.b:library-b:jar:2.0.0:compile
[INFO]    \- (com.fasterxml.jackson.core:jackson-databind:jar:2.18.2:compile - omitted for conflict with 2.14.0)

java.lang.NoSuchMethodError: 'com.fasterxml.jackson.databind.ObjectMapper.readerFor(java.lang.Class)'
    at com.lib.b.Parser.parse(Parser.java:42)
    at com.example.tasks.TaskService.load(TaskService.java:18)

Maven uses the Nearest-Definition Rule: the version closest to the root project wins. Because library-a happened to be declared first, the older 2.14.0 version won, starving library-b of methods introduced in 2.18.0.

The definitive solution is Maven <dependencyManagement> or importing the Spring Boot BOM (spring-boot-dependencies), which forces a single convergent version across the entire transitively resolved graph.

When a class is missing, first determine whether the dependency was never declared, excluded, placed in the wrong scope, or absent from the packaged artifact. When two paths bring the same library, dependency:tree -Dverbose reveals the selected and omitted versions. Changing a random version may hide the immediate symptom while breaking the compatibility set elsewhere.

1
2
3
4

./mvnw dependency:tree
./mvnw dependency:tree -Dincludes=org.junit.jupiter
./mvnw help:effective-pom
./mvnw clean verify

The primary Module 0 path is now Maven end to end: pom.xml, the Maven Wrapper, target/ output, and Maven lifecycle commands. Gradle remains a useful alternative build tool, but comparing it belongs after the Maven model is stable rather than inside the core exercise.