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:

<?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

Dependencies are added using the dependencies tag.

<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 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.

<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>

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

<dependencies>
    <dependency>
        <groupId>xyz.ibudai</groupId>
        <artifactId>demo-b</artifactId>
        <version>1.0.0</version>
        <optional>true</optional>
    </dependency>
</dependencies>

4. Variable Configuration

Versions can be centralized using properties and referenced 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

Multiple sub‑projects are managed with the modules tag.

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

2. Module Inheritance

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

<!-- 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>

4. Unified Management

1. Dependency Management

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

<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

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

<parent>
    ...
</parent>

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

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 .

<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>

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 offers more flexible shading and relocation of dependencies, allowing multiple versions of the same library to coexist.

<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. Java Version

The Maven Compiler Plugin specifies the JDK 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

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

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

3. Main Class

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

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

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