8.4Java Architecture for XML Binding (JAXB) 

Java Architecture for XML Binding (JAXB) ist eine API zum Übertragen von Objektzuständen auf XML-Dokumente und umgekehrt. Anders als eine manuelle Abbildung von Java-Objekten auf XML-Dokumente oder das Parsen von XML-Strukturen und Übertragen der XML-Elemente auf Geschäftsobjekte arbeitet JAXB automatisch. Die Übertragungsregeln definieren Annotationen, die Entwickler selbst an die JavaBeans setzen können, aber JavaBeans werden gleich zusammen mit den Annotationen von einem Werkzeug aus einer XML-Schema-Datei generiert.

JAXB läuft in anderen Versionsnummern als das JDK. Java 7 aktualisiert auf JAXB 2.2, die gleiche Version, die auch Java 8 hat.

 

8.4.1Bean für JAXB aufbauen 

Wir wollen einen Player deklarieren, und JAXB soll ihn anschließend in ein XML-Dokument übertragen:

Listing 8.6com/tutego/insel/xml/jaxb/Player.java, Player

Die Klassen-Annotation @XmlRootElement ist an der JavaBean nötig, wenn die Klasse das Wurzelelement eines XML-Baums bildet. Die Annotation stammt aus dem Paket javax.xml.bind.annotation.

 

8.4.2Utility-Klasse JAXB 

Ein kleines Testprogramm baut eine Person auf und bildet sie dann in XML ab – die Ausgabe der Abbildung kommt auf den Bildschirm. Um ein Objekt in seine XML-Repräsentation zu bringen, lässt sich auf eine einfache statische marshall(…)-Methode der Utility-Klasse JAXB zurückgreifen:

Listing 8.7com/tutego/insel/xml/xml/jaxb/SimplePlayerMarshaller.java, main()

JAXB beachtet standardmäßig alle Bean-Properties, also birthday und name, und nennt die XML-Elemente nach den Properties:

Die marshall(…)-Methode schreibt das in XML transformierte Player-Objekt in unserem Beispiel in den Konsolenausgabestrom. Die JAXB-Klasse bietet daneben auch unmarshall(…)-Methoden, um das Objekt wiederherzustellen, das schauen wir uns im nächsten Beispiel an.

Falls das Schreiben oder Lesen misslingt, gibt es eine RuntimeException. Diese referenziert die intern geprüften Ausnahmen vom Typ DataBindingException.

• static void marshal(Object jaxbObject, File xml)

• static void marshal(Object jaxbObject, OutputStream xml)

• static void marshal(Object jaxbObject, Result xml)

• static void marshal(Object jaxbObject, String xml)

• static void marshal(Object jaxbObject, URI xml)

• static void marshal(Object jaxbObject, URL xml)

• static void marshal(Object jaxbObject, Writer xml)
  Schreibt das XML-Dokument in die angegebene Ausgabe. Im Fall von URI/URL wird ein HTTP-POST gestartet. Ist der Parametertyp String, wird er als URL gesehen und führt ebenfalls zu einem HTTP-Zugriff. Result ist ein Typ für eine XML-Transformation und wird später vorgestellt.

• static <T> T unmarshal(File xml, Class<T> type)

• static <T> T unmarshal(InputStream xml, Class<T> type)

• static <T> T unmarshal(Reader xml, Class<T> type)

• static <T> T unmarshal(Source xml, Class<T> type)

• static <T> T unmarshal(String xml, Class<T> type)

• static <T> T unmarshal(URI xml, Class<T> type)

• static <T> T unmarshal(URL xml, Class<T> type)
  Rekonstruiert aus der gegebenen XML-Quelle den Java-Objektgraphen.

 

8.4.3Ganze Objektgraphen schreiben und lesen 

JAXB bildet nicht nur das zu schreibende Objekt ab, sondern auch rekursiv alle referenzierten Unterobjekte. Wir wollen den Spieler dazu in einen Raum setzen und den Raum in XML abbilden. Dazu muss der Raum die Annotation @XmlRootElement bekommen, und bei Player kann sie entfernt werden, wenn nur der Raum selbst, aber keine Player als Wurzelobjekte zum Marshaller kommen:

