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:

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

Banner image