Declaring a dependency and its scope
A dependency is a library the project uses, named by the same four coordinates a project has. Maven finds it in the local repository, adds it to the class paths of the build, and records it so that a project which depends on this one depends on the library too. The <scope> element says which class paths: the same dependency declared without a scope and declared as a test dependency behave differently, and the difference is one compile error away.
A dependency
Three coordinates and a version. The project below uses JUnit Jupiter, the test library of the JUnit 5 course, because it is the only library in the local repository of this image besides what Maven itself needs. The class under src/main/java imports it on purpose: the main code is where the difference between the two declarations shows.
src/main/java/com/example/deps/Main.java
package com.example.deps;
import org.junit.jupiter.api.Test;
public class Main {
public static void main(String[] args) {
System.out.println(Test.class.getSimpleName());
}
}
Without a scope
A dependency without a scope element has the scope compile, which is the widest of the six: it is on the class path of the code, of the tests and of the run. The main class compiles:
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>deps</artifactId>
<version>1.0.0</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>21</maven.compiler.release>
<junit.version>5.14.3</junit.version>
</properties>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>${junit.version}</version>
</dependency>
</dependencies>
</project>
mvn -B compile > compile.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" compile.log
status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:deps >--------------------------
[INFO] Building deps 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ deps ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ deps ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
dependency:tree prints the graph the project resolves, one line per artifact, with the scope at the end of each line:
mvn -B dependency:tree
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:deps >--------------------------
[INFO] Building deps 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ deps ---
[INFO] com.example:deps:jar:1.0.0
[INFO] \- org.junit.jupiter:junit-jupiter:jar:5.14.3:compile
[INFO] +- org.junit.jupiter:junit-jupiter-api:jar:5.14.3:compile
[INFO] | +- org.opentest4j:opentest4j:jar:1.3.0:compile
[INFO] | +- org.junit.platform:junit-platform-commons:jar:1.14.3:compile
[INFO] | \- org.apiguardian:apiguardian-api:jar:1.1.2:compile
[INFO] +- org.junit.jupiter:junit-jupiter-params:jar:5.14.3:compile
[INFO] \- org.junit.jupiter:junit-jupiter-engine:jar:5.14.3:runtime
[INFO] \- org.junit.platform:junit-platform-engine:jar:1.14.3:runtime
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
Seven lines for one dependency, because a dependency has dependencies of its own: the API, the parameters module, the engine, and the three jars every JUnit module needs. They are transitive dependencies, and the next article is about them.
The scopes are already interesting here. The API, the parameters module and their dependencies are compile, because they are what the code calls. The engine is runtime, because it runs tests and nothing compiles against it. Neither scope is written in this pom: both come from the pom of junit-jupiter itself, which declares its engine as a runtime dependency.
As a test dependency
Now the same dependency with <scope>test</scope>. The main class is unchanged, and it no longer compiles, because the library is not on the main class path:
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>deps</artifactId>
<version>1.0.0</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>21</maven.compiler.release>
<junit.version>5.14.3</junit.version>
</properties>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
mvn -B clean compile > broken.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" broken.log
status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:deps >--------------------------
[INFO] Building deps 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ deps ---
[INFO] Deleting <project>/target
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ deps ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ deps ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] <project>/src/main/java/com/example/deps/Main.java:[3,29] package org.junit.jupiter.api does not exist
[ERROR] <project>/src/main/java/com/example/deps/Main.java:[7,28] cannot find symbol
symbol: class Test
location: class com.example.deps.Main
[INFO] 2 errors
[INFO] -------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile (default-compile) on project deps: Compilation failure: Compilation failure:
[ERROR] <project>/src/main/java/com/example/deps/Main.java:[3,29] package org.junit.jupiter.api does not exist
[ERROR] <project>/src/main/java/com/example/deps/Main.java:[7,28] cannot find symbol
[ERROR] symbol: class Test
[ERROR] location: class com.example.deps.Main
[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.api does not exist is the compiler saying that the import is not on the class path it was given. The dependency is resolved, downloaded and in the local repository; it is simply not on this class path, because a test dependency belongs to the test compile and the test run. Move the same import into a class under src/test/java and it compiles there; the test phase article shows that class.
The tree says the same thing in its last column, and it says it for every transitive artifact too:
mvn -B dependency:tree
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:deps >--------------------------
[INFO] Building deps 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ deps ---
[INFO] com.example:deps: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-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] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
The six scopes
A scope decides which class paths an artifact joins, and whether a project that depends on this one inherits it. The five that a project declares, and the sixth that only a pom in dependencyManagement uses:
- compile is the default. On the class path of the main code, the tests and the run, and passed on to any project that depends on this one.
- provided is on the class path of the main code and the tests, and not at run time: the library is expected from the container or the JDK. A servlet API is the classic case. A project that depends on this one does not inherit it.
- runtime is not on the compile class path, only on the test and run class paths: a JDBC driver, or an implementation behind an interface the code compiles against.
- test is on the test compile and test run class paths only, and is not inherited: JUnit, an assertion library, a mocking library.
- system is a file on this machine, named by an absolute path, with no repository involved. It exists for the JDK itself and for nothing else; a project that uses it cannot be built on another machine.
- import appears only inside <dependencyManagement> of a pom dependency: it takes the dependency list of that pom and adds it to the management of this one. The BOM article is about it.
Two more things about scopes are worth remembering, because they explain lists of jars that look too long. A transitive dependency takes the scope its parent gives it, and the nearest declaration of an artifact wins when two paths reach it; the conflict article makes that visible. And a scope does not change what the jar contains: a jar never carries its dependencies, whatever their scope. A jar with a dependency needs a class path, which is why the package article runs this project with java -cp.
Where to go next
Transitive dependencies reads the seven lines of the tree one by one, and the conflict article shows what happens when two paths bring two versions of the same artifact.
Article author: Arthur Isaev