Listing 8.8com/tutego/insel/xml/xml/jaxb/Room.java, Room

Zwei Annotationen kommen vor: Da Room der Start des Objektgraphen ist, trägt es @XmlRootElement. Als Erweiterung ist das Element namespace für den Namensraum gesetzt, da bei eigenen XML-Dokumenten immer ein Namensraum genutzt werden soll. Weiterhin ist eine Annotation @XmlElement am Getter getPlayers() platziert, um den Namen des XML-Elements zu überschreiben, damit das XML-Element nicht <players> heißt, sondern <player>.

Kommen wir abschließend zu einem Beispiel, das einen Raum mit zwei Spielern aufbaut und diesen Raum dann in eine XML-Datei schreibt:

Listing 8.9com/tutego/insel/xml/jaxb/RoomMarshaller.java, main()

Die Ausgabe ist:

Da beim Spieler das Geburtsdatum nicht gesetzt war (null wird referenziert), wird es auch nicht in XML abgebildet.

 

8.4.4JAXBContext und Marshaller/Unmarshaller nutzen 

Die Utility-Klasse JAXB verfügt ausschließlich über statische überladene marshal(…)- und unmarshal(…)-Methoden, ist aber in Wirklichkeit nur eine Fassade. Vielmehr ist JAXBContext das tatsächliche Ausgangsobjekt, und davon erfragt werden ein Marshaller zum Schreiben und ein Unmarshaller zum Lesen:

Listing 8.10com/tutego/insel/xml/xml/jaxb/PlayerMarshaller.java, main()

Die Ausgabe ist identisch mit der ersten:

Alles bei JAXB beginnt mit der zentralen Klasse JAXBContext. Die statische Methode JAXBContext.newInstance(Class...) erwartet standardmäßig eine Aufzählung der Klassen, die JAXB behandeln soll; die Klassennamen können auch voll qualifiziert über einen String angegeben werden mit newInstance(String). Der JAXBContext liefert den Marshaller zum Schreiben und den Unmarshaller zum Lesen. Die Fabrikmethode createMarshaller() gibt dabei einen Schreiberling, der mit marshal(Object, …) das Wurzelobjekt in einen Datenstrom schreibt. Das zweite Argument von marshal(Object, …) ist unter anderem ein OutputStream (wie System.out in unserem Beispiel), Writer oder File-Objekt.

• static JAXBContext newInstance(Class... classesToBeBound) throws JAXBException
  Liefert ein Exemplar vom JAXBContext mit Klassen, die als Wurzelklassen für JAXB verwendet werden können.

• abstract Marshaller createMarshaller()
  Erzeugt einen Marshaller, der Java-Objekte in XML-Dokumente konvertieren kann.

• abstract Unmarshaller createUnmarshaller()
  Erzeugt einen Unmarshaller, der XML-Dokumente in Java-Objekte konvertiert.

• void marshal(Object jaxbElement, File output)

• void marshal(Object jaxbElement, OutputStream os)

• void marshal(Object jaxbElement, Writer writer)
  Schreibt den Objektgraphen von jaxbElement in eine Datei oder einen Ausgabestrom.

• void marshal(Object jaxbElement, Node node)
  Erzeugt vom Objekt einen DOM-Knoten. Der kann dann in ein XML-Dokument gesetzt werden.

• void marshal(Object jaxbElement, XMLEventWriter writer)

• void marshal(Object jaxbElement, XMLStreamWriter writer)
  Erzeugt für ein jaxbElement einen Informationsstrom für den XMLEventWriter bzw. XMLStreamWriter. Die StAX-Klassen werden später genauer vorgestellt.

• void setProperty(String name, Object value)
  Setzt eine Eigenschaft der Marshaller-Implementierung. Eine Einrückung etwa setzt das Paar Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE.

