7.4 Java 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.

Java 6 integriert JAXB 2.0, und das JDK 6 Update 4 – sehr ungewöhnlich für ein Update – aktualisiert auf JAXB 2.1. Java 7 aktualisiert auf JAXB 2.2.

7.4.1 Bean für JAXB aufbauen

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

Listing 7.6: com/tutego/insel/xml/jaxb/Player.java, Player

@XmlRootElement
class Player
{
  private String name;
  private Date   birthday;

  public String getName()
  {
    return name;
  }

  public void setName( String name )
  {
    this.name = name;
  }

  public void setBirthday( Date birthday )
  {
    this.birthday = birthday;
  }

  public Date getBirthday()
  {
    return birthday;
  }
}

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.

7.4.2 JAXBContext und die Marshaller

Ein kleines Testprogramm baut eine Person auf und bildet sie dann in XML ab – die Ausgabe der Abbildung kommt auf den Bildschirm:

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

Player johnPeel = new Player();
johnPeel.setName( "John Peel" );
johnPeel.setBirthday( new GregorianCalendar(1939,Calendar.AUGUST,30).getTime() );
JAXBContext context = JAXBContext.newInstance( Player.class );
Marshaller m = context.createMarshaller();
m.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE );
m.marshal( johnPeel, System.out );

Nach dem Lauf erscheint auf dem Schirm:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<player>
    <birthday>1939-08-30T00:00:00+01:00</birthday>
    <name>John Peel</name>
</player>

Alles bei JAXB beginnt mit der zentralen Klasse JAXBContext. Die statische Methode JAXBContext.newInstance() erwartet standardmäßig eine Aufzählung der Klassen, die JAXB behandeln soll. Der JAXBContext erzeugt den Marshaller zum Schreiben und den Unmarshaller zum Lesen. Die Fabrikmethode createMarshaller() liefert einen Schreiberling, der mit marshal() das Wurzelobjekt in einen Datenstrom schreibt. Das zweite Argument von marshal() ist unter anderem ein OutputStream (wie System.out in unserem Beispiel), Writer oder File-Objekt.

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

class javax.xml.bind.JAXBContext

• 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.

class javax.xml.bind.Marshaller

• void marshal(Object jaxbElement, File output)
• void marshal(Object jaxbElement, OutputStream os)
• void marshal(Object jaxbElement, Writer writer)
  Schreibt den Objektgraph 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 beziehungsweise 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.

7.4.3 Ganze 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 7.8: com/tutego/insel/xml/xml/jaxb/Room.java, Room

@XmlRootElement( namespace = "http://tutego.com/" )
public class Room
{
  private List<Player> players = new ArrayList<Player>();

  @XmlElement( name = "player" )
  public List<Player> getPlayers()
  {
    return players;
  }

  public void setPlayers( List<Player> players )
  {
    this.players = players;
  }
}

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. Statt allerdings JAXBContext direkt zu nutzen und einen Marshaller zum Schreiben und Unmarshaller zum Lesen zu erfragen, kommt im zweiten Beispiel die Utility-Klasse JAXB zum Einsatz, die ausschließlich statische überladene marshal()- und unmarshal()-Methoden anbietet:

Listing 7.9: com/tutego/insel/xml/jaxb/RoomMarshaller.javal, main()

Player john = new Player();
john.setName( "John Peel" );

Player tweet = new Player();
tweet.setName( "Zwitscher Zoe" );

Room room = new Room();
room.setPlayers( Arrays.asList( john, tweet ) );

File file = new File( "room.xml" );
JAXB.marshal( room, file );

Room room2 = JAXB.unmarshal( file, Room.class );
System.out.println( room2.getPlayers().get( 0 ).getName() ); // John Peel

file.deleteOnExit();

Falls etwas beim Schreiben oder Lesen misslingt, werden die vorher geprüften Ausnahmen in einer DataBindingException ummantelt, die eine RuntimeException ist.

Die Ausgabe ist:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:room xmlns:ns2="http://tutego.com/">
    <player>
        <name>John Peel</name>
    </player>
    <player>
        <name>Zwitscher Zoe</name>
    </player>
