XStream

Presented by

Angelin

Lightweight and easy-to-use open source

Java™ library

Used for serializing java objects into XML and

de-serializing XML back into java objects

Uses reflection API for serialization and

deserialization

xstream-[version].jar and xpp3-[version].jar

are required in the classpath.

Instantiate the XStream class:

XStream xstream = new XStream();

To Serialize an object to a XML String use:

xstream.toXML(Object obj);

To Deserialize an object from an XML String

use:

xstream.fromXML(String xml);

import com.thoughtworks.xstream.XStream;

public class HelloWorld {

public static void main(String[] args) {

XStream xstream = new XStream();

String salutation = "Hello, World!";

String xml = xstream.toXML(salutation);

System.out.print(xml);

}

}

Output

<string>Hello, World!</string>

Output

<com.example.Person>

<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>

<number>123456</number>

</phone>

<fax>

<code>123</code>


</fax>

</com.example.Person>

Name: Joe

Age: 23

Phone:123-123456

Fax:123-112233

Syntax: xstream.useAttributeFor(Class definedIn, String fieldName);

Aliasing enables us to use different tag or

attribute names in the generated XML.

The different types of aliasing that Xstream

supports are:

Class aliasing

Field aliasing

Attribute aliasing

Package aliasing

Omitting fields and root tag of collection

Xstream default serialization nature:

fully qualified class name <> element name

corresponding to the class

Use Class Aliasing to get the class name

(without the package name) as the XML

element name

To create alias for any class' name, use

xstream.alias(String alias, Class clsname);

Before Class Aliasing After Class Aliasing


<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>


<Person>

<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>

</Person>

Syntax:

xstream.alias(String alias, Class clsName);

Example:

xstream.alias(“Person", Person.class);

Syntax:

xstream.aliasField(String alias, Class definedIn, String fieldName);

Example:

xstream.aliasField("Name", Person.class, "name");

Before Field Aliasing After Field Aliasing

<Person>

<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>

</Person>

<Person>

<Name>Joe</Name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>

</Person>

Syntax:

xstream.aliasAttribute(Class definedIn, String fieldName, String

alias); // makes field as attribute and sets an alias name for it

Example:

xstream.aliasAttribute(PhoneNumber.class, "code", "AreaCode");

xstream.aliasAttribute(PhoneNumber.class, "number", "Number");

Before Attribute Aliasing After Attribute Aliasing

<Person>

<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>

</Person>

<Person>

<Name>Joe</Name>

<age>23</age>

<phone AreaCode="123" Number="123456"/>

<fax AreaCode="123" Number="112233"/>

</Person>

xstream.aliasAttribute(PhoneNumber.class, "code", "AreaCode");

xstream.aliasAttribute(PhoneNumber.class, "number", "Number");

Is equivalent to

xstream.useAttributeFor(PhoneNumber.class, "code");

xstream.aliasField("AreaCode", PhoneNumber.class, "code");

xstream.useAttributeFor(PhoneNumber.class, "number");

xstream.aliasField("Number", PhoneNumber.class, "number");

Syntax:

xstream.aliasPackage(String alias, String packageName);

Example:

xstream.aliasPackage("my.company", "com.example");

Before Field Aliasing After Field Aliasing


<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>


<my.company.Person>

<name>Joe</name>

<age>23</age>

<phone>

<code>123</code>


</phone>

<fax>

<code>123</code>


</fax>

</my.company.Person>

Syntax:

xstream.omitField(Class definedIn, String fieldName);

Syntax:

xstream.addImplicitCollection(Class definedIn, String collectionName);

For converting particular types of objects

found in the object graph, to and from XML.

Xstream provides converters for primitives,

String, File, Collections, arrays, and Dates.

Types:

Converters for converting common basic types in

Java into a single String, with no nested

elements

Converters for converting items in collections

such as arrays, Lists, Sets and Maps into nested

elements

To customize the information being serialized

or deserialized.

They can be implemented and registered

using the

XStream.registerConverter() method

Converters for objects that can store all

information in a single value should

implement SingleValueConverter.

Annotations simplify the process of setting aliases and

registering converters etc.

Annotations do not provide more functionality, but may

improve convenience.

Annotation Types Description

@XStreamAlias Annotation used to define an XStream class or

field value.

@XStreamAsAttribute Defines that a field should be serialized as an

attribute.

@XStreamConverter Annotation to declare a converter.

@XStreamImplicit An annotation for marking a field as an

implicit collection.

@XStreamInclude Annotation to force automated processing of

further classes.

@XStreamOmitField Declares a field to be omitted.

processAnnotation() method to configure

Xstream to process annotations defined in

classes

All super types, implemented interfaces, the

class types of the members and all their generic

types will be processed.

For e.g. the statement

xstream.processAnnotations(Person.class);

will also process the annotations of its member

of type Company. So there is no need to

explicitly configure processAnnotation() for the

class Company.

XStream can also be run in a lazy mode,

where it auto-detects the annotations while

processing the object graph and configures

the XStream instance on-the-fly.

Example:

XStream xstream = new XStream() {

{

autodetectAnnotations(true);

}

};

Implications of using autodetectAnnotations

Deserialization will fail if the type has not

already been processed either by having called

XStream's processAnnotations method or by

already having serialized this type. However,

@XStreamAlias is the only annotation that may

fail in this case

May cause thread-unsafe operation

will slow down the marshalling process until all

processed types have been examined once.

Xstream method Equivalent Xstream

Annotation

xstream.alias("Person", Person.class); @XStreamAlias("Person")

public class Person {

...

...

}

Annotation used to define an XStream class or field value.

Xstream method Equivalent Xstream

Annotation

xstream.aliasAttribute(Person.class,

"company", "Company");

@XStreamAlias("Person")


...

...

@XStreamAsAttribute

@XStreamAlias("Company")

private Company company;

...

...

}

Defines that a field should be serialized as an attribute.

Xstream method Equivalent Xstream Annotation

xstream.registerConverter(new

CompanyConverter());

@XStreamConverter(CompanyConverter.class)

public class Company {

...

}

Annotation to declare a converter.


xstream.registerConverter(new

CompanyConverter());



...

@XStreamAsAttribute

@XstreamAlias("Company")

@XStreamConverter(CompanyConverter.class)

private Company company;

...

}

To register the custom converter locally, i.e. only for the

member variable company defined in the Person class


xstream.addImplicitCollection(Cu

stomers.class, "customers");

@XStreamAlias("Customers")

public class Customers {

@XStreamImplicit

private List customers;

...

...

}

An annotation for marking a field as an implicit collection.


xstream.omitField(Person.class,

"phone");



...

@XStreamOmitField

private PhoneNumber phone;

@XStreamOmitField

private PhoneNumber fax;

...

}

Declares a field to be omitted.

Used by base classes to improve annotation processing when

deserializing.

Example:

Annotation processing using autodetectAnnotations

Annotation processing using processAnnotations

Technology

XStream