Der Unmarshaller bietet über zehn Varianten von unmarshal(…), unter anderem mit den Parametertypen File, InputSource, InputStream, Node, Reader, URL, XMLEventReader.

Tipps uns Tricks mit JAXBContext

Den JAXBContext aufzubauen kostet Zeit und Speicher. Er sollte daher für wiederholte Operationen gespeichert werden. Noch eine Information: Marshaller und Unmarshaller sind nicht threadsicher; es darf keine zwei Threads geben, die gleichzeitig den Marshaller/Unmarshaller nutzen.

Die unmarshal(…)-Methode ist überladen mit Parametern, die typische Datenquellen repräsentieren, etwa Dateien oder Eingabeströme wie ein Reader. Allerdings sind noch andere Parametertypen interessant, und es lohnt sich, hier einmal in die API-Dokumentation zu schauen. Ein spannender Typ ist javax.xml.transform.Source bzw. die Implementierung der Schnittstelle durch JAXBSource. JAXBSource ist die Quelle, aus der JAXB seine Informationen bezieht, um ein neues Java-Objekt zu rekonstruieren.

Das nächste Beispiel nimmt sich das aus dem vorangehenden Beispiel aufgebaute Objekt room als Basis und erzeugt eine tiefe Kopie davon:

Listing 8.11com/tutego/insel/xml/xml/jaxb/RoomCopy.java, main() Ausschnitt

Das Beispiel zeigt somit, wie sich mithilfe von JAXB Objektkopien erzeugen lassen.

 

8.4.5Validierung 

Beim Schreiben und auch beim Lesen von XML-Dokumenten kann JAXB diese gegen ein XML-Schema validieren:

• Falsche XML-Dokumente sollen nicht eingelesen werden. Wenn die Schema-Datei zum Beispiel vorschreibt, dass eine Zahl (etwa für die Bohrtiefe) nur im Wertebereich von 0 bis 10.000 liegen darf, und in einer XML-Datei taucht dann ein Wert von 10.600 auf, dann wäre die XML-Datei nach diesem Schema nicht valide. JAXB sollte sie ablehnen.

• Falsche Werte in JavaBeans dürfen nicht zu nichtvaliden XML-Dokumenten führen. JavaBeans bestehen aus einfachen Settern und Gettern, und die Prüfungen im XML-Schema gehen weit über das hinaus, was üblicherweise eine JavaBean prüft. So kann eine Schema-Definition etwa vorschreiben, dass eine Zeichenkette nach einem ganz speziellen regulären Ausdruck geschrieben wird. In der Regel sind die Setter aber nicht so implementiert, dass sie die Strings direkt prüfen. JAXB sollte es auch nicht erlauben, dass JavaBeans mit falschen Strings geschrieben werden und zu nichtvaliden XML-Dokumenten führen können.

Zentral bei der Validierung ist eine XML-Schema-Datei. Doch wo kommt diese her? Wurden aus der Schema-Datei die JavaBeans generiert, ist logischerweise die Schema-Beschreibung schon da. Sind die JavaBeans aber zuerst da, gibt es erst einmal keine Schema-Datei. Über unterschiedliche Wege lässt sich eine passende Schema-Datei entwickeln:

• Per Hand: Die XML-Schema-Datei wird per Hand selbstständig ohne Tool entwickelt.

• Über die XML-Dokumente: Ein Tool analysiert XML-Dateien und erzeugt aufgrund der erkannten Strukturen eine XML-Schema-Datei. Für dieses Verfahren gibt es eine Reihe von Tools, und einige sind auch online verfügbar, etwa http://tutego.de/go/xml-2-xsd.

• Mit schemagen: Das JDK bringt ein Tool mit dem Namen schemagen mit, das auf JAXB-annotierte Beans angesetzt wird und die Schema-Datei generiert.

Mit schemagen aus JAXB-Beans eine XML-Schema-Datei generieren

