Understanding Maven Dependency Mediation (Part 2)

In my last post I talked about how Maven mediates conflicts in the dependency tree in probably the vast majority of all builds. This default algorithm somehow surprisingly ignores the actual version number of the declared dependencies. Instead, it uses the distance to the root of the dependency tree as a basis for the decision, which dependencies make it into the build.

Now, I'm going to cover another approach of how Maven can handle conflicts in the transitively resolved dependencies. Maven switches to this alternative algorithm, as soon as it detects a concrete version number for one of the dependencies that are involved in a conflict. In my last post I explained already, that version numbers without any decoration are considered to be a recommendation. Maven may or may not follow this recommendation. In contrast to this, if you put square brackets around the version in your dependency declaration, Maven assumes you mean it. That is, now you have defined an exact version of a given dependency. If Maven is not able to deliver the desired version(s) to your build, it will generate an appropriate error and fail.

Just as a side note: The syntax for concrete versions allows much more variants than only defining one specific version. In short, it supports the following definitions:

* [A]: Defines one specific version A
* [A,B]: Defines a range of versions from A to B (inclusive)
* [A,]: Defines a range from A (inclusive) upwards
* [,A]: Defines a range up to A (inclusive)

Instead of square brackets, you can use round brackets to define a version range exclusive the delimiting versions. For example, [A,B) defines a range from A (inclusive) up to B (exclusive).

Now, let's see what happens if a concrete version pops up in the dependency tree. Honestly, I didn't find a real example, because concrete versions are used very seldom. So I constructed a hypothetical sample that is based on the ones of my last post. It assumes that someone introduced a concrete version number range in the POM of commons-logging. The range defines that commons-logging needs Log4J in a version between 1.2.12 and 1.2.16 (inclusive). Our sample project itself references this hypothetical version of commons-logging and Log4J V1.2.11.

If we execute this build, Maven decides that Log4J 1.2.16 must be included. This is in contrast to the examples in my last post, when Maven decided in all cases that Log4J V1.2.11 is the "right one" for the build. The point is, that this different behavior of Maven is not triggered by the POM of our sample project, but by the POM of commons-logging. We're not in control of this POM, someone else changed it and suddenly we end up with a different Log4J version in our build.

So why did this happen? Maven detected a conflict in the dependency tree. We requested Log4J V1.2.11, commons-logging requested a different range of Log4J versions. Now, since commons-logging used a concrete number range, the default algorithm is skipped. Instead, Maven actually looks at the values of the conflicting versions. First, it tries to find an overlapping range of all defined concrete versions. In our case this is simple, there is just one such concrete version range. Now, Maven checks if the nearest recommended version number fits into the found overlapping version range. If it does fit into the range, Maven selects the recommended version. In our case, it doesn't (V1.2.11 doesn't fit into [1.2.12,1.2.16]). If this happens, Maven selects the biggest version of the range. In our sample, this is V1.2.16.

What would happen, if the version range is [1.2.11,1.2.16]? In this case, Maven would select Log4J V1.2.11, because now the recommended version in our POM fits in the concrete range [1.2.11,1.2.16] defined in commons-logging. And what would happen, if we define a concrete version [1.2.11] in our POM and commons-logging would define [1.2.12,1.2.16]? In this case, the build will fail, because there is no overlapping version number range.

After reading all this stuff, you might come to the conclusion that all dependency versions should be defined using concrete version numbers. IMO, this is one of two valid options. The other one is to make use of the POM section dependencyManagement. Instead of defining the versions directly at the dependencies, you can define them below the element dependencyManagement in your POMs. Maven guarantees that all versions you define in this section are actually used for your build. In the example above, you get Log4J V1.2.11. The concrete version number range defined in commons-logging is ignored. The backdraft of this approach is obvious: You get your desired version, but you don't get a notification that an unresolved conflict exists in the dependency tree.

Understanding Maven Dependency Mediation (Part 1)

One of the most powerful features of Maven is certainly the management of dependencies. As far as I know, the lack of dependency management in other well-established build tools was actually one of the reasons to start development of Maven. The whole dependency management stuff relies on the fact that people declare all required dependencies for their project explicitly in the POM file. Maven reads this information and decides which jars must be loaded from the repositories and so on. Most of you know all this stuff well, so I won't repeat the basics here again.

However, sometimes the dependency management thing in Maven seems to have a "bad day". Unknown jars pop up in your war file or Maven uses a completely wrong version for your build process. If things like this happen, it is likely that a mechanism called dependency mediation decided to screw up your well-defined list of dependencies. Let's take a look at that beast.

As you know, Maven resolves all required jars for your build transitively from the entries in your POM. For example, if you define a dependency to commons-logging and commons-logging itself defines a dependency to log4j, the commons-logging.jar and log4j.jar will be added to your build process. More formally spoken, transitiveness means that if A->B and B->C then A->C. Transitive dependencies are very cool and they are the prerequisite that really all classes required by your project end up in the classpath, war or whatever.

However, transitive dependencies don't come for free. One of the problems Maven is faced with are conflicts in the dependency tree. The image shows such a conflict. The sample project defines two direct dependencies: One to commons-logging-1.1 and one to log4j-1.2.13. Now, because Maven transitively loads all dependencies that are defined for commons-logging-1.1, a second version of log4j (V1.2.12) pops up in the dependency tree. If this happens, the mechanism called dependency mediation kicks in. Its job is to decide which of the two log4j versions must be used for the build process. In the shown example, log4j-1.2.13 will be selected. But why?

A first, simple explanation would be that V1.2.13 is newer (larger) than 1.2.12 and that's why Maven uses it. To verify if this is true, we can perform a simple test: We change the version of our dependency to log4j from 1.2.13 to 1.2.11. Now, if our explanation is correct, Maven should select log4j-1.2.12 for the build. Try it in one of your projects, Maven still uses V1.2.11 of Log4J. Obviously the actual value of the version had no effect on the dependency mediation.

In fact, Maven knows several strategies to resolve conflicts in the dependency tree. In the above example, the most commonly used and simplest strategy has been chosen. It is triggered, if the dependency in your POM looks like this:

<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.11</version>
</dependency>

The important thing is the version number. It is stated "as is" without any extra additions (I'll come back to this in a follow-up post). If you define version numbers in this syntax, Maven treats it as a recommended version. So what you're actually doing is to tell Maven "I would prefer V1.2.11 of Log4J, but hey, I can live with any other version, too".

If all versions that are in conflict in your dependency tree have been defined like this, Maven simply chooses the one with the smallest distance from the root of the tree. In our example, log4j-1.2.11 has a distance of 1 to the root and log4j-1.2.12 has a distance of 2. Consequently, Maven chose V1.2.11. The actual value of the version doesn't matter at all. This algorithm is as simple as can be - and it works in almost all cases. This is why Maven in most project situations behaves exactly like you expect it. You get the version you declare in your POM, because your dependencies have always the smallest distance to the root of the dependencies tree.

But beware. Let's say someone in the Apache commons-logging project decides for whatever reason to change the POM of commons-logging like this:

<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>[1.2.12]</version>
</dependency>

Now, commons-logging doesn't define a recommended version 1.2.12 anymore, but a specific one. This is done by simply adding the square brackets around the version number. If this happens you suddenly will end up with log4j-1.2.12 in your build - without actually changing your own dependency to log4j-1.2.11. Confused? I'll explain this behavior soon in a follow-up post.