Two minute tutorial

This is a very quick introduction to XStream. Skim read it to get an idea of how simple it is to convert objects to XML and back again. I'm sure you'll have questions afterwards.

Create classes to be serialized

Here's a couple of simple classes. XStream can convert instances of these to XML and back again.

      
     
public class Person {
   
     
  private String firstname;
   
     
  private String lastname;
   
     
  private PhoneNumber phone;
   
     
  private PhoneNumber fax;
   
     
  // ... constructors and methods
   
     
}
   
     

public class PhoneNumber {
   
     
  private int code;
   
     
  private String number;
   
     
  // ... constructors and methods
   
     
}
   
    

Note: Notice that the fields are private. XStream doesn't care about the visibility of the fields. No getters or setters are needed. Also, XStream does not limit you to having a default constructor.

Initializing XStream

To use XStream, simply instantiate an XStream class:

      
     
XStream xstream = new XStream();
   
    

Note: This class is a simple facade designed for common operations. For more flexibility you may choose to create your own facade that behaves differently.

Now, to make the XML outputted by XStream more concise, you can create aliases for your custom class names to XML element names. This is the only type of mapping required to use XStream and even this is optional.

      
     
xstream.alias("person", Person.class);
   
     
xstream.alias("phonenumber", PhoneNumber.class);
   
    

Note: This is an optional step. Without it XStream would work fine, but the XML element names would contain the fully qualified name of each class (including package) which would bulk up the XML a bit.

Serializing an object to XML

Let's create an instance of Person and populate its fields:

      
     
Person joe = new Person("Joe", "Walnes");
   
     
joe.setPhone(new PhoneNumber(123, "1234-456");
   
     
joe.setFax(new PhoneNumber(123, "9999-999");
   
    

Now, to convert it to XML, all you have to do is make a simple call to XStream:

      
     
String xml = xstream.toXML(joe);
   
    

The resulting XML looks like this:

      
     

   
     <
   
     person
   
     >
   
     
  
   
     <
   
     firstname
   
     >
   
     Joe
   
     <
   
     /firstname
   
     >
   
     
  
   
     <
   
     lastname
   
     >
   
     Walnes
   
     <
   
     /lastname
   
     >
   
     
  
   
     <
   
     phone
   
     >
   
     
    
   
     <
   
     code
   
     >
   
     123
   
     <
   
     /code
   
     >
   
     
    
   
     <
   
     number
   
     >
   
     1234-456
   
     <
   
     /number
   
     >
   
     
  
   
     <
   
     /phone
   
     >
   
     
  
   
     <
   
     fax
   
     >
   
     
    
   
     <
   
     code
   
     >
   
     123
   
     <
   
     /code
   
     >
   
     
    
   
     <
   
     number
   
     >
   
     9999-999
   
     <
   
     /number
   
     >
   
     
  
   
     <
   
     /fax
   
     >
   
     

   
     <
   
     /person>
   
    

It's that simple. Look at how clean the XML is too.

Deserializing an object back from XML

To reconstruct an object, purely from the XML:

      
     
Person newJoe = (Person)xstream.fromXML(xml);
   
    

And that's how simple XStream is!

Summary

To recap:

  • Create element name to class name aliases for any custom classes using xstream.alias(String elementName, Class cls);
  • Convert an object to XML using xstream.toXML(Object obj);
  • Convert XML back to an object using xstream.fromXML(String xml);