← Index · ← File index · ← Prev · Next → · 📄 source

#705: `HibernateCollectionsMapper.java`

projectforge-business/src/main/java/org/projectforge/framework/persistence/xstream/HibernateCollectionsMapper.java XStream mapper — replaces Hibernate collection type names with JDK equivalents in XML output, projectforge-business/src/main/java/org/projectforge/framework/persistence/xstream/HibernateCollectionsMapper.java 114 lines · 49 code · 51 comments · 14 blank

Extends XStream's XmlFriendlyMapper to intercept type-to-name and class-to-name lookups during serialization. When XStream needs to write a class name as an XML element or attribute, this mapper substitutes Hibernate-specific collection classes (PersistentList, PersistentSet, etc.) with their standard JDK counterparts (ArrayList, HashSet, etc.). This ensures the generated XML contains readable, framework-agnostic type names. This operates at the name mapping layer — the HibernateCollectionConverter handles the actual collection data conversion.

Architecture

Class Hierarchy

HibernateCollectionsMapper extends com.thoughtworks.xstream.mapper.XmlFriendlyMapper, which itself extends MapperWrapper. The XStream mapper chain follows the Decorator pattern — each mapper wraps another mapper, and calls are forwarded through the chain. This mapper intercepts three specific methods to apply Hibernate→JDK collection class substitutions.

Mapping Tables

The class uses three parallel arrays indexed identically:

Index	Hibernate Class (`hbClasses`)	Hibernate Name (`hbClassNames`)	JDK Replacement (`jdkClasses`/`jdkClassNames`)
0	`PersistentList`	`org.hibernate.collection.spi.PersistentList`	`java.util.ArrayList`
1	`PersistentSet`	`org.hibernate.collection.spi.PersistentSet`	`java.util.HashSet`
2	`PersistentMap`	`org.hibernate.collection.spi.PersistentMap`	`java.util.HashMap`
3	`PersistentSortedSet`	`org.hibernate.collection.spi.PersistentSortedSet`	`java.util.TreeSet`
4	`PersistentSortedMap`	`org.hibernate.collection.spi.PersistentSortedMap`	`java.util.TreeMap`

Overridden Methods

Method	Input	Action
`mapNameToXML(String javaName)`	Fully-qualified Java class name	Applies string replacement via `replaceClasses(String)`, then delegates to super for XML-friendly encoding (e.g. replacing `$` in inner class names).
`serializedClass(Class type)`	`Class` object	Applies class replacement via `replaceClasses(Class)`, then delegates to super.
`serializedMember(Class type, String fieldName)`	Declaring class + field name	Applies class replacement to `type` before delegating to super, ensuring field declarations within Hibernate collections are serialized with JDK type context.

Directionality

This mapper is write-only (serialization/deflating direction). It does not implement the reverse mapping for realClass() or deserialization. The source explicitly notes: "This mapper takes care only of the writing to the XML (deflating) not the other way around (inflating) because there is no need." When XML is deserialized, XStream creates standard JDK collections, and Hibernate's ORM layer wraps them into PersistentCollection subclasses when the entity is later attached to a session.

Integration Points

Wraps the XStream mapper chain — instantiated with a Mapper delegate (the underlying mapper it decorates).
Works alongside HibernateCollectionConverter: the mapper handles what type name appears in XML, the converter handles how the data is written.
Used in XStream configuration alongside HibernateMapper (which has overlapping but more comprehensive mapping logic).

Design Decisions & Gotchas

XmlFriendlyMapper superclass: Extending XmlFriendlyMapper (rather than plain MapperWrapper) ensures that after the class name replacement, the result is still XML-safe (e.g., $ characters from inner class names are encoded).
Parallel arrays pattern: The mapping uses three parallel arrays hard-coded at class initialization time. This is performant (O(n) linear scan of 5 elements) but fragile — if Hibernate adds new PersistentCollection subtypes, this mapper silently ignores them. Compare with HibernateMapper which uses a Map for more readable and extensible registration.
Redundancy with HibernateMapper: Both HibernateCollectionsMapper and HibernateMapper perform collection class name substitution. HibernateMapper (which uses defaultImplementationOf() and serializedClass()) is the more modern approach and includes PersistentBag (which this mapper omits). In practice, only one should be active to avoid double-mapping.
No PersistentBag support: Notice that PersistentBag (Hibernate's default collection for untyped List fields) is missing from this mapper's arrays. It is present in HibernateMapper.
Attribution: Originally authored by Costin Leau.

Git History

868d6abb7 2025 -> 2026
63081666f Source file headers: 2024-> 2025.
c1d14ecdb Migration stuff in progress...
b6092df09 Copyright 2023 -> 2024
ab45d51fa Copyright 2001-2022 -> 2001-2023.
5f7ef41b8 Copyright 2021 -> 2022
ceb63e8a1 Source code header: (C) 2001-2021.
7c79f1922 Copyright of source header -> 2020.
32f634b88 Optimize imports
dd5ca38ac CopyRight of all java file-header updated or created.
9ebb88522 Initial commit

#705: HibernateCollectionsMapper.java