13.4 XML-Dateien mit JDOM verarbeiten

Über JDOM lassen sich die XML-formatierten Dateien einlesen, manipulieren und dann wieder schreiben. Mit einfachen Aufrufen lässt sich ein Dokument im Speicher erstellen. Zur internen JDOM-Repräsentation werden einige Java-typische Features verwendet, beispielsweise die Collection-API zur Speicherung, Reflection oder schwache Referenzen. Die Nutzung der Collection-API ist ein Vorteil, der unter dem herkömmlichen DOM nicht zum Tragen kommt. Durch JDOM können mit dem new-Operator auch Elemente und Attribute einfach erzeugt werden. Es gibt spezielle Klassen für das Dokument, nämlich Elemente, Attribute und Kommentare. Es sind keine Fabrik-Schnittstellen, die konfiguriert werden müssen, sondern alles wird direkt erzeugt.

Die Dokumentenmodelle DOM oder SAX liegen eine Ebene unter JDOM; doch JDOM ist der gemeinsame Aufbau, der die Vorteile von beiden Technologien vereinigt. Mit einem SAX-Parser kann eine Java-spezifische Baumstruktur im Speicher erzeugt werden. Die Bibliothek bietet daher eine neutrale Schnittstelle für diverse Parser, um die Verarbeitung der XML-Daten so unabhängig wie möglich von den Implementierungen zu machen. JDOM unterstützt dabei aktuelle Standards wie DOM Level 2, SAX 2.0 oder XML-Schema. Wenn es nötig wird, DOM oder SAX zu unterstützen, dann bieten Schnittstellen diesen Einstieg an.

Mit JDOM wird auch eine interne Datenstruktur der XML-Datei erzeugt. Dadurch kann jederzeit auf alle Elemente der XML-Datei zugegriffen werden. Dies ist viel effizienter als bei einer Implementierung von DOM, da Java-spezifische Datenstrukturen verwendet werden. JDOM ist eine echte Alternative zu DOM. Eine Zusammenarbeit von JDOM und SAX ist auch möglich, weil JDOM in der Lage ist, als Ausgabe SAX-Ereignisse auszulösen. Diese können mit SAX-basierten Tools weiterverarbeitet werden. Dadurch kann JDOM auch sehr gut in Umgebungen eingesetzt werden, in denen weitere Tools zur Verarbeitung von XML genutzt werden.

13.4.1 JDOM beziehen

JDOM ist freie Software, die auf der Apache-Lizenz beruht. Das heißt, dass JDOM auch in kommerziellen Produkten eingesetzt werden kann, die dann nicht automatisch Open Source sein müssen. Die Entwicklung von JDOM geht von Brett McLaughlin und Jason Hunter aus. Brett und Jason sind zwei bekannte Java-Autoren. Brett hat ein XML-Buch und Jason ein Servlet-Buch beim O'Reilly-Verlag herausgegeben. Die Homepage der Software mit Dokumentation und Mailinglisten liegt auf http://www.jdom.org/. Von dort sollten wir uns für unsere folgende Arbeit das Archiv mit den Bibliotheken und die Hilfe besorgen. Es gibt immer einen Meilenstein und eine nächtliche Version. (Der Meilenstein ist eine gut funktionierende Version, und der nächtliche Build ist nur für die Bastler.) JDOM ist im Standardisierungsprozess der Firma Sun.

13.4.2 Paketübersicht

JDOM besteht aus fünf Paketen mit den Klassen zur Repräsentation des Dokuments, mit Klassen zum Einlesen und Ausgeben.

Das Paket org.jdom

In diesem Paket sind alle Klassen zusammengefasst, damit ein XML-Dokument im Speicher repräsentiert werden kann. Dazu gehören zum Beispiel die Klassen Attribute, Comment, CDATA für Text, DocType, Document, Element, Entity und ProcessingInstruction. Ein Dokument-Objekt hat ein Wurzelelement, eventuell Kommentare, einen DocType und ProcessingInstructions.

Die Pakete org.jdom.output und org.jdom.input

