JDOM 2.0

This page describes the effort toward a JDOM 2.0 and provides an entry point for all the information you need on JDOM2. Skip to the end of this page to get the status of JDOM 2.0 and a list of JDOM 2.0 related pages.

JDOM 2.0 Motivation

The purpose of JDOM 2.0 is to make use of features introduced in Java 5, such as generics (note JDOM officially supports Java6 and up though - see the Java Dependencies/Versions page). Unfortunately the generics changes will break binary backward compatibility so we're moving to a new version as well as a new package name: org.jdom2. People who want to use the JDOM 1.1.x branch can continue to do so, but people who want the modern features can use JDOM 2.0. The same program can even mix and match. Yes there's downsides (http://markmail.org/message/avsyrgfii7z3u6m5) but it's probably worth it.

How much backward compatibility will we break? Only what's necessary. We may maintain source code compatibility so all a programmer will need to do is update their package imports and recompile their project. But if we decide as a group that some changes are so advantageous they're worth requiring code edits, we'll do it.

We'll do the work on GitHub because it simplifies the task of doing experimental branches. I expect a lot of discussion about whether a certain change is worthwhile or not, and GitHub makes it easy to discuss code not just ideas. The JDOM mailing lists will host the discussion. You can also watch for updates on Twitter from @jdomproject and @jdomcommits.

Possible JDOM 2.0 improvements (see JDOM2 Features for more details):

• Support for generics, varargs, enums, covariant return types
• Change JDOM's TextBuffer to StringBuilder
• Examine whether Document should be a Content, or a Node, or what
• Examine if the Collection API rules match what's best (set() method on Collections are not supposed to impact Concurrent Modification)
• Remove code that's in the default package
• Switch out CVS_ID to probably an annotation
• Look at XPath 2.0 support
• Look at StAX support, such as a StAXOutputter
• Michael Kay's suggestion for XPath 2.0 http://markmail.org/message/hvrthg7r647sldrb
• Remove code that checks for JAXP version http://markmail.org/message/q3sjsvnk3igf5cip
• Checks adds before an error occurs http://markmail.org/message/q3sjsvnk3igf5cip
• Reduce compiler warnings for Java 5 features http://markmail.org/message/332lmgoiyjpbqfnm
• Generic return types http://markmail.org/message/332lmgoiyjpbqfnm
• A builder and outputter for JDOM 1.x classes, for people who need to convert
• Investigate a Maven distribution:- Mail Reference and Wiki Page

Volunters

People who have volunteered to be heavily involved in the project:

• Jason Hunter (project owner)
• Rolf Lear (See http://markmail.org/message/e2ljuk56mz337fqj for what he's done before on this subject)
• (Mail the list if you want to be added here)

Initial steps

0. Migrate the code from CVS to GitHub (keeping all the history).
   DONE - see SOURCE and for the procedure see CVS to Git
1. Create a branch for 2.0
   DONE - see Source Branches and JDOM2
2. Do the basic package renames.
   DONE - code is 'rebased' to org.jdom2 and the AllTests junit suite runs. See Commit 2ce8a11a...
3. Fix the test case that's currently failing (test_TCM__void_setExpandEntities_boolean)
   DONE - this was pobably not broken. Probably because I used JUnit 4 when I reported the failure.
4. Upgrade the JUnit libraries and tests
   DONE - All tests using JUnit4 structures now.
5. Use Emma to build up the JUnit test cases to get much better coverage of the junit tests on JDOM (currently have only got 40% coverage of the org.junit code from the JUnit test cases....). Fix any issues that arise in untested code.
   DONE - Using Cobertura instead of Emma
6. Modify the core code and the test harness together to implement the changes - document what changes are made.
   DONE - so that we can get a list of rules for migration from JDOM 1 to JDOM 2.
7. Confirm any deviations from 'compatibility' with the jdom-interest list to ensure that all changes are reasonable.
   DONE
8. Complete the migration, ensure all JavaDoc is complete. All Tests are run, and code test coverage is 'complete'.
   DONE - but constantly being updated for each snapshot see the JDOM 2.0 links

JDOM 2.0 Status

JDOM 2.0 is ready to release. Easter 2012.

There are currently only smallish features that are outstanding on JDOM 2.0. The big features have been completed. See the issue tracker for what's outstanding.

JDOM 2.0 links

JDOM 2.0 information is a little scattered in the github site. These wiki pages are used for tracking some of the major features and non-javadoc documentation. The GitHub Downloads page is used to provide development snapshot downloads. The Github web-pages are used to supply HTML-based content, including the JavaDoc, Performance, JUnit, and Coverage reports.

Here are the references to the major JDOM 2.0 web-based resources. Some of these are duplicated in the 'sidebar' on all the GitHub JDOM wiki pages:

• JDOM 2.0 Primer - Getting started with JDOM2
• JDOM 2.0 Dependencies and Supported Versions - JDOM2 limitations and requirements.
• JDOM 2.0 Snapshot Downloads - more details on the Downloads Wiki page.
• JDOM 2.0 Features New and Revised functionality in JDOM 2.0 ('major' changes only)
• JDOM 1.x to JDOM 2.0 Migration Guide
• JDOM 2.0 API Documentation - revised to match the most recent posted snapshot download
• JDOM 2.0 JUnit Report - revised to match the most recent posted snapshot download
• JDOM 2.0 Code Coverage Report - revised to match the most recent posted snapshot download
• JDOM 2.0 Performance Report - Occasionally updated.
• JDOM 2.0 on Java5 - issues, limitations, and workarounds.