Das Tool schemagen befindet sich wie alle anderen JDK-Tools im bin-Verzeichnis. Das Kommandozeilentool erwartet die Angabe einer Quellcodeklasse oder einer compilierten Klasse und spuckt die Schema-Beschreibungen aus. Kapseln wir das in ein Skript:

Listing 8.12room-schemagen.bat

Und rufen wir es auf:

Das Tool erzeugt zwei Schema-Dateien, und sie sehen so aus:

Listing 8.13schema1.xsd

Listing 8.14schema2.xsd

Ein genaues Verständnis des Schemas ist nicht nötig.

Abbildung 8.1Visualisierung des Schemas

Schema-Validierung mit JAXB

Wir wollen die Validierungsmöglichkeiten von JAXB für unsere bekannte Raum-Datei ausprobieren und bewusst zwei Fehler einbauen (siehe Tabelle 8.4).

Tabelle 8.4Nach dem Schema valide und nichtvalide XML-Datei

Das Java-Programm aus dem vorigen Abschnitt schrieb eine korrekte XML-Datei room.xml. In room-invalid.xml fehlt einmal der Namensraum, und dann sind zwei Namen angegeben, obwohl die Schema-Datei nur einen Namen erlaubt.

Damit JAXB den Fehler erkennt, muss es mit der neuen Schema-Datei verbunden werden. JAXP hat eine eigene API für Validierungen, die dafür eingesetzt wird (mehr zur Schema-Validierung folgt später in Abschnitt 8.9, »XML-Schema-Validierung *«):

Listing 8.17com/tutego/insel/xml/jaxb/ValidatingRoomUnmarshaller.java, main()

Es wird ein Exemplar eines Schema-Objekts erzeugt und dieses über setSchema(Schema) beim Unmarshaller gesetzt. (Achtung: JAXB.unmarshal(file, Room.class) wird nicht funktionieren!)

Schon der erste Fehler in invalid-room.xml führt zum Abbruch:

Ist der Fehler behoben, kommt das zweite Problem zum Tragen, nämlich der Umstand, dass es zwei Namen gibt:

Erst wenn der Fehler behoben wurde, gibt es keine Ausnahme mehr, und JAXB gibt Ruhe.

 

8.4.6Weitere JAXB-Annotationen * 

XML-Schemas können recht komplex werden, sodass auch die Anzahl der JAXB-Annotationen und Möglichkeiten hoch ist. Im Folgenden sollen verschiedene JAXB-Annotationen ihre Wirkung auf die XML-Ausgaben zeigen.

Zugriff über Setter/Getter oder Attribute

JAXB kann sich die Werte über JavaBean-Properties – also Setter/Getter – setzen und lesen und/oder direkt auf die Attribute zugreifen. Der Attributzugriff ist vergleichbar mit der Standardserialisierung, und der Zugriff über die Property ist von der JavaBeans Persistence über java. beans.XMLEncoder/java.beans.XMLDecoder realisiert. Welchen Weg JAXB gehen soll, bestimmt die Annotation @XmlAccessorType, die üblicherweise an der Klasse festgemacht wird. Drei Werte sind interessant:

Tabelle 8.5Womit JAXB die Daten austauscht

Die Standardbelegung ist AccessType.PUBLIC_MEMBER.

@Transient

Die Annotation @Transient nimmt ein Element von der XML-Abbildung aus. Das ist nützlich für den XmlAccessType.FIELD oder XmlAccessType.PROPERTY, da dann auch private Eigenschaften geschrieben werden, was allerdings nicht in jedem Fall erwünscht ist:

Tabelle 8.6Beispiel für @Transient und Ergebnis

Werte als Attribute schreiben mit @XmlAttribute

Üblicherweise schreibt JAXB jeden Wert in ein eigenes XML-Element. Soll der Wert als Attribut geschrieben werden, kommt die Annotation @XmlAttribute zum Einsatz:

Tabelle 8.7Beispiel für @XmlAttribute und Ergebnis

Reihenfolge der Elemente ändern

