Rheinwerk Computing < openbook > Rheinwerk Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger.

Inhaltsverzeichnis
Vorwort
1 Java ist auch eine Sprache
2 Sprachbeschreibung
3 Klassen und Objekte
4 Der Umgang mit Zeichenketten
5 Eigene Klassen schreiben
6 Exceptions
7 Generics<T>
8 Äußere.innere Klassen
9 Besondere Klassen der Java SE
10 Architektur, Design und angewandte Objektorientierung
11 Die Klassenbibliothek
12 Bits und Bytes und Mathematisches
13 Datenstrukturen und Algorithmen
14 Threads und nebenläufige Programmierung
15 Raum und Zeit
16 Dateien, Verzeichnisse und Dateizugriffe
17 Datenströme
18 Die eXtensible Markup Language (XML)
19 Grafische Oberflächen mit Swing
20 Grafikprogrammierung
21 Netzwerkprogrammierung
22 Verteilte Programmierung mit RMI
23 JavaServer Pages und Servlets
24 Datenbankmanagement mit JDBC
25 Reflection und Annotationen
26 Dienstprogramme für die Java-Umgebung
A Die Begleit-DVD
Stichwort
Ihre Meinung?

Spacer
 <<   zurück
Java ist auch eine Insel von Christian Ullenboom
Das umfassende Handbuch
Buch: Java ist auch eine Insel

Java ist auch eine Insel
geb., mit DVD
1482 S., 49,90 Euro
Rheinwerk Computing
ISBN 978-3-8362-1506-0
Pfeil 18 Die eXtensible Markup Language (XML)
  Pfeil 18.1 Auszeichnungssprachen
    Pfeil 18.1.1 Die Standard Generalized Markup Language (SGML)
    Pfeil 18.1.2 Extensible Markup Language (XML)
  Pfeil 18.2 Eigenschaften von XML-Dokumenten
    Pfeil 18.2.1 Elemente und Attribute
    Pfeil 18.2.2 Beschreibungssprache für den Aufbau von XML-Dokumenten
    Pfeil 18.2.3 Schema – eine Alternative zu DTD
    Pfeil 18.2.4 Namensraum (Namespace)
    Pfeil 18.2.5 XML-Applikationen *
  Pfeil 18.3 Die Java-APIs für XML
    Pfeil 18.3.1 Das Document Object Model (DOM)
    Pfeil 18.3.2 Simple API for XML Parsing (SAX)
    Pfeil 18.3.3 Pull-API StAX
    Pfeil 18.3.4 Java Document Object Model (JDOM)
    Pfeil 18.3.5 JAXP als Java-Schnittstelle zu XML
    Pfeil 18.3.6 DOM-Bäume einlesen mit JAXP *
  Pfeil 18.4 Java Architecture for XML Binding (JAXB)
    Pfeil 18.4.1 Bean für JAXB aufbauen
    Pfeil 18.4.2 JAXBContext und die Marshaller
    Pfeil 18.4.3 Ganze Objektgraphen schreiben und lesen
    Pfeil 18.4.4 Validierung
    Pfeil 18.4.5 Weitere JAXB-Annotationen *
    Pfeil 18.4.6 Beans aus XML-Schema-Datei generieren
  Pfeil 18.5 Serielle Verarbeitung mit StAX
    Pfeil 18.5.1 Unterschiede der Verarbeitungsmodelle
    Pfeil 18.5.2 XML-Dateien mit dem Cursor-Verfahren lesen
    Pfeil 18.5.3 XML-Dateien mit dem Iterator-Verfahren verarbeiten *
    Pfeil 18.5.4 Mit Filtern arbeiten *
    Pfeil 18.5.5 XML-Dokumente schreiben
  Pfeil 18.6 Serielle Verarbeitung von XML mit SAX *
    Pfeil 18.6.1 Schnittstellen von SAX
    Pfeil 18.6.2 SAX-Parser erzeugen
    Pfeil 18.6.3 Operationen der Schnittstelle »ContentHandler«
    Pfeil 18.6.4 ErrorHandler und EntityResolver
  Pfeil 18.7 XML-Dateien mit JDOM verarbeiten
    Pfeil 18.7.1 JDOM beziehen
    Pfeil 18.7.2 Paketübersicht *
    Pfeil 18.7.3 Die Document-Klasse
    Pfeil 18.7.4 Eingaben aus der Datei lesen
    Pfeil 18.7.5 Das Dokument im XML-Format ausgeben
    Pfeil 18.7.6 Der Dokumenttyp *
    Pfeil 18.7.7 Elemente
    Pfeil 18.7.8 Zugriff auf Elementinhalte
    Pfeil 18.7.9 Liste mit Unterelementen erzeugen *
    Pfeil 18.7.10 Neue Elemente einfügen und ändern
    Pfeil 18.7.11 Attributinhalte lesen und ändern
    Pfeil 18.7.12 XPath
  Pfeil 18.8 Transformationen mit XSLT *
    Pfeil 18.8.1 Templates und XPath als Kernelemente von XSLT
    Pfeil 18.8.2 Umwandlung von XML-Dateien mit JDOM und JAXP
  Pfeil 18.9 XML-Schema-Validierung *
    Pfeil 18.9.1 SchemaFactory und Schema
    Pfeil 18.9.2 Validator
    Pfeil 18.9.3 Validierung unterschiedlicher Datenquellen durchführen
  Pfeil 18.10 Zum Weiterlesen


