JDOM1-zu-JDOM2-Migration

Prev Next

Wechsel von JDOM 1.x zu JDOM 2.x ab Lobster Data Platform 26.2

Ab Version 26.2 verwendet die Lobster Data Platform ausschließlich JDOM 2.x anstelle von JDOM 1.x, unabhängig von der Java-Version. Die Plattform selbst wurde bereits vollständig auf die aktuelle Version umgestellt und sämtliche interne Imports und API-Aufrufe sind angepasst. Diese Änderung betrifft jedoch auch Ihren eigenen Custom Code, der direkt auf JDOM-Klassen zugreift, insbesondere Execute-Scripts und eigene Java-Klassen, die auf der Plattform bereitgestellt sind.

Dieser Artikel beschreibt, wie Sie betroffenen Code identifizieren, aktualisieren und Ihre Integrationen vor dem Produktiv-Update verifizieren.

Hintergrund

JDOM ist die Java-Bibliothek zur Verarbeitung von XML-Dokumenten. Der Name steht für Java Document Object Model. JDOM 1.x ist nicht mit Java 21 kompatibel. Da die Lobster Data Platform 26.2 nun OpenJDK 21 unterstützt, wurde die Bibliothek durch JDOM 2 ersetzt.  WICHTIG  Die Änderung betrifft alle Installationen der Version 26.2, unabhängig davon, welche Java-Version verwendet wird, also auch Installationen, die noch mit Java 11 laufen.

Wer ist betroffen?

Handlungsbedarf besteht, wenn Ihre Plattform eines der folgenden Artefakte enthält:

  • Execute-Scripts, die JDOM-Klassen importieren oder verwenden

  • Custom Java-Klassen, die gegen die JDOM-API kompiliert sind

  • Sonstige Code-Artefakte, die Packages unterhalb von org.jdom referenzieren

Wenn Sie keinen Custom Code nutzen, der mit JDOM interagiert, ist keine Anpassung erforderlich.

Schritt-für-Schritt-Anleitung

1. Betroffenen Code identifizieren

Durchsuchen Sie Ihre Execute-Scripts und Custom Classes nach Import-Statements, die mit org.jdom beginnen. Entsprechende Beispiele:

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

2. Imports aktualisieren

Ersetzen Sie den JDOM-1.x-Package-Prefix org.jdom durch den JDOM2-Prefix org.jdom2:

JDOM-Import

JDOM2-Import

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;

In vielen Execute-Scripts genügt es, ausschließlich die Imports anzupassen, da Execute-Scripts keine Java-Generics unterstützen. Prüfen Sie dennoch jedes Skript einzeln, denn einige JDOM2-Methoden haben geänderte Signaturen oder wurden umbenannt.

3. API-Änderungen auf Methodenebene prüfen

JDOM 2.x bringt über die Package-Umbenennung hinaus mehrere API-Änderungen mit. Die häufigsten sind:

Typisierte Rückgabewerte
Methoden wie Element.getChildren() geben nun List<Element> anstelle einer Raw List zurück. In Execute-Scripts (ohne Generics-Support) ist das in der Regel transparent. Überprüfen Sie trotzdem, ob explizite Casts weiterhin kompilieren.

XPath-API
Die Klasse org.jdom.xpath.XPath wurde durch org.jdom2.xpath.XPathFactory und org.jdom2.xpath.XPathExpression ersetzt. Passen Sie daher Skripte, die XPath-Queries nutzen, entsprechend an.

Document-Konstruktor mit Root-Element
Wird ein Document mit einem Root-Element im Konstruktor erzeugt, darf anschließend kein weiterer Aufruf von setRootElement() oder addContent() für dasselbe Element erfolgen. JDOM2 wirft in diesem Fall eine IllegalAddException.

// Fehler in JDOM2 – Root-Element wird doppelt gesetzt
Element root = new Element("root");
Document doc = new Document(root);
doc.setRootElement(root); // wirft IllegalAddException

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

Namespace-Validierung
JDOM2 validiert Namespace-Deklarationen strenger. Nicht existierende oder nicht deklarierte Namespaces führen jetzt zu einer Exception, während JDOM 1.x dies stillschweigend akzeptiert hat. Stellen Sie sicher, dass alle in Ihrem Code verwendeten Namespaces richtig deklariert sind.

Pretty Printing und XML-Formatierung
Das Formatierungsverhalten von XMLOutputter hat sich in JDOM2 geändert:

  • Verhaltensänderung: TextMode.PRESERVE⁣fügt keine automatischen Zeilenumbrüche mehr ein. In JDOM 1.x wurden stets Zeilenumbrüche eingefügt und dieses Verhalten war ein bekannter Bug in JDOM.

  • Pretty Format expandiert leere Elemente nicht mehr automatisch. Statt <element></element> wird <element /> ausgegeben. Falls expandierte leere Elemente weiterhin benötigt werden, können Sie dies explizit im Format-Objekt des XMLOutputter aktivieren.

  • Workaround: Verwenden Sie TextMode.TRIM_FULL_WHITE in Kombination mit manueller Einrückung, um ein ähnliches Formatierungsergebnis wie unter JDOM 1.x zu erzielen.

Wenn Ihr Code XML-Output erzeugt und Sie das Ergebnis gegen erwartete Strings vergleichen, müssen Sie Ihre Referenzwerte entsprechend anpassen.

DTD-Resolving
Das Auflösen von DTDs über eine System-ID funktioniert in JDOM2 nicht mehr auf die gleiche Weise. Falls Ihr Custom Code DTD-Resolving über eine System-ID verwendet, prüfen Sie, ob die Auflösung weiterhin korrekt arbeitet, und passen Sie die Konfiguration gegebenenfalls an.

Entfernte oder umbenannte Methoden
Einige Convenience-Methoden von JDOM 1.x wurden in JDOM2 entfernt oder verschoben. Eine vollständige Liste finden Sie in der unten verlinkten offiziellen Migrationsreferenz.

Zusammenfassung der Verhaltensänderungen

Bereich

JDOM 1.x

JDOM 2.x

Package-Prefix

org.jdom

org.jdom2

XPath-API

XPath.newInstance()

XPathFactory.instance().compile()

TextMode.PRESERVE

Fügt immer Zeilenumbrüche ein

Fügt keine Zeilenumbrüche ein

Leere Elemente (Pretty Print)

Expandiert (<e></e>)

Selbstschließend (<e />)

Document-Konstruktor

Doppeltes Setzen des Root-Elements möglich

Wirft IllegalAddException

Namespace-Validierung

Nicht deklarierte Namespaces sind erlaubt

Wirft Exception

DTD-Resolving via System-ID

Funktioniert

Eingeschränkt, daher Prüfung erforderlich

4. Vor dem Produktiv-Deployment testen

  1. Nehmen Sie die Import- und API-Änderungen in einer Nicht-Produktivumgebung (Test-System) vor.

  2. Führen Sie jedes geänderte Script mit repräsentativen Testdaten aus.

  3. Vergleichen Sie den XML-Output sorgfältig – achten Sie insbesondere auf Zeilenumbrüche, Einrückungen und die Darstellung leerer Elemente.

  4. Prüfen Sie besonders Integrationen, bei denen die XML-Struktur oder das Encoding für nachgelagerte Systeme stabil bleiben muss.

Weiterführende Referenz

Eine vollständige Übersicht aller API-Unterschiede zwischen JDOM 1.x und JDOM 2.x finden Sie im offiziellen Migration Guide (Englisch):

JDOM2 Migration Issues (GitHub Wiki)

Fahren Sie fort mit: TLS-Java-Änderungen beachten

Verwandte Artikel