Converters

The core of XStream consists of a registry of Converters. The responsibility of a Converter is to provide a strategy for converting particular types of objects found in the object graph, to and from XML.

XStream is provided with Converters for common types such as primitives, String, File, Collections, arrays, and Dates. The following table lists any converter delivered with XStream and documents, if they are registered by default with which priority.

java.lang (and core special types)
Converter Supported types Example Notes Prio
NullConverter null values <null/> Usually, null fields are left out of the XML, however when used in arrays or the root object they have to be explicitly marked. very high
ArrayConverter any kind of array <string-array>
  <string>apple</string>
  <string>banana</string>
  <string>cabbage</string>
<string-array> 		This supports arrays of primitives as well as objects. It also supports multi-dimensional arrays, even if they are non-rectangular. normal
BooleanConverter boolean
java.lang.Boolean		 <boolean>true</boolean> Can also be registered locally using different values. normal
ByteConverter byte
java.lang.Byte		 <byte>22</byte> The byte is represented as an integer. normal
EncodedByteArrayConverter byte[] <byte-array>AHiEFiEABQ==</byte-array> Uses Base64 encoding to store binary data in XML. Converter can be registered globally or locally. normal
CharConverter char
java.lang.Character		 <char>X</char>
<char null="true"/>		 The '\0' character is invalid in XML. normal
CharArrayConverter char[] <char-array>hello<char-array> Joins all characters into a single String. normal
DoubleConverter double
java.lang.Double		 <double>456774543443.4553435</double>   normal
FloatConverter float
java.lang.Float		 <float>4563443.435</float>   normal
IntConverter int
java.lang.Integer		 <int>12345678</int>   normal
LongConverter long
java.lang.Long		 <long>2344556678888786</long>   normal
NamedArrayConverter any kind of array <string-array>
  <product>apple</product>
  <product>banana</product>
  <product>cabbage</product>
<string-array> 		This supports arrays of primitives as well as objects. It also supports multi-dimensional arrays, even if they are non-rectangular. Should be registered locally or for an individual array type.  
ShortConverter short
java.lang.Short		 <short>1445</short>   normal
StringConverter java.lang.String <string>hello world</string> This converter can be registered with different caching strategies. normal
StringBufferConverter java.lang.StringBuffer <string-buffer>hello world</string-buffer>   normal
StringBuilderConverter java.lang.StringBuilder <string-builder>hello world</string-builder> Available with Java 1.5 or higher. normal
ThrowableConverter java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
java.lang.Error
...and all subclasses of these.		 <java.io.IOException>
  <detailMessage>No file</detailMessage>
  <stack-trace>
    <trace>com.x.Foo.stuff(Foo.java:22)</trace>
    <trace>com.x.Foo.blah(Foo.java:31)</trace>
    <trace>com.x.Foo.main(Foo.java:43)</trace>
  </stack-trace>
</java.io.IOException> 		This is only available with Java 1.4 or higher. It retains the full stack trace, including that of any nested exceptions. The stack trace elements are handled by the StackTraceElementConverter. normal
EnumConverter java.lang.Enum <java.lang.annotation.RetentionPolicy>
CLASS
</java.lang.annotation.RetentionPolicy>		 Available with Java 1.5 or higher. normal
EnumToStringConverter java.lang.Enum The Converter must be initialized with an Enum type and an optional mapping between strings and enum values. By default it will use the Enum's string representation as value. Available with Java 1.5 or higher. Must be registered explicitly for the Enum type or locally.  

java.util
Converter Supported types Example Notes Prio
CollectionConverter java.util.ArrayList
java.util.LinkedList
java.util.HashSet
java.util.Vector
java.util.LinkedHashSet		 <linked-list>
  <string>apple</string>
  <string>banana</string>
  <big-decimal>12345.4555</big-decimal>
</linked-list> 		The objects inside the collection can be any type of objects, including nested collections. Can be registered for an individual Collection type or locally, suppression of implicit type might be necessary. normal
MapConverter java.util.HashMap
java.util.Hashtable
java.util.LinkedHashMap
java.util.concurrent.ConcurrentHashMap		 <map>
  <entry>
    <string>apple</string>
    <float>123.553</float>
  </entry>
  <entry>
    <string>orange</string>
    <float>55.4</float>
  </entry>