In den beiden Paketen liegen die Klassen, die XML-Dateien lesen und schreiben können. XMLOutputter übernimmt die interne Repräsentation und erzeugt eine XML-Ausgabe in einen PrintWriter. Daneben werden die unterschiedlichen Verarbeitungsstrategien DOM und SAX durch die Ausgabeklassen SAXOutputter und DOMOutputter berücksichtigt. SAXOutputter nimmt einen JDOM-Baum und erzeugt benutzerdefinierte SAX2-Ereignisse. Der SAXOutputter ist eine sehr einfache Klasse und bietet lediglich eine output(Document)-Methode an. Mit DOMOutputter wird aus dem internen Baum ein DOM-Baum erstellt. SAXBuilder ist schneller und speicherschonender. Ein DOMBuilder wird meistens nur dann benutzt, wenn ein DOM-Baum weiterverarbeitet werden soll.

Ein Builder nimmt Daten in verschiedenen Formaten entgegen und erzeugt daraus ein JDOM-Dokument-Objekt. Das ist bei JDOM das wirkliche Verdienst, dass unabhängig von der Eingabe ein API-Set zur Verfügung steht. Die verschiedenen DOM-Implementierungen unterscheiden sich an manchen Stellen. Die Schnittstelle Builder wird von allen einlesenden Klassen implementiert. Im Input-Paket befindet sich dafür die Klasse DOMBuilder, die einen JDOM-Baum mit DOM erzeugt, und SAXBuilder, die dafür SAX verwendet. Beide Klassen basieren auf der abstrakten Oberklasse AbstractBuilder, die Builder implementiert und drei build()-Funktionen angibt. Damit kann das Dokument aus einer Datei, einem Stream oder einer URL erzeugt werden. Nach dem Einlesen sind die Daten unabhängig von dem konkreten Parser des Herstellers, und sie können weiterverarbeitet werden.

Im org.jdom.contrib-Package gibt es noch einige Erweiterungen für JDOM. Eine bemerkenswerte Erweiterung ist der ResultSetBuilder. Diese Klasse ermöglicht das Erstellen einer JDOM-Datenstruktur anhand eines java.sql.ResultSet. Dadurch ist eine Brücke zwischen Datenbanken und XML sehr einfach zu realisieren. Diese und noch viele weitere nützliche Erweiterungen sind nicht in der JDOM-Standarddistribution enthalten, sondern können unter der Adresse http://cvs.jdom.org/cgi-bin/viewcvs.cgi/jdom-contrib gefunden werden.

Das Paket org.jdom.transform

Mit diesem Paket wird das JAXP-TraX-Modell in JDOM integriert. Dies ermöglicht JDOM die Unterstützung für XSLT-Transformationen von XML-Dokumenten. Das Paket enthält die beiden Klassen JDOMResult und JDOMSource. Die Klasse JDOMSource ist eine Wrapper-Klasse, die ein JDOM-Dokument als Parameter nimmt und diesen als Eingabe für das JAXP-TraX-Modell bereitstellt. Die Klasse JDOMResult enthält das Ergebnis der Transformation als JDOM-Dokument. Die beiden Klassen haben nur wenige Methoden, und in der API sind Beispiele für die Benutzung dieser Klassen angegeben.

Das Paket org.jdom.adapters

Klassen dieses Pakets implementieren die Schnittstelle DOMAdapter. Sie sind von AbstractDOM Adapter abgeleitet und erlauben JDOM, existierende DOM-Implementierungen zu nutzen. Ein konkreter Adapter ummantelt die Implementierung und gibt ein Dokument-Objekt zurück. Es existieren dafür die Klassen OracleV1DOMAdapter, OracleV2DOMAdapter für Oracle-Version 1 und 2 DOM-Parser, ProjectXDOMAdapter (Projekt X DOM-Parser von Sun), XercesDOMAdapter (DOM-Parser von Apache Xerces), CrimsonDOMAdapter (DOM-Parser von SUN) und XML4JDOMAdapter für einen IBM XML4J-Parser. Jeder Parser, der die Schnittstelle org.xml.sax.XMLReader oder die Schnittstelle org.jdom.adapters.DOMBuilder implementiert, kann als Parser für JDOM verwendet werden. Es ist daher auch möglich, eigene Implementierungen von Parsern zu verwenden. Die Implementierung nutzt als Standard den Xerces-Parser von Apache.

