Java Architecture for XML Binding XI Technologieeinführung... XII Programmiertutorials...XII Referenz... XII Feedback...XIII

Transkript

1

2 Inhalt Vorwort...XI Java Architecture for XML Binding XI Technologieeinführung... XII Programmiertutorials...XII Referenz... XII Feedback...XIII 1 JAXB im Überblick Ziele Entstehung Architektur Annotationen Der Schema-Compiler Der Schema-Generator Das Binding Framework = 2.0? Basistechnologien XML-Schema Namespaces verwenden...21 Elementdeklarationen in XML-Schema Vererbung Kardinalitäten Offene Schemas definieren Namespaces importieren und referenzieren Eindeutigkeit durch ID und IDREF Dokumentation mit Annotationen Das fertige Beispielschema...46 V

3 Inhalt 2.2 XPath Die XPath-Sicht auf XML XPath-Ausdrücke verwenden Beispiele XPath in Java ANT ANT-Übersicht Installation und Aufruf Häufig verwendete Elemente Benutzerdefinierte Tasks xjc und schemagen Tasks Ein Beispiel Hallo JAXB! Systemvoraussetzungen...61 Die Entwicklungsumgebung einrichten JAXB-Referenzimplementierung installieren Die JAXB-Bibliotheken einbinden Die Struktur des Beispielprojekts Am Anfang steht immer: Hallo Welt! Der Weg von Java zu XML Der Weg von XML zu Java Zusammenfassung JAXB-API Die ersten Schritte Am Anfang war der JAXBContext Die Klasse JAXBIntrospector verwenden Objekte erzeugen mit der ObjectFactory Zusammenfassung Marshalling Das Marshaller-Objekt anlegen Den Marshalling-Prozess starten Den Marshalling-Prozess konfigurieren Das fertige Beispiel Marshalling beliebiger Objekte Zusammenfassung Unmarshalling Das Unmarshaller-Objekt anlegen Den Unmarshalling-Prozess starten Den Unmarshalling-Prozess konfigurieren Das fertige Beispiel Das xsi:type-attribut beim Unmarshalling verwenden Elemente verarbeiten Unmarshalling von Teilen eines XML-Dokuments Flexibles Unmarshalling nutzen...95 VI

4 Inhalt Zusammenfassung Validierung Beim Unmarshalling validieren Beim Marshalling validieren Benutzerdefinierte Validierung Zusammenfassung Callback-Mechanismen einsetzen Die Listener-Klasse verwenden Callback-Methoden auf Klassenebene definieren Zusammenfassung Die Binder-Komponente verwenden Eine DOM-Sicht erstellen Die Klasse javax.xml.bind.binder Transformation mit unmarshal und marshal Navigation mit getxmlnode und getjaxbnode Synchronisation mit updatexml und updatejaxb Konkrete Anwendungsfälle Zusammenfassung XML-Schema zu Java Bindungskonfigurationen Eine Bindungskonfiguration definieren Bindungskonfigurationen per xjc-task einbinden Den XJC-Schema-Compiler programmatisch starten Externe Bindungskonfigurationen auf der Kommandozeile Ein Wort zu Versionen Der Sichtbarkeitsbereich Zusammenfassung Die erste Bindungskonfiguration Zusammenfassung Fünf Bindungsdeklarationen für den Alltag Aufzählungen anpassen mit jaxb:collectiontype Paketnamen anpassen mit jaxb:package Generierte Klassen anpassen mit jaxb:class Änderungen auf Komponentenebene mit jaxb:property Dokumentieren mit jaxb:javadoc Zusammenfassung XML-Bezeichner anpassen Einzelne Namenskonflikte auflösen Präfixe und Suffixe mit jaxb:namexmltransform Unterstriche verarbeiten mit jaxb:underscorebinding Bezeichner in Enumerationen Verwenden von Java-Schlüsselwörtern als Bezeichner Java-Namenskonventionen Zusammenfassung Datentypen anpassen VII