Ist die Reihenfolge der XML-Elemente wichtig, so lässt sich mit dem propOrder von @XmlType die Reihenfolge der Eigenschaften bestimmen:

Tabelle 8.8XML-Abbildung ohne und mit @XmlType(propOrder…)

Einzelner Wert ohne eigenes XML-Element

Gibt es nur ein Element in der Klasse, so kann @XmlValue es direkt ohne Unterelement in den Rumpf setzen:

Tabelle 8.9XML-Abbildung mit @XmlValue

Kompakte Listendarstellung

Die Datenstruktur Liste wird in JAXB üblicherweise so abgebildet, dass jedes Listenelement einzeln in ein XML-Element kommt. Die Annotation @XmlList weist JAXB an, Elemente einer Sammlung mit Leerzeichen zu trennen. Das funktioniert gut bei IDs, aber natürlich nicht mit allgemeinen Zeichenketten, die Leerzeichen enthalten:

Tabelle 8.10Beispiel für @XmlList

Elemente zusätzlich einpacken

Die Annotation @XmlElementWrapper dient dazu, ein zusätzliches XML-Element zu erzeugen. In der Regel wird das für Sammlungen angewendet, wie auch das folgende Beispiel zeigt:

Tabelle 8.11Beispiel für @XmlElementWrapper/@XmlElement

Anpassen der XML-Abbildung

Nicht immer passt die Standardabbildung eines Datentyps gut. Für Farben sollen zum Beispiel nicht die Rot-, Grün- und Blau-Werte einzeln geschrieben werden, sondern alles kompakt in einem String. Auch die Standardabbildung für Datumswerte trifft nicht jeden Geschmack:

Tabelle 8.12Standard-XML-Abbildung eines Datums

Für Aufgaben dieser Art erlaubt die Annotation @XmlJavaTypeAdapter die Angabe einer Konverterklasse, die einmal den Weg vom Objekt in eine String-Repräsentation für das XML-Element und dann vom String in das Objekt zurück beschreibt:

Die eigene Klasse DateAdapter erweitert die vorgegebene JAXB-Klasse XmlAdapter und überschreibt zwei Methoden für beide Konvertierungswege:

Damit bekommt die Ausgabe das gewünschte Format:

• abstract ValueType marshal(BoundType v)
  Konvertiert v in einen Werttyp, der dann in eine XML-Repräsentation überführt wird.

• abstract BoundType unmarshal(ValueType v)
  Überführt den Wert in den XML-Typ.

ValueType und BoundType sind Typvariablen, aber ungewöhnlicherweise sind es keine einfachen Großbuchstaben.

Der spezielle Datentyp XMLGregorianCalendar

Neben der Möglichkeit, Datumswerte mit einem @XmlJavaTypeAdapter/XmlAdapter zu übersetzen, bietet JAXB den speziellen abstrakten Datentyp XMLGregorianCalendar. Die Abbildung in XML ist kompakter:

Tabelle 8.13Standardabbildung von XMLGregorianCalendar

XMLGregorianCalendar wird auch automatisch von dem Werkzeug xjc genutzt, wenn in der XML-Schema-Datei ein Datum vorkommt. Nicht ganz einfach sind die Erzeugung eines XMLGregorianCalendar-Objekts und die Belegung – hier gibt es noch Potenzial für Verbesserungen:

Die abstrakte Klasse DatatypeFactory bietet weitere statische Methoden für Mapper-Objekte, die XML in Objekte überführen oder umgekehrt:

• static DatatypeFactory newInstance()
  Liefert eine DatatypeFactory-Implementierung.

• abstract XMLGregorianCalendar newXMLGregorianCalendar()
  Liefert einen XMLGregorianCalendar, bei dem alle Werte undefiniert sind.

• abstract XMLGregorianCalendar newXMLGregorianCalendar(GregorianCalendar cal)

• XMLGregorianCalendar newXMLGregorianCalendarDate(int year, int month, int day, int timezone)

