JDOM1 to JDOM2 migration

Switching from JDOM 1.x to JDOM 2.x in Lobster Data Platform 26.2

Starting with version 26.2, the Lobster Data Platform uses exclusively JDOM 2.x instead of JDOM 1.x, regardless of the Java version in use. The platform itself has already been fully migrated, and all internal imports and API calls have been updated. However, this change also affects your own custom code that accesses JDOM classes directly – in particular, execute scripts and custom Java classes deployed on the platform.

This article explains how to identify affected code, update it, and verify your integrations before deploying to production.

Background

JDOM is the Java library for processing XML documents. The name stands for Java Document Object Model. JDOM 1.x is incompatible with Java 21. Because Lobster Data Platform 26.2 now supports OpenJDK 21, the library has been replaced with JDOM 2.  IMPORTANT   This change impacts all installations of version 26.2, regardless of which Java version is in use – including installations still running on Java 11. 

Who is affected?

Action is required if your platform contains any of the following artifacts:

• Execute scripts that import or use JDOM classes.

• Custom Java classes compiled against the JDOM API.

• Any other code artifacts that reference packages under org.jdom

If you have no custom code that interacts with JDOM, no changes are required.

Step-by-step guide

1. Identify affected code

Look for your Execute scripts and custom classes for import statements beginning with org.jdom.

Examples:

import org.jdom.Document;
import org.jdom.Element;
import org.jdom.input.SAXBuilder;
import org.jdom.output.XMLOutputter;
import org.jdom.xpath.XPath;

2. Update imports

Replace the JDOM 1.x package prefix org.jdom with the JDOM 2 prefix org.jdom2:

import org.jdom.Document;

import org.jdom.Element;

import org.jdom.input.SAXBuilder;

import org.jdom.output.XMLOutputter;

import org.jdom.xpath.XPath;

import org.jdom2.Document;

import org.jdom2.Element;

import org.jdom2.input.SAXBuilder;

import org.jdom2.output.XMLOutputter;

import org.jdom2.xpath.XPathFactory;

For many Execute scripts, updating the imports alone is sufficient, as Execute scripts do not support Java generics. Still, review each script individually – some JDOM 2 methods have changed signatures or have been renamed.

3. Review API changes at the method level

JDOM 2.x introduces several API changes beyond the package rename. The most common ones are:

Typed return values
Methods such as Element.getChildren() now return List<Element> instead of a raw List. In Execute scripts (which do not support generics), this is generally transparent. Check anyway to see if explicit casts still compile.

XPath API
The org.jdom.xpath.XPath class has been replaced by org.jdom2.xpath.XPathFactory and org.jdom2.xpath.XPathExpression. Update any scripts that use XPath queries accordingly.

Document constructor with root element
When a Document is created with a root element passed to the constructor, you must not subsequently call setRootElement() or addContent() for the same element. In this case, JDOM2 throws an IllegalAddException.

// Fails in JDOM 2 – root element is set twice
Element root = new Element("root");
Document doc = new Document(root);
doc.setRootElement(root); // throws IllegalAddException

// Correct
Element root = new Element("root");
Document doc = new Document(root);

Namespace validation
JDOM 2 enforces stricter namespace validation. Undeclared or nonexistent namespaces now throw an exception, whereas JDOM 1.x accepted them silently. Ensure that all namespaces used in your code are declared correctly.

Pretty printing and XML formatting
The formatting behavior of XMLOutputter has changed in JDOM 2:

• Behavior change: TextMode.PRESERVE no longer inserts automatic line breaks. In JDOM 1.x, line breaks were always inserted – this was a known bug in JDOM.

• Pretty format no longer automatically expands empty elements. Instead of <element></element>, the output is <element />. If you need expanded empty elements, this can be explicitly enabled on the Format object of the XMLOutputter.

• Workaround: Use TextMode.TRIM_FULL_WHITE combined with manual indentation to achieve formatting output similar to JDOM 1.x.

If your code generates XML output and compares the result against expected strings, update your reference values accordingly.

DTD resolving
Resolving DTDs via system ID no longer works the same way in JDOM 2. If your custom code uses DTD resolving via system ID, verify that resolution still works correctly and adjust the configuration, if needed.

Removed or renamed methods
Some convenience methods from JDOM 1.x have been removed or relocated in JDOM 2. See the official migration reference linked below for a complete list.

Summary of behavior changes

4. Test before deploying to production

1. Apply the import and API changes in a non-production environment (test system).

2. Run each modified script with representative test data.

3. Compare the XML output carefully – pay particular attention to line breaks, indentation, and the rendering of empty elements.

4. Pay particular attention to integrations where the XML structure or encoding must remain consistent for downstream systems.

Further reference

A complete overview of all API differences between JDOM 1.x and JDOM 2.x is available in the official migration guide:

JDOM2 Migration Issues (GitHub Wiki)

Continue with: Review TLS Java changes