About XStream
XStream is a simple library to serialize objects to XML and back again.
Features
- Ease of use. A high level facade is supplied that simplifies common use cases.
- No mappings required. Most objects can be serialized without need for specifying mappings.
- Performance. Speed and low memory footprint are a crucial part of the design, making it suitable for large object graphs or systems with high message throughput.
- Clean XML. No information is duplicated that can be obtained via reflection. This results in XML that is easier to read for humans and more compact than native Java serialization.
- Requires no modifications to objects. Serializes internal fields, including private and final. Supports non-public and inner classes. Classes are not required to have default constructor.
- Full object graph support. Duplicate references encountered in the object-model will be maintained. Supports circular references.
- Integrates with other XML APIs. By implementing an interface, XStream can serialize directly to/from any tree structure (not just XML).
- Customizable conversion strategies. Strategies can be registered allowing customization of how particular types are represented as XML.
- Error messages. When an exception occurs due to malformed XML, detailed diagnostics are provided to help isolate and fix the problem.
- Alternative output format. The modular design allows other output formats. XStream ships currently with JSON support and morphing.
Typical Uses
- Transport
- Persistence
- Configuration
- Unit Tests
Known Limitations
If using the enhanced mode, XStream can re-instantiate classes that do not have a default constructor. However, if using a different JVM like an old JRockit version, a JDK 1.3 or you have restrictions because of a SecurityManager, a default constructor is required.
The enhanced mode is also necessary to restore final fields for any JDK < 1.5. This implies deserialization of instances of an inner class.
Auto-detection of annotations may cause race conditions. Preprocessing annotations is safe though.
Getting Started
Latest News
February 27, 2008 XStream 1.3 released
The XStream committers proudly present XStream 1.3. This release contains some major refactorings concerning Java annotations, improved XML support regarding encoding and character sets, some minor new features, deprecations and a lot of bug fixes:
- Annotation support is now implemented as Mapper and Annotations can either be processed in advance or on-the-fly (see Annotations tutorial for limitations).
- Improved encoding support for JSON and XML (including automated support for XML headers). Enforceable check for valid XML characters in the written stream.
- Dedicated converters can now be configured for individual fields also using the XStream facade.
- New converters for java.lang.StringBuilder, java.util.UUID, javax.xml.datatype.Duration, and javax.swing.LookAndFeel. New generic converter for types using a java.beans.PropertyEditor. Auto-instantiated SingleValueConverter for Java enums to support enum values as attributes.
- XML elements are now sorted by default according their declaration with the fields defined in parent classes first to improve support for type hierarchies in XML schemata.
- A lot of bug fixes to improve JSON support for arbitrary types. Added section in FAQ for limitations and operation modes.
- Native support for SAP VM.
- All text-based files are now shipped with an appropriate license header to clean-up legal issues.
View the complete change log and download.
Note, to support a representation of null values in some way, it is absolutely necessary that each converter can handle a null value in its marshalling methods. If you have implemented your own custom converters, try to handle such a case also to prevent incompatibilities in case XStream will provide such values with its next major version.