XStream: Java objects to XML and back, with a module layout that tells the story

A serializer whose job is one direction and the reverse

XStream does one thing, described in the README tagline as Java to XML Serialization, and back again. Objects in, XML out, and the same objects reconstructed from that XML.

That framing sounds trivial, and it is the reason the library has stayed in the Java ecosystem for two decades without changing shape. The value is in the object graph, not the format. A configuration object with nested lists, maps and references can be written out and read back without you writing a serialiser, a parser or a schema.

The project metadata lists Java, xml and xstream as its topics, and the homepage sits at x-stream.github.io. The default branch is master, and the source lives under a module called xstream in the root of the repository.

The audience is Java developers with an existing dependency on it. XStream is not a general purpose document format for systems that need to agree on a schema with another organisation. It is a library with a long history, and the interesting questions for a new adopter are about packaging, licensing and how the project is organised rather than about the core idea.

Six modules tell you what the project covers

The repository root is more informative than the README, because the module names describe the scope.

The main API sits in xstream, with unit tests in xstream/src/test. Next to it, xstream-hibernate is a dedicated Hibernate module, so integration with Hibernate is a maintained concern of the project rather than something bolted on. xstream-its holds the integration tests, which is where the library is exercised against the outside world rather than against itself.

Two build-time modules round it out. xstream-jmh is the benchmark module, which tells you the project measures performance rather than assuming it, and xstream-builder is the module that assembles a distribution. xstream-distribution is the website, and pom.xml at the root is the Maven build file for the whole reactor.

The v-1.4.x branch and master also appear side by side in the CI badges at the top of the README, which indicates that the older line is still built while master moves on.

Two archives: the -bin with jars, the -src with the build

Distribution is by archive rather than by a single published jar, and the README is explicit about what each one holds.

All binary artifacts are bundled in the -bin archive, and it includes the XStream jars plus any other library used at build time, or optional runtime extras. The complete source is bundled in the -src archive, which includes the main API, the unit tests, the Maven build files, the Hibernate module and the website:

* Main API [xstream/src/java]
* Unit Tests [xstream/src/test]
* Maven Build Files [pom.xml]
* Hibernate Module [xstream-hibernate]
* Website [xstream-distribution]

That distinction has a practical consequence. If you consume the -bin archive, the runtime extras arrive with it, so a parser dependency is present rather than something you have to know about. If you are maintaining a fork, the -src archive is the unit of work, and it includes the website and the integration tests, so a change to a converter can be validated against the wider suite.

The README does not document a repository-based Maven coordinate for consuming the library, and it does not describe the settings-template.xml file that sits in the repository root. If you need either, the answer is in the source archive or the documentation site rather than in this page.

MXParser is the parser the project points you at

One performance instruction appears in the README and it is specific: MXParser is recommended for use, because it will greatly improve the performance of XStream.

The choice of parser is not cosmetic for a library like this, since parsing is where the cost of an XML round trip concentrates. Recommending a specific parser rather than leaving it to the JVM default tells you the project has a view on this, and that view is worth following if you are moving a large volume of XML through the library.

The README does not quantify the difference, and it does not say what the fallback behaviour looks like when MXParser is absent from the classpath, so an adopter who swaps in a different parser should expect to measure rather than assume.

The other end of the pipeline is the benchmark module, xstream-jmh, which exists to measure the code rather than guess at it. For anyone planning to change serialisation settings, that module is where the comparison belongs.

The licence is the first thing to read

The licence field for this repository is not a standard SPDX identifier. GitHub reports it as a custom licence it cannot classify, and points to the LICENSE file, and the root of the repository contains LICENSE.txt.

That is unusual and it is the single most important fact for a company considering adoption. A permissive licence such as Apache-2.0 or MIT can be checked at a glance, while a custom licence has to be read end to end, including any clauses about redistribution, attribution or use in commercial products. This review does not interpret that licence, and anyone deploying XStream in a shipped product should have their own counsel read LICENSE.txt rather than rely on a summary.

The repository also carries SECURITY.md at the root, and the documentation set listed in the README includes a Security page among the Introduction, Tutorials, JavaDoc, Change History and Frequently Asked Questions entries. For a library that turns bytes into objects, the security documentation is part of the product, not an appendix, and it should be read before any decision about accepting XML from outside your trust boundary.

Release history and where the project stands

The repository is not archived, and the last push was on 2026-07-01. The default branch is master, and the README carries a CI badge for a workflow named CI with Maven on that branch, plus a separate set of badges for the v-1.4.x branch using a different continuous integration service.

The release list is where the story gets uneven. The most recent tag shown is XSTREAM_1_4_8, dated 2016-01-06, while the default branch is named master rather than a version branch. The two CI badge sets therefore cover two different lines: master, which is where current work lands, and v-1.4.x, the older line that is still built.

No stated release cadence exists in the documentation, so the tag list alone cannot be read as a schedule, and the gap between the last push and the last listed tag is not explained by the README. What can be said is concrete: work is landing on master, the legacy line is still built, and the packaged artefacts are the archives rather than the tag names.

Reflective serialisation versus writing the mapping yourself

The real alternative to XStream is not a different library, it is writing the conversion by hand, or choosing a design where the XML shape is produced by explicit code rather than by reflection over your object graph.

The difference in approach is worth being precise about. A reflective serialiser walks your objects at runtime and derives the XML from the fields, so you write no mapping code and the XML follows your class structure, including changes to it. Hand written mapping produces the XML through code you can read, which means the output shape is reviewable, the file format is something you can version deliberately, and a field rename does not silently change the document.

The cost of the explicit route is the mapping code and the maintenance that comes with it. The cost of the reflective route is that the document format is a side effect of your class design, and the class design will change. That trade-off is acceptable when the XML is an internal detail, and painful when it is a contract with another system, a stored artifact you cannot rewrite, or a file a human is expected to edit.

XStream also comes with a Hibernate module, so if your XML sits next to an ORM, the comparison is between one library that already knows about your persistence layer and a hand written serialiser that does not.

Editorial conclusion

XStream fits a Java project that already round-trips objects through XML, particularly one with existing XStream based configuration or persisted payloads where swapping the serializer would mean migrating stored data. It does not fit a new design that wants an explicit, reviewable mapping between fields and XML elements, and it should not be exposed to untrusted XML without reading the security documentation first. Before you rely on it, read LICENSE.txt, since GitHub cannot classify the licence, and check the xstream-hibernate module and the -bin archive against the JDK version your build actually runs.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. x-stream/xstream on GitHub