</ns2:room>

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

class javax.xml.bind.JAXB

• 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-Objektgraph.

7.4.4 Validierung

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 nicht-validen 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 nicht-validen 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, was 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 7.10: room-schemagen.bat

@echo off
PATH=%PATH%;C:\Program Files\Java\jdk1.7.0\bin
schemagen com.tutego.insel.xml.jaxb.Room

Und rufen wir es auf:

$ room-schemagen.bat
Note: Writing C:\...\schema1.xsd
Note: Writing C:\...\schema2.xsd

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

Listing 7.11: schema1.xsd

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" targetNamespace="http://tutego.com/"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:import schemaLocation="schema2.xsd" />

  <xs:element name="room" type="room" />

</xs:schema>

Listing 7.12: schema2.xsd

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="player" type="player" />

  <xs:complexType name="room">
    <xs:sequence>
      <xs:element ref="player" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="player">
    <xs:sequence>
      <xs:element name="birthday" type="xs:dateTime" minOccurs="0" />
      <xs:element name="name" type="xs:string" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
</xs:schema>

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

Abbildung 7.1: Visualisierung 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 7.4).

<?xml version="1.0" encoding="UTF-8"?>
<ns2:room xmlns:ns2="http://tutego.com/">
  <player>
    <name>John Peel</name>
  </player>
  <player>
    <name>Zwitscher Zoe</name>
  </player>
</ns2:room>

<?xml version="1.0" encoding="UTF-8"?>
<room>
  <player>
    <name>John Peel</name>
  </player>
  <player>
    <name>Zwitscher Zoe</name>
    <name>Heini Hayward</name>
  </player>
</room>

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 7.9, »XML-Schema-Validierung *«):

Listing 7.15: com/tutego/insel/xml/jaxb/ValidatingRoomUnmarshaller, main()

File file = new File( "invalid-room.xml" );
JAXBContext context = JAXBContext.newInstance( Room.class );
Unmarshaller unmarshaller = context.createUnmarshaller();
SchemaFactory sf = SchemaFactory.newInstance( W3C_XML_SCHEMA_NS_URI );
Schema schema = sf.newSchema(
  ValidatingRoomUnmarshaller.class.getResource( "/schema1.xsd" ) );
unmarshaller.setSchema( schema );
Room room = (Room) unmarshaller.unmarshal( file );
System.out.println( room.getPlayers() );

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

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

Exception in thread "main" javax.xml.bind.UnmarshalException
 – with linked exception:
[org.xml.sax.SAXParseException; systemId: 
file:/C:/Insel/programme/18_XML/invalid-room.xml; lineNumber: 2; columnNumber: 7; 
cvc-elt.1: Cannot find the declaration of element 'room'.]

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

Exception in thread "main" javax.xml.bind.UnmarshalException
 – with linked exception:
[org.xml.sax.SAXParseException; systemId: 
file:/C:/Insel/programme/18_XML/invalid-room.xml; lineNumber: 8; columnNumber: 11; 
cvc-complex-type.2.4.d: Invalid content was found starting with element 'name'. 
No child element is expected at this point.]

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

7.4.5 Weitere 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 Standard-Serialisierung, 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:

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:

class Person
{
 @XmlTransient public int id;
 public String firstname;
 public String lastname;
}

<person>
 <firstname>Christian</firstname>
 <lastname>Ullenboom</lastname>
</person>

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:

class Person
{
 public String name;
 public @XmlAttribute int id;
}

<person id="123">
 <name>Christian</name>
</person>

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:

class Person
{
 public String lastname, firstname;
}

<person>
 <lastname>Ullenboom</lastname>
 <firstname>Christian</firstname>
</person>

@XmlType(
 propOrder = { "firstname", "lastname" }
)
class Person
{
 public String lastname, firstname;
}

<person>
 <firstname>Christian</firstname>
 <lastname>Ullenboom</lastname>
</person>

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:

class Person
{
 public int id;
}

