2. Un premier exemple

2.1. Premières annotations JAXB

Reprenons notre exemple de la classe Marin, et enrichissons-le un peu.

Exemple 1. Modèle JAXB

//
 // énumération Grade
 //
 public enum Grade {
    MATELOT, BOSCO, PACHA, CUISINIER
}

 //
 // Entité Marin
 //
 @XmlRootElement(name="marin", namespace="http://www.paumard.org/cours-jaxb")
 @XmlAccessorType(XmlAccessType.FIELD)
 @Entity
 public  class Marin  implements Serializable {

     @XmlAttribute(name="id")
     @Id
     @GeneratedValue(strategy = GenerationType.AUTO)
     private Long id;

     private String nom ;

     @Enumerated(EnumType.STRING)
     private Grade grade ;

     // reste de la classe
}

Les trois annotations utilisées sont les suivantes.

@XmlRootElement : indique que nos objets Marin seront des objets racine des documents XML que nous allons générer. Le nom passé en attribut correspond au nom de l'élément racine du document XML généré. Le namespace est lui l'espace de noms utilisé.
@XmlAccessorType : indique que les champs de la classe Marin seront lus directement, sans passer par les getters . Cette annotation peut prendre comme argument XmlAccessType.PROPERTY si l'on veut passer par les getters .
@XmlAttribute : indique que ce champ doit être écrit dans un attribut plutôt qu'un sous-élément. Le nom de cet attribut est précisé en tant qu'attribut de cette annotation.

On constate deux choses sur cet exemple :

les annotations JAXB sont compatibles avec les annotations JPA ;
bien que les annotations soient différentes, les concepts JAXB et JPA sont les mêmes, on peut donc s'attendre à devoir traiter les même problématiques relativement aux relations notamment.

2.2. Création d'un document XML

Écrivons un code permettant de créer un document XML représentant un marin.

Exemple 2. Création d'un document XML par JAXB

public  static  void main(String[] args)  throws JAXBException {
    
     // création d'un objet de type Marin
    Marin marin =  new Marin() ;
    marin.setId(15L) ;
    marin.setNom("Surcouf") ;
    marin.setGrade(Grade.PACHA) ;
    
     // création d'un contexte JAXB sur la classe Marin
    JAXBContext context = JAXBContext.newInstance(Marin.class) ;
    
     // création d'un marshaller à partir de ce contexte
    Marshaller marshaller = context.createMarshaller() ;
    
     // on choisit UTF-8 pour encoder ce fichier
    marshaller.setProperty("jaxb.encoding",  "UTF-8") ;
     // et l'on demande à JAXB de formatter ce fichier de façon 
     // à pouvoir le lire à l'oeil nu
    marshaller.setProperty("jaxb.formatted.output", true) ;
    
     // écriture finale du document XML dans un fichier surcouf.xml
    marshaller.marshal(marin,  new File("surcouf.xml")) ;
}

Examinons le document XML généré.

Exemple 3. Document XML généré par JAXB

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

 <ns2:marin  xmlns:ns2="http://www.paumard.org/cours-jaxb"  id="15">
     <nom>Surcouf</nom>
     <grade>PACHA</grade>
 </ns2:marin>

Ce document est bien conforme à ce qui était prévu :

ce document a bien marin pour élément racine, dans le bon espace de noms ;
le champ id est bien écrit en tant qu'attribut du nœud marin ;
les champs nom et grade sont écrits en tant que sous-éléments du nœud marin.

2.3. Lecture d'un document XML

La lecture de ce document permet de recréer un objet Marin par lecture du document XML. Le code de cette lecture est symétrique du code d'écriture.

Exemple 4. Lecture d'un document XML par JAXB

public  static  void main(String[] args)  throws JAXBException {

     // création d'un contexte JAXB sur la classe Marin
    JAXBContext context = JAXBContext.newInstance(Marin.class) ;
    
     // création d'un unmarshaller
    Unmarshaller unmarshaller = context.createUnmarshaller() ;
    Marin surcouf = (Marin)unmarshaller.unmarshal(new File("surcouf.xml")) ;
    
    System.out.println("Id = " + surcouf.getId()) ;
    System.out.println("Nom = " + surcouf.getNom()) ;
}

2.4. Conclusion

Comme on peut le voir, la création et la lecture de documents XML par JAXB se résument à deux choses :

annoter les classes du modèles correctement ;
écrire quelques lignes de code pour écrire ou lire le contenu XML.

JAXB est très adapté à la lecture et à l'écriture rapide de documents XML. Comme nous allons le voir dans la suite, cette API permet également de traiter des modèles de classes complexes, en suivant la même marche à suivre. De plus, JAXB est interfacé naturellement avec les services web et services REST. Le marshalling d'objets en XML par JAXB est l'un des deux comportements par défaut des services REST JEE5 et JEE6, comme nous allons le voir dans la suite.