#751 : ProjectForgeRootElement.java

Objectif : Une classe de base abstraite pour les éléments racine XML dans le système de sérialisation XmlStream personnalisé de ProjectForge. Il ne s'agit ni de JAXB ni de XStream — c'est un framework XML léger et personnalisé construit de toutes pièces pour des besoins spécifiques au projet : export/import de données entre instances ProjectForge, persistance des préférences utilisateur et sérialisation de configuration. Le Javadoc explique : "Pour l'export et l'import, il est utile d'utiliser une instance de cet objet pour définir par exemple le fuseau horaire, la version, etc." — chaque fichier XML exporté doit contenir des métadonnées : quel fuseau horaire a été utilisé lors de l'export, quelle version de ProjectForge a créé le fichier, et quand il a été créé. Sans ces informations, l'import sur un autre serveur pourrait mal interpréter les dates ou échouer à appliquer les migrations de format.

1. created (Date) : quand le XML a été créé. Le setCreated() sans argument définit automatiquement l'heure actuelle avec une précision à la seconde (millisecondes mises à zéro — withPrecision(DatePrecision.SECOND) en utilisant PFDateTime). C'est important : si deux fichiers XML ont le même created, ils ont été exportés depuis le même lot. L'importateur utilise cet horodatage pour déterminer quelles données sont les plus récentes en cas de conflit.
2. timeZone (java.util.TimeZone) : le fuseau horaire utilisé lors de l'export. Critique pour les dates : si un serveur à Berlin exporte "2025-05-15 09:00 Europe/Berlin" et que l'import a lieu à New York, sans fuseau horaire explicite, la date serait interprétée comme 09:00 EST au lieu de 03:00 EST. Un timeZone explicite empêche les décalages de date lors de l'import multiplateforme.
3. version (String, annotée @XmlField(asAttribute=true)) : la version de ProjectForge qui a créé le fichier. Utilisée pour la migration de format — si l'importateur voit version="7.4", il sait qu'il doit appliquer les convertisseurs pour le format 7.4 → 8.0. L'annotation @XmlField(asAttribute=true) signifie que la version est écrite comme un attribut de l'élément racine : <projectforge version="8.0">, et non comme une balise imbriquée.

Chaque setter retourne ProjectForgeRootElement, permettant une initialisation en chaîne :

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

C'est pratique pour créer des exports — toutes les métadonnées sont configurées en une seule ligne, et l'objet est prêt pour la sérialisation.

ProjectForgeRootElement est la classe de base abstraite. Les éléments racine concrets (par exemple, ProjectForgeData avec la balise racine <projectforgeData>) l'étendent et ajoutent leurs propres champs enfants. L'ensemble du système XmlStream se compose de :

• @XmlField (#752) / @XmlOmitField (#757) — annotations au niveau des champs (équivalentes à @XStreamAlias/@XStreamOmitField de XStream)
• @XmlObject (#754) — marqueur au niveau de la classe pour les objets sérialisables
• XmlObjectReader (#755) / XmlObjectWriter (#756) — moteur de lecture/écriture
• Hiérarchie Converter — convertisseurs de types (Date→ISO, BigDecimal→String, etc.)
• AliasMap (#758) — mapping Classe↔balise XML
• XmlRegistry — registre des objets XML enregistrés

Ce framework coexiste en parallèle avec XStream dans ProjectForge. XStream est utilisé pour les préférences utilisateur (sérialisation de RecentQueue, UserPref), tandis que XmlStream est utilisé pour l'export/import de données entre instances (là où le contrôle du format, la validation et le versioning sont nécessaires).

XStream est une excellente bibliothèque, mais elle a des limitations pour le cas d'usage de l'export de données :

• Versioning : XStream ne supporte pas la migration de format. Si le format XML change entre les versions de ProjectForge, XStream échouerait simplement lors de la désérialisation. XmlStream stocke explicitement la version et permet d'appliquer des convertisseurs pendant la lecture.
• Contrôle du schéma : XStream génère le XML "tel quel" — les noms de champs Java deviennent des noms de balises. XmlStream permet de définir explicitement des alias et la structure via des annotations, ce qui est important pour la rétrocompatibilité.
• Sécurité : XStream peut désérialiser des objets Java arbitraires (une vulnérabilité connue). XmlStream fonctionne uniquement avec les types enregistrés dans XmlRegistry.

868d6abb7 2025 → 2026 (mise à jour de l'année de copyright)
63081666f En-têtes des fichiers source : 2024→2025
5f9bbfbd3 Correction de fautes de frappe dans le répertoire projectforge-business
b6092df09 Copyright 2023 → 2024
ab45d51fa Copyright 2001-2022 → 2001-2023
5f7ef41b8 Copyright 2021 → 2022
cd27dd997 package xstream → xmlstream
ceb63e8a1 En-tête du code source : (C) 2001-2021
7c79f1922 Copyright de l'en-tête source → 2020
24019a0f5 Élimination des occurrences de DateHolder
32f634b88 Optimisation des imports
dd5ca38ac Mise à jour ou création du copyright de tous les en-têtes de fichiers Java
9ebb88522 Commit initial

Modifications notables : 24019a0f5 — a éliminé DateHolder (classe pré-Java-8) de cette classe, migrant la gestion des dates vers PFDateTime (propre wrapper date/heure de ProjectForge autour de java.util.Date et java.time). 5f9bbfbd3 — a corrigé des fautes de frappe dans la base de code (y compris probablement dans les commentaires ou Javadoc). cd27dd997 — le paquetage a été renommé de xstream à xmlstream pour éviter toute confusion avec XStream. Les trois champs principaux (created, timeZone, version) et le modèle d'API fluide sont stables depuis le commit initial.