<person>
 <id>123</id>
</person>

class Person
{
 public @XmlValue int id;
}

<person>123</person>

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:

class Person
{
  public List<String> emails;
}

<person>
 <emails>muh@kuh.de</emails>
 <emails>zick@zak.com</emails>
</person>

class Person
{
 public @XmlList List<String> emails;
}

<person>
  <emails>muh@kuh.de zick@zak.com</emails>
</person>

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:

class Person
{
  public List<String> emails;
}

<person>
  <emails>muh@kuh.de</emails>
  <emails>zick@zack.com</emails>
</person>

class Person
{
 @XmlElementWrapper(name = "emails")
 @XmlElement(name = "email")
 public List<String> emails;
}

<person>
  <emails>
    <email>muh@kuh.de</email>
    <email>zick@zack.com</email>
  </emails>
</person>

Anpassen der XML-Abbildung

Nicht immer passt die Standard-Abbildung 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 Standard-Abbildung für Datumswerte trifft nicht jeden Geschmack:

class Person
{
  public Date birthday;
}

<person>
  <birthday>1973-03-12T00:00:00+01:00</birthday>
</person>

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

class Person
{
  @XmlJavaTypeAdapter( DateAdapter.class )
  public Date birthday;
}

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

class DateAdapter extends XmlAdapter<String, Date>
{
  private final static DateFormat formatter = new SimpleDateFormat( "dd/MM/yyyy" );

  public Date unmarshal( String date ) throws ParseException {
    return formatter.parse( date );
  }

  public String marshal( Date date )  {
    return formatter.format( date );
  }
}

Damit bekommt die Ausgabe das gewünschte Format:

<person>
    <birthday>12/03/1973</birthday>
</person>

abstract class javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType>

• 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:

class Person
{
 public XMLGregorianCalendar birthday;
}

<person>
 <birthday>1973-03-12</birthday>
</person>

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

Person p = new Person();
GregorianCalendar c = new GregorianCalendar( 1973, Calendar.MARCH, 12 );
XMLGregorianCalendar gc = DatatypeFactory.newInstance().newXMLGregorianCalendar( c );
gc.setTimezone( DatatypeConstants.FIELD_UNDEFINED );
gc.setTime( DatatypeConstants.FIELD_UNDEFINED,
            DatatypeConstants.FIELD_UNDEFINED,   
            DatatypeConstants.FIELD_UNDEFINED );
p.birthday = gc;

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

abstract class javax.xml.datatype.DatatypeFactory

• 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.

<xs:element name="period" type="xs:duration"/>

<period>P1Y1M</period>

Hierarchien einsetzen

Die XML-Abbildung von Objekten, die in Klassenbeziehungen organisiert sind, bedarf einer besonderen Vorbereitung. Nehmen wir an, Player und Key seien 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:

abstract class GameObject {
  public String name;
}

@XmlRootElement public class Player extends GameObject { }

@XmlRootElement public class Key extends GameObject {
  public int id;
}

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

Player player= new Player();
player.name = "Chris";

Key key = new Key();
key.name = "Entretenimiento";
key.id = 12;

Room room = new Room();
room.objects.add( key );
room.objects.add( player );

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

public List<GameObject> objects = new ArrayList<GameObject>();

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:

<room>
  <key>
    <name>Entretenimiento</name>
    <id>12</id>
  </key>
  <player>
    <name>Chris</name>
  </player>
</room>

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:

@XmlRootElement public class Room
{
  @XmlElementRefs(
  {
    @XmlElementRef( type = Player.class ),
    @XmlElementRef( type = Key.class ),
  } )
  public List<GameObject> objects = new ArrayList<GameObject>();
}

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).

