#753 : XmlConstants.java

Objectif : Une classe de constantes globales contenant trois valeurs sentinelles — des nombres/chaînes magiques garantis de ne jamais apparaître dans des données réelles, utilisées par le sérialiseur XmlStream pour détecter les conditions de « valeur par défaut non définie » et par les convertisseurs pour représenter null.

1. MAGIC_INT_NUMBER = -21111970 — Un nombre négatif à huit chiffres qui ne sera jamais un ID ou une quantité légitime. Utilisé comme valeur par défaut pour defaultIntValue dans l'annotation @XmlField. Lorsqu'un champ int est égal à cette valeur, il n'est PAS sérialisé en XML — économisant de l'espace. Probablement dérivé de la date de naissance d'un développeur (21/11/1970), une pratique courante pour choisir des nombres magiques inoffensifs.
2. MAGIC_STRING = "faiNg8jojae4Aiy5thaiz7Iefu4Egoarafa6Fu3xEekil8ae" — Une chaîne aléatoire de 46 caractères sans espaces ni caractères spéciaux. Utilisée comme valeur par défaut pour defaultStringValue. Aucun utilisateur réel ne saisira jamais cela comme nom ou description. Lorsqu'elle correspond, le champ est ignoré lors de la sérialisation.
3. NULL_IDENTIFIER = "null" — Un identifiant de chaîne spécial pour les valeurs null en XML. Lorsqu'un champ est null, XmlObjectWriter écrit la chaîne littérale "null" (plutôt que d'omettre la balise). XmlObjectReader restaure null lorsqu'il lit "null". Le commentaire du code prévient : « Pas vraiment utilisable pour les chaînes, mais doit être interprété comme valeur null par tous les autres convertisseurs. » Pour les champs de type chaîne, le littéral « null » pourrait être une donnée légitime, donc cela fonctionne uniquement pour les nombres, dates, booléens, etc.

La conception : lors de la sérialisation, si la valeur d'un champ est égale à sa valeur par défaut déclarée (provenant de l'annotation @XmlField), le champ est omis de la sortie XML. Lors de la désérialisation, si un champ est absent du XML, il reçoit la valeur par défaut. Cela réduit la sortie XML (particulièrement important pour les champs booléens où false est la valeur par défaut typique) et rend le XML plus lisible en affichant uniquement les champs significatifs. Les constantes MAGIC_INT_NUMBER et MAGIC_STRING servent de sentinelles « non défini » — elles distinguent entre « le développeur a intentionnellement défini une valeur par défaut de 0/chaîne vide » et « le développeur n'a défini aucune valeur par défaut ». La méthode hasDefaultType() dans XmlObjectWriter compare ces sentinelles pour décider.

En Java moderne, celles-ci pourraient être des valeurs d'énumération ou des propriétés de configuration. Mais en tant que classe de constantes :

• Visibilité package-private sur MAGIC_INT_NUMBER et MAGIC_STRING — non exposées en dehors du framework
• Constantes de compilation — utilisables dans les valeurs par défaut des annotations (defaultIntValue() default XmlConstants.MAGIC_INT_NUMBER)
• Surcharge nulle — pas de recherche d'énumération, pas d'analyse de fichier de configuration, pas d'injection de dépendances

hasDefaultType() vérifie si une valeur par défaut a été explicitement déclarée dans @XmlField :

• Pour Integer : ann.defaultIntValue() != MAGIC_INT_NUMBER
• Pour String/Enum : !MAGIC_STRING.equals(ann.defaultStringValue())
• Pour Boolean : toujours vrai (false est une valeur par défaut valide)
• Pour Double : !Double.isNaN(ann.defaultDoubleValue())

Si aucune valeur par défaut n'a été déclarée, le champ est toujours sérialisé. Si une valeur par défaut a été déclarée et que la valeur correspond, le champ est ignoré.

868d6abb7 2025 → 2026 (mise à jour de l'année de copyright)
63081666f En-têtes de 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
dd5ca38ac CopyRight de tous les en-têtes de fichiers Java mis à jour ou créés
9ebb88522 Commit initial

Les constantes n'ont pas changé depuis le commit initial. Seuls les en-têtes de copyright et le renommage du package (xstream → xmlstream au commit cd27dd997) ont touché ce fichier. La stabilité est attendue — ce sont des valeurs sentinelles fondamentales ; les modifier briserait la compatibilité de sérialisation avec tous les fichiers XML précédemment écrits.