XStream Core 1.4.20 · com.thoughtworks.xstream.XStream

Simple facade to XStream library, a Java-XML serialization tool.

Example

XStream xstream = new XStream();
String xml = xstream.toXML(myObject); // serialize to XML
Object myObject2 = xstream.fromXML(xml); // deserialize from XML

Aliasing classes

To create shorter XML, you can specify aliases for classes using the alias() method. For example, you can shorten all occurrences of element <com.blah.MyThing> to <my-thing> by registering an alias for the class.

xstream.alias("my-thing", MyThing.class);

Converters

XStream contains a map of com.thoughtworks.xstream.converters.Converter instances, each of which acts as a strategy for converting a particular type of class to XML and back again. Out of the box, XStream contains converters for most basic types (String, Date, int, boolean, etc) and collections (Map, List, Set, Properties, etc). For other objects reflection is used to serialize each field recursively.

Extra converters can be registered using the registerConverter() method. Some non-standard converters are supplied in the com.thoughtworks.xstream.converters.extended package and you can create your own by implementing the com.thoughtworks.xstream.converters.Converter interface.

Example

xstream.registerConverter(new SqlTimestampConverter());
xstream.registerConverter(new DynamicProxyConverter());

The converters can be registered with an explicit priority. By default they are registered with XStream.PRIORITY_NORMAL. Converters of same priority will be used in the reverse sequence they have been registered. The default converter, i.e. the converter which will be used if no other registered converter is suitable, can be registered with priority XStream.PRIORITY_VERY_LOW. XStream uses by default the com.thoughtworks.xstream.converters.reflection.ReflectionConverter as the fallback converter.

Example

xstream.registerConverter(new CustomDefaultConverter(), XStream.PRIORITY_VERY_LOW);

Object graphs

XStream has support for object graphs; a deserialized object graph will keep references intact, including circular references.

XStream can signify references in XML using either relative/absolute XPath or IDs. The mode can be changed using setMode():


`xstream.setMode(XStream.XPATH_RELATIVE_REFERENCES);`	(Default) Uses XPath relative references to signify duplicate references. This produces XML with the least clutter.
`xstream.setMode(XStream.XPATH_ABSOLUTE_REFERENCES);`	Uses XPath absolute references to signify duplicate references. This produces XML with the least clutter.
`xstream.setMode(XStream.SINGLE_NODE_XPATH_RELATIVE_REFERENCES);`	Uses XPath relative references to signify duplicate references. The XPath expression ensures that a single node only is selected always.
`xstream.setMode(XStream.SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES);`	Uses XPath absolute references to signify duplicate references. The XPath expression ensures that a single node only is selected always.
`xstream.setMode(XStream.ID_REFERENCES);`	Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written XML, this is easier to work with.
`xstream.setMode(XStream.NO_REFERENCES);`	This disables object graph support and treats the object structure like a tree. Duplicate references are treated as two separate objects and circular references cause an exception. This is slightly faster and uses less memory than the other two modes.

Thread safety

The XStream instance is thread-safe. That is, once the XStream instance has been created and configured, it may be shared across multiple threads allowing objects to be serialized/deserialized concurrently. Note, that this only applies if annotations are not auto-detected on-the-fly.

Implicit collections

To avoid the need for special tags for collections, you can define implicit collections using one of the addImplicitCollection methods.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	XStream.InitializationException Deprecated As of 1.3, use `com.thoughtworks.xstream.InitializationException` instead

Field Summary

