#751: ProjectForgeRootElement.java

Zweck: Eine abstrakte Basisklasse für XML-Root-Elemente im benutzerdefinierten XmlStream-Serialisierungssystem von ProjectForge. Es handelt sich nicht um JAXB oder XStream – es ist ein leichtgewichtiges, benutzerdefiniertes XML-Framework, das von Grund auf für projektspezifische Anforderungen entwickelt wurde: Datenexport/-import zwischen ProjectForge-Instanzen, Persistenz von Benutzereinstellungen und Konfigurationsserialisierung. Das Javadoc erklärt: „Für Export und Import ist es nützlich, eine Instanz dieses Objekts zu verwenden, um z. B. die Zeitzone, Version usw. zu definieren.“ – jede exportierte XML-Datei muss Metadaten enthalten: welche Zeitzone beim Export verwendet wurde, welche ProjectForge-Version die Datei erstellt hat und wann sie erstellt wurde. Ohne diese Informationen könnte ein Import auf einem anderen Server Daten falsch interpretieren oder Formatmigrationen fehlschlagen lassen.

1. created (Date): Wann das XML erstellt wurde. Die parameterlose Methode setCreated() setzt automatisch die aktuelle Zeit mit Sekundengenauigkeit (Millisekunden auf null gesetzt – withPrecision(DatePrecision.SECOND) unter Verwendung von PFDateTime). Das ist wichtig: Wenn zwei XML-Dateien denselben created-Wert haben, wurden sie im selben Batch exportiert. Der Importeur verwendet diesen Zeitstempel, um in Konfliktszenarien zu bestimmen, welche Daten neuer sind.
2. timeZone (java.util.TimeZone): Die beim Export verwendete Zeitzone. Kritisch für Daten: Wenn ein Server in Berlin „2025-05-15 09:00 Europe/Berlin“ exportiert und der Import in New York erfolgt, würde das Datum ohne explizite Zeitzone als 09:00 EST statt 03:00 EST interpretiert. Eine explizite timeZone verhindert Datumsverschiebungen beim plattformübergreifenden Import.
3. version (String, annotiert mit @XmlField(asAttribute=true)): Die ProjectForge-Version, die die Datei erstellt hat. Wird für die Formatmigration verwendet – wenn der Importeur version="7.4" sieht, weiß er, dass er Konverter für das Format 7.4 → 8.0 anwenden muss. Die Annotation @XmlField(asAttribute=true) bedeutet, dass die Version als Attribut des Root-Elements geschrieben wird: <projectforge version="8.0">, nicht als verschachteltes Tag.

Jeder Setter gibt ProjectForgeRootElement zurück und ermöglicht so eine verkettete Initialisierung:

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

Dies ist praktisch für die Erstellung von Exporten – alle Metadaten werden in einer Zeile konfiguriert, und das Objekt ist bereit für die Serialisierung.

ProjectForgeRootElement ist die abstrakte Basisklasse. Konkrete Root-Elemente (z. B. ProjectForgeData mit dem Root-Tag <projectforgeData>) erweitern sie und fügen eigene Kind-Felder hinzu. Das gesamte XmlStream-System besteht aus:

• @XmlField (#752) / @XmlOmitField (#757) – Feld-Annotationen (äquivalent zu XStreams @XStreamAlias/@XStreamOmitField)
• @XmlObject (#754) – Marker auf Klassenebene für serialisierbare Objekte
• XmlObjectReader (#755) / XmlObjectWriter (#756) – Lese-/Schreib-Engine
• Converter-Hierarchie – Typkonverter (Date→ISO, BigDecimal→String, usw.)
• AliasMap (#758) – Klasse↔XML-Tag-Zuordnung
• XmlRegistry – Registry der registrierten XML-Objekte

Dieses Framework existiert parallel zu XStream in ProjectForge. XStream wird für Benutzereinstellungen (Serialisierung von RecentQueue, UserPref) verwendet, während XmlStream für den Datenaustausch zwischen Instanzen (wo Formatkontrolle, Validierung und Versionierung erforderlich sind) eingesetzt wird.

XStream ist eine hervorragende Bibliothek, hat aber Einschränkungen für den Anwendungsfall des Datenaustauschs:

• Versionierung: XStream unterstützt keine Formatmigration. Wenn sich das XML-Format zwischen ProjectForge-Versionen ändert, würde XStream bei der Deserialisierung einfach fehlschlagen. XmlStream speichert explizit die Version und ermöglicht die Anwendung von Konvertern während des Lesens.
• Schema-Kontrolle: XStream generiert XML „wie es fällt“ – Java-Feldnamen werden zu Tag-Namen. XmlStream erlaubt die explizite Festlegung von Aliasen und Strukturen über Annotationen, was für die Abwärtskompatibilität wichtig ist.
• Sicherheit: XStream kann beliebige Java-Objekte deserialisieren (eine bekannte Sicherheitslücke). XmlStream arbeitet nur mit Typen, die in der XmlRegistry registriert sind.

868d6abb7 2025 → 2026 (Aktualisierung des Copyright-Jahres)
63081666f Quellcode-Dateiköpfe: 2024→2025
5f9bbfbd3 Korrigiert Tippfehler im Verzeichnis projectforge-business
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 Paket xstream → xmlstream
ceb63e8a1 Quellcode-Kopfzeile: (C) 2001-2021
7c79f1922 Copyright der Quellcode-Kopfzeile → 2020
24019a0f5 Eliminiere DateHolder-Vorkommen
32f634b88 Optimiere Imports
dd5ca38ac Copyright aller Java-Dateiköpfe aktualisiert oder erstellt
9ebb88522 Erster Commit

Bemerkenswerte Änderungen: 24019a0f5 – Eliminierung von DateHolder (Klasse vor Java 8) aus dieser Klasse, Migration der Datumsverarbeitung zu PFDateTime (ProjectForge-eigener Datums-/Zeit-Wrapper um java.util.Date und java.time). 5f9bbfbd3 – Korrektur von Tippfehlern in der Codebasis (wahrscheinlich in Kommentaren oder Javadoc). cd27dd997 – Paket umbenannt von xstream zu xmlstream, um Verwechslungen mit XStream zu vermeiden. Die drei Kernfelder (created, timeZone, version) und das Fluent-API-Muster sind seit dem ersten Commit stabil.