• XMLGregorianCalendar newXMLGregorianCalendarTime(int hours, int minutes, int seconds,
  int timezone)

• XMLGregorianCalendar newXMLGregorianCalendarTime(int hours, int minutes, int seconds,
  BigDecimal fractionalSecond, int timezone)

• XMLGregorianCalendar newXMLGregorianCalendar(int year, int month, int day, int hour,
  int minute, int second, int millisecond, int timezone)

• abstract XMLGregorianCalendar newXMLGregorianCalendar(BigInteger year, int month, int day,int hour, int minute, int second, BigDecimal fractionalSecond, int timezone)
  Liefert ein XMLGregorianCalendar-Objekt mit unterschiedlichen Vorbelegungen.

Weiterhin gibt es newDuration(…)-Methoden, die javax.xml.datatype.Duration-Objekte liefern. Die Duration-Objekte können auf XMLGregorianCalendar aufaddiert werden bzw. repräsentieren in XML-Schema-Dateien den Typ xs:duration.

Hierarchien einsetzen

Die XML-Abbildung von Objekten, die in Klassenbeziehungen organisiert sind, bedarf einer besonderen Vorbereitung. Nehmen wir an, Player und Key sind zwei Klassen, die von GameObject abgeleitet sind (eine Schnittstelle wäre für JAXB auch möglich). Unser Ziel ist es, Spieler und Schlüssel in einen Raum zu setzen:

Zunächst gilt, dass die konkreten Klassen die Annotation @XmlRootElement tragen müssen. Ein Beispielraum soll einen Spieler und einen Schlüssel beherbergen:

Der Raum referenziert in einer Liste allgemeine Objekte vom Typ GameObject. Nun reicht im Room ein einfaches

zum Halten der Objektverweise aber nicht aus! Beim Verarbeiten würde JAXB die Information fehlen, welches Element denn tatsächlich in der Liste ist, denn ein Player sollte ja etwa durch <player> beschrieben sein und ein Schlüssel durch <key>. Die Abbildung kann nicht <objects> lauten, denn beim Lesen muss ein konkreter Untertyp rekonstruiert werden; wenn JAXB beim Lesen ein <objects> sieht, weiß es erst einmal nicht, ob ein Player oder ein Key zu erzeugen und in die Liste zu hängen ist. Das Ziel ist aber die folgende Abbildung:

Die Lösung liegt in der Anwendung der Annotationen @XmlElementRefs und @XmlElementRef. Ersteres ist ein Container, und das Zweite bestimmt den Typ, der in der Liste zu erwarten ist:

Mit diesem Hinweis berücksichtigt JAXB den Typ der Kinder und schreibt nicht einfach <objects>. Die Elementtypen in der Sammlung sind von uns mit @XmlRootElement annotiert und geben den Namen der XML-Elemente »player« und »key« vor (wir hätten natürlich mit so etwas wie @XmlRootElement(name="sportsman") den XML-Elementnamen überschreiben können).

 

8.4.7Beans aus XML-Schema-Datei generieren 

Da es für existierende XML-Dateien mühselig ist, die annotierten JavaBeans von Hand aufzubauen, gibt es einen Generator, genannt Java Architecture for XML Binding Compiler, kurz xjc.Er kann von der Kommandozeile, vom Ant-Skript oder auch von Entwicklungsumgebungen aus aufgerufen werden. Er nimmt eine XML-Schema-Datei und generiert die Java-Klassen und eine ObjectFactory, die als – wie der Name schon sagt – Fabrik für die gemappten Objekte aus den XML-Elementen fungiert.

xjc aufrufen

Im ersten Schritt wechseln wir auf die Kommandozeile und testen entweder, ob das bin-Verzeichnis vom JDK im Suchpfad ist, oder wir wechseln in das bin-Verzeichnis, sodass wir xjc direkt aufrufen können, und folgende Ausgabe erscheint:

