Building with Maven

Relevant source files

The following files were used as context for generating this wiki page:

• complete/pom.xml
• complete/mvnw
• complete/mvnw.cmd
• initial/pom.xml
• test/run.sh
• README.adoc

This project utilizes Apache Maven as its build automation and dependency management tool. The build is configured through the pom.xml file and executed using the Maven Wrapper (mvnw), which ensures a consistent build environment without requiring a manual Maven installation. The project is structured as a standard Spring Boot application, leveraging parent POMs and starters for simplified configuration.

The build process compiles the Java source code, runs tests, and packages the application into an executable JAR file. This is orchestrated by the Spring Boot Maven Plugin, which is a core component of the build configuration.

Sources: README.adoc, complete/pom.xml, test/run.sh

Project Object Model (pom.xml)

The pom.xml file is the core of the Maven build configuration. It defines the project's coordinates, dependencies, properties, and build plugins.

Sources: complete/pom.xml, initial/pom.xml

The following diagram illustrates the key sections of the pom.xml file.

Parent POM

The project inherits from the spring-boot-starter-parent. This parent POM provides sensible default configurations for a Spring Boot application, including dependency management for common libraries and default settings for plugins like the spring-boot-maven-plugin.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

Sources: complete/pom.xml:6-11

Project Properties

The pom.xml defines project-specific properties. A key property is the Java version, which is set to 17.

<properties>
    <java.version>17</java.version>
</properties>

Sources: complete/pom.xml:17-19

Dependencies

The project declares its dependencies within the <dependencies> block. The core dependencies are Spring Boot "starters," which simplify dependency management by providing curated sets of transitive dependencies.

Group ID	Artifact ID	Scope	Description
org.springframework.boot	spring-boot-starter-web	compile	Provides dependencies for building web applications, including RESTful applications, using Spring MVC. It includes Tomcat as the default embedded container.
org.springframework.boot	spring-boot-starter-test	test	Provides dependencies for testing Spring Boot applications with libraries like JUnit 5, Mockito, and Spring Test.

Sources: complete/pom.xml:20-31

Build Configuration

The <build> section configures the build process. It includes the spring-boot-maven-plugin, which is essential for packaging the application as an executable JAR. This plugin also allows the application to be run directly from Maven.

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Sources: complete/pom.xml:33-40

Maven Wrapper

The project includes the Maven Wrapper, which consists of scripts (mvnw for Linux/macOS and mvnw.cmd for Windows) that ensure a user can build the project with a specific version of Maven without having to install it manually.

Sources: complete/mvnw, complete/mvnw.cmd

Wrapper Execution Flow

When a wrapper script is executed, it performs the following steps:

1. Validates Environment: Checks if the JAVA_HOME environment variable is set and points to a valid JDK installation.
2. Locates Wrapper JAR: Searches for the maven-wrapper.jar in the .mvn/wrapper/ directory.
3. Downloads Wrapper JAR: If the JAR is not found, it downloads it from the URL specified in .mvn/wrapper/maven-wrapper.properties. The Windows script uses PowerShell for the download.
4. Executes Maven: Invokes the MavenWrapperMain class from the downloaded JAR, passing all command-line arguments to it. This effectively runs the Maven build.

The following flowchart shows the execution logic of the mvnw.cmd script.

Environment Variables

The wrapper scripts can be configured using several optional environment variables.

Variable	Description
JAVA_HOME	Required. Specifies the location of the JDK.
MAVEN_OPTS	Optional parameters passed to the Java VM when running Maven.
MAVEN_BATCH_ECHO	Set to 'on' to enable echoing of batch commands (Windows).
MAVEN_BATCH_PAUSE	Set to 'on' to wait for a key press before the script ends (Windows).

Sources: complete/mvnw.cmd:26-35

Building and Running the Application

The Maven Wrapper is used to execute standard Maven goals. The test/run.sh script demonstrates a typical build sequence.

Common Build Commands

• Clean and Compile: This command cleans the project (deletes the target directory) and compiles the source code.

  ./mvnw clean compile
  

  Sources: test/run.sh:4

• Clean and Package: This command cleans the project and packages it into an executable JAR file in the target directory. This is the most common command to create a distributable artifact.

  ./mvnw clean package
  

  Sources: test/run.sh:16

• Run the Application: The spring-boot-maven-plugin allows you to run the application directly.

  ./mvnw spring-boot:run
  

  Sources: README.adoc

The following sequence diagram illustrates the developer's interaction with the Maven Wrapper to build the project.