7.4.6 Beans 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. Der Java Architecture for XML Binding Compiler, kurz xjc, ist Teil ab JDK 6 und kann von der Kommandozeile, Ant-Skript oder auch von Entwicklungsumgebungen[54](Für Eclipse gibt es dazu das Zusatz-Plugin https://jaxb-workshop.dev.java.net/plugins/eclipse/xjc-plugin.html – NetBeans integriert xjc direkt.) 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.

Die Geocoding API von Yahoo!

Für ein Beispiel wählen wir die Yahoo! Maps Web Services-Geocoding API. Mit ihr lassen sich zu einer Adresse in den USA die Latitude (geografische Breite) und Longitude (geografische Länge) ermitteln (im nächsten Schritt könnte dann ein Kartendienst die Adresse mithilfe der Geodaten anzeigen).

Der Online-Dienst arbeitet über den REST-Stil, das heißt, eine URL enthält die Parameter der Anfrage. Die Webseite von Yahoo! gibt in einem Beispiel für eine URL Folgendes vor:

http://local.yahooapis.com/MapsService/V1/geocode?appid=YD-9G7bey8_
JXxQP6rxl.fBFGgCdNjoDMACQA--&street=701+First+Ave&city=Sunnyvale&state=CA

Der Kartenserver antwortet mit einer XML-Datei (zur Verdeutlichung hübsch formatiert):

<?xml version="1.0"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="urn:yahoo:maps"
           xsi:schemaLocation="urn:yahoo:maps
             http://api.local.yahoo.com/MapsService/V1/GeocodeResponse.xsd">
  <Result precision="address">
    <Latitude>37.416397</Latitude>
    <Longitude>-122.025055</Longitude>
    <Address>701 1st Ave</Address>
    <City>Sunnyvale</City>
    <State>CA</State>
    <Zip>94089-1019</Zip>
    <Country>US</Country>
  </Result>
</ResultSet>

Für unser Beispiel wollen wir das XML-Dokument, das der Yahoo! Maps Web Service liefert, nicht von Hand auseinanderpflücken, sondern JAXB soll uns eine gefüllte JavaBean mit allen Informationen liefern.

xjc aufrufen

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

$ xjc

Usage: xjc [-options ...] <schema file/URL/dir/jar> ... [-b <bindinfo>] ...
If dir is specified, all schema files in it will be compiled.
If jar is specified, /META-INF/sun-jaxb.episode binding file will be compiled.
Options:
  -nv                :  do not perform strict validation of the input schema(s)
  -extension         :  allow vendor extensions – do not strictly follow the
                        Compatibility Rules and App E.2 from the JAXB Spec
  -b <file/dir>      :  specify external bindings files (each <file> must have its own -b)
                        If a directory is given, **/*.xjb is searched
  -d <dir>           :  generated files will go into this directory
  -p <pkg>           :  specifies the target package
  -httpproxy <proxy> :  set HTTP/HTTPS proxy. Format is [user[:password]@]
                        proxyHost:proxyPort
  -httpproxyfile <f> :  Works like -httpproxy but takes the argument in a file to 
                        protect password
  -classpath <arg>   :  specify where to find user class files
  -catalog <file>    :  specify catalog files to resolve external entity references
                        support TR9401, XCatalog, and OASIS XML Catalog format.
  -readOnly          :  generated files will be in read-only mode
  -npa               :  suppress generation of package level annotations 
                        (**/package-info.java)
  -no-header         :  suppress generation of a file header with timestamp
  -target (2.0|2.1)  :  behave like XJC 2.0 or 2.1 and generate code that doesnt use 
                        any 2.2 features.
  -enableIntrospection :  enable correct generation of Boolean getters/setters to 
                          enable Bean Introspection apis
  -contentForWildcard  :  generates content property for types with multiple 
                          xs:any derived elements
  -xmlschema         :  treat input as W3C XML Schema (default)
  -relaxng           :  treat input as RELAX NG (experimental,unsupported)
  -relaxng-compact   :  treat input as RELAX NG compact syntax (experimental,unsupported)
  -dtd               :  treat input as XML DTD (experimental,unsupported)
  -wsdl              :  treat input as WSDL and compile schemas inside it 
                        (experimental,unsupported)
  -verbose           :  be extra verbose
  -quiet             :  suppress compiler output
  -help              :  display this help message
  -version           :  display version information
  -fullversion       :  display full version information

