#751: ProjectForgeRootElement.java

Propósito: Una clase base abstracta para elementos raíz XML en el sistema de serialización XmlStream personalizado de ProjectForge. No es JAXB ni XStream — es un framework XML ligero y personalizado construido desde cero para necesidades específicas del proyecto: exportación/importación de datos entre instancias de ProjectForge, persistencia de preferencias de usuario y serialización de configuración. El Javadoc explica: "Para exportación e importación es útil usar una instancia de este objeto para definir, por ejemplo, la zona horaria, versión, etc." — cada archivo XML exportado debe llevar metadatos: qué zona horaria se usó durante la exportación, qué versión de ProjectForge creó el archivo y cuándo se creó. Sin esta información, la importación en otro servidor podría malinterpretar las fechas o no aplicar las migraciones de formato.

1. created (Date): cuándo se creó el XML. El método setCreated() sin argumentos establece automáticamente la hora actual con precisión de segundos (milisegundos a cero — withPrecision(DatePrecision.SECOND) usando PFDateTime). Esto es importante: si dos archivos XML tienen el mismo created, fueron exportados desde el mismo lote. El importador usa esta marca de tiempo para determinar qué dato es más reciente en escenarios de conflicto.
2. timeZone (java.util.TimeZone): la zona horaria utilizada durante la exportación. Crítico para fechas: si un servidor en Berlín exporta "2025-05-15 09:00 Europe/Berlin" y la importación ocurre en Nueva York, sin una zona horaria explícita la fecha se interpretaría como 09:00 EST en lugar de 03:00 EST. Un timeZone explícito evita desplazamientos de fecha durante la importación entre plataformas.
3. version (String, anotado @XmlField(asAttribute=true)): la versión de ProjectForge que creó el archivo. Se usa para la migración de formato — si el importador ve version="7.4", sabe que debe aplicar convertidores para el formato 7.4 → 8.0. La anotación @XmlField(asAttribute=true) significa que la versión se escribe como un atributo del elemento raíz: <projectforge version="8.0">, no como una etiqueta anidada.

Cada setter devuelve ProjectForgeRootElement, permitiendo la inicialización encadenada:

export.setTimeZone(userTZ).setCreated().setVersion("8.0.0");

Esto es conveniente para crear exportaciones — todos los metadatos se configuran en una línea y el objeto está listo para la serialización.

ProjectForgeRootElement es la clase base abstracta. Los elementos raíz concretos (por ejemplo, ProjectForgeData con la etiqueta raíz <projectforgeData>) la extienden y añaden sus propios campos hijo. Todo el sistema XmlStream consiste en:

• @XmlField (#752) / @XmlOmitField (#757) — anotaciones a nivel de campo (equivalentes a @XStreamAlias/@XStreamOmitField de XStream)
• @XmlObject (#754) — marcador a nivel de clase para objetos serializables
• XmlObjectReader (#755) / XmlObjectWriter (#756) — motor de lectura/escritura
• Jerarquía Converter — convertidores de tipos (Date→ISO, BigDecimal→String, etc.)
• AliasMap (#758) — mapeo Clase↔etiqueta XML
• XmlRegistry — registro de objetos XML registrados

Este framework coexiste en paralelo con XStream en ProjectForge. XStream se usa para preferencias de usuario (serialización de RecentQueue, UserPref), mientras que XmlStream se usa para exportación/importación de datos entre instancias (donde se necesitan control de formato, validación y versionado).

XStream es una excelente librería, pero tiene limitaciones para el caso de uso de exportación de datos:

• Versionado: XStream no soporta migración de formato. Si el formato XML cambió entre versiones de ProjectForge, XStream simplemente fallaría en la deserialización. XmlStream almacena explícitamente la versión y permite aplicar convertidores durante la lectura.
• Control de esquema: XStream genera XML "tal cual" — los nombres de campos Java se convierten en nombres de etiquetas. XmlStream permite establecer explícitamente alias y estructura mediante anotaciones, lo cual es importante para la compatibilidad hacia atrás.
• Seguridad: XStream puede deserializar objetos Java arbitrarios (una vulnerabilidad conocida). XmlStream solo funciona con tipos registrados en XmlRegistry.

868d6abb7 2025 → 2026 (actualización de año de copyright)
63081666f Encabezados de archivos fuente: 2024→2025
5f9bbfbd3 Corrección de errores tipográficos en el directorio projectforge-business
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 paquete xstream → xmlstream
ceb63e8a1 Encabezado de código fuente: (C) 2001-2021
7c79f1922 Copyright del encabezado fuente → 2020
24019a0f5 Eliminar ocurrencias de DateHolder
32f634b88 Optimizar importaciones
dd5ca38ac Copyright de todos los encabezados de archivos Java actualizado o creado
9ebb88522 Commit inicial

Cambios notables: 24019a0f5 — eliminó DateHolder (clase pre-Java-8) de esta clase, migrando el manejo de fechas a PFDateTime (envoltorio de fecha/hora propio de ProjectForge alrededor de java.util.Date y java.time). 5f9bbfbd3 — corrigió errores tipográficos en la base de código (incluyendo probablemente en comentarios o Javadoc). cd27dd997 — el paquete se renombró de xstream a xmlstream para evitar confusiones con XStream. Los tres campos principales (created, timeZone, version) y el patrón de API fluida se han mantenido estables desde el commit inicial.