</map> 		Both key and values can be any type of objects. Can be registered for an individual Map type or locally, suppression of implicit type might be necessary. normal
NamedCollectionConverter java.util.ArrayList
java.util.LinkedList
java.util.HashSet
java.util.Vector
java.util.LinkedHashSet		 <fruits>
  <fruit>apple</fruit>
  <fruit>banana</fruit>
  <fruit>orange</fruit>
</fruits> 		The objects inside the collection can be of any type shared between the objects. Should be registered locally or for an individual Collection type.  
NamedMapConverter java.util.HashMap
java.util.Hashtable
java.util.LinkedHashMap
java.util.concurrent.ConcurrentHashMap		 <map>
  <fruit>
    <name>apple</name>
    <price>123.553</price>
  </fruit>
  <fruit>
    <name>orange</name>
    <price>55.4</price>
  </fruit>
</map> 		Both key and values can be any type of objects. If key or value are written as attributes or if the value is written as text of the entry element, those types must be handled by a SingleValueConverter. Should be registered locally or for an individual Map type.  
PropertiesConverter java.util.Properties <properties>
  <property name="host" value="localhost"/>
  <property name="port" value="888"/>
</properties> 		Because the Properties class only accepts Strings for keys and values, the XML can be more concise. If the Properties instance includes a set of default Properties, these are serialized in a nested <defaults> element. normal
WeakHashMapConverter java.util.WeakHashMap <weak-hash-map/> A WeakHashMap is supposed to release its elements when they are no longer referenced. Therefore is at unmarshalling time no guarantee that an entry is still available when it is referenced later in the stream. As consequence the converter will marshal no elements at all, it will create an empty WeakHashMap at unmarshalling time. normal
SingletonCollectionConverter java.util.Collections.singletonList().getClass()
java.util.Collections.singleton().getClass()		 <singleton-set>
  <string>apple</string>
</singleton-set> 		The objects inside the singleton collection can be any type of objects, including nested collections. normal
SingletonMapConverter java.util.Collections.singletonMap().getClass() <singleton-map>
  <entry>
    <string>apple</string>
    <float>123.553</float>
  </entry>
</singleton-map> 		The objects inside the singleton collection can be any type of objects, including nested collections. normal
TreeMapConverter java.util.TreeMap <tree-map>
  <comparator class="com.blah.MyComparator"/>
  <entry>
    <string>apple</string>
    <float>123.553</float>
  </entry>
  <entry>
    <string>orange</string>
    <float>55.4</float>
  </entry>
</tree-map> 		This is similar to MapConverter with an additional field for storing the java.util.Comparator associated with the TreeMap. normal
TreeSetConverter java.util.TreeSet <tree-set>
  <comparator class="com.blah.MyComparator"/>
  <string>apple</string>
  <string>banana</string>
  <string>cabbage</string>
</tree-set> 		This is similar to CollectionConverter with an additional field for storing the java.util.Comparator associated with the TreeSet. normal
BitSetConverter java.util.BitSet <bit-set>0,1,3,5,6,8,10</bit-set> Stores a comma separated list of which bits are set. Designed to be readable without taking up too much space. normal
DateConverter java.util.Date <date>2004-02-22 15:16:04.0 UTC</date> Can be registered with different formats, locales or time zone globally or locally. normal
GregorianCalendarConverter java.util.Calendar
java.util.GregorianCalendar		 <gregorian-calendar>
  <time>555454646</time>
