#761: ProjectForgeRootElement.java

Что это и зачем

Абстрактный базовый класс для корневых элементов XML в собственной системе сериализации ProjectForge — XmlStream. Это не JAXB и не XStream, а свой легковесный XML-фреймворк, написанный с нуля для конкретных нужд проекта: экспорт/импорт данных между инстансами ProjectForge, сохранение пользовательских настроек, и сериализация конфигурации.

Javadoc: "For export and import it's useful to use an instance of this object to define for example the time zone, version etc." — каждый экспортированный XML-файл должен нести метаданные: часовой пояс, версия ProjectForge, и дата создания. Без этой информации импорт на другом сервере может неправильно интерпретировать даты или не суметь применить миграции формата.

Три поля — три аспекта совместимости

1. created (Date): когда XML был создан. Сеттер setCreated() без аргументов автоматически устанавливает текущее время с точностью до секунд (миллисекунды обнулены — withPrecision(DatePrecision.SECOND) через PFDateTime). Импортёр использует эту метку чтобы понять, какие данные новее при конфликтах.
2. timeZone (java.util.TimeZone): часовой пояс, использованный при экспорте. Критично для дат: если сервер в Берлине экспортирует "2025-05-15 09:00 Europe/Berlin", а импорт в Нью-Йорке, без таймзоны дата будет интерпретирована как 09:00 EST. Наличие явного timeZone предотвращает сдвиги дат.
3. version (String, @XmlField(asAttribute=true)): версия ProjectForge, создавшая файл. Используется для миграции формата — если импортёр видит version="7.4", применяет конвертеры 7.4 → 8.0. Аннотация @XmlField(asAttribute=true) означает запись как атрибут: <projectforge version="8.0">.

Fluent API — все сеттеры возвращают this

Каждый сеттер возвращает ProjectForgeRootElement, позволяя цепочечную инициализацию:

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

Место в иерархии XmlStream

ProjectForgeRootElement — абстрактный базовый класс. Конкретные корневые элементы наследуют его. Вся система XmlStream состоит из:

• @XmlField (#752) / @XmlOmitField (#757) — аннотации полей
• @XmlObject (#754) — аннотация класса
• XmlObjectReader (#755) / XmlObjectWriter (#756) — движок чтения/записи
• Converter иерархия — конвертеры типов
• AliasMap (#758) — маппинг Class↔XML-tag
• XmlRegistry — реестр зарегистрированных XML-объектов

Этот фреймворк существует параллельно с XStream в ProjectForge. XStream для пользовательских настроек, XmlStream — для экспорта/импорта данных.

Почему не XStream?

• Версионирование: XStream не поддерживает миграцию формата
• Контроль схемы: XStream генерирует XML "как получится"
• Безопасность: XStream может десериализовать произвольные Java-объекты (известная уязвимость)

Git History

868d6abb7 2025 → 2026
63081666f Source file headers: 2024→2025
5f9bbfbd3 Fix typos in projectforge-business directory
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
24019a0f5 Eliminate DateHolder occurences
32f634b88 Optimize imports
dd5ca38ac CopyRight of all java file-header updated or created
9ebb88522 Initial commit

Ключевые изменения: 24019a0f5 — удаление DateHolder, миграция на PFDateTime. 5f9bbfbd3 — исправление опечаток. Три основных поля (created, timeZone, version) и fluent API стабильны с начального коммита.