#753: XmlConstants.java

Purpose: A global constants class holding three sentinel values — magic numbers/strings that are guaranteed never to appear in real data, used by the XmlStream serializer to detect "default value not set" conditions and by converters to represent null.

1. MAGIC_INT_NUMBER = -21111970 — A negative eight-digit number that will never be a legitimate ID or quantity. Used as the default value for defaultIntValue in the @XmlField annotation. When an int field equals this value, it is NOT serialized to XML — saving space. Likely derived from a developer's birth date (21.11.1970), a common practice for picking unharmful magic numbers.
2. MAGIC_STRING = "faiNg8jojae4Aiy5thaiz7Iefu4Egoarafa6Fu3xEekil8ae" — A 46-character random string with no spaces or special characters. Used as the default for defaultStringValue. No real user will ever enter this as a name or description. When matched, the field is skipped during serialization.
3. NULL_IDENTIFIER = "null" — A special string identifier for null values in XML. When a field is null, XmlObjectWriter writes the literal string "null" (rather than omitting the tag). XmlObjectReader restores null when it reads "null". The code comment warns: "Not really usable for strings, but should be interpreted as null value by all other converters." For string fields, the literal "null" could be legitimate data, so this only works for numbers, dates, booleans, etc.

The design: during serialization, if a field's value equals its declared default (from @XmlField annotation), the field is omitted from XML output. During deserialization, if a field is absent from XML, it receives the default value. This shrinks XML output (especially important for boolean fields where false is the typical default) and makes XML more readable by showing only meaningful fields. The MAGIC_INT_NUMBER and MAGIC_STRING constants serve as the "unset" sentinel — they distinguish between "the developer intentionally set a default of 0/empty-string" and "the developer didn't set any default." The hasDefaultType() method in XmlObjectWriter compares against these sentinels to decide.

In modern Java, these could be enum values or configuration properties. But as a constants class:

• Package-private visibility on MAGIC_INT_NUMBER and MAGIC_STRING — not exposed outside the framework
• Compile-time constants — usable in annotation default values (defaultIntValue() default XmlConstants.MAGIC_INT_NUMBER)
• Zero overhead — no enum lookup, no config file parsing, no dependency injection

hasDefaultType() checks whether a default was explicitly declared in @XmlField:

• For Integer: ann.defaultIntValue() != MAGIC_INT_NUMBER
• For String/Enum: !MAGIC_STRING.equals(ann.defaultStringValue())
• For Boolean: always true (false is a valid default)
• For Double: !Double.isNaN(ann.defaultDoubleValue())

If no default was declared, the field is always serialized. If a default was declared and the value matches, the field is skipped.

868d6abb7 2025 → 2026 (copyright year update)
63081666f Source file headers: 2024→2025
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 package xstream → xmlstream (renamed to avoid XStream library confusion)
ceb63e8a1 Source code header: (C) 2001-2021
7c79f1922 Copyright of source header → 2020
dd5ca38ac CopyRight of all java file-header updated or created
9ebb88522 Initial commit

The constants have not changed since the initial commit. Only copyright headers and the package rename (xstream → xmlstream at cd27dd997) touched this file. The stability is expected — these are foundational sentinel values; changing them would break serialization compatibility with all previously written XML files.