Comprehensive Maven Guide: Basic Configuration, Dependency Management, Module Setup, and Plugin Usage

If you have some development experience, you have probably struggled with managing JAR files in the lib directory and dealing with compatibility issues; Maven dramatically reduces this overhead by handling project building and dependency management.

1. Basic Configuration

1. Repository Configuration

Maven introduces the concept of repositories. When a dependency is declared, Maven first downloads it from the central repository to the local repository, and then the project reads from the local repository. Private repositories can be added on top of this process.

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

2. Basic Information

A minimal Maven project should contain the following elements, which are identified by the three tags groupId, artifactId, and version when referencing a module.

Below is a basic definition example:

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><span style="color: rgb(97, 174, 238)"><?xml version="1.0" encoding="UTF-8"?></span>
<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></code>

2. Dependency Management

1. Adding Dependencies

Dependencies are added using the dependencies tag.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><dependencies>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.27</version>
        <scope>runtime</scope>
    </dependency>
</dependencies></code>

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

2. Transitive Dependencies

When a project depends on another module, Maven automatically resolves transitive dependencies. Only the direct dependency needs to be declared; Maven will pull in the required transitive dependencies.

3. Excluding Dependencies

Version conflicts can be resolved using the excludes tag.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

Alternatively, the optional tag can prevent transitive propagation of a dependency.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><dependencies>
    <dependency>
        <groupId>xyz.ibudai</groupId>
        <artifactId>demo-b</artifactId>
        <version>1.0.0</version>
        <optional>true</optional>
    </dependency>
</dependencies></code>

4. Variable Configuration

Versions can be centralized using properties and referenced with ${} placeholders.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

3. Module Configuration

1. Module Management

Multiple sub‑projects are managed with the modules tag.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><!-- maven-demo pom.xml -->
<modules>
    <module>module-1</module>
    <module>module-2</module>
</modules></code>

2. Module Inheritance

Child modules inherit the parent’s configuration using the parent tag; groupId and version are inherited by default.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><!-- module-1 pom.xml -->
<parent>
    <groupId>xyz.ibudai</groupId>
    <artifactId>maven-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
</parent>

<artifactId>module-1</artifactId></code>

4. Unified Management

1. Dependency Management

Common dependencies across modules are defined once in the parent’s dependencyManagement section.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

2. Module Example

Modules inherit the versions defined in the parent without specifying them again.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><parent>
    ...
</parent>

<dependencies>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
    </dependency>
</dependencies></code>

5. Plugin Management

Maven provides a rich set of plugins that extend its capabilities.

1. Jar Plugin

The maven-jar-plugin can add custom entries to the JAR’s META-INF/MANIFEST.MF.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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>
                <manifestEntries>
                    <Plugin-Id>demo-plugin</Plugin-Id>
                    <Plugin-Version>1.0.0</Plugin-Version>
                </manifestEntries>
            </manifest>
        </archive>
    </configuration>
</plugin></code>

2. Assembly Plugin

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

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

3. Shade Plugin

The maven-shade-plugin offers more flexible shading and relocation of dependencies, allowing multiple versions of the same library to coexist.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

6. Build Configuration

1. Java Version

The Maven Compiler Plugin specifies the JDK version used for compilation.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><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></code>

2. Resource Exclusion

Configuration files such as application.yml can be excluded from the JAR.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><resources>
    <resource>
        <directory>src/main/resources</directory>
        <excludes>
            <exclude>application.yml</exclude>
        </excludes>
    </resource>
</resources></code>

3. Main Class

The main class can be set explicitly to avoid runtime launch issues.

<code style="padding: 16px; color: rgb(171, 178, 191); font-family: Consolas, Monaco, Menlo, monospace; font-size: 12px"><plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <mainClass>xyz.ibudai.TestWebApplication</mainClass>
        <layout>JAR</layout>
    </configuration>
</plugin></code>

The article concludes with promotional content unrelated to Maven, which is omitted from the academic summary.