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.

java.lang (and core special types)

Converter Supported types Example Notes
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.
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-dimiensional arrays, even if they are non-rectangular.
BooleanConverter boolean
java.lang.Boolean
<boolean>true</boolean>  
ByteConverter byte
java.lang.Byte
<byte>22</byte> The byte is represented as an integer.
EncodedByteArrayConverter byte[] <byte-array>AHiEFiEABQ==</byte-array> Uses Base64 encoding to store binary data in XML.
CharConverter char
java.lang.Character
<char>X</char>  
CharArrayConverter char[] <char-array>hello<char-array> Joins all characters into a single String.
DoubleConverter double
java.lang.Double
<double>456774543443.4553435</double>  
FloatConverter float
java.lang.Float
<float>4563443.435</float>  
IntConverter int
java.lang.Integer
<int>12345678</int>  
LongConverter long
java.lang.Long
<long>2344556678888786</long>  
ShortConverter short
java.lang.Short
<short>1445</short>  
StringConverter java.lang.String <string>hello world</string>  
StringBufferConverter java.lang.StringBuffer <string-buffer>hello world</string-buffer>  
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 under Java 1.4 or greater. It retains the full stack trace, including that of any nested exceptions. The stack trace elements are handled by the StackTraceElementConverter.

java.util

Converter Supported types Example Notes
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.
MapConverter java.util.HashMap
java.util.Hashtable
java.util.LinkedHashMap
<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.
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.
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.
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.
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.
DateConverter java.util.Date <date>2004-02-22 15:16:04.034 PM</date>  
GregorianCalendarConverter java.util.Calendar
java.util.GregorianCalendar
<gregorian-calendar>
  <time>555454646</time>
</gregorian-calendar>
 
LocaleConverter java.util.Locale <locale>en_GB</locale>  
CurrencyConverter java.util.Currency <currency>USD</currency> This is only available under Java 1.4 or greater.

java.sql

Converter Supported types Example Notes
SqlDateConverter java.sql.Date <sql-date>1978-08-25</sql-date>  
SqlTimeConverter java.sql.Time <sql-time>14:07:33</sql-time>  
SqlTimestampConverter java.sql.Timestamp <sql-timestamp>1970-01-01 00:00:01.234</sql-timestamp>  

java.math

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

java.net

Converter Supported types Example Notes
UrlConverter java.net.Url <url>http://codehaus.org/blah</url>  

java.io

Converter Supported types Example Notes
FileConverter java.io.File <file>/stuff/hello.txt</file>  

java.lang.reflect

Converter Supported types Example Notes
JavaClassConverter java.lang.Class <class>com.foo.MyThing</class> This converter will look for the class in the context ClassLoader for the current thread. It is possible to use another ClassLoader by re-registering a new instance of this converter that is wrapped around another ClassLoader.
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>.As with the JavaClassConverter, the converter will use the current thread's context ClassLoader to resolve classes by default. This can be changed by specifying another ClassLoader when constructing this Converter.
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.

java.awt

Converter Supported types Example Notes
ColorConverter java.awt.Color <color>
  <red>255</red>
  <green>255</green>
  <blue>255</blue>
  <alpha>255</alpha>
</color>
Warning: The AWT toolkit is initiailized when a Color is deserialized due to the internals of the Color class. This should only be an issue if deserializing a Color on a headless server process.
FontConverter java.awt.Font   Warning: The AWT toolkit is initiailized when a Font is deserialized due to the internals of the Font class. This should only be an issue if deserializing a Font on a headless server process.

Document History