Cette annotation permet de fixer les schémas XML utilisés pour écrire les documents XML générés, et dans le schéma XML associé au jeu de classes annotées.

Elle a la particularité d'annoter un nom de package, ce qui n'est pas le cas le plus fréquemment rencontré. C'est aussi la raison pour laquelle on s'y attarde ici.

On ne peut pas annoter la déclaration package dans une classe Java, ce n'est pas légal, et cela génère une erreur de compilation. Comment doit-on s'y prendre ?

Pour annoter un package en Java, il faut créer un fichier nommé package-info.java, rangé à la racine de ce package. Ce fichier ressemble à un fichier de classe, sauf qu'il ne correspond pas à un nom de classe : le caractère "-" ne peut pas être utilisé pour construire un nom de classe.

Ce fichier ne peut contenir que le nom du package dans lequel il se trouve. Ce nom peut porter plusieurs informations :

  • la javadoc de ce package ;

  • les annotations que l'on souhaite poser dessus.

Voyons un exemple.


Cette déclaration se déclinera de la façon suivante dans le schéma généré.


@XmlEnum permet de préciser la façon dont les valeurs d'une énumération vont être écrites dans le code XML. @XmlEnum fonctionne comme l'annotation JPA @EnumeratedType, qui permet d'imposer d'écrire en base le nom des valeurs énumérées plutôt que le numéro d'ordre. Voyons un exemple de fonctionnement.


Dans ce premier exemple, les valeurs enumérées seront écrites par leur nom. Il s'agit en fait du comportement par défaut de JAXB, on aurait donc pu faire l'économie de cette déclaration. Notons que la restriction xsd est imposée par la classe portée en attribut de @XmlEnum.


Dans ce deuxième exemple, le type de base utilisé est int. Il nous faut donc préciser les valeurs des entiers associées aux valeurs de notre énumération. C'est le rôle de l'annotation @XmlEnumValue, qui se place sur chaque valeur de l'énumération, et qui porte en attribut l'entier associé à cette valeur.

Si le champ ou le getter que l'on annote est de type List, alors on peut spécifier les choses plus finement. Une List Java permet d'enregistrer des éléments de différents types, soit non spécifiés (comme en Java 4), soit étendant une classe ou une interface donnée dans la déclaration de cette liste. Dans les deux cas, une liste peut porter des éléments de différentes classes.

En utilisant l'annotation @XmlElements, on peut spécifier que chaque élément de la liste, du fait de sa classe, est associée à un nœud différent.

Examinons l'exemple suivant, dans lequel les classes Cuisinier et Capitaine étendent Marin.


Voyons un exemple de document XML généré à partir de cette classe annotée.


Ce document XML porte bien les éléments de notre liste tels que nous les avons spécifiés : les instances de Capitaine dans un élément capitaine etc...

Notons la présence de l'annotation @XmlWrapper sur le champ equipage. C'est cette annotation qui permet de ranger les éléments marin, capitaine et cuisinier dans le sous-élément equipage. Si elle n'avait pas été présente, ces éléments auraient été rangés à plat dans l'élément bateau.

JAXB et services REST
Retour au blog Java le soir
Cours & Tutoriaux