The multi-module reactor

A parent pom with a <modules> list is a reactor: one command builds every module of the list, in an order that Maven works out from the dependencies between them, and the whole run is one build with one result. The modules share the parent’s properties and versions, so a version change is one line. This article builds three modules that depend on each other and reads the order out of the log.

The parent and its modules

The parent is the pom of the previous article plus a module list, and it manages the version of the two modules as well as the one of JUnit, so the children declare their dependencies without a version:

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <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.shop</groupId> <artifactId>shop-parent</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <modules> <module>library</module> <module>service</module> <module>app</module> </modules> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> <junit.version>5.14.3</junit.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>com.example.shop</groupId> <artifactId>library</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example.shop</groupId> <artifactId>service</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> </dependencyManagement> </project>

library

The module nobody depends on: a record with two methods and a pom of four lines.

library/pom.xml

<?xml version="1.0" encoding="UTF-8"?> <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> <parent> <groupId>com.example.shop</groupId> <artifactId>shop-parent</artifactId> <version>1.0.0</version> </parent> <artifactId>library</artifactId> </project>

library/src/main/java/com/example/shop/library/Price.java

package com.example.shop.library; public record Price(long cents) { public Price plus(Price other) { return new Price(cents + other.cents); } public String format() { return "%d.%02d".formatted(cents / 100, cents % 100); } }

service

The module that uses the library, and the first one Maven has to order:

service/pom.xml

<?xml version="1.0" encoding="UTF-8"?> <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> <parent> <groupId>com.example.shop</groupId> <artifactId>shop-parent</artifactId> <version>1.0.0</version> </parent> <artifactId>service</artifactId> <dependencies> <dependency> <groupId>com.example.shop</groupId> <artifactId>library</artifactId> </dependency> </dependencies> </project>

service/src/main/java/com/example/shop/service/Checkout.java

package com.example.shop.service; import com.example.shop.library.Price; public class Checkout { public Price total(int items, long centsEach) { if (items <= 0) { throw new IllegalArgumentException("no items"); } return new Price(items * centsEach); } }

app

The module a person runs: it uses the service, and it is the only one with a test.

app/pom.xml

<?xml version="1.0" encoding="UTF-8"?> <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> <parent> <groupId>com.example.shop</groupId> <artifactId>shop-parent</artifactId> <version>1.0.0</version> </parent> <artifactId>app</artifactId> <dependencies> <dependency> <groupId>com.example.shop</groupId> <artifactId>service</artifactId> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> </dependency> </dependencies> </project>

app/src/main/java/com/example/shop/app/ShopApp.java

package com.example.shop.app; import com.example.shop.library.Price; import com.example.shop.service.Checkout; public class ShopApp { public static void main(String[] args) { Checkout checkout = new Checkout(); Price total = checkout.total(3, 250); System.out.println("total: " + total.format()); } }

app/src/test/java/com/example/shop/app/ShopAppTest.java

package com.example.shop.app; import static org.junit.jupiter.api.Assertions.assertEquals; import com.example.shop.service.Checkout; import org.junit.jupiter.api.Test; class ShopAppTest { @Test void threeItemsAtTwoFifty() { assertEquals("7.50", new Checkout().total(3, 250).format()); } }

The reactor build

One command from the folder of the parent builds the four projects: the parent itself, which produces nothing, and the three modules. Maven prints the order it chose before it starts, and then builds them with a counter:

mvn -B package > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] shop-parent [pom]
[INFO] library [jar]
[INFO] service [jar]
[INFO] app [jar]
[INFO]
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ library ---
[INFO] Recompiling the module because of <REASON>.
[INFO] shop-parent ........................................ SUCCESS [<TIME>]
[INFO] library ............................................ SUCCESS [<TIME>]
[INFO] service ............................................ SUCCESS [<TIME>]
[INFO] app ................................................ SUCCESS [<TIME>]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

The order is not the order of the <modules> list by accident: service needs library and app needs service, so the list happens to be a valid order and Maven keeps it. Written in another order, the same three modules would be sorted the same way, and a cycle between them stops the build before it starts with The projects in the reactor contain a cyclic reference.

[2/4] and the rest of the counter count the projects of the reactor, the parent included. The modules are not read from the local repository during this build: the reactor resolves com.example.shop:library from the library/target/classes it has just built, which is why mvn package is enough and no install is needed before app compiles.

-pl, -am and one module

-pl narrows a reactor build to the projects it names, by folder or by coordinates. -am adds the projects those need ("also make"), so the order stays valid:

mvn -B -pl app -am package > app.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" app.log

status: 0
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] shop-parent [pom]
[INFO] library [jar]
[INFO] service [jar]
[INFO] app [jar]
[INFO]
[INFO] shop-parent ........................................ SUCCESS [<TIME>]
[INFO] library ............................................ SUCCESS [<TIME>]
[INFO] service ............................................ SUCCESS [<TIME>]
[INFO] app ................................................ SUCCESS [<TIME>]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Without -am the same command would fail on app, because service is neither in the reactor nor in the local repository of the modules that were not installed. With -pl library alone the build is one project and the counter disappears, which is the shortest way to compile one module:

mvn -B -pl library package > one.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" one.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------< com.example.shop:library >----------------------
[INFO] Building library 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ library ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ library ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Three more switches belong to the same family. -amd is "also make dependents", the opposite of -am: it adds the projects that depend on the one named, which is how a change in a library is tested against everything that uses it. -rf resumes a build from a project after a failure, which is useful when the failing module is at the end. And -T builds the reactor with more than one thread, which is safe only when the modules do not write to the same file.

Where to go next

The next article installs this reactor into the local repository and uses one of its jars from a project that is not in it, which is how two teams share a library without sharing a checkout.

Article author: Arthur Isaev