XStream – Java Object to XML

xstream-logoXStream is a simple Java library to convert objects to XML and back again. XStream, also provides many features to control the conversion from/to XML.

Objectives:

  • How to simply convert an object to xml and back again?
  • How to control the naming of XML tags using aliases?
  • How to control the conversion using annotations?

Environment & Tools:

  • Eclipse (or any other IDE)
  • Maven (optional)
  • JDK 1.6+

Library:

<dependency>
        <groupId>com.thoughtworks.xstream</groupId>
        <artifactId>xstream</artifactId>
        <version>1.4.4</version>
    </dependency>

( 1 ) Simple Conversion

  • Article.java

We will use this Java object in our examples.

package com.hmkcode.vo;

import java.util.LinkedList;
import java.util.List;

public class Article {

	private String title;
	private String url;
	private boolean published;
	private List<String> categories;
	private List<String> tags;

       //getters & setters	
}

Straight forward conversion

XStream xs = new XStream();

// OBJECT --> XML
String xml = xs.toXML(createArticle());

// XML --> OBJECT
Article article = (Article) xs.fromXML(xml);

Output:

( 2 ) Aliasing “change XML default tags”

If we convert an object directly to XML the name of the root will be class name e.g. <com.hmkcode.vo.Article> and the names of other tags will be similar to the names of the converted object attributes.

// <com.hmkcode.vo.Article> --> <article>
xs.alias("article", Article.class);
// <url> --> <address>
xs.aliasField("address", Article.class, "url");

Output:

( 3 ) Annotations

XStream provides annotations to have better control over the conversion. We will cover the following annotations:

  • @XStreamAlias(“…”) change the default tag name to the one specified.
  • @XStreamImplicit(itemFieldName=”…”): change the default tag name of collections item.
  • @XStreamAsAttribute: make this property as attribute not tag.
  • @XStreamConverter(….): convert the value of this property to the specified one.
  • @XStreamOmitField: Ignore this property when converting to XML.

Enable Annotations

Before using annotation, we have to instruct XStream to detect annotations.

XStream xs = new XStream();
xs.autodetectAnnotations(true);

Applying Annotation:

//<com.hmkcode.vo.Article> --> <article>
@XStreamAlias("article")
public class Article {

    // <title>..</title> --> <article title="...">
    @XStreamAsAttribute
    private String title;

    // <url> --> <address>
    @XStreamAlias("address")
    private String url;

    // <published>true</published> -->  <published>yes</published>
    @XStreamConverter(value=BooleanConverter.class, booleans={false}, strings={"yes", "no"})
    private boolean published;

    // <categories>...</categories> --> nothing 
    @XStreamOmitField
    private List<String> categories;

    //<string>..</string> --> <tag>..<tag>
    @XStreamImplicit(itemFieldName="tag")
    private List<String> tags;

Complete Example:

package com.hmkcode;

import com.hmkcode.vo.Article;
import com.thoughtworks.xstream.XStream;

public class App 
{
    public static void main( String[] args )
    {

    	XStream xs = new XStream();
    	xs.autodetectAnnotations(true);

    	// <com.hmkcode.vo.Article> --> <article>
    	//xs.alias("article", Article.class);
    	// <url> --> <address>
    	// xs.aliasField("address", Article.class, "url");

    	// OBJECT --> XML
        String xml = xs.toXML(createArticle());

        System.out.println("OBJECT --> XML");
        System.out.println(xml);

        System.out.println("\n--------------------------------\n");

    	// XML --> OBJECT
        Article article = (Article) xs.fromXML(xml);

        System.out.println("XML --> OBJECT");
        System.out.println(article);
    }

  private static Article createArticle(){

    	Article article = new Article();

    	article.setTitle("XStream - Java Object to XML & XML to Object Mapping");
    	article.setUrl("http://hmkcode.com/xstream-java-object-xml");
    	article.setPublished(true);

    	article.addCategory("Java");
    	article.addTag("Java");
    	article.addTag("Xstream");
    	article.addTag("XML");
    	article.addTag("Marshalling");
    	article.addTag("Unmarshalling");

    	return article;
    }
}

Source Code @ GitHub