Maven Multi-Module Projects

Introduction

As Java applications grow, they often need to be split into multiple modules (e.g., API layer, service layer, database layer).
Managing each module as a separate Maven project can become painful.

This is where Maven multi-module projects come in.
They allow you to structure and manage multiple related modules under a single parent project, making builds more consistent and efficient.

In this lesson, we’ll cover:

• Parent POM and child modules
• Aggregator vs inheritance in Maven
• A complete multi-module project setup

1. Parent POM and Child Modules

A parent POM acts as the central configuration point for all modules.

• It defines common dependencies, plugins, and properties.
• Each child module inherits these settings, reducing duplication.

Example: Parent POM (pom.xml)

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <!-- Modules declaration -->
    <modules>
        <module>service</module>
        <module>api</module>
        <module>database</module>
    </modules>

    <!-- Shared dependency management -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter</artifactId>
                <version>3.1.0</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

</project>

Example: Child Module POM (service/pom.xml)

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <parent>
        <groupId>com.example</groupId>
        <artifactId>my-app</artifactId>
        <version>1.0.0</version>
    </parent>

    <modelVersion>4.0.0</modelVersion>
    <artifactId>service</artifactId>

    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>api</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</project>

📌 Here, the parent POM manages dependencies, and child modules inherit them.

2. Aggregator vs Inheritance

Multi-module projects often involve two related but different concepts:

✅ In practice, most multi-module projects use both aggregator and inheritance in the parent POM.

3. Example: Multi-Module Project Setup

Let’s build a simple employee management system with three modules:

• api → Defines REST endpoints
• service → Business logic layer
• database → Handles persistence

Directory Structure

my-app/
│
├── pom.xml (Parent POM - aggregator + inheritance)
├── api/
│   └── pom.xml
├── service/
│   └── pom.xml
└── database/
    └── pom.xml

Build Commands

• Build all modules at once: mvn clean install.
• Build only one module (e.g., service): mvn clean install -pl service.
• Build one module and its dependencies: mvn clean install -pl service -am.

Why Use Multi-Module Projects?

• Consistency → Centralized dependency management
• Efficiency → Build only what changed, not the entire project
• Modularity → Easier to maintain and scale large applications
• CI/CD Friendly → Optimized for pipelines where modules can be built independently

Key Takeaways

• Multi-module projects use a parent POM to manage configuration and dependencies.
• Aggregator (modules list) + Inheritance (shared settings) = Clean, maintainable structure.
• Builds can be run at parent level or for specific modules.