XmlField.javaЦентральная аннотация фреймворка XmlStream — аналог @XStreamAlias, @XStreamAsAttribute, @XStreamOmitField и части @XmlElement из JAXB, но в одной аннотации. 92 строки. Помечает поле Java-класса как сериализуемое в XML и управляет тем, как именно оно будет записано. Применяется на уровне полей (@Target(FIELD)) и доступна во время выполнения через reflection (@Retention(RUNTIME)).
alias() — имя в XMLПереопределяет имя поля при сериализации. Без alias: private String firstName → тег <firstName>. С alias: @XmlField(alias="first-name") → тег <first-name>. Полезно когда XML-формат должен соответствовать внешней схеме.
asAttribute() и asElement() — атрибут или элемент?<!-- Как атрибут: --> <user id="42" name="John"/> <!-- Как элемент: --> <user><id>42</id><name>John</name></user>
asAttribute=true — записать как атрибут. asElement=true — явно записать как элемент. Важный нюанс из Javadoc: "asAttribute=false has no effect (please use asElement=true instead)". false — это не отрицание, а "значение по умолчанию, которое может быть переопределено глобальной настройкой".
defaultDoubleValue / defaultIntValue / defaultStringValue / defaultBooleanValue — сжатие XMLЕсли значение поля равно значению по умолчанию, оно НЕ записывается в XML. При чтении: если тег отсутствует, полю присваивается значение по умолчанию. Магические числа из XmlConstants (#751) используются как sentinel "не задано".
asCDATA() — защита от спецсимволовЕсли true, строковое значение оборачивается в XML-блок <![CDATA[...]]>. Нужно для полей с символами <, >, &.
| Возможность | XmlField | XStream | JAXB |
|---|---|---|---|
| Алиас поля | alias="name" | @XStreamAlias("name") | @XmlElement(name="name") |
| Атрибут vs элемент | asAttribute=true | @XStreamAsAttribute | @XmlAttribute |
| Пропуск поля | @XmlOmitField | @XStreamOmitField | @XmlTransient |
| Значение по умолчанию | defaultIntValue=0 | ❌ нет | ❌ нет |
| CDATA | asCDATA=true | ❌ нет | ❌ нет |
| Версионирование | ✅ через XmlObject | ❌ нет | ❌ нет |
868d6abb7 2025 → 2026 (обновление копирайта) 63081666f Source file headers: 2024→2025 b6092df09 Copyright 2023 → 2024 ab45d51fa Copyright 2001-2022 → 2001-2023 5f7ef41b8 Copyright 2021 → 2022 cd27dd997 package xstream → xmlstream ceb63e8a1 Source code header: (C) 2001-2021 7c79f1922 Copyright of source header → 2020 32f634b88 Optimize imports dd5ca38ac CopyRight of all java file-header updated or created 9ebb88522 Initial commit
Атрибуты аннотации не менялись с момента создания. Закомментированный атрибут implementationClass() указывает, что автор рассматривал маппинг интерфейс→реализация на уровне поля, но решил обрабатывать его через XmlObjectReader.addImplementationMapping().