5 Inhalt Datentypen explizit angeben mit jaxb:basetype Datentypen konvertieren mit jaxb:javatype Zusammenfassung Deklarationen überlagern Noch mehr Bindungsdeklarationen Ableiten von einer Oberklasse mit xjc:superclass Ein Wurzelinterface angeben mit xjc:superinterface Erweiterung von jaxb:javatype mit xjc:javatype Das Experiment: xjc:simple Zusammenfassung Java zu XML-Schema JAXBContext und JAXBElement ganz ohne Schema Einfache Elementkonfigurationen Wurzelelemente definieren Der Standardmodus Abbildung als XML-Element explizit konfigurieren Java-Eigenschaften an XML-Attribute binden Java-Eigenschaften an XML-Elementinhalte binden Bindung an XML unterdrücken Reihenfolge der XML-Elemente beeinflussen Namen und Verschachtelung des XML-Typs einstellen XML-Elemente referenzieren Namespace konfigurieren Listen und Elementmischungen Der Standardmodus für Java-Arrays und Java-Listen Listen und Arrays an simpletype/list-deklarationen binden Mehrere Elemente im gleichen Feld speichern Elementlisten verpacken Mischungen von Elementen und Text Enumerationen Enumerationen an XML binden: Standardverhalten Bindung von Enumerationen konfigurieren Eigene Typbindungen definieren Basisdatentyp als Speicherdatentyp Komplexe Datentypen als Speicherdatentypen Unbekannte Attribut- und Elementwerte binden Wildcard-Attribute definieren Wildcard-Elemente deklarieren Lax fischen Objektgraphen in XML abbilden Elemente über Factory-Klassen definieren JAXB-Referenz XJC Kommandozeilenbefehl XJC ANT-Task VIII

6 Inhalt 7.3 schemagen-kommandozeilenbefehl schemagen-ant-task JAXB-Annotationen XmlAccessorOrder XmlAccessorType XmlAnyAttribute XmlAnyElement XmlAttachmentRef XmlAttribute XmlElement XmlElementDecl XmlElementRef XmlElementRefs XmlElements XmlElementWrapper XmlEnum XmlEnumValue XmlID XmlIDREF XmlInlineBinaryData XmlList XmlJavaTypeAdapter XmlJavaTypeAdapters XmlMimeType XmlMixed XmlNs XmlRegistry XmlRootElement XmlSchema XmlSchemaType XmlSchemaTypes XmlTransient XmlType XmlValue Typkonversionen Java zu XML-Schema Typkonversionen XML-Schema zu Java XML-Elemente der Bindungskonfiguration Globale Einstellungen Schemaspezifische Einstellungen Komponentenspezifische Einstellungen Register IX

7 2 2 Basistechnologien In diesem Kapitel gehen wir auf die im Rahmen der JAXB verwendeten Basistechnologien XML-Schema, XPath und ANT ein. 2.1 XML-Schema XML ist seit langem eins der Standardformate, wenn es um die plattformunabhängige Repräsentation von Daten geht. Das Besondere an XML: Es werden nicht nur die reinen Daten, sondern auch die Metadaten in einem XML-Format gespeichert. Also nicht nur die Information Müller, sondern auch die Information Müller ist der Nachname eines Kunden. Rein technisch betrachtet ist XML ein sehr redundantes und aufgeblähtes Format, als Datenaustauschformat hat es den großen Vorteil, dass jeder Entwickler ein XML- Dokument öffnen und lesen kann, ohne dass die Daten zusätzlich aufbereitet werden müssten. Besonders vielseitig wird XML durch die Möglichkeit, die erwarteten Daten in Form einer DTD oder eines XML-Schemas zu spezifizieren. Über solche Formatbeschreibungen lassen sich Form und Gültigkeit eines Datensatzes beschreiben: Jeder Kundendatensatz muss einen Namen angeben, eine Adressangabe ist optional möglich. In diesem Kapitel möchten wir auf die wesentlichen Möglichkeiten von XML-Schema eingehen, das sich zu dem umfangreichsten und genauesten Format zur Beschreibung von Formaten gemausert hat. Mit XML-Schema können wir Grammatiken definieren, also Einschränkungen und Regeln zu den Daten in einem XML-Dokument. Ein mit XML-Schema beschriebenes Dokument kann anhand der Grammatik auf seine Gültigkeit überprüft werden. Eine solche Validierung wird von einem Schema-Validierer durchgeführt. So lassen sich z.b. Daten beschreiben, die dem Nachrichtenaustausch zwischen verschiedenen Anwendungen dienen. Durch Verwendung eines XML-Schemas wird den einzelnen Komponenten ein einheitliches, überprüfbares Format bereitgestellt. 17