Eigentlich ist bis auf die Angabe der Schema-Quelle (aus einer Datei oder alternativ die URL) keine weitere Angabe nötig. Es ist aber praktisch, zwei Optionen zu setzen: -p bestimmt das Java-Paket für die generierten Klassen und -d das Ausgabeverzeichnis, in dem der Generator die erzeugten Dateien ablegt.

Wetterdaten von Open Weather Map beziehen

Für ein Beispiel wählen wir einen Dienst der Open Weather Map, eines frei zugänglichen Servers für Wetterdaten. Die Webseite http://openweathermap.org/API zeigt den Einsatz der einfachen API, bei der ganz simpel in der URL ein Ort kodiert ist, von dem die Wetterdaten erfragt werden sollen, etwa so: http://api.openweathermap.org/data/2.5/find?q=Frankfurt&units=metric& mode=xml. Alternativ lassen sich Grafiken aufbauen, nach Geo-Koordinaten suchen oder statt XML auch JSON produzieren – für unser Beispiel ist XML ganz gut, das für die Anfrage wie folgt aussieht:

Für unser Beispiel wollen wir das XML-Dokument nicht von Hand auseinanderpflücken, sondern JAXB soll uns eine gefüllte JavaBean mit allen Informationen liefern. Leider gibt es für diese einfache XML-Datei kein XML-Schema, sodass wir uns mit einem Trick behelfen, nämlich aus einer XML-Datei ein Schema generieren lassen und dann mit diesem zu xjc gehen. Es gibt im Internet einige freie XML-nach-Schema-Konverter, für mein Beispiel nutze ich http://www. xmlforasp.net/CodeBank/System_Xml_Schema/BuildSchema/BuildXMLSchema.aspx. Damit die Datentypen korrekt erkannt werden, ändere ich in dem Beispiel die Windrichtung vom Ganzzahltyp <direction value="60"…> auf eine Fließkommazahl, etwa value="60.123", sonst steht im generierten Schema der Typ xsd:int, was später zu Problemen führt, wenn der Dienst eine Fließkommazahl liefert.

Diese Ausgabe sollte in einer Datei gespeichert werden, damit sie von xjc verwendet werden kann; nennen wir diese Datei etwa weather.xsd.

In Eclipse lässt sich xjc einfach aufrufen. Selektiere im Package-Explorer weater.xsd, im Kontextmenü Generate • JAXB Classes…, dann wähle das Java-Projekt aus, anschließend Next. Im folgenden Dialog gib als Paket »com.tutego.insel.xml.jaxb.weather« ein, dann klicke auf Finish. Wichtig! Damit xjc gefunden wird, muss das JDK aktiviert sein, nicht das JRE; nur das JDK bringt das Werkzeug xjc mit.

Ein Aufruf von der Kommandozeile sieht so aus (Ausgabe wie sie Eclipse liefert):

Das Tool generiert alle Typen für den komplexen Typ aus dem XML-Schema, um eine Paket-Annotation festmachen zu können, und ObjectFactory, die einfache Fabrikmethoden enthält, um die gemappten Objekte aufbauen zu können.

Dann kann ein Java-Programm den Service mit einer URL ansprechen und sich das Ergebnis-XML in eine JavaBean konvertieren lassen.

Listing 8.18com/tutego/insel/xml/jaxb/Weather.java, main()

Konflikte in der Schema-Datei *

Leider haben viele XML-Schemas ein Problem, sodass sie nicht direkt vom Schema-Compiler verarbeitet werden können. Ein Beispiel zeigt das Dilemma:

In der hierarchischen Struktur heißt das in <head> und <body> vorkommende XML-Element gleich, nämlich content. Die Schema-Datei kann widerspruchslos definieren, dass die beiden XML-Elemente gleich heißen, aber unterschiedliche Attribute erlauben, sozusagen das Head-Content und das Body-Content. Allein durch ihre Hierarchie, also dadurch, dass sie einmal unter head und einmal unter body liegen, sind sie eindeutig bestimmt. Der Schema-Compiler von Java bekommt aber Probleme, da er diese hierarchische Information in eine flache bringt. Er kann einfach eine Klasse Head und Body aufbauen, aber bei <content> steht er vor einem Problem. Da die Schema-Definitionen unterschiedlich sind, müssten zwei verschiedene Java-Klassen unter dem gleichen Namen Content generiert werden. Das geht nicht, und xjc bricht mit Fehlern ab.

