atom feed1 message in org.jdom.jdom-interest[jdom-interest] JDOM artifact 'jdom-l...
FromSent OnAttachments
Rolf LearJun 11, 2012 5:13 am 
Subject:[jdom-interest] JDOM artifact 'jdom-legacy' in maven
From:Rolf Lear (
Date:Jun 11, 2012 5:13:06 am

Hi All.

I am pleased to announce the new JDOM artifact 'jdom-legacy' in maven.

This artifact is introduced to make it possible for maven users to have both JDOM 1.x and 2.x version in their project at the same time.

The Problem: ============

There are three types of JDOM users: - non-maven users - maven users who have a 'simple' dependency chain on JDOM (only require one JDOM version) - maven users with a complicated dependency chain on JDOM (require both 1.x and 2.x JDOM versions).

Non-maven users are completely unaffected by any version/artifact problems, and this is a non-issue for them.

Simple maven dependencies are also easy to handle: maven users (like always) simply choose which version of the jdom artifact to use (1.1.3, 2.0.2, etc.), and these maven users have not been affected by any issues.

The only problem has been for maven users with complicated dependency requirements. The typical condition is for the maven user whio is upgrading their code to use JDOM 2.x, but has a 'transitive dependency' on JDOM 1.x. This happens, for example, when your code uses JDOM 2.x, but you depend on some other maven artifact which in turn depends on JDOM 1.x. In this condition, maven will choose to include just the 2.x version of JDOM, and the program will fail at run-time because the third-party code will not be able to find it's JDOM classes.

The Solution: =============

The solution is to introduce a second maven artifact for JDOM. Maven can then be instructed to pull the second JDOM version of code from the second artifact.

There are effectively two options: either introduce a new artifact for JDOM 2.x code, or alternatively, introduce a new artifact for jdom 1.x code.

In the balance of the options, the better solution is to introduce the new artifact for the 1.x code.

Thus, JDOM 1.1.3 has now also been released as jdom-legacy-1.1.3 :|org.jdom|jdom-legacy|1.1.3|jar

Rationale: ==========

In hindsight, it was a mistake to release JDOM 2.x versions to the existing jdom artifact in maven. With the changed package from org.jdom.* to org.jdom2.*, there should have been a new artifact as well for JDOM 2.x

Unfortunately, this mistake cannot be undone, leaving the maven system in a 'messy' state.

Given all the complicated use-cases of maven users, and given the limited options available for 'correcting' the situation, it comes down to the weighing of pro's and con's and choosing a compromise solution.

for non-maven users: there is no impact

for 'simple case' maven users: there is no impact - they just continue using the 'jdom' artifact the way they always have.

for 'complex case' maven users: the impact is very minimal - all they need to do is add a dependency on 'jdom-legacy'.

Finally, the jdom-legacy solution has a very low risk.

Example - Simple: =================

You have a project you are upgrading to use JDOM 2.x.

All you need to do is change your JDOM dependency to version 2.0.2, pull in the new version with mvn, and fix your code to use the new org.jdom2.* packages.

<dependency> <groupId>org.jdom</groupId> <artifactId>jdom.dep</artifactId> <version>2.0.2</version> </dependency>

Example - Complex: ==================

You are upgrading your project to use 2.x, but you have a dependency on some third-party code which in turn requires JDOM 1.x.

For example your current dependencies may look like (htmlcleaner is a project that has a reference to JDOM 1.1 -|net.sourceforge.htmlcleaner|htmlcleaner|2.2|jar ):

<dependency> <groupId>org.jdom</groupId> <artifactId>jdom</artifactId> <version>1.1.3</version> </dependency> <dependency> <groupId>net.sourceforge.htmlcleaner</groupId> <artifactId>htmlcleaner</artifactId> <version>2.2</version> </dependency>

Now, if you want to upgrade your code to use JDOM 2.x, you would *want* to just change your version dependency from 1.1.3 to 2.0.2 as follows:

<dependency> <groupId>org.jdom</groupId> <artifactId>jdom</artifactId> <version>2.0.2</version> </dependency> <dependency> <groupId>net.sourceforge.htmlcleaner</groupId> <artifactId>htmlcleaner</artifactId> <version>2.2</version> </dependency>

Unfortunately though, your code will fail to compile/run because maven will 'pull' the 2.0.2 version of JDOM, and not 1.1 (the htmlcleaner version) and the htmlcleaner code will be referencing the package org.jdom.* which will not exist (JDOM 2.x has package org.jdom2.*)

The *fix* for this problem is simple: all you need to do is, in your project, to also depend on jdom-legacy:

<dependency> <groupId>org.jdom</groupId> <artifactId>jdom</artifactId> <version>2.0.2</version> </dependency> <dependency> <groupId>org.jdom</groupId> <artifactId>jdom-legacy</artifactId> <version>1.1.3</version> </dependency> <dependency> <groupId>net.sourceforge.htmlcleaner</groupId> <artifactId>htmlcleaner</artifactId> <version>2.2</version> </dependency>