Modifier and Type	Field and Description
private static final String	ANNOTATION_MAPPER_TYPE
private AnnotationConfiguration	annotationConfiguration Deprecated as a consequence of `AnnotationConfiguration` being deprecated.
private AttributeAliasingMapper	attributeAliasingMapper
private AttributeMapper	attributeMapper
private ClassAliasingMapper	classAliasingMapper
private ClassLoaderReference	classLoaderReference
public static final String	COLLECTION_UPDATE_LIMIT
public static final String	COLLECTION_UPDATE_SECONDS
private int	collectionUpdateLimit
private ConverterLookup	converterLookup
private ConverterRegistry	converterRegistry
private DefaultImplementationsMapper	defaultImplementationsMapper
private ElementIgnoringMapper	elementIgnoringMapper
private FieldAliasingMapper	fieldAliasingMapper
private HierarchicalStreamDriver	hierarchicalStreamDriver
public static final int	ID_REFERENCES
private static final Pattern	IGNORE_ALL
private ImmutableTypesMapper	immutableTypesMapper
private ImplicitCollectionMapper	implicitCollectionMapper
private LocalConversionMapper	localConversionMapper
private Mapper	mapper
private MarshallingStrategy	marshallingStrategy
public static final int	NO_REFERENCES
private PackageAliasingMapper	packageAliasingMapper
public static final int	PRIORITY_LOW
public static final int	PRIORITY_NORMAL
public static final int	PRIORITY_VERY_HIGH
public static final int	PRIORITY_VERY_LOW
private ReflectionProvider	reflectionProvider
private SecurityMapper	securityMapper
public static final int	SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES
public static final int	SINGLE_NODE_XPATH_RELATIVE_REFERENCES
private SystemAttributeAliasingMapper	systemAttributeAliasingMapper
public static final int	XPATH_ABSOLUTE_REFERENCES
public static final int	XPATH_RELATIVE_REFERENCES

Constructor Summary

Access	Constructor and Description
public	XStream() Constructs a default XStream.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching reflection provider reflectionProvider) Constructs an XStream with a special `ReflectionProvider`.
public	XStream(HierarchicalStreamDriver the driver instance hierarchicalStreamDriver) Constructs an XStream with a special `HierarchicalStreamDriver`.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance hierarchicalStreamDriver) Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider`.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, Mapper the instance with the `Mapper` chain or null for the default chain mapper, HierarchicalStreamDriver the driver instance driver) Deprecated As of 1.3, use `XStream(ReflectionProvider, HierarchicalStreamDriver, ClassLoader, Mapper)` instead Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider` and a prepared `Mapper` chain.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance driver, ClassLoaderReference the reference to the `ClassLoader` to use classLoaderReference) Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider` and a `ClassLoaderReference`.
public	XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader) Deprecated As of 1.4.5 use `XStream(ReflectionProvider, HierarchicalStreamDriver, ClassLoaderReference)` Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider` and the `ClassLoader` to use.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance driver, ClassLoader the `ClassLoader` to use classLoader, Mapper the instance with the `Mapper` chain or null for the default chain mapper) Deprecated As of 1.4.5 use `XStream(ReflectionProvider, HierarchicalStreamDriver, ClassLoaderReference, Mapper)` Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` chain and the `ClassLoader` to use.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance driver, ClassLoaderReference the reference to the `ClassLoader` to use classLoaderReference, Mapper the instance with the `Mapper` chain or null for the default chain mapper) Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` chain and the `ClassLoaderReference`.
private	XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoaderReference classLoader, Mapper mapper, final DefaultConverterLookup defaultConverterLookup)
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance driver, ClassLoader the `ClassLoader` to use classLoader, Mapper the instance with the `Mapper` chain or null for the default chain mapper, ConverterLookup the instance that is used to lookup the converters converterLookup, ConverterRegistry an instance to manage the converter instances converterRegistry) Deprecated As of 1.4.5 use `XStream(ReflectionProvider, HierarchicalStreamDriver, ClassLoaderReference, Mapper, ConverterLookup, ConverterRegistry)` Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` chain, the `ClassLoaderReference` and an own `ConverterLookup` and `ConverterRegistry`.
public	XStream(ReflectionProvider the reflection provider to use or null for best matching Provider reflectionProvider, HierarchicalStreamDriver the driver instance driver, ClassLoaderReference the reference to the `ClassLoader` to use classLoaderReference, Mapper the instance with the `Mapper` chain or null for the default chain mapper, ConverterLookup the instance that is used to lookup the converters converterLookup, ConverterRegistry an instance to manage the converter instances or null to prevent any further registry (including annotations) converterRegistry) Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` chain, the `ClassLoaderReference` and an own `ConverterLookup` and `ConverterRegistry`.