Fehler dieser Art gibt es leider häufig, und sie sind der Grund, warum aus vielen Schemas nicht einfach JavaBeans generiert werden können. Erfolglos ohne weitere Einstellungen sind beispielsweise DocBook, Office Open XML, SVG, MathML und weitere. Doch was könnte die Lösung sein? xjc sieht Konfigurationsdateien vor, die das Mapping anpassen können. In diesen Mapping-Dokumenten identifiziert ein XPath-Ausdruck die problematische Stelle und gibt einen Substitutionstyp an. Die Dokumentation auf der JAXB-Homepage weist Interessierte in die richtige Richtung.

JAXB-Plugins

Auf der Webseite http://java.net/projects/jaxb2-commons/ gibt es eine Reihe nützlicher zusätzlicher Plugins für JAXB. Zu ihnen gehören:

• JAXB2 Basic Plugins: Diese Plugin-Sammlung besteht aus Equals (erzeugt die equals(…)-Methode, wobei der Gleichheitstest über ein Equals-Strategie-Objekt austauschbar ist), HashCode (erzeugt hashCode(), wobei auch hier die Berechnung des Hashwerts über ein Strategie-Objekt erfolgt), ToString (erzeugt toString(), auch wieder über ein externes ToStringStrategy-Objekt), Copyable (erzeugt copyTo(…), um Objektzustände in ein anderes typkompatibles Objekt zu kopieren, und auch clone(); arbeitet dabei mit CopyStrategie), Mergeable (realisiert mergeFrom(…)-Methoden mit MergeStrategy-Objekten, die Zustände eines anderen Objekts mit den eigenen vereinen), JAXBIndex (generiert eine jaxb.index-Datei, die alle generierten Schema-Klassen auflistet), Inheritance und AutoInheritance (erlauben JAXB-Beans, globale Elemente oder komplexe Typen von gewünschten Basisklassen zu erben oder Schnittstellen zu implementieren), Wildcard (spezifiziert, wie sich das Wildcard-Property verhalten soll), Setters (etwas andere Setter-Implementierung bei Sammlungen) und Simplify Plugin (komplexe Properties in Einzel-Properties aufspalten).

• Camelcase Always Plugin: Sind die Elementnamen groß geschrieben, so wird JAXB automatisch groß geschriebene Properties umsetzen, sodass etwa aus NAME der Setter/Getter setNAME(…) und getNAME() entsteht. Das Plugin verhindert dies und nennt die Setter/Getter wie gewohnt setName(…) und getName().

• Value-Constructor Plugin: Jede JavaBean bekommt von xjc nur einen Standard-Konstruktor. Das Plugin gibt einen weiteren Konstruktor hinzu, der alle Attribute direkt initialisiert.

• Default Value Plugin: Ein XML-Schema kann mit defaultValue vordefinierte Initialbelegungen für Attribute angeben. xjc ignoriert diese. Das Plugin wertet diese Vorbelegungen aus und initialisiert die Attribute der JavaBean gemäß den Werten.

• Property Change Listener Injector Plugin: Eine über xjc generierte JavaBean schreibt einen bei setXXX(…) übergebenen Wert direkt in das private Attribut durch. Mit dem Plugin wird ein VetoableChangeListener eingeführt, der gegen Wertänderungen votieren kann.

• Fluent API Plugin: Anstatt eine Bean nur mit Setter-Aufrufen zu initialisieren, etwa eine Person mit setName(…) und setAge(…), generiert das Fluent API Plugin kaskadierbare Methoden, sodass im Beispiel unserer Person nur new Person().withName(…).withAge(…) zu schreiben ist.