Rheinwerk Computing - Zum Seitenanfang

18.4 Java Architecture for XML Binding (JAXB)  Zur nächsten ÜberschriftZur vorigen Überschrift

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


Rheinwerk Computing - Zum Seitenanfang

18.4.1 Bean für JAXB aufbauen  Zur nächsten ÜberschriftZur vorigen Überschrift

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

Listing 18.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.


Rheinwerk Computing - Zum Seitenanfang

18.4.2 JAXBContext und die Marshaller  Zur nächsten ÜberschriftZur vorigen Überschrift

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

Listing 18.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 kommt 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 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 auf der Marshaller-Implementierung. So setzt das Paar Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE eine Einrückung.

Rheinwerk Computing - Zum Seitenanfang

18.4.3 Ganze Objektgraphen schreiben und lesen  Zur nächsten ÜberschriftZur vorigen Überschrift

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

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



Rheinwerk Computing - Zum Seitenanfang

18.4.4 Validierung  Zur nächsten ÜberschriftZur vorigen Überschrift

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, eine Zahl (etwa für die Bohrtiefe) darf nur im Wertebereich von 0 bis 10.000 liegen, 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.
  • Fasche 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 kann.

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

C:\Insel\programme\2_16_XML\src>schemagen com.tutego.insel.xml.jaxb.Room -cp Umbruch
  "c:\Program Files\Java\jdk1.6.0\lib\tools.jar"
Note: Writing C:\Insel\programme\18_XML\src\schema1.xsd
Note: Writing C:\Insel\programme\18_XML\src\schema2.xsd

Der Schalter -cp muss (bisher) auf tools.jar stehen.

Zwei Schema-Dateien erzeugt das Tool, und sie sehen so aus:

Listing 18.10  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 18.11  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 18.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:


Valide XML-Datei (nach Schema) Nicht-valide XML-Datei (nach Schema)

Listing 18.12  room.xml

<?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>

Listing 18.13  room-invalid.xml

<?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 zu Schema-Validierung später in Abschnitt 18.9, »XML-Schema Validierung *«):

Listing 18.14  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( Umbruch
"/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/ Umbruch
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 hoch, nämlich dass es zwei Namen gibt:

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

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


Rheinwerk Computing - Zum Seitenanfang

18.4.5 Weitere JAXB-Annotationen *  Zur nächsten ÜberschriftZur vorigen Überschrift

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


@XmlAccessorType( XmlAccessType.FIELD )

jedes nicht-statische Attribut

@XmlAccessorType( XmlAccessType.PROPERTY )

jede JavaBean-Property

@XmlAccessorType( XmlAccessType.PUBLIC_MEMBER )

nur jede öffentliche JavaBean-Property oder jedes öffentliche Attribut


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 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 @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 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öhnlicher Weise 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 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 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.

Beispiel Eine XML-Schema-Datei soll für das Element period eine Dauer definieren:

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

Angewendet kann es so aussehen, um die Dauer von einem Jahr und einem Monat anzugeben:

<period>P1Y1M</period>

Werden aus Schema-Dateien die Java-Beans automatisch generiert, wird Duration für xs:duration eingesetzt.


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


Rheinwerk Computing - Zum Seitenanfang

18.4.6 Beans aus XML-Schema-Datei generieren  topZur vorigen Überschrift

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 [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 vor:

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

Der Kartenserver antwortet mit einer XML-Datei (zum 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
grammar is not specified

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        : behave like XJC 2.0 and generate code that doesnt use 
                       any 2.1 features.
  -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

Extensions:
  -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 Umbruch
  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(), Umbruch
  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. [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. Seidem 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 dass 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 diese Art gibt es leider häufig, und sind der Grund, warum aus vielen Schemas nicht einfach JavaBeans generiert werden kann. 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. Darunter:

  • 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. Dieses 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. >> Zum Feedback-Formular
 <<   zurück
 Ihre Meinung?
Wie hat Ihnen das <openbook> gefallen?
Ihre Meinung

 Buchempfehlungen
Zum Katalog: Java ist auch eine Insel






 Java ist auch
 eine Insel


Zum Katalog: Java SE Bibliotheken






 Java SE Bibliotheken


Zum Katalog: Professionell entwickeln mit Java EE 7






 Professionell
 entwickeln mit
 Java EE 7


Zum Katalog: Einstieg in Eclipse






 Einstieg in
 Eclipse


Zum Katalog: Einstieg in Java






 Einstieg in
 Java


 Shopping
Versandkostenfrei bestellen in Deutschland und Österreich
InfoInfo




Copyright © Rheinwerk Verlag GmbH 2011
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das <openbook> denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


[Rheinwerk Computing]

Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de