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:
- It fills in a missing version. A dependency without a <version> takes the managed one, and a dependency with no managed version and no version of its own is an error: 'dependencies.dependency.version' ... is missing.
- It overrides a transitive version. This is the part that beats nearest wins: the managed version applies to every path, so an old version reached by a short path and a new one reached by a long path both become the managed one. -Dverbose then shows omitted for conflict with ... against the managed version.
- It changes nothing else. A managed artifact is not added to the project: the block is a table of versions, not a dependency. That is why the BOM import brings seven versions and no jars, and why the tree above has the same artifacts as before.
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