52. JAXB (Java Architecture for XML Binding)

Niveau :

Intermédiaire

JAXB est une spécification qui permet de faire correspondre un document XML à un ensemble de classes et vice versa au moyen d'opérations de sérialisation/désérialisation nommées marshalling/unmarshalling.

JAXB permet aux développeurs de manipuler un document XML sans avoir à connaître XML ou la façon dont un document XML est traité comme cela est le cas avec SAX, DOM ou StAX. La manipulation du document XML se fait en utilisant des objets précédemment générés à partir d'une DTD pour JAXB 1.0 et d'un schéma XML du document à traiter pour JAXB 2.0.

Le page officiel de JAXB est à l'url : https://www.oracle.com/technical-resources/articles/javase/jaxb.html

Ce chapitre contient plusieurs sections :

• JAXB 1.0
• JAXB 2.0

52.1. JAXB 1.0

JAXB est l'acronyme de Java Architecture for XML Binding.

Le but de l'API et des spécifications JAXB est de faciliter la manipulation d'un document XML en générant un ensemble de classes qui fournissent un niveau d'abstraction plus élevé que l'utilisation de JAXP (SAX ou DOM). Avec ces deux API, toute la logique de traitements des données contenues dans le document est à écrire.

JAXB au contraire fournit un outil qui analyse un schéma XML et génère à partir de ce dernier un ensemble de classes qui vont encapsuler les traitements de manipulation du document.

Le grand avantage est de fournir au développeur un moyen de manipuler un document XML sans connaître XML ou les technologies d'analyse. Toutes les manipulations se font au travers d'objets Java.

Ces classes sont utilisées pour faire correspondre le document XML avec des instances de ces classes et vice versa : ces opérations se nomment respectivement unmarshalling et marshalling.

L'implémentation de référence de JAXB v1.0 est fournie avec le JSWDK 1.1.

Les exemples de ce chapitre utilisent cette implémentation de référence et le fichier XML suivant :

<bibliotheque>
  <livre>
    <titre>titre 1</titre>
    <auteur>auteur 1</auteur>
    <editeur>editeur 1</editeur>
  </livre>
  <livre>
    <titre>titre 2</titre>
    <auteur>auteur 2</auteur>
    <editeur>editeur 2</editeur>
  </livre>
  <livre>
    <titre>titre 3</titre>
    <auteur>auteur 3</auteur>
    <editeur>editeur 3</editeur>
  </livre>
</bibliotheque>

Le schéma XML correspondant à ce fichier XML est le suivant :

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="bibliotheque">
  <xs:complexType>
    <xs:sequence>
      <xs:element ref="livre" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  </xs:element>
  <xs:element name="livre">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="titre"/>
        <xs:element ref="auteur"/>
        <xs:element ref="editeur"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="titre" type="xs:string"/>
  <xs:element name="auteur" type="xs:string"/>
  <xs:element name="editeur" type="xs:string"/>
</xs:schema>

52.1.1. La génération des classes

L'outil xjc permet d'analyser un schéma XML et de générer les interfaces et les classes qui vont permettre la manipulation d'un document XML qui respecte ce schéma. Cette opération se nomme binding.

La syntaxe de cet outil est très simple :

xjc [options] schema

schema est le nom d'un fichier contenant le schéma XML.

Les principales options sont les suivantes :

• -nv : ne pas réaliser une validation stricte du schéma fourni
• -d répertoire : permet de préciser le nom du répertoire qui va contenir les classes générées
• -p package : permet de préciser le nom du package qui va contenir les classes générées

C:\java\jaxb>xjc test.xsd
parsing a schema...
compiling a schema...
generated\impl\AuteurImpl.java
generated\impl\BibliothequeImpl.java
generated\impl\BibliothequeTypeImpl.java
generated\impl\EditeurImpl.java
generated\impl\LivreImpl.java
generated\impl\LivreTypeImpl.java
generated\impl\TitreImpl.java
generated\Auteur.java
generated\Bibliotheque.java
generated\BibliothequeType.java
generated\Editeur.java
generated\Livre.java
generated\LivreType.java
generated\ObjectFactory.java
generated\Titre.java
generated\bgm.ser
generated\jaxb.properties

L'exécution de la commande de l'exemple génère les fichiers suivants :

Generated
    Auteur.java
    bgm.ser
    Bibliotheque.java
    BibliothequeType.java
    Editeur.java
    jaxb.properties
    Livre.java
    LivreType.java
    ObjectFactory.java
    Titre.java
    generated\impl
        AuteurImpl.java
        BibliothequeImpl.java
        BibliothequeTypeImpl.java 
        EditeurImpl.java
        LivreImpl.java
        LivreTypeImpl.java
        TitreImpl.java

Sans précision, les fichiers générés le sont dans le répertoire "Generated".

Pour préciser un autre répertoire, il faut utiliser l'option -d :

xjc -d sources test.xsd

Les classes et interfaces sont générées dans le répertoire "sources/generated"

Si le répertoire précisé n'existe pas, une exception est levée.

C:\java\jaxb>xjc -d sources test.xsd
parsing a schema...
compiling a schema...
java.lang.reflect.InvocationTargetException
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.
java:39)

Pour éviter l'utilisation du répertoire "generated", il faut préciser un package pour les entités générées en utilisant l'option -p.

