Post

Creating and Managing Multi-Module Projects in Maven

Posted
By Alexander Chuev
4 min read

Introduction

Maven is a powerful tool for managing Java projects, and one of its key features is support for multi-module projects. Multi-module projects allow you to manage complex systems by breaking them into smaller, manageable sub-projects or modules. This article explores what multi-module projects are, why they are beneficial, how to set up Maven for multi-module projects, and how to manage dependencies between modules.

What Multi-Module Projects Are

A multi-module project is a Maven project that consists of a main project (often referred to as the “parent” project) and several sub-projects (modules). Each module can be a separate Maven project with its own pom.xml file, but all modules are organized under a single parent project.

Benefits of Multi-Module Projects:

  1. Organizational Clarity
    They help organize complex systems into smaller, more manageable pieces, making it easier to understand and work with large codebases.
  2. Build Management
    A single command can build all modules, ensuring that changes in one module are reflected across the entire project.
  3. Dependency Management
    Common dependencies can be managed at the parent level, reducing redundancy and ensuring consistency.
  4. Modular Development
    Different teams can work on different modules independently, facilitating parallel development and improving collaboration.

Setting Up Maven to Work with Multiple Modules

Before setting up a multi-module project, you first need to create a Maven project that will act as the parent. This parent project will manage child modules, allowing them to share configurations and dependencies.

Step 1: Create the Parent Project

  1. Navigate to the Project Directory
    Open a terminal or command prompt and navigate to the directory where you want to create the project. For example: 
    1

    cd /path/to/your/projects
  2. Create the Parent Project
    Use the following Maven command to create a new parent project: 
    1

    mvn archetype:generate -DgroupId=com.example -DartifactId=parent-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

    This will create a Maven project with groupId: com.example, artifactId: parent-project, and packaging: jar by default.

  3. Modify the Parent pom.xml
    Navigate into the newly created parent-project directory: 
    1

    cd parent-project

    Modify the pom.xml file of the parent project to act as a packaging POM:

    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    <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>parent-project</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging> <!-- This makes it a parent project -->
       
    <modules>
        <!-- Add child modules here later -->
    </modules>
</project>

Step 2: Create Child Modules

  1. Create the Child Module
    In the parent-project directory, create a child module using the following Maven command: 
    1

    mvn archetype:generate -DgroupId=com.example -DartifactId=child-module-a -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
  2. Add the Parent Section
    After creating the child module, you need to modify the child module’s pom.xml to reference the parent POM. Add the following <parent> section to the top of the child module’s pom.xml: 
    1
2
3
4
5
6
7
8
9
10
11

    <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/POM/4.0.0>">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0-SNAPSHOT</version>
  </parent>
  <artifactId>child-module-a</artifactId>
</project>
  3. Update the Parent pom.xml
    Add the module to the parent-project's pom.xml file by including it in the <modules> section: 
    1
2
3

    <modules>
    <module>child-module-a</module>
</modules>
  4. Create Additional Child Modules
    Repeat the process to create additional child modules, updating the <modules> section each time: 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    <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/POM/4.0.0>">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>parent-project</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>
    
  <modules>
    <module>child-module-a</module>
    <module>child-module-b</module>
  </modules>
</project>

Step 3: Build the Multi-Module Project

After setting up the parent and child modules, you can build the entire project by running the following command from the root of the parent-project:

1

mvn clean install

This will build all child modules in the correct order.

Managing Dependencies Between Modules

Managing dependencies between modules in a multi-module project is straightforward with Maven. Here’s how you can handle it:

  1. Declare Module Dependencies
    If one module depends on another, declare this dependency in the dependent module’s pom.xml. For example, if child-module-b depends on child-module-a, then module-b/pom.xml will look like:

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    <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/POM/4.0.0>">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>parent-project</artifactId>
    <version>1.0-SNAPSHOT</version>
  </parent>
  <artifactId>child-module-b</artifactId>
    
  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>child-module-a</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
</project>

    In this example, maven will resolve this dependency and ensure that child-module-a is built before child-module-b.

  2. Use Dependency Management
    You can use the <dependencyManagement> section in the parent pom.xml to manage versions and scopes of dependencies across modules. This ensures consistency and reduces duplication.

    An example of parent-project/pom.xml:

    1
2
3
4
5
6
7
8
9

    <dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>child-module-a</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
</dependencyManagement>

    This section centralizes dependency versions, avoiding the need to specify versions in each sub-module.

  3. Build the Entire Project
    Use Maven commands to build the entire multi-module project. Running mvn clean install from the parent project’s directory will build all modules in the correct order, taking care of dependencies between them.

Conclusion

Multi-module projects in Maven provide a robust framework for managing complex Java applications by breaking them down into smaller, more manageable components. By setting up a parent project and individual sub-modules, you can achieve better organization, streamlined builds, and efficient dependency management. Understanding and leveraging these capabilities allows you to handle large-scale projects effectively, ensuring consistency and reducing development overhead.

maven
Maven
© 2024 Java Tutorial Online. All rights reserved.