13.4.3 Die Document-Klasse

Dokumente werden bei JDOM über die Klasse Document verwaltet. Ein Dokument besteht aus einem DocType, ProcessingInstructions, einem Wurzelelement und Kommentaren. Die Klasse Document gibt es auch in der Standardschnittstelle für das DOM. Falls sowohl JDOM als auch DOM verwendet werden, muss für die Klasse Document der voll qualifizierte Klassenname mit vollständiger Angabe der Pakete verwendet werden, weil sonst nicht klar ist, welche Document-Klasse verwendet wird.

Ein Document im Speicher erstellen

Um ein Document-Objekt zu erzeugen, bietet die Klasse drei Konstruktoren an. Über einen Standard-Konstruktor erzeugen wir ein leeres Dokument. Dies können wir später bearbeiten, indem wir zum Beispiel Elemente (Objekt vom Typ Element), Entitäten oder Kommentare einfügen. Ein neues Dokument mit einem Element erhalten wir über einen Konstruktor, dem wir ein Wurzelelement angeben. Jedes XML-Dokument hat ein Wurzelelement.

<party>
</party >

Document doc = new Document( new Element("party") );

13.4.4 Eingaben aus der Datei lesen

Ein zweiter Weg, um ein JDOM-Dokument anzulegen, führt über einen Eingabestrom oder eine Datei. Dafür benötigen wir einen Builder, zum Beispiel den SAXBuilder (den wir bevorzugen wollen).

SAXBuilder builder = new SAXBuilder();
Document doc = builder.build( dateiname );

Die Klasse Document kann selbst nicht aus anderen Quellen Daten entnehmen. Es sind immer die Builder, die Document-Objekte liefern. Es ist ebenso möglich, ein JDOM-Dokument mithilfe des DOM-Parsers DOMBuilder zu erzeugen. Als Parameter im Konstruktor können der zu verwendende Parser und ein boolean-Wert, der die Validierung auf wohldefinierten XML-Code einschaltet, angegeben werden.

13.4.5 Das Dokument als XML-Datei ausgeben

Mit der Hilfsklasse XMLOutputter lässt sich der interne JDOM-Baum leicht als XML-Datenstrom ausgeben. Durch diesen Formatierer werden die Daten mit Einrückungen geschrieben. Jeder Eintrag kommt in eine einzelne Zeile. Durch folgende zwei Zeilen wird ein JDOM-Dokument über die Konsole ausgegeben:

XMLOutputter out = new XMLOutputter();
out.output( doc, System.out );

Über dem Konstruktor kann die Einrückung bestimmt werden.

XMLOutputter out = new XMLOutputter( "  ", false );
Out.output( doc, System.out );

Diese Anweisungen erzeugen eine kompakte Ausgabe ohne Einrückung und Trennzeilen.

13.4.6 Der Dokumenttyp

Ein XML-Dokument beschreibt in seinem Dokumenttyp den Typ der Datei und besitzt oft einen Verweis auf die beschreibende DTD.

<!DOCTYPE html PUBLIC
  
  ">http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>

Bearbeiten wir dies über JDOM, so liefert die Methode getDocType() vom Dokument-Objekt ein DocType-Objekt, welches wir nach den IDs fragen können. Über setDocType() kann der veränderte Dokumenttyp neu zugewiesen werden.

class org.jdom.Document
implements Serializable, Cloneable

DocType getDocType() Liefert das zugehörige DocType-Objekt oder null, wenn keines existiert.

Document setDocType( DocType docType ) Setzt ein neues DocType-Objekt für das Dokument.

DocType docType = doc.getDocType();
System.out.println( "Element: " + docType.getElementName() );
System.out.println( "Public ID: " + docType.getPublicID() );
System.out.println( "System ID: " + docType.getSystemID() );

Zu den Methoden getPublicID() und getSystemID() gibt es entsprechende Setze-Methoden, nicht aber für den Elementnamen, dieser kann nachträglich nicht mehr modifiziert werden. Wir müssen dann ein neues DocTyp-Objekt anlegen. Es gibt mehrere Varianten von Konstruktoren, mit denen gesteuert werden kann, welche Einträge gesetzt werden.