C:\java\jaxb>xjc -d sources -p fr.jmdoudoux.dej.jaxb test.xsd
parsing a schema...
compiling a schema...
com\moi\test\jaxb\Auteur.java
com\moi\test\jaxb\Bibliotheque.java
com\moi\test\jaxb\BibliothequeType.java
com\moi\test\jaxb\Editeur.java
com\moi\test\jaxb\Livre.java
com\moi\test\jaxb\LivreType.java
com\moi\test\jaxb\ObjectFactory.java
com\moi\test\jaxb\Titre.java
com\moi\test\jaxb\jaxb.properties
com\moi\test\jaxb\bgm.ser
com\moi\test\jaxb\impl\AuteurImpl.java
com\moi\test\jaxb\impl\BibliothequeImpl.java
com\moi\test\jaxb\impl\BibliothequeTypeImpl.java
com\moi\test\jaxb\impl\EditeurImpl.java
com\moi\test\jaxb\impl\LivreImpl.java
com\moi\test\jaxb\impl\LivreTypeImpl.java
com\moi\test\jaxb\impl\TitreImpl.java

Un objet de type factory et des interfaces pour chacun des éléments qui composent le document sont définis.

Pour chaque élément qui peut contenir d'autres éléments, des interfaces de XXXType sont créées (BibliothequeType et LivreType dans l'exemple).

L'interface BibliothequeType définit simplement un getter sur une collection qui contiendra tous les livres.

L'interface LivreType définit des getters et des setters sur les éléments auteur, editeur et titre.

Les interfaces Titre, Editeur et Auteur définissent un getter et un setter sur les valeurs des données que ces éléments contiennent.

La classe ObjectFactory permet de créer des instances des différentes entités définies.

Le répertoire impl contient les classes qui implémentent ces interfaces. Ces classes sont spécifiques à l'implémentation des spécifications JAXB utilisée.

Pour pouvoir utiliser ces interfaces et ces classes, il faut les compiler en incluant au classpath, tous les fichiers .jar contenus dans le répertoire lib de l'implémentation de JAXB.

52.1.2. L'API JAXB

L'API JAXB propose un framework composé de classes regroupées dans trois packages :

• javax.xml.bind : contient les interfaces principales et la classe JAXBContext
• javax.xml.bind.util : contient des utilitaires
• javax.xml.bind.helper : contient une implémentation partielle de certaines interfaces pour faciliter le développement d'une implémentation des spécifications de JAXB

52.1.3. L'utilisation des classes générées et de l'API

Pour pouvoir utiliser JAXP, il faut tout d'abord obtenir un objet de type JAXBContext qui est le point d'entrée pour utiliser l'API. Il faut ensuite utiliser la méthode newInstance() qui attend en paramètre le nom du package contennant les interfaces générées (celui fournit au paramètre -p de la commande xjc).

Pour pouvoir créer en mémoire les objets qui représentent le document XML, il faut à partir de l'instance du type JAXBContext, appeler la méthode createUnmarshaller() qui renvoie un objet de type Unmarshaller.

L'appel de la méthode unmarshal() permet de créer les différents objets.

Pour parcourir le document, il suffit d'utiliser les différents objets instanciés.

package fr.jmdoudoux.dej.jaxb;
import javax.xml.bind.*;
import java.io.*;
import java.util.*;
public class TestJAXB {

