public class XStream extends Object
XStream xstream = new XStream(); String xml = xstream.toXML(myObject); // serialize to XML Object myObject2 = xstream.fromXML(xml); // deserialize from XML
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);
XStream contains a map of 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 edu.internet2.middleware.grouperClientExt.com.thoughtworks.xstream.converters.extended
package and you can create your own by implementing the
Converter
interface.
xstream.registerConverter(new SqlTimestampConverter()); xstream.registerConverter(new DynamicProxyConverter());
The default converter, ie the converter which will be used if no other registered converter is
suitable, can be configured by either one of the constructors or can be changed using the
changeDefaultConverter()
method. If not set, XStream uses
ReflectionConverter
as the initial default
converter.
xstream.changeDefaultConverter(new ACustomDefaultConverter());
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.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. |
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.
To avoid the need for special tags for collections, you can define implicit collections using one
of the addImplicitCollection
methods.
Modifier and Type | Class and Description |
---|---|
static class |
XStream.InitializationException
Deprecated.
since 1.3, use
InitializationException instead |
Modifier and Type | Field and Description |
---|---|
static int |
ID_REFERENCES |
static int |
NO_REFERENCES |
static int |
PRIORITY_LOW |
static int |
PRIORITY_NORMAL |
static int |
PRIORITY_VERY_HIGH |
static int |
PRIORITY_VERY_LOW |
static int |
XPATH_ABSOLUTE_REFERENCES |
static int |
XPATH_REFERENCES
Deprecated.
since 1.2, use
XPATH_RELATIVE_REFERENCES or
XPATH_ABSOLUTE_REFERENCES instead. |
static int |
XPATH_RELATIVE_REFERENCES |
Constructor and Description |
---|
XStream()
Constructs a default XStream.
|
XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
Constructs an XStream with a special
HierarchicalStreamDriver . |
XStream(ReflectionProvider reflectionProvider)
Constructs an XStream with a special
ReflectionProvider . |
XStream(ReflectionProvider reflectionProvider,
ClassMapper classMapper,
HierarchicalStreamDriver driver)
Deprecated.
|
XStream(ReflectionProvider reflectionProvider,
ClassMapper classMapper,
HierarchicalStreamDriver driver,
String classAttributeIdentifier)
Deprecated.
As of 1.2, use
XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver) and
register classAttributeIdentifier as alias |
XStream(ReflectionProvider reflectionProvider,
HierarchicalStreamDriver hierarchicalStreamDriver)
Constructs an XStream with a special
HierarchicalStreamDriver and ReflectionProvider . |
XStream(ReflectionProvider reflectionProvider,
HierarchicalStreamDriver driver,
ClassLoader classLoader)
Constructs an XStream with a special
HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared
ClassLoader to use. |
XStream(ReflectionProvider reflectionProvider,
HierarchicalStreamDriver driver,
ClassLoader classLoader,
Mapper mapper)
Constructs an XStream with a special
HierarchicalStreamDriver and ReflectionProvider and additionally with a prepared Mapper
and the ClassLoader in use. |
XStream(ReflectionProvider reflectionProvider,
HierarchicalStreamDriver driver,
ClassLoader classLoader,
Mapper mapper,
ConverterLookup converterLookup,
ConverterRegistry converterRegistry)
Constructs an XStream with a special
HierarchicalStreamDriver , ReflectionProvider , a prepared Mapper
and the ClassLoader in use and an own ConverterRegistry . |
XStream(ReflectionProvider reflectionProvider,
Mapper mapper,
HierarchicalStreamDriver driver)
Deprecated.
since 1.3, use
#XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader) instead |
Modifier and Type | Method and Description |
---|---|
void |
addDefaultImplementation(Class defaultImplementation,
Class ofType)
Associate a default implementation of a class with an object.
|
void |
addImmutableType(Class type)
Add immutable types.
|
void |
addImplicitCollection(Class ownerType,
String fieldName)
Adds a default implicit collection which is used for any unmapped xml tag.
|
void |
addImplicitCollection(Class ownerType,
String fieldName,
Class itemType)
Adds implicit collection which is used for all items of the given itemType.
|
void |
addImplicitCollection(Class ownerType,
String fieldName,
String itemFieldName,
Class itemType)
Adds implicit collection which is used for all items of the given element name defined by
itemFieldName.
|
void |
alias(String name,
Class type)
Alias a Class to a shorter name to be used in XML elements.
|
void |
alias(String name,
Class type,
Class defaultImplementation)
Alias a Class to a shorter name to be used in XML elements.
|
void |
aliasAttribute(Class definedIn,
String attributeName,
String alias)
Create an alias for an attribute.
|
void |
aliasAttribute(String alias,
String attributeName)
Create an alias for an attribute
|
void |
aliasField(String alias,
Class definedIn,
String fieldName)
Create an alias for a field name.
|
void |
aliasType(String name,
Class type)
Alias a type to a shorter name to be used in XML elements.
|
void |
autodetectAnnotations(boolean mode)
Set the auto-detection mode of the AnnotationMapper.
|
ObjectInputStream |
createObjectInputStream(HierarchicalStreamReader reader)
Creates an ObjectInputStream that deserializes a stream of objects from a reader using
XStream.
|
ObjectInputStream |
createObjectInputStream(InputStream in)
Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using
XStream.
|
ObjectInputStream |
createObjectInputStream(Reader xmlReader)
Creates an ObjectInputStream that deserializes a stream of objects from a reader using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(HierarchicalStreamWriter writer)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(HierarchicalStreamWriter writer,
String rootNodeName)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(OutputStream out)
Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(OutputStream out,
String rootNodeName)
Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(Writer writer)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using
XStream.
|
ObjectOutputStream |
createObjectOutputStream(Writer writer,
String rootNodeName)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using
XStream.
|
Object |
fromXML(InputStream input)
Deserialize an object from an XML InputStream.
|
Object |
fromXML(InputStream xml,
Object root)
Deserialize an object from an XML InputStream, populating the fields of the given root object
instead of instantiating a new one.
|
Object |
fromXML(Reader xml)
Deserialize an object from an XML Reader.
|
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.
|
Object |
fromXML(String xml)
Deserialize an object from an XML String.
|
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.
|
ClassLoader |
getClassLoader()
Change the ClassLoader XStream uses to load classes.
|
ClassMapper |
getClassMapper()
Deprecated.
As of 1.2, use
getMapper() |
ConverterLookup |
getConverterLookup() |
Mapper |
getMapper()
Retrieve the
Mapper . |
ReflectionProvider |
getReflectionProvider()
Retrieve the
ReflectionProvider in use. |
void |
marshal(Object obj,
HierarchicalStreamWriter writer)
Serialize and object to a hierarchical data structure (such as XML).
|
void |
marshal(Object obj,
HierarchicalStreamWriter writer,
DataHolder dataHolder)
Serialize and object to a hierarchical data structure (such as XML).
|
DataHolder |
newDataHolder()
Create a DataHolder that can be used to pass data to the converters.
|
void |
omitField(Class definedIn,
String fieldName)
Prevents a field from being serialized.
|
void |
processAnnotations(Class type)
Process the annotations of the given type and configure the XStream.
|
void |
processAnnotations(Class[] types)
Process the annotations of the given types and configure the XStream.
|
void |
registerConverter(Converter converter) |
void |
registerConverter(Converter converter,
int priority) |
void |
registerConverter(SingleValueConverter converter) |
void |
registerConverter(SingleValueConverter converter,
int priority) |
void |
registerLocalConverter(Class definedIn,
String fieldName,
Converter converter)
Register a local
Converter for a field. |
void |
registerLocalConverter(Class definedIn,
String fieldName,
SingleValueConverter converter)
Register a local
SingleValueConverter for a field. |
void |
setClassLoader(ClassLoader classLoader)
Change the ClassLoader XStream uses to load classes.
|
void |
setMarshallingStrategy(MarshallingStrategy marshallingStrategy) |
void |
setMode(int mode)
Change mode for dealing with duplicate references.
|
protected void |
setupAliases() |
protected void |
setupConverters() |
protected void |
setupDefaultImplementations() |
protected void |
setupImmutableTypes() |
String |
toXML(Object obj)
Serialize an object to a pretty-printed XML String.
|
void |
toXML(Object obj,
OutputStream out)
Serialize an object to the given OutputStream as pretty-printed XML.
|
void |
toXML(Object obj,
Writer out)
Serialize an object to the given Writer as pretty-printed XML.
|
Object |
unmarshal(HierarchicalStreamReader reader)
Deserialize an object from a hierarchical data structure (such as XML).
|
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.
|
Object |
unmarshal(HierarchicalStreamReader reader,
Object root,
DataHolder dataHolder)
Deserialize an object from a hierarchical data structure (such as XML).
|
void |
useAttributeFor(Class type)
Use an attribute for an arbitrary type.
|
void |
useAttributeFor(Class definedIn,
String fieldName)
Use an attribute for a field declared in a specific type.
|
void |
useAttributeFor(String fieldName,
Class type)
Use an attribute for a field or a specific type.
|
protected boolean |
useXStream11XmlFriendlyMapper() |
protected MapperWrapper |
wrapMapper(MapperWrapper next) |
public static final int NO_REFERENCES
public static final int ID_REFERENCES
public static final int XPATH_RELATIVE_REFERENCES
public static final int XPATH_ABSOLUTE_REFERENCES
public static final int XPATH_REFERENCES
XPATH_RELATIVE_REFERENCES
or
XPATH_ABSOLUTE_REFERENCES
instead.public static final int PRIORITY_VERY_HIGH
public static final int PRIORITY_NORMAL
public static final int PRIORITY_LOW
public static final int PRIORITY_VERY_LOW
public XStream()
XppDriver
as default and tries to determine the best
match for the ReflectionProvider
on its own.XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider)
ReflectionProvider
. The instance will use the XppDriver
as default.XStream.InitializationException
- in case of an initialization problempublic XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
HierarchicalStreamDriver
. The instance will tries to determine the best
match for the ReflectionProvider
on its own.XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver hierarchicalStreamDriver)
HierarchicalStreamDriver
and ReflectionProvider
.XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver)
XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)
public XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, String classAttributeIdentifier)
XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)
and
register classAttributeIdentifier as aliaspublic XStream(ReflectionProvider reflectionProvider, Mapper mapper, HierarchicalStreamDriver driver)
#XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader)
insteadHierarchicalStreamDriver
and ReflectionProvider
and additionally with a prepared Mapper
.XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader)
HierarchicalStreamDriver
and ReflectionProvider
and additionally with a prepared
ClassLoader
to use.XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader, Mapper mapper)
HierarchicalStreamDriver
and ReflectionProvider
and additionally with a prepared Mapper
and the ClassLoader
in use.
Note, if the class loader should be changed later again, you should provide a ClassLoaderReference
as ClassLoader
that is also
use in the Mapper
chain.
XStream.InitializationException
- in case of an initialization problempublic XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader, Mapper mapper, ConverterLookup converterLookup, ConverterRegistry converterRegistry)
HierarchicalStreamDriver
, ReflectionProvider
, a prepared Mapper
and the ClassLoader
in use and an own ConverterRegistry
.
Note, if the class loader should be changed later again, you should provide a ClassLoaderReference
as ClassLoader
that is also
use in the Mapper
chain.
XStream.InitializationException
- in case of an initialization problemprotected MapperWrapper wrapMapper(MapperWrapper next)
protected boolean useXStream11XmlFriendlyMapper()
protected void setupAliases()
protected void setupDefaultImplementations()
protected void setupConverters()
protected void setupImmutableTypes()
public void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
public String toXML(Object obj)
XStreamException
- if the object cannot be serializedpublic void toXML(Object obj, Writer out)
XStreamException
- if the object cannot be serializedpublic void toXML(Object obj, OutputStream out)
XStreamException
- if the object cannot be serializedpublic void marshal(Object obj, HierarchicalStreamWriter writer)
XStreamException
- if the object cannot be serializedpublic void marshal(Object obj, HierarchicalStreamWriter writer, DataHolder dataHolder)
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.XStreamException
- if the object cannot be serializedpublic Object fromXML(String xml)
XStreamException
- if the object cannot be deserializedpublic Object fromXML(Reader xml)
XStreamException
- if the object cannot be deserializedpublic Object fromXML(InputStream input)
XStreamException
- if the object cannot be deserializedpublic Object fromXML(String xml, Object root)
XStreamException
- if the object cannot be deserializedpublic Object fromXML(Reader xml, Object root)
XStreamException
- if the object cannot be deserializedpublic Object fromXML(InputStream xml, Object root)
XStreamException
- if the object cannot be deserializedpublic Object unmarshal(HierarchicalStreamReader reader)
XStreamException
- if the object cannot be deserializedpublic Object unmarshal(HierarchicalStreamReader reader, Object root)
XStreamException
- if the object cannot be deserializedpublic Object unmarshal(HierarchicalStreamReader reader, Object root, DataHolder dataHolder)
root
- 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!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.XStreamException
- if the object cannot be deserializedpublic void alias(String name, Class type)
name
- Short nametype
- Type to be aliasedXStream.InitializationException
- if no ClassAliasingMapper
is availablepublic void aliasType(String name, Class type)
name
- Short nametype
- Type to be aliasedXStream.InitializationException
- if no ClassAliasingMapper
is availablepublic void alias(String name, Class type, Class defaultImplementation)
name
- Short nametype
- Type to be aliaseddefaultImplementation
- Default implementation of type to use if no other specified.XStream.InitializationException
- if no DefaultImplementationsMapper
or no ClassAliasingMapper
is availablepublic void aliasField(String alias, Class definedIn, String fieldName)
alias
- the alias itselfdefinedIn
- the type that declares the fieldfieldName
- the name of the fieldXStream.InitializationException
- if no FieldAliasingMapper
is availablepublic void aliasAttribute(String alias, String attributeName)
alias
- the alias itselfattributeName
- the name of the attributeXStream.InitializationException
- if no AttributeAliasingMapper
is availablepublic void aliasAttribute(Class definedIn, String attributeName, String alias)
definedIn
- the type where the attribute is definedattributeName
- the name of the attributealias
- the alias itselfXStream.InitializationException
- if no AttributeAliasingMapper
is availablepublic void useAttributeFor(String fieldName, Class type)
fieldName
- the name of the fieldtype
- the Class of the type to be rendered as XML attributeXStream.InitializationException
- if no AttributeMapper
is availablepublic void useAttributeFor(Class definedIn, String fieldName)
fieldName
- the name of the fielddefinedIn
- the Class containing such fieldXStream.InitializationException
- if no AttributeMapper
is availablepublic void useAttributeFor(Class type)
type
- the Class of the type to be rendered as XML attributeXStream.InitializationException
- if no AttributeMapper
is availablepublic void addDefaultImplementation(Class defaultImplementation, Class ofType)
defaultImplementation
- ofType
- XStream.InitializationException
- if no DefaultImplementationsMapper
is availablepublic void addImmutableType(Class type)
XStream.InitializationException
- if no ImmutableTypesMapper
is availablepublic void registerConverter(Converter converter)
public void registerConverter(Converter converter, int priority)
public void registerConverter(SingleValueConverter converter)
public void registerConverter(SingleValueConverter converter, int priority)
public void registerLocalConverter(Class definedIn, String fieldName, Converter converter)
Converter
for a field.definedIn
- the class type the field is defined infieldName
- the field nameconverter
- the converter to usepublic void registerLocalConverter(Class definedIn, String fieldName, SingleValueConverter converter)
SingleValueConverter
for a field.definedIn
- the class type the field is defined infieldName
- the field nameconverter
- the converter to usepublic ClassMapper getClassMapper()
getMapper()
ClassCastException
- if mapper is not really a deprecated ClassMapper
instancepublic Mapper getMapper()
Mapper
. This is by default a chain of MapperWrappers
.public ReflectionProvider getReflectionProvider()
ReflectionProvider
in use.public ConverterLookup getConverterLookup()
public void setMode(int mode)
XPATH_ABSOLUTE_REFERENCES
, XPATH_RELATIVE_REFERENCES
,
XStream.ID_REFERENCES
and XStream.NO_REFERENCES
.IllegalArgumentException
- if the mode is not one of the declared typesXPATH_ABSOLUTE_REFERENCES
,
XPATH_RELATIVE_REFERENCES
,
ID_REFERENCES
,
NO_REFERENCES
public void addImplicitCollection(Class ownerType, String fieldName)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be an
java.util.ArrayList
.public void addImplicitCollection(Class ownerType, String fieldName, Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be an
java.util.ArrayList
.itemType
- type of the items to be part of this collection.XStream.InitializationException
- if no ImplicitCollectionMapper
is availablepublic void addImplicitCollection(Class ownerType, String fieldName, String itemFieldName, Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be an
java.util.ArrayList
.itemFieldName
- element name of the implicit collectionitemType
- item type to be aliases be the itemFieldNameXStream.InitializationException
- if no ImplicitCollectionMapper
is availablepublic DataHolder newDataHolder()
marshal(Object, HierarchicalStreamWriter, DataHolder)
or
unmarshal(HierarchicalStreamReader, Object, DataHolder)
.DataHolder
public ObjectOutputStream createObjectOutputStream(Writer writer) throws IOException
To change the name of the root element (from <object-stream>), use
createObjectOutputStream(java.io.Writer, String)
.
public ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer) throws IOException
To change the name of the root element (from <object-stream>), use
createObjectOutputStream(java.io.Writer, String)
.
public ObjectOutputStream createObjectOutputStream(Writer writer, String rootNodeName) throws IOException
public ObjectOutputStream createObjectOutputStream(OutputStream out) throws IOException
To change the name of the root element (from <object-stream>), use
createObjectOutputStream(java.io.Writer, String)
.
public ObjectOutputStream createObjectOutputStream(OutputStream out, String rootNodeName) throws IOException
public ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer, String rootNodeName) throws IOException
Because an ObjectOutputStream can contain multiple items and XML only allows a single root node, the stream must be written inside an enclosing node.
It is necessary to call ObjectOutputStream.close() when done, otherwise the stream will be incomplete.
ObjectOutputStream out = xstream.createObjectOutputStream(aWriter, "things"); out.writeInt(123); out.writeObject("Hello"); out.writeObject(someObject) out.close();
writer
- The writer to serialize the objects to.rootNodeName
- The name of the root node enclosing the stream of objects.IOException
createObjectInputStream(edu.internet2.middleware.grouperClientExt.com.thoughtworks.xstream.io.HierarchicalStreamReader)
public ObjectInputStream createObjectInputStream(Reader xmlReader) throws IOException
public ObjectInputStream createObjectInputStream(InputStream in) throws IOException
public ObjectInputStream createObjectInputStream(HierarchicalStreamReader reader) throws IOException
ObjectInputStream in = xstream.createObjectOutputStream(aReader); int a = out.readInt(); Object b = out.readObject(); Object c = out.readObject();
public void setClassLoader(ClassLoader classLoader)
public ClassLoader getClassLoader()
public void omitField(Class definedIn, String fieldName)
XStream.InitializationException
- if no FieldAliasingMapper
is availablepublic void processAnnotations(Class[] types)
types
- the types with XStream annotationspublic void processAnnotations(Class type)
type
- the type with XStream annotationspublic void autodetectAnnotations(boolean mode)
mode
- true
if annotations are auto-detectedCopyright © 2016 Internet2. All rights reserved.