#759: XmlOmitField.java
projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlOmitField.java Anotación marcadora Java — excluye un campo de la serialización XML de XmlStream. Fuente: projectforge-business/src/main/java/org/projectforge/framework/xmlstream/XmlOmitField.java 39 líneas · 9 código · 26 comentarios · 4 en blanco
Propósito: Una anotación marcadora sin parámetros que indica al framework XmlStream que omita un campo durante la serialización y deserialización XML. Es el equivalente de XmlStream a la palabra clave transient de Java y a @XmlTransient de JAXB, pero limitado exclusivamente al framework XmlStream de ProjectForge — dejando el campo intacto para la serialización Java, la persistencia JPA y otros subsistemas.
Arquitectura
La anotación en sí es mínima — 3 líneas de código,
@Target(FIELD),
@Retention(RUNTIME). Su poder proviene de los
consumidores que verifican su presencia:
•
XmlObjectWriter.writeField() (
#758, línea ~242):
if (field.isAnnotationPresent(XmlOmitField.class)) continue;
•
XmlObjectReader.read() (
#757, línea ~471): omite los campos anotados con
@XmlOmitField durante la deserialización
No hay lógica en la anotación misma — es un marcador puro consumido de forma reflectiva por el par lector/escritor.
¿Por qué una anotación separada en lugar de transient?
La palabra clave transient de Java excluye un campo de todos los mecanismos de serialización — Serialización Java, XStream, XmlStream, mapeadores JSON, todo. Esto suele ser demasiado amplio:
Escenario: Un campo como computedHash debería almacenarse en caché en la sesión HTTP (serialización Java) pero no debe aparecer en exportaciones XML (derrochador, engañoso).
Solución: Hacer que el campo no sea transitorio (para que participe en la serialización de sesión Java) y anotarlo con @XmlOmitField (para que XmlStream lo omita). Esto proporciona un control por framework sobre la visibilidad de la serialización.
Ejemplo de seguridad: password en PFUserDO. El campo es transient (seguridad de sesión) Y está anotado con @XmlOmitField (seguridad XML). Incluso si alguien elimina transient para depuración, la anotación proporciona una segunda barrera que evita que las contraseñas se filtren en las exportaciones XML.
Contraste con @XmlField(defaultValue=...)
| Mecanismo | Cuando se omite el campo | Caso de uso |
|---|
@XmlOmitField | Siempre — independientemente del valor | Contraseñas, campos calculados, estado temporal, datos sensibles |
@XmlField(defaultIntValue=0) | Condicionalmente — solo cuando el valor es igual al predeterminado | Optimización de tamaño: omitir valores cero, cadenas vacías, nulos |
La diferencia es semántica: @XmlOmitField dice "este campo no tiene nada que hacer en XML", mientras que @XmlField(defaultValue=...) dice "este campo a veces es redundante — omítelo cuando lo sea". Uno es una política estricta, el otro es una optimización suave.
Historial de Git
868d6abb7 2025 → 2026 (actualización de año de copyright)
63081666f Encabezados de archivos fuente: 2024→2025
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 paquete xstream → xmlstream (renombrado para evitar confusión con la librería XStream)
ceb63e8a1 Encabezado de código fuente: (C) 2001-2021
7c79f1922 Copyright del encabezado fuente → 2020
32f634b88 Optimizar importaciones
dd5ca38ac Copyright de todos los encabezados de archivos Java actualizado o creado
9ebb88522 Commit inicial
La anotación ha permanecido sin cambios desde el commit inicial — solo los encabezados de copyright y un cambio de nombre de paquete (xstream → xmlstream). Esta estabilidad refleja su diseño: una anotación marcadora sin parámetros no tiene partes móviles que puedan romperse. El único cambio significativo fue cd27dd997 que renombró el paquete de xstream a xmlstream para evitar colisión de nombres con la librería XStream (com.thoughtworks.xstream).
Trío de anotaciones XmlStream
| Anotación | Archivo | Rol |
|---|
@XmlField | #755 | Declara un campo para serialización con nombre, tipo, valor predeterminado, formato, orden |
@XmlObject | #756 | Declara una clase como serializable en XML con alias |
@XmlOmitField | #759 | Excluye un campo de la serialización por completo |
Juntas, estas tres anotaciones forman la superficie de configuración completa del framework XmlStream. @XmlObject habilita una clase para serialización, @XmlField configura campos individuales, y @XmlOmitField deshabilita campos selectivamente. Esto es más simple que JAXB (que tiene ~20 anotaciones) y más explícito que el enfoque de convención pura de XStream.