JDOM1.1.2 and Maven

The objective is to make the JDOM 1.1.2 jar available on maven-central so that other projects can just suck in the jdom jars by setting the appropriate dependencies in their project configurations.

This functionality is complete now. Skip to the end of the document for details on how it was done.

Objectives

• There must be a 1.1.2 jar in maven-central
• There must be the appropriate 'header' information so that others can easily access the jar.
• There must be a clear/documented procedure to follow for publishing subsequent 1.1.x jar versions

Anti-Objectives

... yes, an 'invented' word, but, in a different sense: "What we don't want!"

• convert the 1.1.x branch in to a 'mavenized' build structure (though that may be considered for jdom2.x ). That being said, having a maven 'wrapper' around the current ant build process would be a possibility.

Constraints

• there must be the smallest possible code change in the 1.1.2 branch.
• the jdom 1.1.2 and subsequent official release will still be published on www.jdom.org.

Considerations

• One option is to do the whole process 'manually'
• The procedure established for setting up 1.1.2 Maven publishing will likely establish the 'pattern' for JDOM2 publising as well, so it should take in to consideration the fact that when JDOM2 finally gets published in maven-central, there will be users who want to remain on the 1.1.x series of maven releases, and other users who will pull from the 2.x releases.

Investigations

• What is http://search.maven.org/#browse|718051244
• What is http://search.maven.org/#browse|100982423

Implementation

This feature is now done for JDOM 1.1.2. Here are the details of how it was implemented.

The path chosen is the 'manual' process of uploading a maven 'Bundle' to maven-central. This process is abtracted significantly. It is easier to understand the process 'backwards':

1. you need to get the jars on to maven-central
2. you can't just 'dump' stuff on maven central. There are trusted 'gateways' for adding content. One of these gateways is the Open-Source restricted 'nexus' operated by Sonatype.
3. The OSS gateway on Sonatype has some restrictions: any jar submitted must be accompanied by a source code and javadoc jar. Additionally all three jars must be signed by an 'authorized' user.
4. To be authorized you need an account on their systems, and you need a public PGP/GPG identity key.
5. The OSS gateway has a system in place where you 'stage' a package. When the package is completely 'staged', you can release it. The released package will be synchronized with the maven-central servers (every few hours).
6. There are a few ways to stage a repository. One of them is to upload a single file containing the 'pom', all the jars and their signatures. This is called a 'bundle', and is in the form of a 'jar' file which contains the pom, the three base jars (code/source/javadoc) and the signatures of all files.
7. The JDOM 1.1.2 ant build.xml file is able to build (in the 'maven' target) the above 'bundle' jar which is then manually uploaded to oss.sonatype.org and manually 'released'.

To build the maven bundle using the ant target you need to have a way to sign the jars. If we were using a full maven build process it would be relatively easy to set this up. Since we don't, you need to set up the process 'the hard way'. Here's how I did it (I have done it on both Windows, and linux, but windows is the more complicated, and the one I normally use - my laptop is windows) :

1. intall gpg4win
2. you may need to reboot to put the gpg tool in your path.
3. use the 'Kleopatra' tool to generate a signing key.
4. publish the signing key to hkp://pool.sks-keyservers.net
5. test the tool by signing something arbitrary gpg -abv somefile. You should be prompted for a 'passphrase'.
6. run the 'maven' target: ant maven
7. upload the generated maven-bundle jar to oss.sonatype.org.
8. 'release' it.