JDOM2 Using Java5

Please see the JDOM2 Supported Versions page for a statement about Java supported versions.

It is likely that JDOM2 will run fine for almost everyone as-is on Java5. There are a limited number of places where you may encounter problems. In summary, they are: StAX support, and very complicated XSD schemas which contain xmllink references.

If you use these features you may want to read up on how to make them work in Java5.

JDOM2 does not fully support Java5 out-of-the-box. JDOM2 uses some Java6 features that have to be added in to Java 5 to make them work. Additionally, even when the code runs on Java5, there are a few Java5 issues which may affect your program. This page documents how to set up JDOM2 in a Java5 envionment, what limitations you may run in to, and how you may be able to work around those limitations.

Note that bugs encountered in JDOM2 when running under Java5 are likely to be set with a very low priority unless they can be reproduced in Java6 or later.

Technical notes about JDOM and Java5

The following lists those Java6-and-newer features which have had to be accomodated to make the code run in Java5. This is a growing list of 'what not to do' in JDOM2 to maintain Java5 runtime compatibility.

• avoid Arrays.copyOf(...) - JDOM2 has implemented an alternate org.jdom2.internal.ArrayCopy.copyOf(Object[], int)
• avoid use of ArrayDeque - use LinkedList or some other alternate.
• avoid use of some javax.xml.XMLConstants constants which can disappear if you include StAX in a Java5 runtime. This is a complicated one, byt the StAX API is in JSR173, and this ships as a javax.xml.* API. This JSR library includes javax.xml.XMLConstants, but not all of the XMLConxtants are defined. This can cause wierd problems. As a consequence, avoid use of XMLConstants: FEATURE_SECURE_PROCESSING, W3C_*
• avoid use of 'Source' based inputs for StAX parsers - Java5 does not support javax.xml.stream.XMLInputFactory methods with javax.xml.transform.Source arguments.
• avoid use of org.xml.sax.ext.DefaultHandler2 because it has a major bug in Java5: I can't find the actual bug, but these are symptoms - https://issues.apache.org/bugzilla/show_bug.cgi?id=38316 and https://issues.apache.org/jira/browse/XERCESJ-1261

Xerces

Java5 internally contains an Xerces parser, but it is buggy, old, and slow. It is recommended that you include the latest Xerces parser independantly on your classpath. The version JDOM2 is tested with is Xerces 2.11.0. It is 'unwise' to run JDOM with the Java5 internal SAX parser. You get what you deserve ...

To use Xerces with Java5 you need to include both the xercesImpl.jar and the xml-apis.jar in your classpath. JDOM2 is distributed with both of these jars.

StAX

To make JDOM2's StAX support work in Java5 you need to include the StAX API, and an implementation of that API. There are basically just two implementations available: the 'reference' and the Woodstox implementations.

JDOM2 is tested with the reference implementation.

To include the reference implementation you need both the API and the implementation: jsr173_1.0_api.jar and sjsxp.jar respectively. You can get them from the JSR173 team source or pull them from stax folder of the jdom2_dev_jars.zip file on the Downloads page. Note that the jsr173_1.0_api.jar contains a limited/broken version of the javax.xml.XMLConstants class, so beware of your classpath order.

Alternatively you can run the Woodstox implementation. You can read the Woodstox documentation for running Woodstox in Java5, which you should do anyway, but before you download things you will likely find everything you need in the jdom2_dev_jars.zip file on the Downloads page.

Known Issues

XMLSchema and SchemaFactory.newSchema()

In Java5 there appears to be an issue with using javax.xml.validation.SchemaFactory.newSchema() method. This method is supposed to create a Schema instance that validates using the internal XSD Schema references on the input document. In Java5 this works to the extent that the XSD document is specified, but xmllink references on that XSD schema are not followed. In particular, and for example, there are two test cases in TestSAXComplexSchema. The first test case uses xerces-specific initialization to set up the SAXBuilder. The second uses the general SchemaFactory.newSchema() mechanism. In Java5 the first test succeeds, and the second fails.

In Java5, if you have (very) complicated xmllink references in the XML Schema definitions for your documents then you should use the parser-specific mechanisms to initialize SAXBuilder.

StAX XMLInputFactory and javax.xml.transform.Source

Support of Source inputs for XMLInputFactory is apparently optional. In Java5 these methods throw UnsupportedOperationException. Do not use them.