DocType doctype =  new DocType( "html", "-//W3C...", ">http://..."; ) ;
doc.setDocType( doctype  );

13.4.7 Elemente

Jedes Dokument besteht aus einem Wurzelelement. Wir haben schon gesehen, dass dies durch die Klasse Element abgebildet wird. Mit dem Wurzelelement gelingt der Zugriff auf die anderen Elemente des Dokumentenbaums.

Wurzelelement

Im Folgenden wird die Beispieldatei party.xml verwendet, um die Funktionen von JDOM vorzustellen. Durch das Erzeugen eines leeren JDOM-Dokuments und die Methoden zur Erzeugung von Elementen und Attributen kann diese Datei auch leicht mit JDOM erzeugt werden.

party.xml
<party datum=«31.12.01«>
    <gast name="Albert Angsthase">
        <getraenk>Wein</getraenk>
        <getraenk>Bier</getraenk>
        <zustand ledig=«true« nuechtern=«false«/>
    </gast>
    <gast name="Martina Mutig">
        <getraenk>Apfelsaft</getraenk>
        <zustand ledig=«true« nuechtern=«true«/>
    </gast>
    <gast name="Zacharias Zottelig"></gast>
</party>

Um an das Wurzelelement <party> zu kommen und von dort aus weitere Elemente oder Attribute auslesen zu können, schreiben wir:

//Erzeugen eines JDOM-Dokuments anhand der Datei party.xml
SAXBuilder builder = new SAXBuilder();
Document doc = builder.build( "party.xml" );
//Lesen des Wurzelelements des JDOM-Dokuments doc
Element party = doc.getRootElement();

class org.jdom.Document
implements Serializable, Cloneable

Element getRootElement() Gibt das Root-Element zurück oder null, falls kein Root-Element vorhanden ist.

boolean isRootElement() Rückgabe eines Wahrheitswerts, der ausdrückt, ob das Element die Wurzel der JDOM-Datenstruktur ist.

Durch die oben gezeigten Anweisungen wird aus der XML-Datei party.xml eine JDOM-Datenstruktur im Speicher erzeugt. Um mit dem Inhalt der XML-Datei arbeiten zu können, ist der Zugriff auf die einzelnen Elemente notwendig. Durch die Methode getRoot Element() wird das Wurzelelement der XML-Datei zurückgegeben. Dieses Element ist der Ausgangspunkt für die weitere Verarbeitung der Datei.

Zugriff auf Elemente

Um ein bestimmtes Element zu erhalten, gibt es die Methode getChild(String name). Mit dieser Methode wird das nächste Unterelement des Elements, das diesen Namen trägt, zurückgegeben. Eine Liste mit allen Elementen liefert die Methode getChildren(). Sie gibt eine Liste mit allen Elementen mit diesem Namen zurück.

class org.jdom.Element
implements Serializable, Cloneable

Element getChild( String name ) Rückgabe des ersten untergeordneten Elements mit dem lokalen Namen name, das keinem Namensraum zugeordnet ist.

Element getChild( String name, Namespace ns ) Rückgabe des ersten untergeordneten Elements mit dem lokalen Namen name, das dem Namensraum ns zugeordnet ist.

List getChildren() Rückgabe einer Liste der Elemente, die diesem Element direkt untergeordnet sind. Falls keine Elemente existieren, wird eine leere Liste zurückgegeben. Änderungen an der Liste spiegeln sich auch in der JDOM-Datenstruktur wider.

List getChildren( String name ) Rückgabe einer Liste der Elemente mit dem Namen name, die diesem Element direkt untergeordnet sind. Falls keine Elemente existieren, wird eine leere Liste zurückgegeben. Änderungen an der Liste spiegeln sich auch in der JDOM-Datenstruktur wider.

List getChildren( String name, Namespace ns ) Rückgabe einer Liste der Elemente mit dem Namen name, die diesem Namensraum zugeordnet und diesem Element direkt untergeordnet sind. Falls keine Elemente existieren, wird eine leere Liste zurückgegeben. Änderungen an der Liste spiegeln sich auch in der JDOM-Datenstruktur wider.

boolean hasChildren() Rückgabe eines boolean-Werts, der ausdrückt, ob Elemente untergeordnet sind oder nicht.

