Comprehensive Maven Tutorial: Basic Configuration, Dependency Management, Module Setup, Plugin Usage, and Build Settings

Hello, I am a senior architect. If you have development experience, you have probably struggled with managing JAR files in the lib directory and dealing with compatibility issues by manually downloading different versions.

Maven dramatically reduces this overhead by handling project building and dependency management, allowing developers to focus on business logic.

Maven is a project management tool that can build Java projects and manage their dependencies.

1. Basic Configuration

1. Repository Configuration

Maven introduces the concept of repositories. When you publish a JAR to a repository, other developers can declare the dependency in their POM and Maven will first download it from the central repository to the local repository, then the project reads from the local repository.

Organizations often set up private repositories that are checked before the central repository.

By using repositories, developers no longer need to manually manage JAR files, improving efficiency.

2. Basic Information

A minimal Maven project should contain the following three elements to identify a module: groupId , artifactId , and version .

Example definition:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    <!-- Fixed 4.0.0, specifies the POM model version -->
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>xyz.ibudai</groupId>
    <artifactId>maven-demo</artifactId>
    <version>1.0.0‑SNAPSHOT</version>
    <description>This is maven demo.</description>
</project>

2. Dependency Management

1. Adding Dependencies

Use the dependencies tag to import required libraries.

<dependencies>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql‑connector‑java</artifactId>
        <version>8.0.27</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

The possible values for scope are shown in the following image.

2. Transitive Dependencies

When a project depends on another module, Maven automatically resolves its transitive dependencies. You only need to declare the direct dependency; Maven will pull in the required indirect ones.

Dependency order follows a “first declared, first imported” rule, and Maven selects the appropriate version based on hierarchy and declaration order.

3. Excluding Dependencies

If version conflicts arise, you can exclude unwanted transitive dependencies using the excludes tag.

<dependencies>
    <dependency>
        <groupId>xyz.ibudai</groupId>
        <artifactId>demo‑a</artifactId>
        <version>1.0.0</version>
        <excludes>
            <exclude>
                <groupId>xyz.ibudai</groupId>
                <artifactId>dependency‑b</artifactId>
                <version>1.0.0</version>
            </exclude>
        </excludes>
    </dependency>
</dependencies>

You can also use the optional tag to prevent a dependency from being transitively passed to downstream modules.

4. Variable Configuration

To manage versions centrally, define properties and reference them with ${} placeholders.

<properties>
    <mysql.version>8.0.30</mysql.version>
    <junit.version>4.13.2</junit.version>
</properties>

<dependencies>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql‑connector‑java</artifactId>
        <version>${mysql.version}</version>
    </dependency>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>${junit.version}</version>
    </dependency>
</dependencies>

3. Module Configuration

1. Module Management

When a project contains multiple sub‑modules, use the modules tag to list them.

<!-- maven‑demo pom.xml -->
<modules>
    <module>module‑1</module>
    <module>module‑2</module>
</modules>

2. Module Inheritance

Specify a parent POM with the parent tag; child modules inherit the parent’s groupId , artifactId , and version unless overridden.

<parent>
    <groupId>xyz.ibudai</groupId>
    <artifactId>maven‑demo</artifactId>
    <version>1.0‑SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
</parent>

<artifactId>module‑1</artifactId>

4. Unified Management

1. Centralized Dependency Management

Define common dependencies in the parent’s dependencyManagement section; child modules only need to declare the dependency without version.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql‑connector‑java</artifactId>
            <version>8.0.30</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.13.2</version>
        </dependency>
    </dependencies>
</dependencyManagement>

2. Module Example

Module‑1 inherits the parent’s dependency management and adds only the MySQL dependency; the version is taken from the parent.

<dependencies>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql‑connector‑java</artifactId>
    </dependency>
</dependencies>

Module‑2 similarly inherits and adds JUnit.

<dependencies>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
    </dependency>
</dependencies>

5. Plugin Management

1. Jar Plugin

The maven‑jar‑plugin allows you to customize the JAR’s manifest.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven‑jar‑plugin</artifactId>
    <version>2.3.1</version>
    <configuration>
        <archive>
            <manifest>
                <mainClass>org.example.MyTest</mainClass>
                <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
            </manifest>
            <manifestEntries>
                <Plugin‑Id>demo‑plugin</Plugin‑Id>
                <Plugin‑Version>1.0.0</Plugin‑Version>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>

2. Assembly Plugin

The maven‑assembly‑plugin can package the project together with all its dependencies into a single JAR.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven‑assembly‑plugin</artifactId>
    <version>3.1.0</version>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar‑with‑dependencies</descriptorRef>
        </descriptorRefs>
        <finalName>${project.artifactId}-${project.version}-all</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <attach>false</attach>
        <archive>
            <manifest>
                <mainClass>fully.qualified.MainClass</mainClass>
                <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
            </manifest>
        </archive>
    </configuration>
    <executions>
        <execution>
            <id>make‑assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

3. Shade Plugin

The maven‑shade‑plugin creates an uber‑JAR with optional class relocation and filtering.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven‑shade‑plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <minimizeJar>true</minimizeJar>
        <artifactSet>
            <includes>
                <include>com.fasterxml.jackson.core:jackson‑core</include>
            </includes>
        </artifactSet>
        <relocations>
            <relocation>
                <pattern>com.fasterxml.jackson.core</pattern>
                <shadedPattern>com.ibudai.fasterxml.jackson.core</shadedPattern>
            </relocation>
        </relocations>
        <filters>
            <filter>
                <artifact>*:*</artifact>
                <excludes>
                    <exclude>META‑INF/license/**</exclude>
                    <exclude>META‑INF/*</exclude>
                    <exclude>LICENSE</exclude>
                    <exclude>NOTICE</exclude>
                </excludes>
            </filter>
        </filters>
    </configuration>
</plugin>

6. Build Configuration

1. JDK Version

Specify the Java version used for compilation.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven‑compiler‑plugin</artifactId>
    <version>3.1</version>
    <configuration>
        <source>8</source>
        <target>8</target>
    </configuration>
</plugin>

2. Resource Exclusion

Exclude configuration files (e.g., application.yml ) from the packaged JAR.

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <excludes>
            <exclude>application.yml</exclude>
        </excludes>
    </resource>
</resources>

3. Main Class

Define the entry point for the JAR using the mainClass configuration.

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring‑boot‑maven‑plugin</artifactId>
    <configuration>
        <mainClass>xyz.ibudai.TestWebApplication</mainClass>
        <layout>JAR</layout>
    </configuration>
</plugin>

By following the above steps, you can efficiently manage dependencies, modules, plugins, and build settings in Maven‑based Java backend projects.