Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 41 ยท Dependencies

Transitive Dependencies and Mediation

See how Maven pulls in transitive dependencies, how nearest-wins and first-declaration pick one version, and how exclusions and optional dependencies change the graph.

When you add one library, you rarely get one JAR. A JSON library may need a text utility, which may need a character-data library. You did not ask for those, yet your code can end up running with them. These are transitive dependencies: the dependencies of your dependencies, discovered by reading each library's own POM.

Transitivity is why Maven is so convenient, and also why dependency problems happen. Two libraries may need different versions of a third one, and only one version can be on the classpath. Maven settles this with a fixed set of rules called mediation. If you know the rules, version surprises stop being mysterious.

Maven cannot run in the browser, so commands and POM snippets here are read-only. The two runnable programs are Java stand-ins: the first applies the mediation rule to a list, the second is a small resolver with exclusions and optional dependencies. They follow the same rules as Maven, but they are written for teaching and are not Maven's real code.

Direct and transitive

A direct dependency is one you wrote in your own <dependencies>. A transitive dependency is anything reached through another dependency's POM. The whole thing is a tree (more precisely a graph, since the same library can be reached through different paths).

flowchart TD
    app["my-app"] --> A["lib-a 1.0"]
    app --> B["lib-b 1.0"]
    A --> X2["x 2.0"]
    B --> C["lib-c 1.0"]
    C --> X1["x 1.0"]

Two paths lead to library x, asking for different versions. Maven has to pick one.

You can print the tree for your own project with mvn dependency:tree. Each level of indentation is one more hop away from your project. That distance is called the depth of the dependency. In the diagram, lib-a has depth 1, and x 2.0 has depth 2 while x 1.0 has depth 3.

The mediation rules

When the same artifact (same groupId and artifactId) appears more than once with different versions, Maven applies two rules in order:

Rule 1, nearest wins

Count the hops Depth from your project to the library.
Closest path wins The version at the lowest depth is used.
Others dropped The farther versions never reach the classpath.

Maven does not pick the highest version.

1 / 2

The big surprise is that "newest wins" is not a rule. If a library you depend on needs x 2.0 through a long chain and an older library asks for x 1.0 directly, x 1.0 is used, even though it is older. In the diagram above, x 2.0 is closer (depth 2), so it wins and the x 1.0 branch is dropped.

Here is the rule applied to a list. Every row is one place where x was requested. Notice that the tie between the last two rows is settled only by order.

Java Nearest wins, then first declared

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Case 3 shows the simplest fix when you disagree with Maven: declare the library yourself. A direct dependency has depth 1, so nothing can be closer. The next lesson shows a cleaner tool for this, dependencyManagement.

Seeing the decision: dependency:tree

The normal mvn dependency:tree shows only the winners. To see what lost and why, add -Dverbose:

Terminal
mvn dependency:tree -Dverbose
TEXT
[INFO] com.example:my-app:jar:1.0
[INFO] +- lib:a:jar:1.0:compile
[INFO] |  \- lib:x:jar:2.0:compile
[INFO] \- lib:b:jar:1.0:compile
[INFO]    \- lib:c:jar:1.0:compile
[INFO]       \- (lib:x:jar:1.0:compile - omitted for conflict with 2.0)

Read the last line as: "something asked for x 1.0 here, but Maven kept 2.0, so this branch was omitted." You will use this output heavily in Diagnosing Dependency Conflicts.

Exclusions

Sometimes you do not want a transitive dependency at all: it conflicts with something else, it is a second copy of a logging framework, or it is simply unused. An <exclusion> removes it from the subtree of one dependency:

XML
<dependency>
  <groupId>lib</groupId>
  <artifactId>lib-d</artifactId>
  <version>1.0</version>
  <exclusions>
    <exclusion>
      <groupId>lib</groupId>
      <artifactId>x</artifactId>
    </exclusion>
  </exclusions>
</dependency>

An exclusion names groupId and artifactId but never a version. It applies only below the dependency where you wrote it, so the same library may still arrive through another path. Maven 3.2.1 and later accept wildcards, for example <groupId>*</groupId><artifactId>*</artifactId> to cut off everything below a dependency, which is handy when you know a library is fully shaded or you will supply its pieces yourself.

Use exclusions sparingly. Each one is a promise that the library still works without that code, and nothing checks the promise except your tests.

Optional dependencies

A library author can mark a dependency as optional:

XML
<dependency>
  <groupId>lib</groupId>
  <artifactId>y</artifactId>
  <version>1.0</version>
  <optional>true</optional>
</dependency>

This says: "I need y for a feature of my own, but I do not want to force it on people who depend on me." The library itself is built with y on its classpath, but projects that depend on it do not receive y transitively. If you want that feature, you add y to your own POM. Libraries use this for integrations: a web framework may mark its Jackson support optional so that it does not drag in a JSON library for users who never use it.

If you see a feature fail with ClassNotFoundException, check whether the class comes from an optional dependency you must add yourself.

A mini resolver

The program below implements the rules from this lesson: breadth-first search by depth, declaration order as the tie-breaker, exclusions and optional dependencies. It prints a verbose-style tree and the final list for five scenarios using the same small repository. The libraries are made up.

Study how the scenarios change the result, then edit them. For example, reverse the order of the first two declarations in scenario 2.

Java A mediation resolver with exclusions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In scenario 1, only x 2.0 survives, because it is closer. In scenario 2 and 2b, the same two libraries give different results purely because of declaration order. That fragility is a good reason to manage versions explicitly instead of relying on the tie-break.

Practical advice

  • Look at the tree (mvn dependency:tree -Dverbose) whenever a library surprises you. Do not guess.
  • Prefer pinning a conflicting library with dependencyManagement (next lesson) over rearranging dependencies.
  • Exclude carefully, and write a comment saying why.
  • Do not re-declare every transitive library "to be safe". Declare what your code imports, and let Maven do the rest.
  • Remember that a newer version is not automatically chosen. If you need a fix released in a later version, you must request it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Library x is requested at depth 2 as version 2.0 and at depth 3 as version 1.0. Which version does Maven use?

    Nearest wins. Depth is what counts, not the version number, so x 2.0 at depth 2 beats x 1.0 at depth 3.
  2. 2. Two paths request different versions of x, both at depth 2. What decides the result?

    On a tie in depth, the first declaration wins. That is why reordering dependencies can change the resolved version.
  3. 3. What does an exclusion on a dependency do?

    Exclusions name groupId and artifactId, and apply only below the dependency where they are declared. The library may still arrive via another path.
  4. 4. Library L declares dependency y as optional. You depend on L. Do you get y?

    Optional dependencies are used to build L but are not passed on to its consumers.
  5. 5. Which option shows the versions that were omitted because of conflicts?

    The verbose flag keeps the losing branches in the output, labelled omitted for conflict.

Summary

  • Transitive dependencies are the dependencies of your dependencies, discovered from their POMs.
  • When versions of one artifact clash, nearest wins. A tie is broken by first declaration. Newest does not win.
  • Declaring a library directly (depth 1) or managing its version overrides the default choice.
  • An exclusion removes a library below one dependency. An optional dependency is not passed on to consumers.
  • mvn dependency:tree -Dverbose shows what was kept and what was omitted.

Next: Managing Versions: dependencyManagement and BOMs