</gregorian-calendar> 		  normal
ISO8601DateConverter java.util.Date <date>2006-07-28T12:06:17.654-03:00</date> Not automatically registered, can be used globally or locally. Implementation needs joda-time for JDK 1.7 or below.  
ISO8601GregorianCalendarConverter java.util.GregorianCalendar <gregorian-calendar>
2006-07-28T12:07:02.788-03:00
</gregorian-calendar> 		Not automatically registered, can be used globally or locally. Implementation needs joda-time for JDK 1.7 or below.  
LocaleConverter java.util.Locale <locale>en_GB</locale>   normal
CurrencyConverter java.util.Currency <currency>USD</currency> Available with Java 1.4 or higher. normal
UUIDConverter java.util.UUID <uuid>ca05f023-e07f-4956-a6ef-14ddd23df47b</uuid> Available with Java 1.5 or higher. normal
OptionalConverter java.util.Optional <optional>
  <value  class="string">test</value>
</optional> 		Available with Java 1.8 or higher. normal
OptionalDoubleConverter java.util.OptionalDouble <optional-double>1.8</optional-double> Available with Java 1.8 or higher. normal
OptionalIntConverter java.util.OptionalInt <optional-int>42</optional-int> Available with Java 1.8 or higher. normal
OptionalLongConverter java.util.OptionalLong <optional-long>2344556678888786</optional-long> Available with Java 1.8 or higher. normal
EnumMapConverter java.util.EnumMap <enum-map enum-type="simple">
  <entry>
    <simple>GREEN</simple>
    <string>grass</string>
  </entry>
  <entry>
    <simple>BLUE</simple>
    <string>sky</string>
  </entry>
</enum-map>		 Available with Java 1.5 or higher. normal
EnumSetConverter java.util.EnumSet <enum-set enum-type="simple">
  GREEN,BLUE
</enum-set>		 Available with Java 1.5 or higher. normal
RegexPatternConverter java.util.regex.Pattern <java.util.regex.Pattern>
  <pattern>.*</pattern>
  <flags>0</flags>
</java.util.regex.Pattern> 		Available with Java 1.4 or higher. normal

java.util.concurrent.atomic
Converter Supported types Example Notes Prio
AtomicBooleanConverter java.util.concurrent.atomic.AtomicBoolean <atomic-boolean>true</atomic-boolean> Available with Java 1.5 or higher. normal
AtomicIntegerConverter java.util.concurrent.atomic.AtomicInteger <atomic-integer>12345678</atomic-integer> Available with Java 1.5 or higher. normal
AtomicLongConverter java.util.concurrent.atomic.AtomicLong <atomic-long>2344556678888786</atomic-long> Available with Java 1.5 or higher. normal
AtomicReferenceConverter java.util.concurrent.atomic.AtomicReference <atomic-reference>
  <value class="string">test</value>
</atomic-reference> 		Available with Java 1.5 or higher. normal

java.time
Converter Supported types Example Notes Prio
DurationConverter java.time.Duration <duration>PT24000H</duration> Available with Java 8 or higher. normal
InstantConverter java.time.Instant <instant>2017-07-30T20:40:00Z</instant> Available with Java 8 or higher. normal
LocalDateConverter java.time.LocalDate <local-date>2017-10-30</local-date> Available with Java 8 or higher. normal
LocalDateTimeConverter java.time.LocalDateTime <local-date-time>2017-10-30T20:40:15</local-date-time> Available with Java 8 or higher. normal
LocalTimeConverter java.time.LocalTime <local-time>20:40:15</local-time> Available with Java 8 or higher. normal
MonthDayConverter java.time.MonthDay <month-day>--01-13</month-day> Available with Java 8 or higher. normal
OffsetDateTimeConverter java.time.OffsetDateTime <offset-date-time>2017-07-30T20:40:00Z</offset-date-time> Available with Java 8 or higher. normal
OffsetTimeConverter java.time.OffsetTime <offset-time>20:40:15+01:00</offset-time> Available with Java 8 or higher. normal
PeriodConverter java.time.Period <period>P1000D</period> Available with Java 8 or higher. normal
SystemClockConverter java.time.Clock$SystemClock <system-clock>   <zone>Europe/Berlin</zone> </system-clock> Available with Java 8 or higher. normal
YearConverter java.time.Year <year>2017</year> Available with Java 8 or higher. normal
YearMonthConverter java.time.YearMonth <year-month>2017-02</year-month> Available with Java 8 or higher. normal
ZonedDateTimeConverter java.time.ZonedDateTime <zoned-date-time>2017-10-30T20:40:00Z[Europe/London]</zoned-date-time> Available with Java 8 or higher. normal
ZoneIdConverter java.time.ZoneId
java.time.ZoneOffset
java.time.ZoneRegion		 <zone-id>Z</zone-id> Available with Java 8 or higher. normal

