Here is the complete HTML translated into French, with the language set to `fr`, the FR link marked as active, and the title updated with `[FR]`. ```html #754 : XmlField [FR]
EN · DE · RU · FR · ES
← Index · ← Index des fichiers · ← Précédent · Suivant → · 📄 source

#754 : XmlField.java

projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlField.java Annotation Java — annotation centrale au niveau des champs du framework XmlStream. 92 lignes. @Target(FIELD), @Retention(RUNTIME). Source : projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlField.java 92 lignes · 17 code · 63 commentaires · 12 vides
Objectif : L'annotation centrale du framework XmlStream — équivalent à @XmlElement, @XmlAttribute de JAXB, @XStreamAlias et @XStreamAsAttribute de XStream, le tout combiné en une seule annotation. Marque un champ Java comme sérialisable en XML et contrôle exactement comment il est écrit. Appliquée au niveau du champ (@Target(FIELD)) et disponible à l'exécution via la réflexion (@Retention(RUNTIME)) — c'est ainsi que XmlObjectWriter et XmlObjectReader découvrent les champs sérialisables.

8 Attributs d'annotation

alias() — Nom de l'élément/attribut XML

Remplace le nom du champ lors de la sérialisation. Sans alias : private String firstName → balise <firstName>. Avec alias : @XmlField(alias="first-name") → balise <first-name>. Utile lorsque le format XML doit se conformer à un schéma externe ou lorsqu'un nom de champ Java entre en conflit avec un mot réservé XML.

asAttribute() et asElement() — Attribut vs élément

Contrôle si la valeur est sérialisée en tant qu'attribut XML (compact) ou élément (structuré) :

<!-- En tant qu'attribut : -->
<user id="42" name="John"/>

<!-- En tant qu'élément : -->
<user><id>42</id><name>John</name></user>

Nuance importante du Javadoc : "asAttribute=false n'a aucun effet (veuillez utiliser asElement=true à la place)" et vice versa. Cela signifie que false n'est pas une négation — c'est "laisser par défaut", ce qui peut être remplacé par les paramètres globaux dans XmlObjectWriter.asAttributeAsDefault(). Pour garantir la sérialisation en attribut, utilisez asAttribute=true. Pour garantir un élément, utilisez asElement=true.

defaultDoubleValue / defaultIntValue / defaultStringValue / defaultBooleanValue — Compression XML

Si la valeur du champ est égale à la valeur par défaut déclarée, elle n'est PAS sérialisée en XML. C'est un mécanisme de compression : les valeurs par défaut typiques n'occupent pas d'espace dans la sortie. Lors de la désérialisation, les balises absentes reçoivent la valeur par défaut. Les nombres magiques de XmlConstants (#751) servent de sentinelle "non défini" pour les valeurs par défaut int et string. Pour boolean, la valeur par défaut est false (la valeur la plus courante). Pour double, la valeur par défaut est NaN ("non défini").

asCDATA() — Protection des caractères spéciaux

Si true, la valeur de la chaîne est encapsulée dans un bloc XML <![CDATA[...]]>. Nécessaire pour les champs pouvant contenir les caractères <, >, & — par exemple, HTML dans les champs de description ou SQL dans les logs. Sans CDATA, ces caractères devraient être échappés en &lt;, &gt;, &amp;, rendant le XML illisible.

Consommation à l'exécution

  1. XmlObjectWriter parcourt tous les champs d'un objet via la réflexion lors de la sérialisation
  2. Pour chaque champ, vérifie la présence de @XmlField (et l'absence de @XmlOmitField)
  3. Si présent, lit les paramètres : alias (nom de balise), asAttribute (format), default* (logique de saut), asCDATA (format)
  4. Appelle le Converter approprié pour transformer la valeur du champ en chaîne
  5. XmlObjectReader fait l'inverse : lit la balise/l'attribut depuis le XML, trouve le champ correspondant par nom ou alias, appelle Converter pour la transformation inverse

Comparaison avec XStream et JAXB

FonctionnalitéXmlFieldXStreamJAXB
Alias de champalias="name"@XStreamAlias("name")@XmlElement(name="name")
Attribut vs élémentasAttribute=true@XStreamAsAttribute@XmlAttribute
Exclusion de champ@XmlOmitField@XStreamOmitField@XmlTransient
Valeur par défautdefaultIntValue=0❌ aucune❌ aucune
CDATAasCDATA=true❌ aucune❌ aucune
Versionnage du format✅ via XmlObject❌ aucune❌ aucune
XmlField + XmlStream offrent plus de contrôle sur le format XML que XStream, mais nécessitent une annotation manuelle. XStream "fonctionne" sans annotations mais génère un XML moins contrôlé. Le choix de XmlStream pour l'export de données a été motivé spécifiquement par le besoin de contrôle du format et de versionnage.

Historique Git

868d6abb7 2025 → 2026 (mise à jour de l'année de copyright)
63081666f En-têtes des fichiers source : 2024→2025
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 package xstream → xmlstream (renommé pour éviter la confusion avec la bibliothèque XStream)
ceb63e8a1 En-tête du code source : (C) 2001-2021
7c79f1922 Copyright de l'en-tête source → 2020
32f634b88 Optimiser les imports
dd5ca38ac Copyright de tous les en-têtes de fichiers Java mis à jour ou créés
9ebb88522 Commit initial
Les attributs de l'annotation sont stables depuis le commit initial. Seuls les en-têtes de copyright, l'optimisation des imports (32f634b88) et le renommage du package ont touché ce fichier. L'attribut commenté implementationClass() suggère que l'auteur a envisagé un mappage interface-implémentation au niveau du champ mais a choisi de le gérer dans XmlObjectReader.addImplementationMapping() à la place.