Element party = doc.getRootElement();
Element albert = party.getChild( "gast" );

Element albertGetraenk = albert.getChild( "getraenk" );

Element albertGetraenk = party.getChild( "gast" ).getChild( "getraenk" );

List gaeste = party.getChildren( "gast" );

13.4.8 Zugriff auf Elementinhalte

Von Beginn eines Elements bis zu dessen Ende treffen wir auf drei unterschiedliche Informationen:

Es können weitere Elemente folgen. Im oberen Beispiel folgt in <gast> noch ein Element <getraenk>.

Das Element enthält Text (wie das Element <getraenk>).

Zusätzlich kann ein Element auch Attribute beinhalten. Dies haben wir auch beim Element <gast> gesehen, das als Attribut den Namen des Gasts enthält. Der Inhalt von Attributen ist immer Text.

Für diese Aufgaben bietet die Element-Klasse unterschiedliche Anfrage- und Setze-Methoden. Wir wollen mit dem Einfachsten, dem Zugriff auf den Textinhalt eines Elements, beginnen.

Elementinhalte auslesen und setzen

Betrachten wir das Element, dessen Inhalt wir auslesen wollen, so nutzen wir dazu die Methode getText().

<getraenk>Wein</getraenk>

Sie liefert einen String, sofern eine String-Repräsentation des Inhalts erlaubt ist. Falls das Element keinen Text oder nur Unterelemente besitzt, so ist der Rückgabewert ein Leerstring.

Um an das erste Getränk von Albert zu kommen, schreiben wir:

Element party = doc.getRootElement();
Element albertGetraenk = party.getChild( "gast" ).getChild( "getraenk" );
String getraenk = albertGetraenk.getText();

class org.jdom.Element
implements Serializable, Cloneable

String getText() Rückgabe des Inhalts des Elements. Dies beinhaltet alle Leerzeichen und CDATA-Sektionen. Falls der Elementinhalt nicht zurückgegeben werden kann, wird der leere String zurückgegeben.

String getTextNormalize() Verhält sich wie getText(). Leerzeichen am Anfang und am Ende des Strings werden entfernt. Leerzeichen innerhalb des Strings werden auf ein Leerzeichen normalisiert. Falls der Text nur aus Leerzeichen besteht, wird der leere String zurückgegeben.

String getTextTrim() Verhält sich wie getTextNormalize(). Leerzeichen innerhalb des Strings bleiben erhalten.

Für die Methode getText() muss das Element vorliegen, dessen Inhalt gelesen werden soll. Mit der Methode getChildText() kann auch direkt der Inhalt eines untergeordneten Elements ermittelt werden. Das nachfolgende Beispiel liest den Text des ersten untergeordneten Elements mit dem Namen getraenk. Das übergeordnete Element von Getränk ist albert.

Element albert = party.getChild( "gast" );
String getraenk = albert.getChildText( "getraenk" );

In der Implementierung der Methode getChildText() sind die Methoden getChild() und getText() zusammengefasst.

class org.jdom.Element
implements Serializable, Cloneable

String getChildText( String name ) Rückgabe des Inhalts des Elements mit dem Namen name. Falls der Inhalt kein Text ist, wird ein leerer String zurückgegeben. Falls das Element nicht existiert, wird null zurückgegeben.

String getChildText( String name, Namespace ns ) Verhält sich wie getChildText(String) im Namensraum ns.

String getChildTextTrim( String name ) Verhält sich wie getChildText(String). Leerzeichen am Anfang und am Ende des Strings werden entfernt. Leerzeichen innerhalb des Strings bleiben erhalten.

String getChildTextTrim( String name, Namespace ns ) Verhält sich wie getChildTextTrim(String) im Namensraum ns.

String getName() Rückgabe des lokalen Namens des Elements ohne Namensraum-Präfix.

Namespace getNamespace() Rückgabe des Namensraums oder eines leeren Strings, falls diesem Element kein Namensraum zugeordnet ist.

Namespace getNamespace( String prefix ) Rückgabe des Namensraums des Elements mit diesem Präfix. Dies beinhaltet das Hochlaufen in der Hierarchie des JDOM-Dokuments. Falls kein Namensraum gefunden wird, gibt diese Methode null zurück.