java.time.chrono
Converter Supported types Example Notes Prio
ChronologyConverter java.time.chrono.Chronology implementations <chronology>ISO</chronology> Available with Java 8 or higher. normal
HijrahDateConverter java.time.chrono.HijrahDate <hijrah-date>Hijrah-umalqura AH 1438-11-07</hijrah-date> Available with Java 8 or higher. normal
JapaneseDateConverter java.time.chrono.JapaneseDate <japanese-date>Japanese Heisei 29-07-30</japanese-date> Available with Java 8 or higher. normal
JapaneseEraConverter java.time.chrono.JapaneseEra <japanese-era>Taisho</japanese-era> Available with Java 8 or higher. normal
MinguoDateConverter java.time.chrono.MinguoDate <minguo-date>Minguo ROC 106-07-30</minguo-date> Available with Java 8 or higher. normal
ThaiBuddhistDateConverter java.time.chrono.ThaiBuddhistDate <thai-buddhist-date>haiBuddhist BE 2560-07-30</thai-buddhist-date> Available with Java 8 or higher. normal

java.time.temporal
Converter Supported types Example Notes Prio
ValueRangeConverter java.time.temporal.ValueRange <temporal-value-range>
  <maxLargest>45</maxLargest>
  <maxSmallest>30</maxSmallest>
  <minLargest>1</minLargest>
  <minSmallest>0</minSmallest>
</temporal-value-range> 		Available with Java 8 or higher. normal
WeekFieldsConverter java.time.temporal.WeekFields <week-fields>
  <minimalDays>2</minimalDays>
  <firstDayOfWeek>MONDAY</firstDayOfWeek>
</week-fields> 		Available with Java 8 or higher. normal

java.sql
Converter Supported types Example Notes Prio
SqlDateConverter java.sql.Date <sql-date>1978-08-25</sql-date> Only automatically registered if runtime has JDBC support. normal
SqlTimeConverter java.sql.Time <sql-time>14:07:33</sql-time> Only automatically registered if runtime has JDBC support. normal
SqlTimestampConverter java.sql.Timestamp <sql-timestamp>1970-01-01 00:00:01.234</sql-timestamp> Only automatically registered if runtime has JDBC support. normal
ISO8601SqlTimestampConverter java.sql.Timestamp <sql-timestamp>2006-07-28T12:06:17.654000000-03:00</sql-timestamp> Not automatically registered, can be used globally or locally. Implementation needs joda-time for JDK 1.7 or below.  

java.math
Converter Supported types Example Notes Prio
BigDecimalConverter java.math.BigDecimal <big-decimal>342346.445332</big-decimal>   normal
BigIntegerConverter java.math.BigInteger <big-int>23434224556</big-int>   normal

java.net
Converter Supported types Example Notes Prio
URIConverter java.net.URI <uri>mailto:xstream-user.codehaus.org</uri>   normal
URLConverter java.net.URL <url>http://codehaus.org/blah</url>   normal

java.io
Converter Supported types Example Notes Prio
FileConverter java.io.File <file>/stuff/hello.txt</file>   normal
SerializableConverter java.io.Serializable   See description at Generalized Converters. low
ExternalizableConverter java.io.Externalizable <externalizable-type>
  <string>apple</string>
  <int>42</int>
  <big-decimal>12345.4555</big-decimal>
</externalizable-type> 		See description at Generalized Converters. low

java.nio
Converter Supported types Example Notes Prio
CharsetConverter java.nio.charset.Charset <charset>US-ASCII</charset> Available with Java 1.4 or higher. normal
PathConverter java.nio.file.Path <path>../dir/file.txt</path> Available with Java 7 or higher. normal