  public static void main(String[] args) {

    try {
      JAXBContext jc = JAXBContext.newInstance("fr.jmdoudoux.dej.jaxb");
      Unmarshaller unmarshaller = jc.createUnmarshaller();
      unmarshaller.setValidating(true);

      Bibliotheque bibliotheque = (Bibliotheque) unmarshaller.unmarshal(new File("test.xml"));

      List livres = bibliotheque.getLivre();
      for (int i = 0; i < livres.size(); i++) {
        LivreType livre = (LivreType) livres.get(i);
        System.out.println("Livre ");
        System.out.println("Titre   : " + livre.getTitre());
        System.out.println("Auteur  : " + livre.getAuteur());
        System.out.println("Editeur : " + livre.getEditeur());
        System.out.println();
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Livre 
Titre   : titre 1
Auteur  : auteur 1
Editeur : editeur 1
Livre 
Titre   : titre 2
Auteur  : auteur 2
Editeur : editeur 2
Livre 
Titre   : titre 3
Auteur  : auteur 3
Editeur : editeur 3

52.1.4. La création d'un nouveau document XML

Parmi les classes générées à partir du schéma XML, il y a la classe ObjectFactory qui permet de créer des instances des autres classes générées.

import javax.xml.bind.*;
import java.io.*;
import java.util.*;
public class TestJAXB2 {

  public static void main(String[] args) {
    try {
      ObjectFactory objFactory = new ObjectFactory();

      Bibliotheque bibliotheque = (Bibliotheque) objFactory.createBibliotheque();
      List livres = bibliotheque.getLivre();
      for (int i = 1; i < 4; i++) {
        LivreType livreType = objFactory.createLivreType();
        //    LivreType livre = objFactory.createLivreType();

        livreType.setAuteur("Auteur" + i);
        livreType.setEditeur("Editeur" + i);
        livreType.setTitre("Titre" + i);
        livres.add(livreType);
      }

    } catch (Exception e) {

    }
  }
}

52.1.5. La génération d'un document XML

Une fois la représentation en mémoire du document XML créée ou modifiée, il est fréquent de devoir l'envoyer dans un flux tel qu'un fichier pour conserver les modifications. Cette opération se nomme marshalling.

Pour réaliser cette opération, il faut tout d'abord obtenir un objet du type JAXBContext en utilisant la méthode newInstance(). Cette méthode demande en paramètre une chaîne de caractères indiquant le package des interfaces générées à partir du schéma.

La méthode createMarshaller() permet d'obtenir un objet de type Marshaller. C'est cet objet qui va formater le document XML.

Il est possible de lui préciser des propriétés pour effectuer sa tâche en utilisant la méthode setProperty(). Des constantes sont définies pour ces propriétés dont les principales sont :

• JAXB_ENCODING : permet de préciser le jeu de caractères d'encodage du document XML sous la forme d'une chaîne de caractères
• JAXB_FORMATTED_OUTPUT : booléen qui indique si le document XML doit être formaté

Les propriétés doivent être des objets.

L'appel de la méthode marshal() formate le document dont l'objet racine est fourni en premier paramètre. Il existe plusieurs surcharges de cette méthode pour préciser où est envoyé le résultat de la génération. Le second paramètre permet de préciser cette cible : un flux en sortie, un arbre DOM, des événements SAX.

package fr.jmdoudoux.dej.jaxb;
import javax.xml.bind.*;
import java.io.*;
import java.util.*;
public class TestJAXB3 {

  public static void main(String[] args) {
    try {

      ObjectFactory objFactory = new ObjectFactory();

      Bibliotheque bibliotheque = (Bibliotheque) objFactory.createBibliotheque();
      List livres = bibliotheque.getLivre();
      for (int i = 1; i < 4; i++) {
        LivreType livreType = objFactory.createLivreType();
        //    LivreType livre = objFactory.createLivreType();

        livreType.setAuteur("Auteur" + i);
        livreType.setEditeur("Editeur" + i);
        livreType.setTitre("Titre" + i);
        livres.add(livreType);
      }
      JAXBContext jaxbContext = JAXBContext.newInstance("fr.jmdoudoux.dej.jaxb");
      Marshaller marshaller = jaxbContext.createMarshaller();
      marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, new Boolean(true));
      Validator validator = jaxbContext.createValidator();

      marshaller.marshal(bibliotheque, System.out);
    } catch (Exception e) {
    }
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bibliotheque>
<livre>
<titre>Titre1</titre>
<auteur>Auteur1</auteur>
<editeur>Editeur1</editeur>
</livre>
<livre>
<titre>Titre2</titre>
<auteur>Auteur2</auteur>
<editeur>Editeur2</editeur>
</livre>
<livre>
<titre>Titre3</titre>
<auteur>Auteur3</auteur>
<editeur>Editeur3</editeur>
</livre>
</bibliotheque>

52.2. JAXB 2.0

JAXB 2.0 a été développé sous la JSR 222 et est incorporée dans Java EE 5 et dans Java SE 6.

Les fonctionnalités de JAXB 2.0 par rapport à JAXB 1.0 sont :

• support uniquement des schémas XML (les DTD ne sont plus supportées)
• mise en oeuvre des annotations
• assure la correspondance bidirectionnelle entre un schéma XML et le bean correspondant.
• l'utilisation de fonctionnalités proposées par Java 5 notamment les generics et les énumérations
• le nombre d'entités générées est moins important : JAXB 2.0 génère une classe pour chaque complexType du schéma alors que JAXB 1.0 génère une interface et une classe qui implémente cette interface. Une méthode de la classe ObjectFactory est générée pour renvoyer une instance de cette classe.

En plus de son utilité principale, JAXB 2.0 propose d'atteindre plusieurs objectifs :

• Être facile à utiliser pour consulter et modifier un document XML sans connaissance ni de XML ni de techniques de traitement de documents XML
• Être configurable : JAXB met en oeuvre des fonctionnalités par défaut qu'il est possible de modifier par configuration pour répondre à ses propres besoins
• S'assurer que la création d'un document XML à partir d'objets et retransformer ce document en objets donne le même ensemble d'objets
• Pouvoir valider un document XML ou les objets qui encapsulent un document sans avoir à écrire le document correspondant
• Être portable : chaque implémentation doit au minimum mettre en oeuvre les spécifications de JAXB

L'utilisation de JAXB implique généralement deux étapes :

• Génération des classes et interfaces à partir du schéma XML
• Utilisation des classes générées et de l'API JAXB pour transformer un document XML en graphe d'objets et vice versa, pour manipuler les données dans le graphe d'objets et pour valider le document

JAXB 2.0 permet toujours de mapper des objets Java dans un document XML et vice versa. Il permet aussi de générer des classes Java à partir un schéma XML et inversement.

La sérialisation d'un graphe d'objets Java est effectuée par une opération de mashalling. L'opération inverse est dite unmashalling. Lors de ces deux opérations, le document XML peut être validé.

JAXB 2.0 utilise de nombreuses annotations définies dans le package javax.xml.bin.annotation essentiellement pour préciser le mode de fonctionnement lors des opérations de marshalling/unmarshalling.

Ces annotations précisent le mapping entre les classes Java et le document XML. La plupart de ces annotations ont des valeurs par défaut ce qui réduit l'obligation de leur utilisation si la valeur par défaut correspond au besoin.

JAXB 2.0 permet aussi de réaliser dynamiquement à l'exécution une transformation d'un graphe d'objets en document XML et vice versa. C'est cette fonctionnalité qui est largement utilisée dans les services web grâce à l'API JAX-WS 2.0.

La classe abstraite JAXBContext fournie par l'API JAXB permet de gérer la transformation d'objets Java en XML et vice versa.

JAXB 2.0 propose plusieurs outils pour faciliter sa mise en oeuvre :

• un générateur de classes Java (schema compiler) à partir d'un schéma XML. L'outil est nommé xjc dans l'implémentation de référence. Les classes générées mettent en oeuvre les annotations de JAXB.
• un générateur de schéma XML (schema generator) à partir d'un graphe d'objets nommé schemagen dans l'implémentation de référence.

L'API JAXB est contenue dans la package javax.xml.bind

52.2.1. L'obtention de JAXB 2.0

JAXB 2.0 est incorporée dans Java EE 5 et dans Java SE 6.

Avec la version fournie avec JWSDP 2.0, les bibliothèques suivantes doivent être ajoutées au classpath :
jaxb\lib\jaxb-api.jar,
jaxb\lib\jaxb-impl.jar,
jaxb\lib\jaxb-xjc.jar,
jwsdp-shared\lib\activation.jar,
sjsxp\lib\jsr173_api.jar,
sjsxp\lib\sjsxp.jar

Attention JAXB 2.0 requiert un JDK 5.0 minimum pour être utilisé.

52.2.2. La mise en oeuvre de JAXB 2.0

La mise en oeuvre de JAXB requiert pour un usage standard plusieurs étapes :

• La génération des classes en utilisant l'outil xjc de JAXB à partir d'un schéma du document XML
• Ecriture de code utilisant les classes générées et l'API JAXB pour transformer un document XML en objets Java, modifier des données encapsulées dans le graphe d'objets ou transformer le graphe d'objets en un document XML avec une validation optionnelle du document
• La compilation du code généré et écrit puis l'exécution de l'application

L'utilisation de JAXB se fait donc en deux phases :

1. générer des classes à partir d'un schéma XML et les utiliser dans le code de l'application
2. à l'exécution de l'application, le document XML est transformé en graphe d'objets, les données de ces objets peuvent être modifiées puis le document XML peut être regénéré à partir des objets.

L'utilisation de JAXB met en oeuvre plusieurs éléments :

• Une ou plusieurs classes annotées qui vont encapsuler des données du document XML
• (optionnel) un schéma XML : c'est un document XML qui décrit la structure des éléments, attributs et entités d'un document XML. Le but d'un schéma XML est similaire à celui d'une DTD mais le schéma propose une description plus riche et plus fine. Ce schéma peut éventuellement être enrichi de données de configurations concernant les classes à générer
• (optionnel) un outil qui génère les classes annotées à partir d'un schéma avec éventuellement un fichier de configuration pour les classes à générer
• Une API utilisée à l'exécution pour transformer un document XML en un ensemble d'objets du type des classes annotées ou vice versa et permettre des validations
• Un document XML qui sera lu et/ou écrit en fonction des traitements à réaliser

Les avantages d'utiliser JAXB sont nombreux :

• Facilite la manipulation de documents XML dans une application Java
• Manipulation du document XML au travers d'objets : aucune connaissance de XML ou de la manière de traiter un document n'est requise
• Un document XML peut être créé en utilisant les classes générées
• Les traitements de JAXB peuvent être configurés
• Les ressources requises par le graphe d'objets utilisé par JAXB sont moins importantes qu'avec DOM

52.2.3. La génération des classes à partir d'un schéma

Pour permettre l'utilisation et la manipulation d'un document XML, JAXB propose de générer un ensemble de classes à partir du schéma XML du document.

Chaque implémentation de JAXB doit fournir un outil (binding compiler) qui permet la génération de classes et interfaces à partir d'un schema  (binding a schema).

52.2.4. La commande xjc

L'implémentation de référence fournit l'outil xjc pour générer les classes à partir d'un schéma XML.

L'utilisation la plus simple de l'outil xjc est de lui fournir le fichier qui contient le schéma XML du document à utiliser.

xjc biblio.xsd

L'outil xjc possède plusieurs options dont voici les principales :

52.2.5. Les classes générées

Le compilateur génère des classes en correspondance avec le schéma XML fourni à l'outil.

<?xml version="1.0"  encoding="UTF-8"?> 
<xs:schema  xmlns:xs="http://www.w3.org/2001/XMLSchema"
            targetNamespace="http://www.jmdoudoux.com/test/jaxb"
            xmlns:tns="http://www.jmdoudoux.com/test/jaxb"
            elementFormDefault="qualified"> 
  <xs:element  name="bibliotheque"> 
    <xs:complexType> 
      <xs:sequence> 
        <xs:element  maxOccurs="unbounded" name="livre"> 
          <xs:complexType> 
            <xs:sequence> 
              <xs:element  name="titre" type="xs:string" /> 
              <xs:element  name="auteur"> 
                <xs:complexType> 
                  <xs:sequence> 
                    <xs:element name="nom"  type="xs:string" /> 
                    <xs:element  name="prenom" type="xs:string" /> 
                  </xs:sequence> 
                </xs:complexType> 
              </xs:element> 
              <xs:element  name="editeur" type="xs:string" /> 
            </xs:sequence> 
          </xs:complexType> 
        </xs:element> 
      </xs:sequence> 
    </xs:complexType> 
  </xs:element>
</xs:schema>

C:\Documents and Settings\jmd\workspace\TestJAXB>xjc -d src biblio.xsd
parsing a schema...
compiling a schema...
com\jmdoudoux\test\jaxb\Bibliotheque.java
com\jmdoudoux\test\jaxb\ObjectFactory.java
com\jmdoudoux\test\jaxb\package-info.java

Trois entités sont générées dans le répertoire src :

• fr.jmdoudoux.dej.jaxb.Bibliotheque.java : classes qui encapsulent le document XML
• fr.jmdoudoux.dej.jaxb.package-info.java : permet de conserver les espaces de nommages utilisés dans le package
• fr.jmdoudoux.dej.jaxb.ObjectFactory.java : fabrique qui permet d'instancier des objets utilisés lors du mapping

Par défaut, le package utilisé est déduit de l'espace de nommage défini dans le schéma.

Chaque classe qui encapsule un type complexe du schéma possède des getters et setters sur les éléments du schéma.

La fabrique permet de créer des instances de chacun des types d'objets correspondant à un type complexe du schéma. Cette fabrique est particulièrement utile lors de la création d'un nouveau document XML : le graphe d'objets est créé en ajoutant des instances des objets retournés par cette fabrique.

Les classes générées sont dépendantes de l'implémentation de JAXB utilisée : il est préférable d'utiliser les classes générées par une implémentation avec cette implémentation.

Par défaut, JAXB utilise des règles pour définir chaque entité incluse dans le schéma (element et complexType définis dans le schéma).

52.2.6. L'utilisation de l'API JAXB 2.0

JAXB fournit une API qui permet à l'exécution d'effectuer les opérations de transformation d'un document XML en un graphe d'objets utilisant les classes générées et vice versa (unmashalling/marshalling) ainsi que des opérations de validation.

L'objet principal pour les opérations de transformation est l'objet JAXBContext : il permet d'utiliser l'API JAXB. Pour obtenir une instance de cet objet, il faut utiliser la méthode statique newInstance() en lui passant en paramètre le ou les packages contenant les classes générées à utiliser. Dans le cas où plusieurs packages doivent être précisés, il faut les séparer par une virgule.

Une autre surcharge de la méthode newInstance() attend en paramètre la classe qui encapsule la racine du document.

JAXBContext jc = JAXBContext.newInstance("fr.jmdoudoux.dej.jaxb");

52.2.6.1. Le mapping d'un document XML à des objets (unmarshalling)

L'API JAXB propose de transformer un document XML en un ensemble d'objets qui vont encapsuler les données et la hiérarchie du document. Ces objets sont des instances des classes générées à partir du schéma XML.

La création des objets nécessite la création d'un objet de type JAXBContext en utilisant la méthode statique newInstance().

Il faut ensuite instancier un objet de type Unmarshaller qui va permettre de transformer un document XML en un ensemble d'objets. Un telle instance est obtenue en utilisant la méthode createUnmarshaller() de la classe JAXBContext.

  Unmarshaller unmarshaller = jc.createUnmarshaller();

La méthode unmarshal() de la classe Unmarshaller se charge de traiter un document XML et retourne un objet du type complexe qui encapsule la racine du document XML. Elle possède de nombreuses surcharges à utiliser en fonction des besoins.

  Bibliotheque bibliotheque = (Bibliotheque) unmarshaller.unmarshal(new File("biblio.xml"));

A partir de cet objet, il est possible d'obtenir et de modifier des données encapsulées dans les différents objets créés à partir des classes générées et du contenu du document. Chacun de ces objets possède un getter et un setter sur leur noeud direct.

List<Livre> livres = bibliotheque.getLivre();
      for (int i = 0; i < livres.size(); i++) {
      Livre livre = livres.get(i);
      System.out.println("Livre ");
      System.out.println("Titre : " + livre.getTitre());
      System.out.println("Auteur : " + livre.getAuteur().getNom() 
        + " " +livre.getAuteur().getPrenom());
      System.out.println("Editeur : " + livre.getEditeur());
      System.out.println();

Il est possible de demander la validation du document avec le schéma en utilisant la méthode setValidating() de la classe Unmarshaller.

      unmarshaller.setValidating(true);

package fr.jmdoudoux.dej.jaxb;

import java.io.File;
import java.util.List;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;

import fr.jmdoudoux.dej.jaxb.Bibliotheque.Livre;

public class TestJAXB2 {

  public static void main(String[] args) {
    try {
      JAXBContext jc = JAXBContext.newInstance("fr.jmdoudoux.dej.jaxb");
      Unmarshaller unmarshaller = jc.createUnmarshaller();
      Bibliotheque bibliotheque = (Bibliotheque) unmarshaller.unmarshal(
	     new File("biblio.xml"));
      List<Livre> livres = bibliotheque.getLivre();
      for (int i = 0; i < livres.size(); i++) {
      Livre livre = livres.get(i);
      System.out.println("Livre ");
      System.out.println("Titre : " + livre.getTitre());
      System.out.println("Auteur : " + livre.getAuteur().getNom() 
        + " " +livre.getAuteur().getPrenom());
      System.out.println("Editeur : " + livre.getEditeur());
      System.out.println();
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

<?xml version="1.0"  encoding="UTF-8"?>
<tns:bibliotheque  xmlns:tns="http://www.jmdoudoux.com/test/jaxb"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.jmdoudoux.com/test/jaxb biblio.xsd  ">
   <tns:livre>
     <tns:titre>titre 1</tns:titre>
     <tns:auteur>
       <tns:nom>nom 1</tns:nom>
       <tns:prenom>prenom 1</tns:prenom>
     </tns:auteur>
     <tns:editeur>editeur 1</tns:editeur>
   </tns:livre>
   <tns:livre>
     <tns:titre>titre 2</tns:titre>
     <tns:auteur>
       <tns:nom>nom 2</tns:nom>
       <tns:prenom>prenom 2</tns:prenom>
     </tns:auteur>
     <tns:editeur>editeur 2</tns:editeur>
   </tns:livre>
   <tns:livre>
     <tns:titre>titre 3</tns:titre>
     <tns:auteur>
       <tns:nom>nom 3</tns:nom>
       <tns:prenom>prenom 3</tns:prenom>
     </tns:auteur>
     <tns:editeur>editeur 3</tns:editeur>
   </tns:livre>
</tns:bibliotheque>

Livre
Titre : titre 1
Auteur : nom 1 prenom 1
Editeur : editeur 1

Livre
Titre : titre 2
Auteur : nom 2 prenom 2
Editeur : editeur 2

Livre
Titre : titre 3
Auteur : nom 3 prenom 3
Editeur : editeur 3

52.2.6.2. La création d'un document XML à partir d'objets

JAXB permet de créer un document XML à partir d'un graphe d'objets : cette opération est nommée marshalling. Une opération de mashalling est l'opération inverse de l'opération d'unmarshalling.

Ce graphe d'objets peut être issu d'une opération de type unmarshalling (construction à partir d'un document XML existant) ou issu d'une création de toutes pièces de l'ensemble des objets. Dans le premier cas cela correspond à une modification du document et dans le second cas à une création de document.

La création des objets nécessite la création d'un objet de type JAXBContext en utilisant la méthode statique newInstance().

Il faut ensuite instancier un objet de type Marshaller qui va permettre de transformerun ensemble d'objets en un document XML. Une telle instance est obtenue en utilisant la méthode createMarshaller() de la classe JAXBContext.

      Marshaller marshaller = jc.createMarshaller();

La méthode marshal() de la classe Marshaller se charge de créer un document XML à partir d'un graphe d'objets dont l'objet racine lui est fourni en paramètre.

La méthode marshal() possède plusieurs surcharges qui permettent de préciser la forme du document XML généré :

• un fichier (File),
• un flux (outputStream),
• un flux de caractères (Writer),
• un document DOM (Document),
• un gestionnaire d'événements SAX (ContentHandler),
• un objet de type javax.xml.transform.SAXResult,
• un objet de type javax.xml.transform.DOMResult,
• un objet de type javax.xml.transform.StreamResult,
• un objet de type javax.xml.stream.XMLStreamWriter,
• ou un objet de type javax.xml.stream.XMLEventWriter.

L'objet Mashaller possède des propriétés qu'il est possible de valoriser en utilisant la méthode setProperty(). Les spécifications de JAXB proposent des propriétés qui doivent être obligatoirement supportées par l'implémentation. Chaque implémentation est libre de proposer des propriétés supplémentaires.

      Marshaller m = context.createMarshaller();
      m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

Il est possible de demander la validation du graphe d'objets. La validation n'est pas intégrée à l'opération de mashalling mais elle est effectuée à la demande.

La validation s'effectue en utilisant la classe Validator. Une instance de cette classe est obtenue en utilisation la méthode createValidator() de la classe JAXBContext.

Validator validator = jaxbContext.createValidator();

Pour valider le graphe d'objets vis-à-vis du schéma, il faut utiliser la méthode validate() de la classe Validator en lui passant en paramètre l'objet qui encapsule la racine du document.

52.2.6.3. La création d'un document en utilisant des classes annotées

JAXB permet de mapper une ou plusieurs classes annotées vers un document XML sans être obligé d'utiliser un schéma XML. Dans ce cas, le développeur a la charge d'écrire la ou les classes annotées requises.

Il n'est donc pas nécessaire d'utiliser des classes générées par le compilateur de schéma mais dans ce cas, la ou les classes doivent être créées manuellement en utilisant les annotations adéquates.

La classe qui encapsule la racine du document doit être annotée avec l'annotation @XmlRootElement. Une exception de type javax.xml.bind.MarshalException est levée par JAXB si la classe racine ne possède pas cette annotation.

javax.xml.bind.MarshalException
 - with linked exception:
[com.sun.istack.internal.SAXException2: unable to marshal type "fr.jmdoudoux.dej.jaxb.
Personne" as an element because it is missing an @XmlRootElement annotation]

JAXB utilise des comportements par défaut qui ne nécessitent de la part du développeur que de définir des comportements particuliers si les valeurs par défaut ne conviennent pas.

package fr.jmdoudoux.dej.jaxb;

import java.util.Date;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Personne {
  private String nom;
  private String prenom;
  private int taille;
  private Date dateNaiss;
  
  public Personne() {
  }

  public Personne(String nom, String prenom, int taille, Date dateNaiss) {
    super();
    this.nom = nom;
    this.prenom = prenom;
    this.taille = taille;
    this.dateNaiss = dateNaiss;
  }

  public Date getDateNaiss() {
    return dateNaiss;
  }

  public void setDateNaiss(Date dateNaiss) {
    this.dateNaiss = dateNaiss;
  }

  public String getNom() {
    return nom;
  }

  public void setNom(String nom) {
    this.nom = nom;
  }

  public String getPrenom() {
    return prenom;
  }

  public void setPrenom(String prenom) {
    this.prenom = prenom;
  }

  public int getTaille() {
    return taille;
  }

  public void setTaille(int taille) {
    this.taille = taille;
  }
}

La création du document nécessite la création d'un objet de type JAXBContext en utilisant la méthode statique newInstance().

Il faut ensuite créer un objet de type Marshaller à partir du contexte et appeler sa méthode marshal() pour générer le document.

package fr.jmdoudoux.dej.jaxb;

import java.util.Date;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;

public class TestJAXB1 {
 
  public static void main(String[] args) {
    try {
      JAXBContext context = JAXBContext.newInstance(Personne.class);
      Marshaller m = context.createMarshaller();
      m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
      Personne p = new Personne("nom1", "prenom1", 175, new Date());
      m.marshal(p, System.out);
    } catch (JAXBException ex) {
      ex.printStackTrace();
    }
  }
}

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
<personne>
  <dateNaiss>2007-01-16T17:03:31.213+01:00</dateNaiss>
  <nom>nom1</nom>
  <prenom>prenom1</prenom>
  <taille>175</taille>
</personne>

52.2.6.4. La création d'un document en utilisant les classes générées à partir d'un schéma

Une des classes générées à partir du schéma se nomme ObjectFactory : c'est une fabrique d'objets pour les classes générées qui encapsulent des données d'un document respectant le schéma.

Pour créer un document XML en utilisant ces classes, il faut mettre en oeuvre plusieurs étapes.

La création du document nécessite la création d'un objet de type JAXBContext en utilisant la méthode statique newInstance().

Il faut ensuite créer le graphe d'objets en utilisant la classe ObjectFactory pour instancier les différents objets et valoriser les données de ces objets en utilisant les setters.

Il faut créer un objet de type Marshaller à partir du contexte et appeler sa méthode marshal() pour générer le document.

package fr.jmdoudoux.dej.jaxb;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;

public class TestJAXB3 {
  public static void main(String[] args) {
    try {
      JAXBContext context = JAXBContext.newInstance(Bibliotheque.class);
      Marshaller m = context.createMarshaller();
      m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

      ObjectFactory fabrique = new ObjectFactory();
      Bibliotheque bibliotheque = fabrique.createBibliotheque();

      Bibliotheque.Livre livre = fabrique.createBibliothequeLivre();
      livre.setEditeur("editeur 1");
      livre.setTitre("titre 1");

      Bibliotheque.Livre.Auteur auteur = fabrique
          .createBibliothequeLivreAuteur();
      auteur.setNom("nom 1");
      auteur.setPrenom("prenom 1");
      livre.setAuteur(auteur);

      bibliotheque.getLivre().add(livre);

      m.marshal(bibliotheque, System.out);
    } catch (JAXBException ex) {
      ex.printStackTrace();
    }
  }
}

52.2.7. La configuration de la liaison XML / Objets

JAXB propose des fonctionnalités pour configurer finement les traitements qu'il propose.

52.2.7.1. L'annotation du schéma XML

JAXB utilise des traitements par défaut qu'il est possible de configurer différemment en utilisant soit les annotations soit un fichier de configuration qui sera fourni au compilateur.

Les classes générées peuvent aussi être configurées, notamment le nom du package et des classes utilisées.

Par défaut, le générateur de classes à partir du schéma utilise des conventions de nommage des différentes entités générées à partir des noms utilisés dans le schéma. Il est possible de configurer de façon différente les noms utilisés.

Les spécifications JAXB décrivent de façon précise comment les éléments d'un schéma sont transformés en classes Java. Il est possible de préciser des informations particulières dans le schéma pour modifier ce comportement par défaut.

Ces informations peuvent être incluses directement dans le schéma ou fournies dans un fichier dédié. Dans le schéma, ces informations sont fournies dans un tag <annotation> qui contient un tag fils <appinfo>.

<?xml  version="1.0" encoding="UTF-8"?>
<xs:schema  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://www.jmdoudoux.com/test/jaxb/perso"
   xmlns:tns="http://www.jmdoudoux.com/test/jaxb"
   xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
  jaxb:extensionBindingPrefixes="xjc"
   xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"  jaxb:version="1.0"
  elementFormDefault="qualified">
  <xs:element  name="bibliotheque">
    <xs:complexType>
      <xs:sequence>
        <xs:element  maxOccurs="unbounded" name="livre">
          <xs:complexType>
            <xs:sequence>
              <xs:element  name="titre" type="xs:string" />
               <xs:element  name="auteur">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element  name="nom"
                       type="xs:string" />
                    <xs:element  name="prenom"
                      type="xs:string" />
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element  name="editeur" type="xs:string">
                <!--
                  Personnalisation de la  propriété editeur en nomEditeur
                -->
                <xs:annotation>
                  <xs:appinfo>
                    <jaxb:property  name="nomEditeur" />
                  </xs:appinfo>
                </xs:annotation>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

C:\Documents and Settings\jmd\workspace\TestJAXB>xjc -d src -extension biblio2.x
sd
parsing a schema...
compiling a schema...
com\jmdoudoux\test\jaxb\perso\Bibliotheque.java
com\jmdoudoux\test\jaxb\perso\ObjectFactory.java
com\jmdoudoux\test\jaxb\perso\package-info.java

L'option -extension du générateur de classes autorise l'outil à utiliser des extensions proposées par l'implémentation de JAXB. Sans cette option, l'outil utilise le mode strict et une exception est levée si une extension est utilisée.

...
    @XmlAccessorType(XmlAccessType.FIELD)
    @XmlType(name = "", propOrder = {
        "titre",
        "auteur",
        "nomEditeur"
    })
    public static class Livre {

        @XmlElement(required = true)
        protected String titre;
        @XmlElement(required = true)
        protected Bibliotheque.Livre.Auteur auteur;
        @XmlElement(name = "editeur", required = true)
        protected String nomEditeur;

...

        /**
         * Gets the value of the nomEditeur property.
         * 
         * @return
         *     possible object is
         *     {@link String }
         *     
         */
        public String getNomEditeur() {
            return nomEditeur;
        }

        /**
         * Sets the value of the nomEditeur property.
         * 
         * @param value
         *     allowed object is
         *     {@link String }
         *     
         */
        public void setNomEditeur(String value) {
            this.nomEditeur = value;
        }
...

JAXB propose de nombreuses fonctionnalités de configuration : consultez les spécifications pour de plus amples détails.

52.2.7.2. Les annotations de JAXB

La configuration de la transformation d'un document XML en objets Java est réalisée grâce à l'utilisation d'annotations dédiées dans les classes Java.

De nombreuses annotations sont définies par JAXB 2.0 dont voici les principales :

Ces annotations sont définies dans le package javax.xml.bind.annotation.

L'annotation @XmlRootElement peut être utilisée sur une classe pour préciser que cette classe sera le tag racine du document XML. Chaque attribut de la classe sera un tag fils dans le document XML. L'attribut namespace de l'annotation @XmlRootElement permet de préciser l'espace de nommage.

L'annotation XmlTransient permet d'ignorer une entité dans le mapping.

  @XmlTransient
  public String getNom() {
    return nom;
  }

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<personne xmlns="http://www.jmdoudoux.com/test/jaxb">
    <dateNaiss>2007-06-21T15:18:28.809+02:00</dateNaiss>
    <prenom>prenom1</prenom>
    <taille>175</taille>
</personne>

L'annotation XmlAttribute permet de mapper une propriété sous la forme d'un attribut et fournir des précisions sur la configuration de cet attribut.

@XmlAttribute (name="nom")
public String getNom() {
  return nom;
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<personne  xmlns="http://www.jmdoudoux.com/test/jaxb" nom="nom1">
  <dateNaiss>2007-06-21T15:20:34.377+02:00</dateNaiss>
  <prenom>prenom1</prenom>
  <taille>175</taille>
</personne>

Pour les collections, il est possible d'utiliser l'annotation @XmlElementWrapper pour définir un élément père qui encapsule les occurrences de la collection et d'utiliser l'annotation XmlElement pour préciser le nom de chaque élément de la collection.

  @XmlElementWrapper(name = "adresses")
  @XmlElement(name = "adresse")
  protected List<Adresse> adresses = new ArrayList<Adresse>();

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
<personne  xmlns="http://www.jmdoudoux.com/test/jaxb">
  <adresses>
    <adresse>
      <codePostal>54000</codePostal>
      <ligne1>ligne1</ligne1>
      <ligne2>ligne2</ligne2>
      <pays>pays1</pays>
      <ville>ville1</ville>
    </adresse>
  </adresses>
  <dateNaiss>2007-06-21T15:34:35.547+02:00</dateNaiss>
  <nom>nom1</nom>
  <prenom>prenom1</prenom>
  <taille>175</taille>
</personne>

Il est possible de configurer l'ordre des éléments.

@XmlRootElement
@XmlType(propOrder = {"nom", "prenom", "taille", "dateNaiss", "adresses"})
public class Personne {
  private String nom;
  private String prenom;
  private int    taille;
  private Date   dateNaiss;
  
  @XmlElementWrapper(name = "adresses")
  @XmlElement(name = "adresse")
  protected List<Adresse> adresses = new ArrayList<Adresse>();
  
  // getters et setters ...

}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<personne  xmlns="http://www.jmdoudoux.com/test/jaxb">
  <nom>nom1</nom>
  <prenom>prenom1</prenom>
  <taille>175</taille>
  <dateNaiss>2007-06-21T15:44:12.815+02:00</dateNaiss>
  <adresses>
    <adresse>
      <codePostal>54000</codePostal>
      <ligne1>ligne1</ligne1>
      <ligne2>ligne2</ligne2>
      <pays>pays1</pays>
      <ville>ville1</ville>
    </adresse>
  </adresses>
</personne>

Il est possible de définir des classes de type Adapter qui permettent de personnaliser la façon dont un objet est sérialisé/désérialisé dans le document XML.

Ces adapters héritent de la classe javax.xml.bind.annotation.adapters.XmlAdapter. Il suffit de redéfinir les méthodes marshal() et unmashal(). Ces méthodes seront utilisées à l'exécution par l'API JAXB lors des transformations.

package fr.jmdoudoux.dej.jaxb;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;

import javax.xml.bind.annotation.adapters.XmlAdapter;

public class DateAdapter extends XmlAdapter<String, Date> {

  DateFormat df = new SimpleDateFormat("dd/MM/yyyy");

  public Date unmarshal(String date) throws Exception {
    return df.parse(date);
  }

  public String marshal(Date date) throws Exception {
    return df.format(date);
  }
}

L'annotation @XmlJavaTypeAdapter permet de préciser la classe de type Adapter qui sera à utiliser à la place de la conversion par défaut.

package fr.jmdoudoux.dej.jaxb;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;

@XmlRootElement
@XmlType(propOrder = {"nom", "prenom", "taille", "dateNaiss", "adresses"}) 
public class Personne {
  private String nom;
  private String prenom;
  private int    taille;
  private Date   dateNaiss;
  
  @XmlElementWrapper(name = "adresses")
  @XmlElement(name = "adresse")
  protected List<Adresse> adresses = new ArrayList<Adresse>();

  public Personne() {
  }

  public Personne(String nom, String prenom, int taille, Date dateNaiss) {
    super();
    this.nom = nom;
    this.prenom = prenom;
    this.taille = taille;
    this.dateNaiss = dateNaiss;
  }

  @XmlJavaTypeAdapter(DateAdapter.class) 
  public Date getDateNaiss() {
    return dateNaiss;
  }

  public void setDateNaiss(Date dateNaiss) {
    this.dateNaiss = dateNaiss;
  }
  
  // getters et setters ...

}

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
<personne  xmlns="http://www.jmdoudoux.com/test/jaxb">
  <nom>nom1</nom>
  <prenom>prenom1</prenom>
  <taille>175</taille>
  <dateNaiss>22/06/2007</dateNaiss>
  <adresses>
    <adresse>
      <codePostal>54000</codePostal>
      <ligne1>ligne1</ligne1>
      <ligne2>ligne2</ligne2>
      <pays>pays1</pays>
      <ville>ville1</ville>
    </adresse>
  </adresses>
</personne>

Ceci ne présente qu'une toute petite partie des fonctionnalités proposées par JAXB. Pour de plus amples informations, consultez les spécifications de JAXB.

52.2.7.3. La génération d'un schéma à partir de classes compilées

L'outil schemagen fourni avec l'implémentation par défaut permet de générer un schéma XML à partir de classes annotées compilées.

C:\Documents and Settings\jmd\workspace\TestJAXB>schemagen -cp ./bin fr.jmdoudo
ux.test.jaxb.Personne
Note: Writing schema1.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="personne" type="personne"/>
  <xs:complexType  name="personne">
      <xs:sequence>
        <xs:element name="nom"  type="xs:string" minOccurs="0"/>
        <xs:element name="prenom"  type="xs:string" minOccurs="0"/>
        <xs:element name="taille"  type="xs:int"/>
        <xs:element name="dateNaiss"  type="xs:string" minOccurs="0"/>
        <xs:element name="adresses"  minOccurs="0">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="adresse" type="adresse" maxOccurs="unbounded" minOccurs="0"/>
            </xs:sequence>
           </xs:complexType>
         </xs:element>
       </xs:sequence>
     </xs:complexType>
     <xs:complexType name="adresse">
       <xs:sequence>
         <xs:element name="codePostal" type="xs:string"  minOccurs="0"/>
         <xs:element name="ligne1" type="xs:string"  minOccurs="0"/>
         <xs:element name="ligne2" type="xs:string"  minOccurs="0"/>
         <xs:element name="pays" type="xs:string"  minOccurs="0"/>
         <xs:element name="ville" type="xs:string"  minOccurs="0"/>
       </xs:sequence>
     </xs:complexType>
</xs:schema>

78 commentaires