8 2 Basistechnologien Im Zusammenhang mit XML-Schema werden oft die Begriffe Schemadokument und Schemainstanz verwendet. Ein XML-Schemadokument definiert die oben genannte Grammatik zu den XML- Daten und legt so deren Struktur für alle Beteiligten fest. Eine XML-Schemainstanz hingegen ist ein XML-Dokument, das ein Schemadokument verwendet, um XML-Daten konform zu einer Grammatik zu beschreiben. XML-Schema wird heute von vielen XML-basierten Standards und APIs verwendet wie z.b. der Web Service Description Language (WSDL). Ursprünglich vorgeschlagen von Microsoft, wurde die Sprache schließlich 2001 als Empfehlung durch das Webkonsortium W3C 1 offiziell veröffentlicht. Im Gegensatz zu anderen Grammatikdefinitionen wie DTD, die mittels einer zusätzlichen Sprache definiert werden, basiert XML-Schema selbst auch auf XML. Weitere Vorzüge sind die Erweiterbarkeit und eine Vielzahl an vordefinierten Datentypen. Außerdem werden objektorientierte Konzepte wie Namensräume und Vererbung unterstützt. Aus diesen Gründen hat sich XML-Schema mittlerweile gegen DTD durchgesetzt. Aber auch XML- Schema hat natürlich Konkurrenz, der wichtigste Standard ist hier wohl RelaxNG, für den in JAXB bereits experimentelle Unterstützung zu finden ist. Bei der Arbeit mit JAXB wird uns XML-Schema ein ständiger Begleiter sein. Es gibt eine ganze Reihe toller Bücher zum Thema XML-Schema. Daher wird dieses Kapitel sich darauf beschränken, einen Überblick über die wichtigsten Konzepte zu geben, die wir für das unmittelbare Verständnis der Beispiele in diesem Buch für notwendig halten. Um ein XML-Schema definieren zu können, benötigen wir natürlich ein Grundverständnis für den Aufbau eines XML-Schemas. Daher wird zunächst der Schemaaufbau unter Verwendung von Namensräumen erläutert. Danach werden wir uns ausführlich der Definition von Datentypen widmen, da wir diese später mit JAXB an unsere Java-Klassen binden wollen. Ein weiteres wichtiges Thema in diesem Zusammenhang ist die Formulierung von Einschränkungen auf diesen Datentypen. Da wir natürlich mit objektorientierten Datenmodellen arbeiten wollen, darf auch die Vererbung von Datentypen in XML-Schema nicht fehlen. Vererbung ist aber nur ein Mittel zur Erweiterbarkeit von Schemas. Wir werden uns daher noch mit weiteren Mitteln zur Definition von erweiterbaren, offenen Schemas befassen. In dieser Hinsicht betrachten wir abschließend das Zusammensetzen eines Schemas aus mehreren Teilschemas, was uns eine komponentenbasierte Definition der Daten ermöglicht. Die genannten Konzepte werden wir anhand eines Objektmodells darstellen, das sukzessive im Verlauf des Kapitels aufgebaut wird. Auf diesem Domänenobjektmodell, im Englischen das Domain Object Model, werden dann alle weiteren Programmierbeispiele im Verlauf des Buches aufbauen Document Type Definitions 18

9 2.1 XML-Schema Da eine erschöpfende Behandlung von XML-Schema weit über den Rahmen dieses Kapitels hinausgeht, sei für weitere Informationen auf das Buch XML Schema von Eric van der Vlist verwiesen. Ein XML-Schemadokument bildet also die Grundlage einer Java-XML-Bindung mit JAXB. Ein solches Schemadokument beschreibt dabei sowohl Struktur als auch Datentypen einer Schemainstanz. Im einfachsten Fall besteht ein Schemadokument aus der Definition der gültigen Elemente sowie deren Reihenfolge und Anordnung. Es lassen sich aber auch komplexe Strukturen aufbauen, die sich über mehrere Schemas erstrecken und ganze Datentyphierarchien aufbauen. Im Verlauf dieses Kapitels werden wir mehrere Schemas entwickeln und diese zu einer komplexen Struktur zusammenfügen. Zunächst aber konzentrieren wir uns auf ein einfaches Beispiel: Stellen wir uns einen Online-Banking-Service vor, der auf eintreffende XML-Requests von Clients eine entsprechende Response im XML-Format zurückliefert. Im Request wird eine Kunden-ID mitgeliefert. Als Antwort liefert der Service dann entsprechende Informationen über die Stammdaten, die Kontodaten sowie über ein evtl. vorhandenes Aktienportfolio des Kunden. Diese Daten werden z.b. aus einer Datenbank gewonnen. Die Struktur der vom Service zurückgelieferten Daten wird durch die folgenden XML-Schemas definiert. response: Enthält die Antwort des Service auf einen eingehenden Request. customerelement: Enthält die Stammdaten eines Kunden. accountelement: Enthält alle kontorelevanten Daten eines Kunden. portfolioelement: Repräsentiert das Aktienportfolio eines Kunden. Das Schema response nutzt dabei die in den Schemas customer, account und portfolio erstellten Datentypen, um eine Datenstruktur für die Ausgabe an den Client zusammenzustellen. Abbildung 2.1 Das response-schema Um nicht gleich die Übersicht zu verlieren, sehen wir uns zunächst nur die Stammdaten eines Kunden an. 19

10 2 Basistechnologien Abbildung 2.2 Stammdaten eines Kunden Für diese Daten sieht ein einfaches Schemadokument nun so aus: <?xml version="1.0" encoding="utf-8"?> <xs:schema targetnamespace=" xmlns:xs=" <xs:element name="customerelement"> <xs:complextype> <xs:sequence> <xs:element name="name" type="xs:string" /> <xs:element name="address" type="xs:string" /> <xs:element name="birthdate" type="xs:date" /> <xs:element name="phone" type="xs:integer" /> <xs:element name=" " type="xs:string" /> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> Das Dokument oben legt für den Kunden also ein Element mit den entsprechenden Unterelementen für die Stammdaten an. Das schema-element Sehen wir uns zunächst den Kopf dieses Dokuments ein wenig genauer an. Ein Schemadokument beginnt immer mit dem einleitenden Wurzelelement schema. Im obigen Beispiel sind in diesem schema-element zwei weitere Attribute definiert, die beide jeweils eine URL als Wert enthalten. <?xml version="1.0" encoding="utf-8"?> <xs:schema targetnamespace=" xmlns:xs=" </xs:schema> 20

11 2.1 XML-Schema Diese Attribute definieren verschiedene Namensräume in unserem Schemadokument. Diese werden gewöhnlich im einleitenden schema-element definiert. Ihre Verwendung wird im nächsten Abschnitt behandelt. Sehen wir uns zunächst noch der Vollständigkeit halber ein entsprechendes XML-Dokument zu unserem Schemadokument an. <?xml version="1.0"?> <cst:customerelement xmlns:cst=" <name>rainer Bier</name> <address>friedrichshain 555, Berlin, Germany</address> <birthdate> </birthdate> <phone> </phone> </cst:customerelement> Dieses Dokument nutzt also das vorher definierte customerelement-element, um einen Kundendatensatz zu beschreiben Namespaces verwenden In der Einleitung wurde erwähnt, dass durch XML-Schema Grammatiken definiert werden. Eine Grammatik setzt grundsätzlich auf einem bestimmten Vokabular auf. Solche Vokabulare können wir in XML-Schema durch Definition von Elementen frei bestimmen. Was aber, wenn sich unsere Datentypen mit den Definitionen anderer Vokabulare überschneiden? Das Problem solcher Namenskonflikte wird in XML-Schema durch die Verwendung von Namensräumen, den Namespaces, gelöst. Die XML-Spezifikation definiert einen Namespace wie folgt: An XML namespace is a collection of names, identified by a URI reference [RFC2396], which are used in XML documents as element types and attribute names. Ein Namespace schafft also einen gemeinsamen Kontext für eine Menge von Elementen, Attributen und Datentypen. Ziel dabei ist es, eine einheitliche und eindeutige Bezeichnung der Elemente zu ermöglichen. Vergleichbar zu einem XML-Namespace ist ein Java-Paket, in dem Java-Klassen gruppiert werden, um Namenskonflikte zu verhindern und den Klassen einen gemeinsamen Kontext zu geben. Das Standardvokabular von XML-Schema besitzt z.b. den Namespace der auch schon im einleitenden Beispiel verwendet wurde. Dieser Namespace enthält die grundlegenden Elemente zur Definition neuer Elemente, Attribute und Typen. Wenn wir nun weitere Elemente definieren, können wir diese einem anderen, von uns gewählten Namespace zuordnen. Bei der Benennung unserer Elemente bleiben wir dadurch völlig frei Namespaces definieren Eine Namespace-Definition wie beispielsweise xmlns:xs=" setzt sich zusammen aus: 21

12 Register A all 28 Annotationen 5 XmlAccessorOrder 227, 306 XmlAccessorType 205, 307 XmlAnyAttribute 284, 311 XmlAnyElement 286, 312 XmlAttachmentRef 314 XmlAttribute 216, 314 XmlElement 210, 316 XmlElementDecl 295, 318 XmlElementRefs 236, 261, 320, 321 XmlElements 251, 323 XmlElementWrapper 264, 324 XmlEnum 271, 325 XmlEnumValue 273, 326 XmlID 291, 327 XmlIDREF 290, 328 XmlInlineBinaryData 330 XmlJavaTypeAdapter 181, 276, 331, 332, 370 XmlList 249, 330 XmlMimeType 333 XmlMixed 266, 333 XmlNs 334 XmlRegistry 295, 334 XmlRootElement 201, 335 XmlSchema 239, 336 XmlSchemaType 338, 339 XmlTransient 223, 340 XmlType 228, 341 XmlValue 221, 342 anonymoustypename namexmltransform 362 ANT 55 classpath-task 57 javac-task 57 property-task 57 schemagen-task 66, 304 Target 56 Task 56 taskdef-task 58 xjc-task 68, 301 any 38 anyattribute 38 attachmentref 149 attribute 25 B basetype 169, 366 Beispielschemas 46 Binder 13,

13 Register Binding Framework 5, 10 Bindungsdeklarationen attachementref 149 basetype 169, 366 choicecontentproperty 349 class 138, 363 collectiontype 138, 347 dom 378 enablefailfastcheck 349 enablejavanamingconventions 168, 352 Externe importieren 185 factorymethod 380 fixedattributeasconstantproperty 150, 348 generateelementclass 352 generateelementproperty 147, 365 generateissetmethod 136, 349 generatevalueclass 354 globalbindings 346 inlinebinarydata 379 javadoc 138, 360, 363, 365, 373, 377 javatype 172, 369 localscoping 357 mapsimpletypedef 356 namexmltransform 157, 360 optionalproperty 355 package 138, 359 parsemethod 371 printmethod 180, 371 property 138, 364 schemabindings 359 typesafeenumbase 351 typesafeenumclass 162, 372 typesafeenummaxmembers 352 typesafeenummember 163, 375 typesafeenummembername 164, 352 underscorebinding 159, 351 Build-Prozess 55 Build-Skript 56 C choice 28 choicecontentproperty 349 class 138, 363 collectiontype 138, 347 complextype 27 D DataTypeConverter 177 Default-Namespace 24 DocumentBuilderFactory 54 dom 378 E element 25 elementname namexmltransform 361 enablefailfastcheck 349 enablejavanamingconventions 168, 352 Entwicklungsumgebung 61 enumeration 32 Event Callbacks 12 F Facets 31 factorymethod 380 fixedattributeasconstantproperty 150, 348 Flexible Unmarshalling 11 G generateelementclass 352 generateelementproperty 147, 365 generateissetmethod 136, 349 generatevalueclass 354 globalbindings 346 H Hallo Welt 61 I ID 43 IDREF