java.lang.reflect
Converter Supported types Example Notes Prio
JavaClassConverter java.lang.Class <class>com.foo.MyThing</class> This converter uses the ClassLoaderReference of the XStream instance. Can be registered with Mapper globally or locally to respect type aliases. normal
JavaFieldConverter java.lang.reflect.Field <field>
  <name>myField</name>
  <class>com.foo.MyThing</class>
</field> 		This converter uses the ClassLoaderReference of the XStream instance. Can be registered with Mapper globally or locally to respect type aliases. normal
JavaMethodConverter java.lang.reflect.Method
java.lang.reflect.Constructor		 <method>
  <class>com.foo.MyThing</class>
  <name>doStuff</name>
  <parameter-types>
    <class>java.lang.String</class>
    <class>java.util.Iterator</class>
  </parameter-types>
</method> 		The enclosing element for this tag will either by <method> or <constructor>. This converter uses the ClassLoaderReference of the XStream insatance. Can be regisreted with Mapper globally or locally to respect type aliases. normal
DynamicProxyConverter Any dynamic proxy generated by java.lang.reflect.Proxy <dynamic-proxy>
  <interface>com.foo.Blah</interface>
  <interface>com.foo.Woo</interface>
  <handler class="com.foo.MyHandler">
    <something>blah</something>
  </handler>
</dynamic-proxy> 		The dynamic proxy itself is not serialized, however the interfaces it implements and the actual InvocationHandler instance are serialized. This allows the proxy to be reconstructed after deserialization. normal

java.awt
Converter Supported types Example Notes Prio
ColorConverter java.awt.Color <awt-color>
  <red>255</red>
  <green>255</green>
  <blue>255</blue>
  <alpha>255</alpha>
</awt-color> 		Only automatically registered if runtime has AWT support.
Warning: The AWT toolkit is definitely initialized when a Color is deserialized.		 normal
FontConverter java.awt.Font
javax.swing.plaf.FontUIResource		 <awt-font>
  <family class="string">Arial</family>
  <size class="float">20.0</size>
  <width class="null"/>
  <posture class="null"/>
  <weight class="float">2.0</weight>
  <superscript class="null"/>
</awt-font> 		Only automatically registered if runtime has AWT support.
Warning: The AWT toolkit is definitely initialized when a Font is deserialized.		 normal

java.awt.font
Converter Supported types Example Notes Prio
TextAttributeConverter java.awt.font.TextAttribute <awt-text-attribute>family</awt-text-attribute> Only automatically registered if runtime has AWT support.
Warning: The AWT toolkit is definitely initialized when a TextAttribute is deserialized.		 normal

javax.activation
Converter Supported types Example Notes Prio
ActivationDataFlavorConverter javax.activation.ActivationDataFlavor <activation-data-flavor>
  <mimeType>application/x-junit</mimeType>
  <humanRepresentableName>JUnit</humanRepresentableName>
  <representationClass>java.io.InputStream</representationClass>
</activation-data-flavor> 		Available with Java 6, 7 and 8. Requires module java.activation with Java 9 or higher.
normal

javax.swing
Converter Supported types Example Notes Prio
LookAndFeelConverter javax.swing.LookAndFeel implementations   Only automatically registered if runtime has Swing support. normal

javax.security.auth
Converter Supported types Example Notes Prio
SubjectConverter javax.security.auth.Subject <auth-subject>
  <principals>
    <com.thoughtworks.xstream.Admin/>
  </principals>
  <readOnly>false</readOnly>
</auth-subject>
 Available with Java 1.4 or higher. This converter does not serialize any credentials but only the principals. normal

javax.xml.datatype
Converter Supported types Example Notes Prio
DurationConverter javax.xml.datatype.Duration <duration>PT1H2M</duration> Available with Java 1.5 or higher. normal