Method Summary

Modifier and Type	Method and Description
public void	addDefaultImplementation(Class<T> defaultImplementation, Class<T> ofType) Associate a default implementation of a class with an object.
public void	addImmutableType(Class<T> type) Deprecated As of 1.4.9 use `addImmutableType(Class, boolean)` Add immutable types.
public void	addImmutableType(final Class<T> type, final boolean `true` if support at deserialization time is required for compatibility at the cost of a higher memory footprint, `false` otherwise isReferenceable) Add immutable types.
private void	addImmutableTypeDynamically(String className, boolean isReferenceable)
public void	addImplicitArray(Class<T> class owning the implicit array ownerType, String name of the array field fieldName) Adds an implicit array.
public void	addImplicitArray(Class<T> class owning the implicit array ownerType, String name of the array field in the ownerType fieldName, Class<T> type of the items to be part of this array itemType) Adds an implicit array which is used for all items of the given itemType when the array type matches.
public void	addImplicitArray(Class<T> class owning the implicit array ownerType, String name of the array field in the ownerType fieldName, String alias name of the items itemName) Adds an implicit array which is used for all items of the given element name defined by itemName.
public void	addImplicitCollection(Class<T> class owning the implicit collection ownerType, String name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type. fieldName) Adds a default implicit collection which is used for any unmapped XML tag.
public void	addImplicitCollection(Class<T> class owning the implicit collection ownerType, String name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type. fieldName, Class<T> type of the items to be part of this collection itemType) Adds implicit collection which is used for all items of the given itemType.
public void	addImplicitCollection(Class<T> class owning the implicit collection ownerType, String name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type. fieldName, String element name of the implicit collection itemFieldName, Class<T> item type to be aliases be the itemFieldName itemType) Adds implicit collection which is used for all items of the given element name defined by itemFieldName.
public void	addImplicitMap(Class<T> class owning the implicit map ownerType, String name of the field in the ownerType. This field must be a concrete map type or matching the default implementation type of the map type. fieldName, Class<T> type of the items to be part of this map as value itemType, String the name of the field of the itemType that is used for the key in the map keyFieldName) Adds an implicit map.
public void	addImplicitMap(Class<T> class owning the implicit map ownerType, String name of the field in the ownerType. This field must be a concrete map type or matching the default implementation type of the map type. fieldName, String alias name of the items itemName, Class<T> type of the items to be part of this map as value itemType, String the name of the field of the itemType that is used for the key in the map keyFieldName) Adds an implicit map.
public void	addPermission(TypePermission the permission to add permission) Add a new security permission.
public void	alias(String Short name name, Class<T> Type to be aliased type) Alias a Class to a shorter name to be used in XML elements.
public void	alias(String Short name name, Class<T> Type to be aliased type, Class<T> Default implementation of type to use if no other specified. defaultImplementation) Alias a Class to a shorter name to be used in XML elements.
public void	aliasAttribute(String the alias itself alias, String the name of the attribute attributeName) Create an alias for an attribute
public void	aliasAttribute(Class<T> the type where the attribute is defined definedIn, String the name of the attribute attributeName, String the alias itself alias) Create an alias for an attribute.
private void	aliasDynamically(String alias, String className)
public void	aliasField(String the alias itself alias, Class<T> the type that declares the field definedIn, String the name of the field fieldName) Create an alias for a field name.
public void	aliasPackage(String Short name name, String package to be aliased pkgName) Alias a package to a shorter name to be used in XML elements.
public void	aliasSystemAttribute(String the alias itself (may be `null`) alias, String the name of the system attribute systemAttributeName) Create an alias for a system attribute.
public void	aliasType(String Short name name, Class<T> Type to be aliased type) Alias a type to a shorter name to be used in XML elements.
public void	allowTypeHierarchy(Class<T> the base type to allow type) Add security permission for a type hierarchy.
public void	allowTypes(String[] the type names to allow names) Add security permission for explicit types by name.
public void	allowTypes(Class<T>[] the types to allow types) Add security permission for explicit types.
public void	allowTypesByRegExp(String[] the regular expressions to allow type names regexps) Add security permission for types matching one of the specified regular expressions.
public void	allowTypesByRegExp(Pattern[] the regular expressions to allow type names regexps) Add security permission for types matching one of the specified regular expressions.
public void	allowTypesByWildcard(String[] the patterns to allow type names patterns) Add security permission for types matching one of the specified wildcard patterns.
public void	autodetectAnnotations(boolean `true` if annotations are auto-detected mode) Set the auto-detection mode of the AnnotationMapper.
private Mapper	buildMapper()
private Mapper	buildMapperDynamically(String className, Class<T>[] constructorParamTypes, Object[] constructorParamValues)
public ObjectInputStream	createObjectInputStream(Reader xmlReader) Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
public ObjectInputStream	createObjectInputStream(InputStream in) Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using XStream.
public ObjectInputStream	createObjectInputStream(final HierarchicalStreamReader reader) Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
public ObjectInputStream	createObjectInputStream(final HierarchicalStreamReader reader, DataHolder dataHolder) Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
public ObjectOutputStream	createObjectOutputStream(Writer writer) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
public ObjectOutputStream	createObjectOutputStream(HierarchicalStreamWriter writer) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
public ObjectOutputStream	createObjectOutputStream(Writer writer, String rootNodeName) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
public ObjectOutputStream	createObjectOutputStream(OutputStream out) Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
public ObjectOutputStream	createObjectOutputStream(OutputStream out, String rootNodeName) Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
public ObjectOutputStream	createObjectOutputStream(final HierarchicalStreamWriter The writer to serialize the objects to. writer, final String The name of the root node enclosing the stream of objects. rootNodeName) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
public ObjectOutputStream	createObjectOutputStream(final HierarchicalStreamWriter writer, final String rootNodeName, final DataHolder dataHolder) Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
public void	denyPermission(TypePermission the permission to deny permission) Add security permission denying another one.
public void	denyTypeHierarchy(Class<T> the base type to forbid type) Add security permission forbidding a type hierarchy.
private void	denyTypeHierarchyDynamically(String className)
public void	denyTypes(String[] the type names to forbid names) Add security permission forbidding explicit types by name.
public void	denyTypes(Class<T>[] the types to forbid types) Add security permission forbidding explicit types.
public void	denyTypesByRegExp(String[] the regular expressions to forbid type names regexps) Add security permission forbidding types matching one of the specified regular expressions.
public void	denyTypesByRegExp(Pattern[] the regular expressions to forbid type names regexps) Add security permission forbidding types matching one of the specified regular expressions.
public void	denyTypesByWildcard(String[] the patterns to forbid names patterns) Add security permission forbidding types matching one of the specified wildcard patterns.
public Object	fromXML(String xml) Deserialize an object from an XML String.
public Object	fromXML(Reader reader) Deserialize an object from an XML Reader.
public Object	fromXML(InputStream input) Deserialize an object from an XML InputStream.
public Object	fromXML(URL url) Deserialize an object from a URL.
public Object	fromXML(File file) Deserialize an object from a file.
public Object	fromXML(String xml, Object root) Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one.
public Object	fromXML(Reader xml, Object root) Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one.
public Object	fromXML(URL url, Object root) Deserialize an object from a URL, populating the fields of the given root object instead of instantiating a new one.
public Object	fromXML(File file, Object root) Deserialize an object from a file, populating the fields of the given root object instead of instantiating a new one.
public Object	fromXML(InputStream input, Object root) Deserialize an object from an XML InputStream, populating the fields of the given root object instead of instantiating a new one.
public ClassLoader	getClassLoader() Retrieve the ClassLoader XStream uses to load classes.
public ClassLoaderReference	Returns: the reference getClassLoaderReference() Retrieve the reference to this instance' ClassLoader.
public ConverterLookup	getConverterLookup()
public Mapper	Returns: the mapper getMapper() Retrieve the `Mapper`.
public ReflectionProvider	Returns: the mapper getReflectionProvider() Retrieve the `ReflectionProvider` in use.
public void	ignoreUnknownElements() Ignore all unknown elements.
public void	ignoreUnknownElements(String the name pattern as regular expression pattern) Add pattern for unknown element names to ignore.
public void	ignoreUnknownElements(final Pattern the name pattern as regular expression pattern) Add pattern for unknown element names to ignore.
public void	marshal(Object obj, HierarchicalStreamWriter writer) Serialize and object to a hierarchical data structure (such as XML).
public void	marshal(Object obj, HierarchicalStreamWriter writer, DataHolder Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed. dataHolder) Serialize and object to a hierarchical data structure (such as XML).
public DataHolder	Returns: a new `DataHolder` newDataHolder() Create a DataHolder that can be used to pass data to the converters.
public void	omitField(Class<T> definedIn, String fieldName) Prevents a field from being serialized.
public void	processAnnotations(final Class<T>[] the types with XStream annotations types) Process the annotations of the given types and configure the XStream.
public void	processAnnotations(final Class<T> the type with XStream annotations type) Process the annotations of the given type and configure the XStream.
public void	registerConverter(Converter converter)
public void	registerConverter(Converter converter, int priority)
public void	registerConverter(SingleValueConverter converter)
public void	registerConverter(SingleValueConverter converter, int priority)
private void	registerConverterDynamically(String className, int priority, Class<T>[] constructorParamTypes, Object[] constructorParamValues)
public void	registerLocalConverter(Class<T> the class type the field is defined in definedIn, String the field name fieldName, Converter the converter to use converter) Register a local `Converter` for a field.
public void	registerLocalConverter(Class<T> the class type the field is defined in definedIn, String the field name fieldName, SingleValueConverter the converter to use converter) Register a local `SingleValueConverter` for a field.
public void	setClassLoader(ClassLoader classLoader) Change the ClassLoader XStream uses to load classes.
public void	setCollectionUpdateLimit(int limit in seconds or 0 to disable check maxSeconds) Set time limit for adding elements to collections or maps.
public void	setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
public void	setMode(int mode) Change mode for dealing with duplicate references.
protected void	setupAliases()
protected void	setupConverters()
protected void	setupDefaultImplementations()
public static void	setupDefaultSecurity(final XStream xstream) Deprecated As of 1.4.18 Setup the security framework of a XStream instance.
protected void	setupImmutableTypes()
private void	setupMappers()
protected void	setupSecurity()
public String	toXML(Object obj) Serialize an object to a pretty-printed XML String.
public void	toXML(Object obj, Writer out) Serialize an object to the given Writer as pretty-printed XML.
public void	toXML(Object obj, OutputStream out) Serialize an object to the given OutputStream as pretty-printed XML.
public Object	unmarshal(HierarchicalStreamReader reader) Deserialize an object from a hierarchical data structure (such as XML).
public Object	unmarshal(HierarchicalStreamReader reader, Object root) Deserialize an object from a hierarchical data structure (such as XML), populating the fields of the given root object instead of instantiating a new one.
public Object	unmarshal(HierarchicalStreamReader reader, Object If present, the passed in object will have its fields populated, as opposed to XStream creating a new instance. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care! root, DataHolder Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed. dataHolder) Deserialize an object from a hierarchical data structure (such as XML).
public void	useAttributeFor(String the name of the field fieldName, Class<T> the Class of the type to be rendered as XML attribute type) Use an attribute for a field or a specific type.
public void	useAttributeFor(Class<T> the Class containing such field definedIn, String the name of the field fieldName) Use an attribute for a field declared in a specific type.
public void	useAttributeFor(Class<T> the Class of the type to be rendered as XML attribute type) Use an attribute for an arbitrary type.
protected boolean	useXStream11XmlFriendlyMapper() Deprecated As of 1.4.8
protected MapperWrapper	wrapMapper(MapperWrapper next)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public Class XStream

Aliasing classes

Converters

Object graphs

Thread safety

Implicit collections

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary