dependencyManagement and BOMs

dependencyManagement is the answer to the conflict of the previous article: a block of the pom that fixes the version of an artifact for every dependency that names it, direct or transitive, and beats the nearest-wins rule. A BOM is a pom that contains nothing but such a block, which a project imports with scope import. JUnit publishes one, and importing it is how a JUnit project keeps its seven artifacts on one version.

The project

The project of the conflict article, with the pom of the transitive article: one aggregate dependency, one test.

src/main/java/com/example/calc/Calc.java

package com.example.calc; public class Calc { public static int add(int a, int b) { return a + b; } }

src/test/java/com/example/calc/CalcTest.java

package com.example.calc; import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; class CalcTest { @Test void addsTwoNumbers() { assertEquals(4, Calc.add(1, 3)); } }

The JUnit BOM

The BOM is org.junit:junit-bom, packaged as a pom and imported in dependencyManagement. Importing it adds every JUnit artifact at 5.14.3 to the managed versions of this project. The two dependencies below it then need no version at all:

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</groupId> <artifactId>calc</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.junit</groupId> <artifactId>junit-bom</artifactId> <version>5.14.3</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <scope>test</scope> </dependency> </dependencies> </project>

The second dependency is here to ask the question the previous article ended on: a direct declaration used to win, and with a BOM it does not. The tree answers it:

mvn -B dependency:tree

[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ calc ---
[INFO] com.example:calc:jar:1.0.0
[INFO] +- org.junit.jupiter:junit-jupiter:jar:5.14.3:test
[INFO] | +- org.junit.jupiter:junit-jupiter-params:jar:5.14.3:test
[INFO] | \- org.junit.jupiter:junit-jupiter-engine:jar:5.14.3:test
[INFO] | \- org.junit.platform:junit-platform-engine:jar:1.14.3:test
[INFO] \- org.junit.jupiter:junit-jupiter-api:jar:5.14.3:test
[INFO] +- org.opentest4j:opentest4j:jar:1.3.0:test
[INFO] +- org.junit.platform:junit-platform-commons:jar:1.14.3:test
[INFO] \- org.apiguardian:apiguardian-api:jar:1.1.2:test
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

One version, 5.14.3, on all seven artifacts, and the direct declaration is not marked as a conflict at all. dependencyManagement is applied to the graph before the nearest-wins rule runs, so the two paths that used to disagree now agree before they are compared.

The test that now runs

The same test as the failing project, on the same graph with one version:

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

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.calc.CalcTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: <TIME> s -- in com.example.calc.CalcTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

What dependencyManagement does

The block is a list of versions, and it has three effects that are easy to keep apart:

The BOM itself is a pom with <packaging>pom</packaging> whose dependencyManagement lists the versions of one release of a library. Importing it is a merge; a parent pom can import several, and the parent article builds a parent that manages the versions of its own modules. The BOM of JUnit is also the answer to the question of which versions belong together: its 5.14.3 pins jupiter 5.14.3 and platform 1.14.3, which is the pairing the conflict article was missing.

Exclusions

The other way to change a graph is to remove a part of it. <exclusions> names artifacts that a dependency must not bring with it. Here the aggregate may keep everything but the parameterised test module, which a project that does not use it may not want:

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</groupId> <artifactId>calc</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.14.3</version> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-params</artifactId> </exclusion> </exclusions> </dependency> </dependencies> </project>

The test class of this project is a parameterised one, which is what the excluded module is for. Its class does not exist any more, so the test compile fails:

src/test/java/com/example/calc/ParamsTest.java

package com.example.calc; import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.CsvSource; class ParamsTest { @ParameterizedTest @CsvSource({"1, 1, 2", "2, 3, 5"}) void adds(int a, int b, int sum) { assertEquals(sum, a + b); } }

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

status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 2 source files with javac [debug release 21] to target/test-classes
[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[5,32] package org.junit.jupiter.params does not exist
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[6,41] package org.junit.jupiter.params.provider does not exist
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[9,6] cannot find symbol
  symbol: class ParameterizedTest
  location: class com.example.calc.ParamsTest
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[10,6] cannot find symbol
  symbol: class CsvSource
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[9,6] cannot find symbol
[ERROR] symbol: class ParameterizedTest
[ERROR] location: class com.example.calc.ParamsTest
[ERROR] <project>/src/test/java/com/example/calc/ParamsTest.java:[10,6] cannot find symbol
[ERROR] symbol: class CsvSource
[ERROR] location: class com.example.calc.ParamsTest
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException

package org.junit.jupiter.params does not exist is the whole message: the exclusion did what it says. An exclusion is a sharp tool for a real conflict, for a module a library brings and the project replaces, or for a transitive dependency whose license is wrong for the project. Used against a module the code calls, it produces exactly this error, and the tree is the place to see that the module is gone:

mvn -B dependency:tree

[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ calc ---
[INFO] com.example:calc:jar:1.0.0
[INFO] \- org.junit.jupiter:junit-jupiter:jar:5.14.3:test
[INFO] +- org.junit.jupiter:junit-jupiter-api:jar:5.14.3:test
[INFO] | +- org.opentest4j:opentest4j:jar:1.3.0:test
[INFO] | +- org.junit.platform:junit-platform-commons:jar:1.14.3:test
[INFO] | \- org.apiguardian:apiguardian-api:jar:1.1.2:test
[INFO] \- org.junit.jupiter:junit-jupiter-engine:jar:5.14.3:test
[INFO] \- org.junit.platform:junit-platform-engine:jar:1.14.3:test
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Where to go next

The local repository article opens the folder these versions came from, and the parent pom article puts the BOM into a pom that three modules share.

Article author: Arthur Isaev

Banner image