Generalized Converters
Converter Supported types Explanation Notes Prio
ReflectionConverter Any type The Converter is used as fallback. It uses reflection to examine the class and will serialize its fields.   very low
AnnotationReflectionConverter Any type The Converter is used as fallback. It uses reflection to examine the class and will serialize its fields and supports annotations for local converters. Needs JDK 1.5, default for JDK 1.5. Deprecated since XStream 1.3 and must be registered now explicitly.  
SerializableConverter java.io.Serializable or types with one of the serializable methods readObject or writeObject The Converter is used for any JDK-serializable types, if not handled by a specialized Converter.   low
ExternalizableConverter java.io.Externalizable The Converter is used for any externalizable type, if not handled by a specialized Converter.   low
LambdaConverter For serializable lambda types. Non-serializable lambda instances will be mapped to null, since they contain no information for recreation. Serializable lambda types have such info, but it is specific to compiler vendor and occurrence in the code. Never assume that you can deserialize such an element when you use a different version of your code or a different compiler. Available with Java 8 or higher. normal
ToAttributedValueConverter Any type with all fields to be represented by a single string but one. The Converter is used to write all but one fields of the type as attributes. The left over field is then used as current value. Must be registered globally or locally for the appropriate type.  
ToStringConverter Any type with natural String representation The Converter must be initialized with a type, that provides a complete String representation with its toString() method and is able to be recreated by a constructor taking a single String argument. Must be registered globally or locally for the appropriate type.  
JavaBeanConverter Java beans The Converter handles any type as Java bean. It expects the type to convert to have a public default constructor and appropriate getter and setters. Must be registered globally or locally. Can be used as fallback with priority very low.  
PropertyEditorCapableConverter Any type with a PropertyEditor implementation The Converter can handles any type that provides a PropertyEditor implementation. The PropertyEditor's methods getAsText() and setAsText() are used to convert between object and string representation. Must be registered globally or locally for the appropriate type.  

Converters for 3rd party classes
Converter Supported types Explanation Notes Add-On
CGLIBEnhancedConverter Proxies generated by the CGLIB Enhancer The Converter handles proxies generated by the CGLIB Enhancer, if there were not multiple callbacks registered. A proxy with multiple callbacks can currently not be handled at all. Must be registered globally and in combination with the CGLIBMapper. See FAQ. xstream
HibernatePersistentCollectionConverter org.hibernate.collection.internal.PersistentBag
org.hibernate.collection.internal.PersistentList
org.hibernate.collection.internal.PersistentSet
org.hibernate.envers.entities.mapper.relation.lazy.proxy.ListProxy
org.hibernate.envers.entities.mapper.relation.lazy.proxy.SetProxy		 The Converter handles Hibernate 4 (or 3) standard collections and Envers proxies. It will handle any element of the collection. Must be registered explicitly in combination with the HibernateMapper and all the other Hibernate converters. See package description. xstream-hibernate
HibernatePersistentMapConverter org.hibernate.collection.internal.PersistentMap
org.hibernate.envers.entities.mapper.relation.lazy.proxy.MapProxy		 The Converter handles unsorted Hibernate 4 (or 3) maps or Envers proxy. It will handle any key and value of the map. Must be registered explicitly in combination with the HibernateMapper and all the other Hibernate converters. See package description. xstream-hibernate
HibernatePersistentSortedMapConverter org.hibernate.collection.internal.PersistentSortedMap
org.hibernate.envers.entities.mapper.relation.lazy.proxy.SortedMapProxy		 The Converter handles sorted Hibernate 4 (or 3) maps or Envers proxy. It will handle any key and value of the map. Must be registered explicitly in combination with the HibernateMapper and all the other Hibernate converters. See package description. xstream-hibernate
HibernatePersistentSortedSetConverter org.hibernate.collection.intrernal.PersistentSortedSet
org.hibernate.envers.entities.mapper.relation.lazy.proxy.SortedSetProxy		 The Converter handles sorted Hibernate 4 (or 3) sets or Envers proxy. It will handle any element of the set. Must be registered explicitly in combination with the HibernateMapper and all the other Hibernate converters. See package description. xstream-hibernate
HibernateProxyConverter org.hibernate.proxy.HibernateProxy The Converter handle any element that is wrapped by a Hibernate proxy. Must be registered explicitly in combination with the HibernateMapper and all the other Hibernate converters. See package description. xstream-hibernate

Software

Evaluating XStream

Using XStream

Javadoc

Tutorials

Developing XStream