String getNamespacePrefix() Rückgabe des Namensraum-Präfixes. Falls kein Namensraum-Präfix existiert, wird ein Leerstring zurückgegeben.

String getNamespaceURI() Rückgabe der Namensraum-URI, die dem Präfix dieses Elements zugeordnet ist, oder des Standardnamensraums. Falls keine URI gefunden werden kann, wird ein leerer String zurückgegeben.

13.4.9 Liste mit Unterelementen erzeugen

Mit den oben beschriebenen Methoden war es bislang immer nur möglich, das erste untergeordnete Element mit einem bestimmten Namen zu lesen. Um gezielt nach bestimmten Elementen zu suchen, ist es notwendig, die untergeordneten Elemente in eine Liste zu übertragen. Mit der Methode getContent() wird eine Liste mit allen Elementen und Unterelementen erzeugt. Diese Liste enthält Referenzen der Elemente aus der JDOM-Datenstruktur.

Element party = doc.getRootElement();
List partyInfo = party.getContent();

Mit einem Iterator kann diese Liste durchlaufen werden.

Iterator partyIterator = partyInfo.iterator();
while ( partyIterator.hasNext() )
{
  System.out.println( partyIterator.next().toString() );
}

class org.jdom.Element
implements Serializable, Cloneable

List getContent() Dies liefert den vollständigen Inhalt eines Elements mit allen Unterelementen. Die Liste kann Objekte vom Typ String, Element, Comment, ProcessingInstruction und Entity enthalten. Falls keine Elemente vorhanden sind, wird eine leere Liste zurückgegeben.

13.4.10 Neue Elemente einfügen und ändern

Um neue Elemente zu erzeugen, bietet die Klasse Element unter anderem den Konstruktor Element(String) an. Es wird ein Element mit dem entsprechenden Namen erzeugt.

Element party = doc.getRootElement();
Element albert = party.getChild( "gast" );
List albertInfo = albert.getContent();
Element wasser = new Element( "getraenk" );
wasser.addContent( "Wasser" );

Um den Wert eines Elements zu ändern, gibt es die Methoden setText() und addContent(). Die Methode setText() hat allerdings die unangenehme Eigenschaft, alle Unterelemente zu entfernen. Die Methode addContent() fügt neuen Inhalt hinzu.

Wenn der Inhalt eines Elements ausgetauscht werden soll, muss der Alte entfernt und der neue Inhalt mit addContent() hinzugefügt werden. Die Methode addContent() kann nicht nur Text, sondern jeden beliebigen Inhalt einfügen.

Zuerst wird das erste Unterelement gelöscht:

albert.removeChild( "getraenk" );

Ein neues Element wasser wird erzeugt und mit Inhalt gefüllt:

Element wasser = new Element( "getraenk" );
wasser.addContent( "Wasser" );

Das neue Element wird dem Element albert untergeordnet:

albert.addContent( wasser );

Werfen wir erneut einen Blick auf unsere XML-Datei und entfernen das erste Element <getraenk>, das dem ersten Element <gast> untergeordnet ist.

<party datum="31.12.01">
    <gast name="Albert Angsthase">
        <getraenk>Wein</getraenk>
        <getraenk>Bier</getraenk>
        <zustand ledig="true" nuechtern="false"/>
    </gast>
<party>

Element party = doc.getRootElement();
Element albert = party.getChild( "gast" );
// Es werden nur die direkten Nachfolger durchsucht. Diese Funktion
 // findet das Element <getraenk>Wein</getraenk> nicht.
party.removeChild("getraenk");

// Mit dieser Funktion wird das Element
// <getraenk>Wein</getraenk> gelöscht.
albert.removeChild( "getraenk" );

class org.jdom.Element
implements Serializable, Cloneable

Element( String name ) Dieser Konstruktor erzeugt ein Element mit dem Namen name, ohne Zuordnung zu einem Namensraum.

Element( String name, Namespace namespace ) Dieser Konstruktor erzeugt ein Element mit dem Namen name und dem Namensraum namespace.

Element( String name, String uri ) Dieser Konstruktor erzeugt ein neues Element mit dem lokalen Namen name und der URI des Namensraums, der zu dem Element ohne Präfix gehört.

