|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.thoughtworks.xstream.XStream
Simple facade to XStream library, a Java-XML serialization tool.
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 occurences 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
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 XPath or IDs. The
mode can be changed using setMode()
:
xstream.setMode(XStream.XPATH_REFERENCES); |
(Default) Uses XPath 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 seperate 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.
Field Summary | |
static int |
ID_REFERENCES
|
static int |
NO_REFERENCES
|
static int |
XPATH_REFERENCES
|
Constructor Summary | |
XStream()
|
|
XStream(Converter defaultConverter)
|
|
XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
|
|
XStream(ReflectionProvider reflectionProvider)
|
|
XStream(ReflectionProvider reflectionProvider,
ClassMapper classMapper,
HierarchicalStreamDriver driver)
|
|
XStream(ReflectionProvider reflectionProvider,
ClassMapper classMapper,
HierarchicalStreamDriver driver,
java.lang.String classAttributeIdentifier)
|
|
XStream(ReflectionProvider reflectionProvider,
ClassMapper classMapper,
HierarchicalStreamDriver driver,
java.lang.String classAttributeIdentifier,
Converter defaultConverter)
|
|
XStream(ReflectionProvider reflectionProvider,
HierarchicalStreamDriver hierarchicalStreamDriver)
|
Method Summary | |
void |
addDefaultCollection(java.lang.Class ownerType,
java.lang.String fieldName)
Deprecated. Use addImplicitCollection() instead. |
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName)
Adds a default implicit collection which is used for any unmapped xml tag. |
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName,
java.lang.Class itemType)
Adds implicit collection which is used for all items of the given itemType. |
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName,
java.lang.String itemFieldName,
java.lang.Class itemType)
Adds implicit collection which is used for all items of the given element name defined by itemFieldName. |
void |
alias(java.lang.String elementName,
java.lang.Class type)
Alias a Class to a shorter name to be used in XML elements. |
void |
alias(java.lang.String elementName,
java.lang.Class type,
java.lang.Class defaultImplementation)
Alias a Class to a shorter name to be used in XML elements. |
void |
changeDefaultConverter(Converter defaultConverter)
|
java.io.ObjectInputStream |
createObjectInputStream(HierarchicalStreamReader reader)
Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream. |
java.io.ObjectInputStream |
createObjectInputStream(java.io.Reader xmlReader)
Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream. |
java.io.ObjectOutputStream |
createObjectOutputStream(HierarchicalStreamWriter writer)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream. |
java.io.ObjectOutputStream |
createObjectOutputStream(HierarchicalStreamWriter writer,
java.lang.String rootNodeName)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream. |
java.io.ObjectOutputStream |
createObjectOutputStream(java.io.Writer writer)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream. |
java.io.ObjectOutputStream |
createObjectOutputStream(java.io.Writer writer,
java.lang.String rootNodeName)
Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream. |
java.lang.Object |
fromXML(java.io.Reader xml)
Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one. |
java.lang.Object |
fromXML(java.io.Reader xml,
java.lang.Object root)
Deserialize an object from an XML Reader. |
java.lang.Object |
fromXML(java.lang.String xml)
Deserialize an object from an XML String. |
java.lang.Object |
fromXML(java.lang.String xml,
java.lang.Object root)
Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one. |
ClassMapper |
getClassMapper()
|
ConverterLookup |
getConverterLookup()
|
void |
marshal(java.lang.Object obj,
HierarchicalStreamWriter writer)
Serialize and object to a hierarchical data structure (such as XML). |
void |
marshal(java.lang.Object obj,
HierarchicalStreamWriter writer,
DataHolder dataHolder)
Serialize and object to a hierarchical data structure (such as XML). |
DataHolder |
newDataHolder()
|
void |
registerConverter(Converter converter)
|
void |
setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
|
void |
setMode(int mode)
Change mode for dealing with duplicate references. |
java.lang.String |
toXML(java.lang.Object obj)
Serialize an object to a pretty-printed XML String. |
void |
toXML(java.lang.Object obj,
java.io.Writer writer)
Serialize an object to the given Writer as pretty-printed XML. |
java.lang.Object |
unmarshal(HierarchicalStreamReader reader)
Deserialize an object from a hierarchical data structure (such as XML). |
java.lang.Object |
unmarshal(HierarchicalStreamReader reader,
java.lang.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. |
java.lang.Object |
unmarshal(HierarchicalStreamReader reader,
java.lang.Object root,
DataHolder dataHolder)
Deserialize an object from a hierarchical data structure (such as XML). |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int NO_REFERENCES
public static final int ID_REFERENCES
public static final int XPATH_REFERENCES
Constructor Detail |
public XStream()
public XStream(Converter defaultConverter)
public XStream(HierarchicalStreamDriver hierarchicalStreamDriver)
public XStream(ReflectionProvider reflectionProvider)
public XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver hierarchicalStreamDriver)
public XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver)
public XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, java.lang.String classAttributeIdentifier)
public XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, java.lang.String classAttributeIdentifier, Converter defaultConverter)
Method Detail |
public void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)
public java.lang.String toXML(java.lang.Object obj)
public void toXML(java.lang.Object obj, java.io.Writer writer)
public void marshal(java.lang.Object obj, HierarchicalStreamWriter writer)
public void marshal(java.lang.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.public java.lang.Object fromXML(java.lang.String xml)
public java.lang.Object fromXML(java.io.Reader xml)
public java.lang.Object fromXML(java.lang.String xml, java.lang.Object root)
public java.lang.Object fromXML(java.io.Reader xml, java.lang.Object root)
public java.lang.Object unmarshal(HierarchicalStreamReader reader)
public java.lang.Object unmarshal(HierarchicalStreamReader reader, java.lang.Object root)
public java.lang.Object unmarshal(HierarchicalStreamReader reader, java.lang.Object root, DataHolder dataHolder)
root
- If present, the passed in object will have its fields populated, as opposed to XStream creating a
new instance.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.public void alias(java.lang.String elementName, java.lang.Class type)
elementName
- Short nametype
- Type to be aliasedpublic void alias(java.lang.String elementName, java.lang.Class type, java.lang.Class defaultImplementation)
elementName
- Short nametype
- Type to be aliaseddefaultImplementation
- Default implementation of type to use if no other specified.public void changeDefaultConverter(Converter defaultConverter)
public void registerConverter(Converter converter)
public ClassMapper getClassMapper()
public ConverterLookup getConverterLookup()
public void setMode(int mode)
XStream.XPATH_REFERENCES
,
XStream.ID_REFERENCES
and XStream.NO_REFERENCES
.
XPATH_REFERENCES
,
ID_REFERENCES
,
NO_REFERENCES
public void addDefaultCollection(java.lang.Class ownerType, java.lang.String fieldName)
public void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This filed must be an java.util.ArrayList
.public void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This filed must be an java.util.ArrayList
.itemType
- type of the items to be part of this collection.public void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.String itemFieldName, java.lang.Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This filed must be an java.util.ArrayList
.itemFieldName
- element name of the implicit collectionitemType
- item type to be aliases be the itemFieldNamepublic DataHolder newDataHolder()
public java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer) throws java.io.IOException
To change the name of the root element (from <object-stream>), use
createObjectOutputStream(java.io.Writer, String)
.
java.io.IOException
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)
,
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)
public java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer) throws java.io.IOException
To change the name of the root element (from <object-stream>), use
createObjectOutputStream(java.io.Writer, String)
.
java.io.IOException
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)
,
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)
public java.io.ObjectOutputStream createObjectOutputStream(java.io.Writer writer, java.lang.String rootNodeName) throws java.io.IOException
java.io.IOException
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)
,
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)
public java.io.ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer, java.lang.String rootNodeName) throws java.io.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.
java.io.IOException
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)
public java.io.ObjectInputStream createObjectInputStream(java.io.Reader xmlReader) throws java.io.IOException
java.io.IOException
createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)
,
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)
public java.io.ObjectInputStream createObjectInputStream(HierarchicalStreamReader reader) throws java.io.IOException
ObjectInputStream in = xstream.createObjectOutputStream(aReader); int a = out.readInt(); Object b = out.readObject(); Object c = out.readObject();
java.io.IOException
createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |