8.7XML-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 Fabrikschnittstellen, die konfiguriert werden müssen, sondern alles wird direkt erzeugt.
Die Modelle StAX, SAX oder DOM liegen eine Ebene unter JDOM, denn sie dienen als Ausgangspunkt zum Aufbau eines JDOM-Baums. Das heißt, dass ein vorgeschalteter SAX- oder StAX-Parser (bei JDOM Builder genannt) die JDOM-Baumstruktur im Speicher erzeugt. Die Bibliothek bietet daher eine neutrale Schnittstelle für diverse Parser, um die Verarbeitung der XML-Daten so unabhängig von den Implementierungen wie möglich zu machen. JDOM unterstützt dabei aktuelle Standards wie DOM Level 3, SAX 2.0 oder XML Schema. Wenn es nötig wird, DOM oder SAX zu unterstützen, 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. Da JDOM Java-spezifische Datenstrukturen verwendet, ist die Verarbeitung effizienter als bei DOM. JDOM stellt eine echte Alternative zu DOM dar. 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. So lässt sich JDOM auch sehr gut in Umgebungen einsetzen, in denen weitere Tools zur Verarbeitung von XML genutzt werden.
8.7.1JDOM beziehen
Die Projekt-Homepage http://www.jdom.org/ bietet Download, Dokumentation und Mailinglisten. Das ZIP-Archiv http://www.jdom.org/dist/binary/jdom-2.0.5.zip enthält das Java-Archiv jdom-2.0.5.jar, das wir dem Klassenpfad hinzufügen. Die API-Dokumentation liegt online unter http://jdom.org/docs/apidocs/index.html. JDOM ist freie Software, die auf der Apache-Lizenz beruht. Das heißt, dass JDOM auch in kommerziellen Produkten eingesetzt werden kann, ohne dass diese automatisch Open Source sein müssen.
JDOM-Version und JDOM-Alternativen
JDOM ist vor Java 5 und dem Einzug von Generics entwickelt worden, und es dauerte lange, bis JDOM 2 auf Java 5 umzog. dom4j dagegen nutzte schon recht früh Generics. XOM nutzt nach außen keine Typen der Collection-API, denn spezielle XOM-Klassen wie Nodes und Elements sind Container und liefern typisierte Objekte. Leider implementieren sie keine neuen Java-Collection-API-Klassen wie Iterable, und die Weiterentwicklung ist fraglich. Wenn wir im Folgenden von JDOM sprechen, meinen wir immer die aktuelle Version JDOM 2.
8.7.2Paketübersicht *
JDOM besteht aus 15 Paketen und Unterpaketen mit den Klassen zur Repräsentation des Dokuments, zum Einlesen und Ausgeben, zur Transformation und für XPath-Anfragen. Die wichtigsten davon stellen die nächsten Abschnitte vor.
Das Paket org.jdom2
Das Paket org.jdom2 (ab JDOM 2, vorher org.jdom) fasst alle Klassen zusammen, um ein XML-Dokument im Speicher zu repräsentieren. Dazu gehören zum Beispiel die Klassen Attribute, Comment, CDATA, DocType, Document, Element, Entity und ProcessingInstruction. Ein Dokument-Objekt hat ein Wurzelelement, eventuell Kommentare, einen DocType und eine ProcessingInstruction. Content ist die abstrakte Basisklasse und Oberklasse von Comment, DocType, Element, EntityRef, ProcessingInstruction und Text. Die Schnittstelle Parent implementieren alle Klassen, die Content haben können. Viele Schnittstellen gibt es in JDOM nicht. Andere XML-APIs verfolgen bei dieser Frage andere Ansätze; domj4 definiert zentrale Elemente als Schnittstellen, und die pure DOM-API beschreibt alles über Schnittstellen – konkrete Objekte kommen nur aus Fabriken, und die Implementierung ist unsichtbar.
Die Pakete org.jdom2.output und org.jdom2.input
In den beiden Paketen org.jdom2.output und org.jdom2.input 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.
Ein Builder nimmt XML-Daten in verschiedenen Formaten entgegen und erzeugt daraus ein JDOM-Document-Objekt. Das ist bei JDOM der wirkliche Verdienst, dass unabhängig von der Eingabeverarbeitung 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 befinden sich dafür die Klassen DOMBuilder, die einen JDOM-Baum mit DOM erzeugt, und SAXBuilder, die dafür SAX verwendet. Damit kann das Dokument aus einer Datei, einem Stream oder einer URL erzeugt werden. Nach dem Einlesen sind die Daten vom konkreten Parser des Herstellers unabhängig und können weiterverarbeitet werden. SAXBuilder ist schneller und speicherschonender. Ein DOMBuilder wird meistens nur dann benutzt, wenn ein DOM-Baum weiterverarbeitet werden soll.
Das Paket org.jdom2.transform
Mit dem Paket org.jdom2.transform wird das JAXP-TraX-Modell in JDOM integriert. Dies ermöglicht es JDOM, XSLT-Transformationen von XML-Dokumenten zu unterstützen. 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.jdom2.xpath
Im Paket org.jdom2.xpath befindet sich nur eine Utility-Klasse XPath. Diese Klasse bildet die Basis für die Verwendung der Abfragesprache XPath mit JDOM. Eine kurze Einführung in XPath sowie Beispiele für den Einsatz in JDOM bietet Abschnitt 8.7.12, »XPath«. Neben der Implementierung, die mit JDOM geliefert wird, kann auch eine spezielle Implementierung der XPath-Methoden für JDOM eingesetzt werden. JDOM bringt keine eigene XPath-Implementierung mit, sondern basiert auf der Open-Source-Implementierung Jaxen (http://jaxen.codehaus.org/).
8.7.3Die Document-Klasse
Dokumente werden bei JDOM über die Klasse Document verwaltet. Ein Dokument besteht aus einem DocType, einer ProcessingInstruction, 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 JDOM-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. Dieses können wir später bearbeiten, indem wir zum Beispiel Elemente (Objekte vom Typ Element), Entitäten oder Kommentare einfügen. Ein neues Dokument mit einem Element erhalten wir über einen Konstruktor, zu dem wir ein Wurzelelement angeben. Jedes XML-Dokument hat ein Wurzelelement.
[zB]Beispiel
Die folgende Zeile erzeugt ein JDOM-Dokument mit einem Wurzelelement:
Listing 8.30com/tutego/insel/xml/jdom/CreateRoot.java, main()
In XML formatiert, könnte das so aussehen:
</party>
8.7.4Eingaben aus der Datei lesen
Ein zweiter Weg, um ein JDOM-Dokument anzulegen, führt über einen Eingabestrom oder einen Dateinamen. Dafür benötigen wir einen Builder, zum Beispiel den SAXBuilder (den wir bevorzugen wollen).
[zB]Beispiel
Lies die Datei party.xml ein:
Listing 8.31com/tutego/insel/xml/jdom/ReadXmlFile.java, main() Teil 1
StandardCharsets.UTF_8 ) ) {
Document doc = new SAXBuilder().build( in );
…
}
Die mögliche Ausnahme JDOMException bei build(…) muss die Anwendung abfangen. Kürzer ist das Programm bei XML-Dateien im Standard-Dateisystem, doch die Kodierung ist hier nicht explizit.
Bei dieser Abkürzung muss die Anwendung IOException und JDOMException behandeln.
Die Klasse Document bietet selbst keine Lesemethoden. Es sind immer die Builder, die Document-Objekte liefern. Es ist ebenso möglich, ein JDOM-Dokument mithilfe des DOM-Parsers über DOMBuilder zu erzeugen. Neben den Standard-Konstruktoren bei SAXBuilder und DOMBuilder lässt sich unter anderem ein boolean-Wert angeben, der die Validierung auf wohldefinierten XML-Code einschaltet.
[+]Tipp
Wenn ein DOM-Baum nicht schon vorliegt, ist es sinnvoll, ein JDOM-Dokument stets mit dem SAX-Parser zu erzeugen. Das schont die Ressourcen und geht viel schneller, weil keine spezielle Datenstruktur für den DOM-Baum erzeugt werden muss. Das Ergebnis ist in beiden Fällen ein JDOM-Dokument, das die XML-Datei in einer baumähnlichen Struktur abbildet.
implements SAXEngine
SAXBuilder()
Baut einen XML-Leser auf Basis von SAX auf. Es wird nicht validiert.SAXBuilder(boolean validate)
Baut einen validierenden SAXBuilder auf.Document build(File file)
Document build(InputSource in)
Document build(InputStream in)
Document build(InputStream in, String systemId)
Document build(Reader characterStream)
Document build(Reader characterStream, String systemId)
Document build(String systemId)
Document build(URL url)
Baut ein JDOM-Dokument aus der gegebenen Quelle auf. Im Fall des String-Arguments handelt es sich um einen URI-Namen und nicht um ein XML-Dokument im String.
8.7.5Das Dokument im XML-Format ausgeben
Mit einem XMLOutputter lässt sich der interne JDOM-Baum als XML-Datenstrom in einen OutputStream oder Writer schieben.
[zB]Beispiel
Gib das JDOM-Dokument auf der Konsole aus:
Listing 8.32com/tutego/insel/xml/jdom/ReadXmlFile.java, main() Teil 2
out.output( doc, System.out );
Die Standardparametrisierung des Formatierers schreibt die XML-Daten mit schönen Einrückungen. Jeder Eintrag kommt in eine einzelne Zeile. Weitere Anpassungen der Formatierung übernimmt ein org.jdom2.output.Format-Objekt. Einige statische Methoden bereiten Format-Objekte mit unterschiedlichen Belegungen vor, so getPrettyFormat() für hübsch eingerückte Ausgaben und getCompactFormat() mit so genannter Leerraum-Normalisierung, wie es die API-Dokumentation nennt, und getRawFormat().
out.output( doc, System.out );
Unterschiedliche setXXX(…)-Methoden auf dem XMLOutputter-Objekt ermöglichen eine weitere individuelle Anpassung der Format-Objekte. Soll das Ergebnis als String vorliegen, kann outputString(…) verwendet werden, das ein String-Objekt liefert.
[zB]Beispiel
Konvertiere einen String in XML:
8.7.6Der Dokumenttyp *
Ein XML-Dokument beschreibt in seinem Dokumenttyp den Typ der Datei und besitzt oft einen Verweis auf die beschreibende DTD.
[zB]Beispiel
Ein gültiger Dokumenttyp für XHTML-Dateien hat folgendes Format:
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"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, das wir nach den IDs fragen können. Über setDocType(DocType) kann der veränderte Dokumenttyp neu zugewiesen werden.
implements Parent
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.
[zB]Beispiel
Wir erfragen vom Dokument den Elementnamen, die öffentliche ID und die System-ID:
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 DocType-Objekt anlegen. Es gibt mehrere Varianten von Konstruktoren, mit denen gesteuert werden kann, welche Einträge gesetzt werden.
[zB]Beispiel
Wir legen ein neues DocType-Objekt an und weisen es einem Dokument doc zu:
doc.setDocType( doctype );
8.7.7Elemente
Jedes Dokument besteht aus einem Wurzelelement. Wir haben schon gesehen, dass dieses durch die allgemeine Klasse Element abgebildet wird. Mit dem Wurzelelement gelingt der Zugriff auf die anderen Elemente des Dokumentenbaums.
Wurzelelement
Die folgenden Beispieldateien verwenden die XML-Datei party.xml, um die Methoden von JDOM vorzustellen. Durch das Erzeugen eines leeren JDOM-Dokuments und die Methoden zur Erstellung von Elementen und Attributen kann JDOM den Dateiinhalt auch leicht aufbauen:
Listing 8.33party.xml
<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 gelangen und von dort aus weitere Elemente oder Attribute auslesen zu können, erzeugen wir zunächst ein JDOM-Dokument aus der Datei party.xml und nutzen zum Zugriff getRootElement().
[zB]Beispiel
Lies die Datei party.xml, und erfrage das Wurzelelement:
Listing 8.34com/tutego/insel/xml/jdom/RootElement.java, main()
Element party = doc.getRootElement();
implements Parent
Element getRootElement()
Gibt das Root-Element zurück oder null, falls kein Root-Element vorhanden 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 getRootElement() 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 zurückgegeben, das diesen Namen trägt.
[zB]Beispiel
Wenn wir den ersten Gast auf der Party haben möchten, schreiben wir:
Listing 8.35com/tutego/insel/xml/jdom/AlbertTheFirst.java, main()
Element albert = party.getChild( "gast" );
Wenn wir wissen wollen, was Albert trinkt, schreiben wir:
Durch eine Kaskadierung ist es möglich, über das Wurzelelement auf das Getränk des ersten Gastes zuzugreifen:
Eine Liste mit allen Elementen liefert die Methode getChildren(). Sie gibt eine mit Element generisch deklarierte java.util.List mit allen Elementen dieses Namens zurück.
[zB]Beispiel
Falls wir eine Gästeliste der Party haben wollen, schreiben wir:
Diese Liste enthält alle Elemente der Form <gast ...> ... </gast>, die direkt unter dem Element <party> liegen.
extends Content
implements Parent
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<Element> 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<Element> 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.boolean isRootElement()
Gibt einen Wahrheitswert zurück, der ausdrückt, ob das Element die Wurzel der JDOM-Datenstruktur ist.
8.7.8Zugriff 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 Gastes 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():
Sie liefert einen String, sofern eine String-Repräsentation des Inhalts erlaubt ist. Falls das Element keinen Text oder nur Unterelemente besitzt, ist der Rückgabewert ein Leer-String.
[zB]Beispiel
Um an das erste Getränk von Albert zu kommen, schreiben wir:
Listing 8.36com/tutego/insel/xml/jdom/AlbertsDrink.java, Ausschnitt main()
Element albertGetraenk = party.getChild( "gast" ).getChild( "getraenk" );
String getraenk = albertGetraenk.getText();
extends Content
implements Parent
String getText()
Rückgabe des Inhalts des Elements. Dies beinhaltet allen Weißraum und CDATA-Sektionen. Falls der Elementinhalt nicht zurückgegeben werden kann, wird der leere String zurückgegeben.String getTextNormalize()
Verhält sich wie getText(). Weißraum am Anfang und am Ende des Strings wird entfernt. Mehrfach hintereinander gesetzter Weißraum innerhalb des Strings wird auf ein Leerzeichen normalisiert. Falls der Text nur aus Weißraum besteht, wird der leere String zurückgegeben.String getTextTrim()
Verhält sich wie getTextNormalize(), doch Weißraum innerhalb des Strings bleibt erhalten.
Für die Methode getText() muss das Element vorliegen, dessen Inhalt gelesen werden soll. Mit der Methode getChildText() kann der Inhalt eines untergeordneten Elements auch direkt ermittelt werden.
[zB]Beispiel
Lies den Text des ersten untergeordneten Elements mit dem Namen getraenk. Das übergeordnete Element von Getränk ist albert:
Listing 8.37com/tutego/insel/xml/jdom/AlbertsDrink.java, Ausschnitt main()
String getraenk = albert.getChildText( "getraenk" );
In der Implementierung der Methode getChildText(…) sind die Methoden getChild(…) und getText() zusammengefasst.
extends Content
implements Parent
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). Weißraum am Anfang und am Ende des Strings wird entfernt. Weißraum innerhalb des Strings bleibt 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 Leer-String zurückgegeben.String getNamespaceURI()
Rückgabe des Namensraum-URIs, der dem Präfix dieses Elements zugeordnet ist, oder des Standardnamensraums. Falls kein URI gefunden werden kann, wird ein leerer String zurückgegeben.
8.7.9Liste 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.
[zB]Beispiel
Hole eine Liste aller Informationen der Party, und laufe sie mit einem Iterator ab:
Listing 8.38com/tutego/insel/xml/jdom/PartyList.java, main()
Iterator<Content> partyIterator = partyInfo.iterator();
while ( partyIterator.hasNext() )
System.out.println( partyIterator.next() );
extends Content
implements Parent
List<Content> 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.
8.7.10Neue 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.
[zB]Beispiel
Erfrage eine Liste mit allen Unterelementen von albert, erzeuge ein neues Element, und füge es in die Liste ein:
Listing 8.39com/tutego/insel/xml/jdom/AlbertsWater.java, main()
Element albert = party.getChild( "gast" );
List<Content> 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 mit addContent(…) hinzugefügt werden. Die Methode addContent(…) kann nicht nur Text, sondern jeden beliebigen Inhalt einfügen.
[zB]Beispiel
Albert will in Zukunft keinen Wein mehr trinken, sondern nur noch Wasser und Bier. Dazu wird zuerst das erste Unterelement gelöscht:
Ein neues Element wasser wird erzeugt und mit Inhalt gefüllt:
wasser.addContent( "Wasser" );
Das neue Element wird dem Element albert untergeordnet:
Werfen wir erneut einen Blick auf unsere XML-Datei, und entfernen wir das erste Element <getraenk>, das dem ersten Element <gast> untergeordnet ist:
<gast name="Albert Angsthase">
<getraenk>Wein</getraenk>
<getraenk>Bier</getraenk>
<zustand ledig="true" nuechtern="false"/>
</gast>
<party>
[zB]Beispiel
Die Methode removeChild entfernt das Element <getraenk>:
Element albert = party.getChild( "gast" );
Es werden nur die direkten Nachfolger durchsucht. Diese Methode findet das Element <getraenk>Wein</getraenk> nicht.
Mit removeChild(…) wird das Element <getraenk>Wein</getraenk> gelöscht.
extends Content
implements Parent
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 dem URI des Namensraums, die zu dem Element ohne Präfix gehören.Element(String name, String prefix, String uri)
Dieser Konstruktor erzeugt ein neues Element mit dem lokalen Namen name, dem Namenspräfix prefix und dem 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 dem Namen name, das 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(content child)
Ergänzt den Inhalt des Elements um das Element als Unterelement.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 oder null, falls das Element keinem Dokument zugeordnet ist.
8.7.11Attributinhalte 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:
Das Element hat als Attribut name="Albert Angsthase". Diesen Wert liefert die Methode getAttribute(String).getValue() der Klasse Element.
[zB]Beispiel
Lies den Namen des ersten Gastes:
Listing 8.40com/tutego/insel/xml/jdom/Wedding.java, main()
Element albert = party.getChild( "gast" );
Attribute albertAttr = albert.getAttribute( "name" );
String albertName = albert.getAttribute( "name" ).getValue();
Martina möchte wissen, ob Albert noch ledig ist:
Auf ähnliche Weise lässt sich der Wert eines Attributs ändern. Dazu gibt es die Methoden setAttribute(String) der Klasse Attribute und addAttribute(Attribute) der Klasse Element.
[zB]Beispiel
Martina und Albert haben geheiratet, und Albert nimmt den Namen von Martina an:
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>:
wein.addContent( "Wein" );
Danach suchen wir Martina in der Gästeliste und fügen das Element <wein> ein:
while ( gaesteListe.hasNext() ) {
Element gast = (Element) gaesteListe.next();
if ( "Martina Mutig".equals(
gast.getAttribute( "name" ).getValue()) )
gast.addContent( wein );
}
Das Beispiel macht 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.
extends Content
implements Parent
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, ist die Rückgabe null.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 des Attributwerts mit dem Namen name, dem kein Namensraum zugeordnet ist. Es wird null zurückgegeben, falls keine Attribute dieses Namens 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 hinzu. 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 die Methode addAttribute(Attribute attribute) verwendet werden.
implements NamespaceAware, Serializable, Cloneable
String getValue()
Rückgabe des Werts dieses Attributs
Die folgenden 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 den URI zurück, der 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.Attribute setValue(String value)
Setzt den Wert dieses Attributs.
8.7.12XPath
Der Standard XPath (http://www.w3.org/TR/xpath20/) bietet eine Syntax, um einzelne Knoten oder Knotenmengen aus einer XML-Struktur zu erhalten, so wie auch eine Notation im Dateisystem die Angabe einer Datei erlaubt. Der XPath-Standard wird vom W3C verwaltet und findet in vielen Bereichen Anwendung, etwa in XSLT.
XPath betrachtet die XML-Datenstruktur als Baum. Am Anfang dieses Baums steht die XPath-Wurzel, die sich wie üblich vor dem ersten Element des XML-Dokuments befindet. Innerhalb des Baums kann ein XPath-Ausdruck die einzelnen Elemente, deren Attribute und Werte, Verarbeitungsanweisungen und Kommentare selektieren. Die folgenden Beispiele stellen den Zugriff auf Elemente, Elementwerte, Attribute und Attributwerte vor.
Knoten(-mengen) selektieren
XPath bietet zwei Notationen zur Selektierung:
Die einfachere Form ist die Dateisystem-Notation, die sich an den Regeln für das UNIX-Dateisystem orientiert.
Daneben gibt es noch eine spezielle XPath-Notation, die etwas komplizierter ist.
In Tabelle 8.16 werden einige Sprachkonstrukte der beiden Notationen exemplarisch einander gegenübergestellt:
Beschreibung | XPath-Notation | Dateisystem-Notation |
---|---|---|
Zugriff auf den ersten Knoten namens party | /child::party | /party |
übergeordnete Knoten verwenden | /child::party/child::gast/¿ | /party/gast/zustand/.. |
der erste Gast unserer Party | /child::party/child::gast[1] | /party/gast[1] |
alle ledigen Gäste | /child::party/child::gast/¿ | /party/gast/¿ |
Tabelle 8.16Dateisystem-Notation und XPath-Notation im Vergleich
Es gibt ebenso die Möglichkeit, auf Geschwisterknoten und den aktuellen Knoten zuzugreifen. Zudem können Knoten in Abhängigkeit zu der Position im XML-Dokument und bestimmten Werten von Elementen und Attributen abgefragt werden. Um die Beispiele einfach zu halten, wollen wir allerdings immer die Dateisystem-Notation verwenden.
XPath-Tools
Im Code Strings mit XPath-Ausdrücken für XML-Dateien zu nutzen ist nicht immer so praktisch, vor allen Dingen wenn der Ausdruck komplexer ist. Es bietet sich daher an, XML-Dokumente in ein entsprechendes Werkzeug zu laden und über eine grafische Oberfläche die XPath-Ausdrücke zu testen, bis sie »passen«. Eines der Tools ist etwa der XPath Visualizer von Microsoft unter https://xpathvisualizer.codeplex.com/.
XPath-APIs
So, wie es unterschiedliche APIs zur Repräsentation der XML-Bäume im Speicher gibt (W3C DOM, JDOM …), gibt es auch mehrere XPath-APIs. Zwei wichtige sind:
DOM Level 3 XPath: Eine programmiersprachenunabhängige API ausschließlich für Bäume nach dem offiziellen W3C-DOM-Modell. Das Paket javax.xml.xpath setzt diese API in Java um.
Jaxen: eine Java-API, die unterschiedliche DOM-Modelle wie DOM, JDOM und dom4j zusammenbringt
XPath mit JDOM
Um XPath-Anfragen mit JDOM durchzuführen, stehen die Typen org.jdom2.xpath. XPathFactory (nicht javax.xml.xpath.XPathFactory!) und XPathExpression (nicht javax.xml.xpath.XPathExpression!) im Zentrum. Im Hintergrund arbeitet standardmäßig Jaxen. JDOM bringt das nötige Java-Archiv für Jaxen mit. Damit die folgenden Beispiele laufen, muss aus dem Ordner lib des Archivs jdom-xyz.zip die JAR-Datei jaxen-1.1.6.jar in den Klassenpfad aufgenommen werden. Unter http://jaxen.codehaus.org/releases.html lässt sich die jeweils aktuelle Version beziehen, Updates sind aber selten.
Zu einem XPathFactory-Objekt führt die Fabrikmethode XPathFactory.instance(). Diesem Objekt wird im nächsten Schritt der eigentliche XPath-Ausdruck übergeben: XPathFactory.instance().compile(xpath). Das Ergebnis ist ein XPathExpression-Objekt, welches wir fragen können, welche Knoten in der Ergebnismenge liegen. Der XPath-Ausdruck legt fest, was aus dem XML-Dokument gewünscht ist. Die Liste kann Elemente, Attribute oder Strings enthalten, daher sind keine Typinformationen vorhanden und Generics helfen nicht viel.
[zB]Beispiel
Gib die Namen aller Gäste aus:
Listing 8.41com/tutego/insel/jdom/xpath/XPathDemo1.java, Ausschnitt
List<Object> names = xpath.evaluate( doc );
for ( Object object : names ) {
Attribute attribute = (Attribute) object;
System.out.println( attribute.getValue() );
}
Da es keine Typinformationen gibt, liefert evaluate(…) immer nur eine Liste von unbekannten Objekten, die von uns über eine explizite Typanpassung in einen sinnvollen Typ gebracht werden müssen.
[zB]Beispiel
Selektiere mit einem XPath-Ausdruck die Getränke der Gäste, und gib sie auf den Bildschirm aus:
Listing 8.42com/tutego/insel/jdom/xpath/XPathDemo2.java, Ausschnitt
for ( Object object : xpath.evaluate( doc ) )
System.out.println( ((Element)object).getValue() );
Das Ergebnis dieser beiden Aufrufe ist immer eine Knotenmenge. Es gibt aber auch Situationen, in denen nur das erste Element der Ergebnisliste verarbeitet werden soll oder nur ein Element als Ergebnis bei einem XPath-Ausdruck möglich ist, wie zum Beispiel bei der Abfrage von Elementen mit Index-Angabe. Für diesen Fall bietet die Klasse XPathExpression die praktische Methode evaluateFirst(Object context).
[zB]Beispiel
Gib den Namen des ersten Gastes aus:
Listing 8.43com/tutego/insel/jdom/xpath/XPathDemo3.java, Ausschnitt
Object firstGuest = xpath.evaluateFirst( doc );
System.out.println( ((Attribute) firstGuest).getValue() );
static XPathFactory newInstance()
Liefert eine XPathFactory basierend auf der Standard-XPath-Implementierung Jaxen.XPathExpression<Object> compile(String expression)
Übersetzt einen XPath-Ausdruck. Weitere überladene Methoden von compile(…) erlauben Filter und Variablen.
extends java.lang.Cloneable
List<T> evaluate(Object context)
Wertet den vorcompilierten XPath-Ausdruck auf dem übergebenen Inhalt aus.T evaluateFirst(Object context)
Liefert das erste Ergebnis vom ausgewerteten XPath-Ausdruck.String getExpression()
Liefert den XPath-Ausdruck aus String.Weitere Methoden können Variablen setzen und Diagnosen durchführen.
Nutzen von XPath-Ausdrücken
Die Möglichkeiten von XPath können als Alternative zu den Zugriffen über die Datenstrukturen von Java betrachtet werden. Es ist häufig einfacher, mit einem XPath-Ausdruck als mit einzelnen Methodenaufrufen den Pfad zu den Inhalten zu kodieren. Eine Anwendung, die dem Benutzer einen Zugriff auf die XML-Daten bietet, sollte auf jeden Fall XPath anbieten, weil dies der Standard für den Zugriff ist.
Speziell für Datenbanken, die sich auf die Speicherung von XML-Dokumenten spezialisiert haben, ist es üblich, XPath als Abfragesprache zu verwenden. Als Standard in diesem Umfeld gilt XQuery, das eine SQL-ähnliche deklarative Syntax bietet. Ebenso wird XPath im Standard XSLT verwendet, um Knoten für die Umwandlung auszuwählen. Wir stellen diesen Standard im nächsten Abschnitt kurz vor.