Element( String name, String prefix, String uri ) Dieser Konstruktor erzeugt ein neues Element mit dem lokalen Namen name, dem Namenspräfix prefix und der URI des Namensraums.

Von diesen Konstruktoren ist in den Beispielen nur der Erste benutzt worden.

boolean removeChild( String name ) Entfernt das erste gefundene Unterelement mit den Namen name, das gefunden wird und keinem Namensraum zugeordnet ist. Es werden nur die direkten Nachfolger durchsucht.

boolean removeChild( String name, Namespace ns) Verhält sich wie removeChild(String name). Der Namensraum wird bei der Auswahl des Elements berücksichtigt.

boolean removeChildren() Entfernt alle untergeordneten Elemente.

boolean removeChildren( String name ) Entfernt alle Unterelemente mit den Namen name, die gefunden werden und keinem Namensraum zugeordnet sind. Es werden nur die direkten Nachfolger durchsucht.

boolean removeChildren( String name, Namespace ns ) Verhält sich wie removeChildren(String) im Namensraum ns.

Bei den folgenden Methoden wird als Rückgabewert das geänderte Element zurückgegeben:

Element setText( String text ) Setzt den Inhalt des Elements. Alle anderen Inhalte und alle Unterelemente werden gelöscht.

Element addContent( String text ) Ergänzt den Inhalt des Elements um den Text.

Element addContent( Element element ) Ergänzt den Inhalt des Elements um das Element als Unterelement.

Element addContent( ProcessingInstruction pi ) Ergänzt den Inhalt des Elements um die Processing Instruction pi.

Element addContent( EntityRef entität ) Ergänzt den Inhalt des Elements um die Entität.

Element addContent( CDATA cdata ) Ergänzt den Inhalt des Elements um eine CDATA-Sektion.

Element addContent( Comment comment ) Ergänzt den Inhalt des Elements um einen Kommentar.

Element getCopy( String name ) Erzeugt eine Kopie des Elements mit dem neuen Namen name, ohne Zuordnung zu einem Namensraum.

Element getCopy( String name, Namespace ns ) Erzeugt eine Kopie des Elements mit dem neuem Namen name und eine Zuordnung zu dem Namensraum ns.

Document getDocument() Liefert das Dokument dieses Elements; null, falls das Element keinem Dokument zugeordnet ist.

13.4.11 Attributinhalte lesen und ändern

Ein Element kann auch einen Attributwert enthalten. Dies ist der Wert, der direkt in dem Tag mit angegeben ist. Betrachten wir dazu folgendes Element:

<gast name="Albert Angsthase">

Das Element hat als Attribut name="Albert Angsthase". Dieser Wert kann mit der Methode getAttribute(String).getValue() der Klasse Element gelesen werden. In diesem Fall wird mit getAttribute("name").getValue() der Attributwert von dem Element albert gelesen.

Element party = doc.getRootElement();
Element albert = party.getChild( "gast" );
String albertName = albert.getAttribute( "name" );

Genauso kann auch der Wert eines Attributs geschrieben werden. Dazu gibt es die Methoden setAttribute(String) der Klasse Attribute und addAttribute(Attribute) der Klasse Element. Es gibt eine Klasse Attribute, mit deren Hilfe das Modellieren von Attributen mit Java ermöglicht wird.

Wollen wir den Namen von Albert wissen, schreiben wir:

String albertName = albert.getAttribute( "name" ).getValue();

Wenn Martina wissen möchte, ob Albert noch ledig ist:

albert.getChild( "zustand" ).getAttribute( "ledig" ).getValue();

Martina und Albert haben geheiratet, und Albert nimmt den Namen von Martina an:

albert.getAttribute( "name" ).setAttribute( "Albert Mutig" );

Seit der Hochzeit mit Albert trinkt Martina auch Wein. Also muss ein neues Element wein unter dem Element <gast name="Martina Mutig"> eingefügt werden. Zuerst erzeugen wir ein Element der Form <getraenk>Wein</getraenk>.

Element wein = new Element( "getraenk" );
wein.addContent( "Wein" );

Danach suchen wir Martina in der Gästeliste und fügen das Element <wein> ein:

