#712: XStreamMarshallingStrategy.java

Architecture

Class Hierarchy

MarshallingStrategy (interface)
  └── AbstractTreeMarshallingStrategy
       ├── ReferenceByXPathMarshallingStrategy  (XPath-based circular reference handling)
       │    └── XStreamMarshallingStrategy       (this class — swaps in HibernateProxyXPathMarshaller)
       └── ReferenceByIdMarshallingStrategy      (ID/IDREF-based circular reference handling)
            └── ProxyIdRefMarshallingStrategy     (#709 — swaps in ProxyIdRefMarshaller)

Constructor

public XStreamMarshallingStrategy(int mode) {
    super(mode);
}

Accepts an XPath reference mode constant (RELATIVE, ABSOLUTE, SINGLE_NODE, etc.) and passes it to the superclass. The mode controls how XPath expressions are generated for back-references in circular entity graphs.

createMarshallingContext() — The Factory Method

@Override
protected TreeMarshaller createMarshallingContext(
    HierarchicalStreamWriter writer,
    ConverterLookup converterLookup,
    Mapper mapper)
{
    return new HibernateProxyXPathMarshaller(writer, converterLookup, mapper, RELATIVE);
}

This is the single overridden method — a textbook Template Method pattern. The superclass ReferenceByXPathMarshallingStrategy calls createMarshallingContext() whenever it needs a TreeMarshaller to serialize an object graph. Instead of returning the default ReferenceByXPathMarshaller, this override returns a HibernateProxyXPathMarshaller instance.

Integration Points

• XStream configuration: Set on an XStream instance via xstream.setMarshallingStrategy(new XStreamMarshallingStrategy(ReferenceByXPathMarshallingStrategy.RELATIVE)). This is typically done once during application startup when configuring the XStream instance for XML export.
• Creates: HibernateProxyXPathMarshaller as the marshaller for all serialization operations.
• Sibling strategy: ProxyIdRefMarshallingStrategy — provides the same proxy-aware marshalling but using ID/IDREF attributes instead of XPath references. Both strategies serve the same purpose but use different XML reference mechanisms. The application can choose between them based on XML format preferences.
• References JIRA XSTR-226: The source comment links to the Codehaus JIRA issue that documented the original XStream/Hibernate proxy incompatibility.

Strategy Comparison: XPath vs. ID/IDREF

How the Entire Bridge Layer Fits Together

When XStream serializes a JPA entity graph in ProjectForge, the following pipeline executes:

1. XStreamMarshallingStrategy (this class) is invoked to create a marshalling context.
2. It instantiates HibernateProxyXPathMarshaller as the tree marshaller.
3. As the marshaller traverses the object graph, it calls convertAnother(), which unwraps HibernateProxy instances before delegating to XStream's reference tracking.
4. When XStream needs to convert a specific class, HibernateMapper resolves the class name (substituting proxy names with real entity names, and Hibernate collection names with JDK collection names).
5. When XStream encounters a PersistentCollection, HibernateCollectionConverter forces initialization and delegates to the appropriate JDK collection converter.
6. When XStream encounters a HibernateProxy, HibernateProxyConverter unwraps it to the real entity before serialization.

Design Decisions & Gotchas

• Template Method pattern: The strategy uses the Template Method pattern — the superclass defines the algorithm (how to marshal an object graph), and this subclass provides the specific TreeMarshaller implementation. This is the canonical XStream extension point for custom marshalling behavior.
• RELATIVE mode hardcode: The hardcoded RELATIVE in createMarshallingContext() means the constructor's mode parameter is vestigial. This is likely an oversight or a deliberate decision to ensure proxy-aware marshalling always uses relative XPaths regardless of what callers pass. In practice, RELATIVE is the most robust mode for entity graphs because entity hierarchies can shift during refactoring.
• Minimal implementation: This class is only ~20 lines — the real work is delegated to HibernateProxyXPathMarshaller. This is a good example of the Single Responsibility Principle: the strategy's job is to wire components together, not to implement marshalling logic.
• No converters or mappers registered here: This strategy only deals with the marshaller. Converters (HibernateCollectionConverter, HibernateProxyConverter) and mappers (HibernateCollectionsMapper, HibernateMapper) are registered separately on the XStream instance. The strategy does not know about them — they operate independently at their respective layers.

Git History

868d6abb7 2025 -> 2026
63081666f Source file headers: 2024-> 2025.
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.
dd5ca38ac CopyRight of all java file-header updated or created.
9ebb88522 Initial commit