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

If you have some development experience, you have probably struggled with manually downloading and replacing JAR files in the lib directory, especially when dealing with compatibility issues. Maven dramatically reduces this preparation work by handling dependency resolution automatically.

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.xml and Maven will first try to download it from the central repository to the local repository, then use the local copy for the build.

Organizations often set up private repositories that are consulted before the central one, providing an additional layer of control.

2. Basic Information

A minimal Maven project contains the three coordinates groupId , artifactId , and version . Below is a simple pom.xml example:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    <!-- Fixed 4.0.0, the version of the POM model -->
    <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 declare required libraries. Example:

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

The scope element can be compile , provided , runtime , test , or system .

2. Transitive Dependencies

Maven resolves transitive dependencies automatically. If Dependency‑A depends on Dependency‑B , which in turn depends on Dependency‑C , you only need to declare Dependency‑A in your project; Maven will pull in Dependency‑B and Dependency‑C as needed.

3. Excluding Dependencies

When version conflicts arise, you can exclude unwanted transitive dependencies using the excludes tag:

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

Alternatively, you can mark a dependency as optional to prevent it from being transitively propagated.

4. Property Variables

Define version numbers or other values in a properties section and reference them with ${...} to keep versions consistent across the project.

<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

Multi‑module projects use the modules tag to list sub‑projects:

<modules>
    <module>module-1</module>
    <module>module-2</module>
</modules>

2. Module Inheritance

Each sub‑module can inherit common configuration from a parent POM using the parent element. The parent’s groupId , artifactId , and version are inherited automatically, and relativePath points to the parent’s pom.xml (default ../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 Dependency Management

1. Dependency Management Section

Define common dependency versions in the parent’s dependencyManagement block. Sub‑modules only need to declare the dependency without a version; Maven will inherit the version from the parent.

<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

Both module-1 and module-2 inherit the versions defined in maven-demo and can add their own dependencies without repeating version numbers.

5. Plugin Management

1. Maven Jar Plugin

The maven-jar-plugin allows you to customize the JAR’s META-INF/MANIFEST.MF file, for example by setting the main class and adding custom entries.

<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 create an "uber JAR" that bundles all runtime dependencies together.

<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 also creates an uber JAR but offers more fine‑grained control, such as selective inclusion, package relocation, and file 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. Java Version

Specify the JDK version used for compilation with the maven-compiler-plugin :

<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 so they can be modified without rebuilding:

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

3. Main Class Configuration

Define the entry point of the JAR using the spring-boot-maven-plugin (or any other plugin) to set <mainClass> :

<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 these steps, you can efficiently manage dependencies, organize multi‑module projects, and customize the build output using Maven’s powerful plugin ecosystem.