#759 : XmlOmitField.java
projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlOmitField.java Annotation de marquage Java — exclut un champ de la sérialisation XML XmlStream. Source : projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlOmitField.java 39 lignes · 9 lignes de code · 26 commentaires · 4 lignes vides
Objectif : Une annotation de marquage sans paramètre qui indique au framework XmlStream d'ignorer un champ lors de la sérialisation et de la désérialisation XML. C'est l'équivalent XmlStream du mot-clé transient de Java et de @XmlTransient de JAXB, mais limité exclusivement au framework XmlStream de ProjectForge — laissant le champ intact pour la sérialisation Java, la persistance JPA et les autres sous-systèmes.
Architecture
L'annotation elle-même est minimale — 3 lignes de code,
@Target(FIELD),
@Retention(RUNTIME). Sa puissance vient des
consommateurs qui vérifient sa présence :
•
XmlObjectWriter.writeField() (
#758, ligne ~242) :
if (field.isAnnotationPresent(XmlOmitField.class)) continue;
•
XmlObjectReader.read() (
#757, ligne ~471) : ignore les champs annotés avec
@XmlOmitField lors de la désérialisation
Il n'y a aucune logique dans l'annotation elle-même — c'est un pur marqueur consommé par réflexion par la paire lecteur/écrivain.
Pourquoi une annotation séparée plutôt que transient ?
Le mot-clé transient de Java exclut un champ de tous les mécanismes de sérialisation — sérialisation Java, XStream, XmlStream, mappeurs JSON, tout. C'est souvent trop large :
Scénario : Un champ comme computedHash devrait être mis en cache dans la session HTTP (sérialisation Java) mais ne doit pas apparaître dans les exportations XML (gaspillage, trompeur).
Solution : Rendre le champ non-transient (afin qu'il participe à la sérialisation de session Java) et l'annoter avec @XmlOmitField (afin que XmlStream l'ignore). Cela donne un contrôle par framework sur la visibilité de la sérialisation.
Exemple de sécurité : password dans PFUserDO. Le champ est transient (sécurité de session) ET annoté avec @XmlOmitField (sécurité XML). Même si quelqu'un supprime transient pour le débogage, l'annotation fournit une deuxième barrière empêchant les mots de passe de fuir dans les exportations XML.
Contraste avec @XmlField(defaultValue=...)
| Mécanisme | Quand le champ est ignoré | Cas d'utilisation |
|---|
@XmlOmitField | Toujours — quelle que soit la valeur | Mots de passe, champs calculés, état temporaire, données sensibles |
@XmlField(defaultIntValue=0) | Conditionnellement — uniquement lorsque la valeur est égale à la valeur par défaut | Optimisation de taille : omettre les valeurs nulles, les chaînes vides, les nulls |
La différence est sémantique : @XmlOmitField signifie "ce champ n'a rien à faire dans le XML", tandis que @XmlField(defaultValue=...) signifie "ce champ est parfois redondant — ignore-le quand il l'est". L'un est une politique stricte, l'autre une optimisation douce.
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 toute 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
L'annotation est restée inchangée depuis le commit initial — seuls les en-têtes de copyright et un renommage de package (xstream → xmlstream). Cette stabilité reflète sa conception : une annotation de marquage sans paramètre n'a aucune pièce mobile qui pourrait se casser. Le seul changement significatif a été cd27dd997 qui a renommé le package de xstream à xmlstream pour éviter une collision de noms avec la bibliothèque XStream (com.thoughtworks.xstream).
Le trio d'annotations XmlStream
| Annotation | Fichier | Rôle |
|---|
@XmlField | #755 | Déclare un champ pour la sérialisation avec nom, type, valeur par défaut, format, ordre |
@XmlObject | #756 | Déclare une classe comme sérialisable en XML avec un alias |
@XmlOmitField | #759 | Exclut complètement un champ de la sérialisation |
Ensemble, ces trois annotations forment la surface de configuration complète du framework XmlStream. @XmlObject active une classe pour la sérialisation, @XmlField configure les champs individuels, et @XmlOmitField désactive sélectivement des champs. C'est plus simple que JAXB (qui a environ 20 annotations) et plus explicite que l'approche purement conventionnelle de XStream.