// Liste aller Gäste
Iterator gaesteListe = party.getChildren( "gast" ).iterator(); 
while ( gaesteListe.hasNext() )
{
  Element gast = (Element) gaesteListe.next();
  if ( "Martina Mutig".equals( gast.getAttribute( "name" ).getValue()) )
    gast.addContent( wein );
}

An diesem Beispiel wird deutlich, wie flexibel die Methode addContent(Inhalt) ist. Es zeigt ebenso, wie JDOM für Java, etwa durch die Implementierung der Schnittstelle List, optimiert wurde.

class org.jdom.Element
implements Serializable, Cloneable

Attribute getAttribute( String name ) Rückgabe des Attributs mit dem Namen name, das keinem Namensraum zugeordnet ist. Falls das Element kein Attribut mit dem Namen name hat, wird eine leere Liste zurückgegeben.

Attribute getAttribute( String name, Namespace ns ) Verhält sich wie getAttribute(String) in dem Namensraum ns.

List getAttributes() Rückgabe einer Liste aller Attribute eines Elements oder einer leeren Liste, falls das Element keine Attribute hat.

String getAttributeValue( String name ) Rückgabe der Attribute mit dem Namen name, dem kein Namensraum zugeordnet ist. Es wird null zurückgegeben, falls keine Attribute mit diesem Namen existieren, und der leere String, falls der Wert des Attributs leer ist.

String getAttributeValue( String name, Namespace ns ) Verhält sich wie getAttributeValue(String) in dem Namensraum ns.

Element setAttributes( List attributes ) Fügt alle Attribute der Liste dem Element zu. Alle vorhandenen Attribute werden entfernt. Das geänderte Element wird zurückgegeben.

Element addAttribute( Attribute attribute ) Einfügen des Attributs attribute. Bereits vorhandene Attribute mit gleichem Namen und gleichem Namensraum werden ersetzt.

Element addAttribute( String name, String value ) Einfügen des Attributs mit dem Namen name und dem Wert value. Um Attribute mit einem Namensraum hinzuzufügen, sollte man die Methode addAttribute(Attribute attribute) verwenden.

class org.jdom.Attribute
implements Serializable, Cloneable

String getValue() Rückgabe des Werts dieses Attributs

Die nachfolgenden Methoden versuchen eine Umwandlung in einen primitiven Datentyp. Falls eine Umwandlung nicht möglich ist, wird eine DataConversionException ausgelöst.

getBooleanValue() Gibt den Wert des Attributs als boolean zurück.

double getDoubleValue() Gibt den Wert des Attributs als double zurück.

float getFloatValue() Gibt den Wert des Attributs als float zurück.

int getIntValue() Gibt den Wert des Attributs als int zurück.

long getLongValue() Gibt den Wert des Attributs als long zurück.

String getName() Gibt den lokalen Namen des Attributs zurück. Falls der Name die Form [namespacePrefix]:[elementName] hat, wird [elementName] zurückgegeben. Wenn der Name kein Namensraum-Präfix hat, wird einfach nur der Name ausgegeben.

Namespace getNamespace() Gibt den Namensraum des Attributs zurück. Falls kein Namensraum vorhanden ist, wird das konstante Namensraum-Objekt NO_NAMESPACE zurückgegeben. Diese Konstante enthält ein Namensraum-Objekt mit dem leeren String als Namensraum.

String getNamespacePrefix() Gibt das Präfix des Namensraums zurück. Falls kein Namensraum zugeordnet ist, wird ein leerer String zurückgegeben.

String getNamespaceURI() Gibt die URI zurück, die zu dem Namensraum dieses Elements gehört. Falls kein Namensraum zugeordnet ist, wird ein leerer String zurückgegeben.

Element getParent() Gibt das Element zurück, das dem Element dieses Attributs übergeordnet ist. Falls kein übergeordnetes Element vorhanden ist, wird null zurückgegeben.

String getQualifiedName() Rückgabe des qualifizierten Namens des Attributs. Falls der Name die Form [namespacePrefix]:[elementName] hat, wird dies zurückgegeben. Ansonsten wird der lokale Name zurückgegeben.

getSerializedForm() Rückgabe des Attributs im XML-Format

Attribute setValue( String value ) Setzt den Wert dieses Attributs.