Extensions:
  -Xinject-code      :  inject specified Java code fragments into the generated code
  -Xlocator          :  enable source location support for generated code
  -Xsync-methods     :  generate accessor methods with the 'synchronized' keyword
  -mark-generated    :  mark the generated code as @javax.annotation.Generated
  -episode <FILE>    :  generate the episode file for separate compilation

Eigentlich ist bis auf die Angabe der Schema-Quelle (aus einer Datei oder 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, wo der Generator die erzeugten Dateien ablegt. Yahoo! bietet die Schema-Datei unter http://local.yahooapis.com/MapsService/V1/GeocodeResponse.xsd an, die sich direkt bei xjc angeben lässt:

$ xjc -d "c:/" -p com.tutego.insel.xml.jaxb.yahoo.geocoding http://local.yahooapis.com/ 
MapsService/V1/GeocodeResponse.xsd
parsing a schema...
compiling a schema...
com\tutego\insel\xml\jaxb\yahoo\geocoding\ObjectFactory.java
com\tutego\insel\xml\jaxb\yahoo\geocoding\ResultSet.java
com\tutego\insel\xml\jaxb\yahoo\geocoding\ResultType.java
com\tutego\insel\xml\jaxb\yahoo\geocoding\package-info.java

Das Tool generiert die Klasse ResultSet und ResultType für den komplexen Typ aus dem XML-Schema sowie package-info.java, um eine Paket-Annotation festmachen zu können, und ObjectFactory, die zwei einfache Fabrikmethoden enthält, um ein ResultSet- und ResultType-Objekt aufbauen zu können.

Die von xjc nach c:/ geschriebenen Java-Klassen müssen nun in das Java-Projekt geschoben werden. Dann kann ein Java-Programm den Service mit einer URL ansprechen, einen Unmarshaller aufbauen und sich das Ergebnis-XML in eine JavaBean konvertieren lassen.

JAXBContext context = JAXBContext.newInstance( ObjectFactory.class );
Unmarshaller unmarshaller = context.createUnmarshaller();

// http://developer.yahoo.com/maps/rest/V1/geocode.html
String url = "http://local.yahooapis.com/MapsService/V1/geocode?" +
              "appid=YD-9G7bey8_JXxQP6rxl.fBFGgCdNjoDMACQA--&" +
              "street=701+First+Ave&city=Sunnyvale&state=CA";
ResultSet results = (ResultSet) unmarshaller.unmarshal( new URL(url) );

ResultType result = results.getResult().get( 0 );
System.out.printf( "Longitude = %s, Latitude= %s%n",
                   result.getLongitude(), result.getLatitude() );

Die Bildschirmausgabe zeigt die geografische Länge und Breite der Yahoo!-Konzernzentrale:

Longitude = –122.025055, Latitude= 37.416397

Konflikte in der Schema-Datei *

Der Yahoo!-Service ist zwar nett, aber gerne hätte ich anderes OX-Mapping von anderen XML-Dokumenten gezeigt.[55](Die Google Keyhole Markup Language (KML) Version 2.1 funktioniert auch. Die Schema-Datei http://code.google.com/intl/de/apis/kml/schema/kml21.xsd macht keine Probleme. Seitdem KML aber beim Open Geospatial Consortium liegt, gibt es für Version 2.2 und das Schema http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd Übersetzungsprobleme.) Leider haben viele XML-Schemas ein Problem, sodass sie nicht direkt vom Schema-Compiler verarbeitet werden können. Ein Beispiel zeigt das Dilemma:

<container>
 <head><content title="Titel"/></head>
 <body><content doc="doc.txt"/></body>
</container>

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 und 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? jxc 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 Spezifikation unter https://jaxb.dev.java.net/spec-download.html weist Interessierte in die richtige Richtung.

JAXB-Plugins

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

• 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.

Ihr Kommentar

Wie hat Ihnen das <openbook> gefallen? Wir freuen uns immer über Ihre freundlichen und kritischen Rückmeldungen.