14 Register import 42 include 42 inlinebinarydata 379 J javac 57 javadoc 138, 377 class 363 package 360 property 365 typesafeenum 373 typesafeenummember 373 javatype 172, 369 JAXB-API 71 JAXB-Bibliotheken 62 JAXBContext 72, 194, 295 JAXBElement 78, 85, 91, 194, 296 JAXBIntrospector 75 JAXB-Referenzimplementierung 62 L localscoping 357 M mapsimpletypedef 356 Marshaller 79 Callback-Mechanismus 108 formatierte Ausgabe 81 schemalocation angeben 82 validieren 99 Marshalling 12, 79 modelgroupname namexmltransform 361 N Namespaces 21, 237 XPath 54 namexmltransform 157, 360 anonymoustypename 362 elementname 361 modelgroupname 361 typename 360 O ObjectFactory 77, 295 optionalproperty 355 P package 138, 359 parsemethod 180, 371 printmethod 180, 371 property 364 R restriction 31 S schema 20 schemabindings 359 Schema-Compiler 5, 8 schemagen 58, 304 Kommandozeilenbefehl 303 Schema-Generator 5, 9 schemagen-task 66 SchemaOutputResolver 197 sequence 28 simpletype 30 Structural Unmarshalling 11 T Target 56 Target-Namespace 22 Task 56 typename namexmltransform 360 typesafeenumbase 351 typesafeenumclass 162, 372 typesafeenummaxmembers 352 typesafeenummember 163, 375 typesafeenummembername 164, 352 Typkonversionen 177 Java-XML 343 XML-Java

15 Register U underscorebinding 159, 351 Unmarshaller Callback-Mechanismus 108 Unmarshalling 11, 87 V ValidationEvent 101 ValidationEventCollector 105 ValidationEventHandler 102 ValidationEventLocator 102 Validierung 12, 97 X xjc 58, 301 Kommandozeilenbefehl 299 xjc-task 68 XmlAccessorOrder 227, 306 XmlAccessorType 205, 307 XmlAccessType 205 XmlAdapter 276 XmlAnyAttribute 284, 311 XmlAnyElement 312 XmlAttachmentRef 314 XmlAttribute 216, 314 namespace 241 XmlElement 210, 316 namespace 241 XmlElementDecl 295, 318 XmlRegistry 318 XmlElementRefs 236, 261, 320, 321 XmlElements 251, 323 XmlElementWrapper 264, 324 XmlEnum 271, 325 XmlEnumValue 273, 326 XmlID 291, 327 XmlIDREF 290, 328 XmlInlineBinaryData 330 XmlJavaTypeAdapter 181, 276, 331, 370 XmlList 249, 330 XmlMimeType 333 XmlMixed 266, 333 XmlNs 334, 337 XmlRegistry 295, 334 XmlRootElement 64, 86, 201, 335 XmlSchema 239, 336 XML-Schema 17 all 28 Annotationen 45 any 38 anyattribute 38 attribute 26 Beispiele 46 choice 28 complextype 27 Default-Namespace 24 element 25 Elementreferenzen 43 enumeration 32 Facets 31 Globaler Datentyp 30 ID 43 IDREF 43 import 42 include 42 Kardinalitäten 37 Komplexe Datentypen 27 Lokaler Datentyp 29 Namespaces 21 restriction 31 schema 20 Schema-Import 40 sequence 28 simpletype 30 Target-Namespace 22 Vererbung 35 Wertebereiche definieren 33 Wildcards 38 xmlns 23 XMLSchema-instance 23 XmlSchemaType 338, 339 XmlTransient 223, 340 XmlType 341 namespace

16 Register proporder 228 XmlValue 221, 342 mit Listen 250 XPath 48 Beispiele 51 Knotenselektion 50 Namespaces 54 Prädikate 51 XPathFactory 54 XQuery