[jdom-interest] JDOM artifact 'jdom-legacy' in maven

[Rolf Lear]

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 :
http://search.maven.org/#artifactdetails|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 -
http://search.maven.org/#artifactdetails|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>





Rolf