15.8 Java Architecture for XML Binding (JAXB)

JAXB ist eine API zum Übertragen von Objektzuständen auf XML-Dokumente. 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 oder eine Schema-Datei. Im Fall von Annotationen bestimmen sie die abzubildenden Elemente, im Fall einer Schema-Datei generiert ein Programm selbstständig die JavaBeans, die die XML-Dokumente repräsentieren. Java 6 integriert JAXB 2.0, und das JDK 6 Update 4 – sehr ungewöhnlich für ein Update – aktualisiert JAXB auf 2.1.

Für diesen Abschnitt wollen wir den Weg über Annotationen wählen – mit Schema-Dateien findet sich eine Dokumentation auf der Webseite http://java.sun.com/developer/technicalArticles/WebServices/jaxb/index.html.

15.8.1 Beans für JAXB aufbauen

Wir wollen eine Disko mit einem DJ verbinden und den Verbund dann in eine XML-Datei übertragen. Beginnen wir bei der Disko:

Listing 15.29 com/tutego/insel/xml/jaxb/Club.java

package com.tutego.insel.xml.jaxb; 
 
import javax.xml.bind.annotation.XmlRootElement; 
 
@XmlRootElement( namespace = "http://tutego.com/" ) 
public class Club 
{ 
  private DJ  dj; 
  private int numberOfPersons; 
 
  public DJ getDj() 
  { 
    return dj; 
  } 
 
  public void setDj( DJ dj ) 
  { 
    this.dj = dj; 
  } 
 
  public int getNumberOfPersons() 
  { 
    return numberOfPersons; 
  } 
 
  public void setNumberOfPersons( int numberOfPersons ) 
  { 
    this.numberOfPersons = numberOfPersons; 
  } 
}

Die nötigen Annotationen für JAXB stammen aus dem Paket javax.xml.bind.annotation. Die Klassen-Annotation @XmlRootElement ist an der JavaBean nötig, wenn die Klasse das Wurzelelement eines XML-Baums bildet. Optional ist das Element namespace für den Namensraum, den wir aber gesetzt haben, da immer ein Namensraum genutzt werden soll.

JAXB beachtet standardmäßig alle Bean-Eigenschaften, also numberOfPersons und dj, und nennt die XML-Elemente nach den Properties. Für den DJ sehen wir eine zweite Klasse vor, die über die Annotation @XmlElement den Namen des XML-Elements überschreibt, damit der Name des DJs nicht im XML-Element <djName> erscheint, sondern in <name>.

Listing 15.30 com/tutego/insel/xml/jaxb/DJ.java

package com.tutego.insel.xml.jaxb; 
 
import javax.xml.bind.annotation.XmlElement; 
 
class DJ 
{ 
  private String djName; 
 
  @XmlElement( name = "name" ) 
  public String getDjName() 
  { 
    return djName; 
  } 
 
  public void setDjName( String name ) 
  { 
    this.djName = name; 
  } 
}

15.8.2 JAXBContext und die Marshaller/Unmarshaller

Ein kleines Testprogramm soll einen DJ mit einer Disko verbinden und beide speichern. Der erste Schritt ist, wie üblich, in Java Objekte aufzubauen und die Assoziation zu bilden.

Listing 15.31 com/tutego/insel/xml/xml/jaxb/ClubMarshaller.java, main()

DJ dj = new DJ(); 
dj.setName( "John Peel" ); 
 
Club club = new Club(); 
club.setDj( dj ); 
club.setNumberOfPersons( 1234 );

Das Ergebnis wird später so aussehen:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<ns2:club xmlns:ns2="http://tutego.com/"> 
    <dj> 
        <name>John Peel</name> 
    </dj> 
    <numberOfPersons>1234</numberOfPersons> 
</ns2:club>

Die JAXB-API

Alles bei JAXB beginnt bei der zentralen Klasse JAXBContext. Sie erzeugt entweder einen Marshaller zum Schreiben oder einen Unmarshaller zum Lesen. Die Funktion newInstance() erwartet standardmäßig eine Aufzählung der Klassen, die JAXB behandeln soll. Die Fabrikmethode createMarshaller() liefert einen Schreiberling, der mit marshal() das Wurzelobjekt in einen Datenstrom schreibt.

Listing 15.32 com/tutego/insel/xml/xml/jaxb/ClubMarshaller.java, main()

JAXBContext context = JAXBContext.newInstance( Club.class ); 
Marshaller m = context.createMarshaller(); 
m.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE ); 
m.marshal( club, System.out );

Das zweite Argument von marshal() ist ein OutputStream (wie System.out) oder Writer – andere Typen sind möglich, sind aber hier nicht so relevant. Um in eine Datei zu schreiben, bemühen wir den FileWriter:

Writer w = null; 
try { 
  w = new FileWriter( "club-jaxb.xml" ); 
  m.marshal( club, w ); 
} 
finally { 
  try { w.close(); } catch ( Exception e ) { } 
}

Mit einer XML-Datei können der Unmarshaller und seine Methode unmarshal() das Objekt rekonstruieren:

Unmarshaller um = context.createUnmarshaller(); 
Club club2 = (Club) um.unmarshal( new FileReader( "club-jaxb.xml" ) ); 
System.out.println( club2.getDj().getDjName() ); 
System.out.println( club2.getNumberOfPersons() );

15.8.3 Weitere JAXB-Annotationen

XML-Schematas können recht komplex werden, sodass auch die Anzahl der JAXB-Annotionen und Möglichkeiten hoch ist. Im Folgenden sollen verschiedene JAXB-Annotationen die Wirkungen 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, 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 aus der XML-Abbildung aus. Das ist nützlich für den XmlAccessType.FIELD oder XmlAccessType.PROPERTY, da dann auch private Eigenschaften geschrieben werden, was 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 @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 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@zack.com</emails> 
</person>

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

<person> 
  <emails>muh@kuh.de zick@zack.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 vordefinierte 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>

Der spezielle Datentyp XMLGregorianCalendar

Neben der Möglichkeit, Datumswerte mit einem XmlJavaTypeAdapter zu übersetzen, bietet JAXB den speziellen 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;

Hierarchien einsetzen

Die XML-Abbildung von Objekten, die in Klassenbeziehungen organisiert sind, bedarf einer besonderen Vorbereitung. Seien Player und Key zwei Klassen, die von GameObject abgeleitet sind (eine Schnittstelle wäre für JAXB auch möglich). 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ß er 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 @XmlElement-Ref. Erstes ist ein Container und Zweites 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 annotiertet 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.)

Ihr Kommentar