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

#704: `HibernateCollectionConverter.java`

projectforge-business/src/main/java/org/projectforge/framework/persistence/xstream/HibernateCollectionConverter.java XStream converter — converts Hibernate persistent collections to JDK collections during marshalling, projectforge-business/src/main/java/org/projectforge/framework/persistence/xstream/HibernateCollectionConverter.java 130 lines · 69 code · 45 comments · 16 blank

Implements com.thoughtworks.xstream.converters.Converter to intercept every PersistentCollection instance before XStream serializes it. Forces initialization of lazy-loaded collections, extracts the underlying java.util collection (dealing with Hibernate's peculiar internal representation of sets as maps), and delegates the actual XML writing to the appropriate standard XStream converter. This is the value-level converter — the HibernateCollectionsMapper handles name-level mapping, and this converter handles the actual collection data.

Architecture

Converter Registration

XStream converters form a chain. When XStream encounters an object to serialize, it iterates registered converters calling canConvert(Class). HibernateCollectionConverter claims any class assignable to org.hibernate.collection.spi.PersistentCollection — this covers PersistentBag, PersistentList, PersistentSet, PersistentSortedSet, PersistentMap, and PersistentSortedMap. Because XStream checks converters in registration order, this converter must be registered before default converters. This is done by HibernateMapper when configuring XStream instances.

Constructor: Converter Caching

The constructor accepts a ConverterLookup and immediately resolves and caches five converter references:

Field	Converted Type	Purpose
`listSetConverter`	`ArrayList.class`	Handles List and Set output
`mapConverter`	`HashMap.class`	Handles Map output
`treeMapConverter`	`TreeMap.class`	Handles sorted map output
`treeSetConverter`	`TreeSet.class`	Handles sorted set output
`defaultConverter`	`Object.class`	Fallback for unrecognized types

marshal() Algorithm

Cast to PersistentCollection: Checks if source instanceof PersistentCollection. If so, calls forceInitialization() to trigger lazy loading, then retrieves getStoredSnapshot() — the underlying JDK collection that Hibernate uses internally. (Note: a TODO comment references getCollectionSnapshot() as a potential alternative.)
PersistentSortedSet workaround: Hibernate stores sorted sets internally as a HashMap where keys are the set elements. The converter extracts .values() and wraps them in a new TreeSet to restore proper set semantics.
PersistentSet workaround: Same problem — stored as HashMap internally. Extracts .values() and wraps in a new HashSet.
Converter dispatch: Tests the final collection class against the cached converters in order: listSetConverter (for ArrayList/HashSet/TreeSet), mapConverter, treeMapConverter, treeSetConverter. Falls back to defaultConverter.

unmarshal() — Not Implemented

unmarshal() returns null. This converter is unidirectional — it only handles serialization (Java→XML). Deserialization (XML→Java) produces standard JDK collections, which are then assigned to entity fields. Hibernate replaces them with persistent wrappers when the entity is later attached to a session.

Integration Points

Registered with XStream instances via HibernateMapper or direct xstream.registerConverter() calls.
Works in tandem with HibernateCollectionsMapper: the mapper translates collection type names in the XML, while this converter translates the collection contents at marshal time.
Used by the XML export subsystem (XStreamMarshallingStrategy) that serializes entity graphs for backup/configuration XML files.

Design Decisions & Gotchas

forceInitialization(): This triggers a database query if the collection was lazy-loaded but not yet accessed. For XML export of large entity graphs, this can cause a cascade of queries. The caller (typically a service layer export method) must ensure the Hibernate session remains open and ideally pre-fetch associations with JOIN FETCH queries.
Hibernate Set-as-Map quirk: Hibernate 3.x/4.x internally represents both PersistentSet and PersistentSortedSet using HashMap structures. The converter must explicitly unwrap these. If this logic were removed, XStream would serialize sets as XML maps (with key elements), producing unparseable output.
Snapshot vs. Collection: The TODO comment at line ~66 suggests using getCollectionSnapshot().getSnapshot() instead of getStoredSnapshot(). The current approach works because forceInitialization() guarantees the stored snapshot exists, but this is fragile across Hibernate versions.
Thread safety: The cached converter references are immutable after construction. The instance is effectively thread-safe for read-only converter operations.
Attribution: Originally authored by Costin Leau, a known contributor to the Spring/Hibernate integration ecosystem.

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

#704: HibernateCollectionConverter.java