XStream使用文档.doc

XStream使用文档 作者：胡少锋 Email：2011年11月1 基本介绍1.1 前言XStream 是一个轻量级的、简单易用的开放源代码 Java库，用于将 Java 对象序列化为 XML 或者再转换回来。而且XStream还能将java对象转成其它格式，比如JSon。官方上的XStream特点：l 使用简单l 不需要配置映射l 速度快，占用内存小l 生成的XML文件简洁l 不需要修改序列化对象的类型l 支持类嵌套l 详细的错误日志l 可转成其它格式XStream相比其它框架有如下的优点：l XStream 不关心序列化/逆序列化的类的字段的可见性。l 序列化/逆序列化类的字段不需要 getter 和 setter 方法。l 序列化/逆序列化的类不需要有默认构造函数。2 安装和使用2.1 下载XStream的网站/download.html上面可以下载到各种版本。目前用最新版本是1.4.1，下载这个版本即可。2.2 安装XStream的安装方法比较简单，将xstream-1.4.1.jar以及kxml2-2.3.0.jar放置到类路径下面即可使用。如下图所示：3 开始一个例子3.1 新建一个空的java project工程通过eclipse向导新建一个Java Project工程，并将上面提的两个类添加到类路径下。工程如下：3.2 编写Java后台类，代码如下新建一个cn的package，然后在cn下面新建两个Java类，Person和PhoneNumber，代码分别如下：Person.javapackage cn;public class Person private String firstname;private String lastname;private PhoneNumber phone;private PhoneNumber fax;public Person(String firstName, String lastName) this.firstname = firstName;this.lastname = lastName;public String getFirstname() return firstname;public void setFirstname(String firstname) this.firstname = firstname;public String getLastname() return lastname;public void setLastname(String lastname) this.lastname = lastname;public PhoneNumber getPhone() return phone;public void setPhone(PhoneNumber phone) this.phone = phone;public PhoneNumber getFax() return fax;public void setFax(PhoneNumber fax) this.fax = fax;PhoneNumber.javapackage cn;public class PhoneNumber private int code;private String number;public PhoneNumber(int code, String number) this.code = code;this.number = number;public int getCode() return code;public void setCode(int code) this.code = code;public String getNumber() return number;public void setNumber(String number) this.number = number;以上是两个很普通的Java对象。下面将写测试代码，将一个Person对象转成xml；然后再从xml转成Java对象。在cn包下面建立一个Main.java，代码如下：package cn;import com.thoughtworks.xstream.XStream;public class Main /* * param args */public static void main(String args) XStream xstream = new XStream();xstream.alias(person, Person.class);xstream.alias(phonenumber, PhoneNumber.class);Person joe = new Person(Joe, Walnes);joe.setPhone(new PhoneNumber(123, 1234-456);joe.setFax(new PhoneNumber(123, 9999-999);String xml = xstream.toXML(joe);System.out.println(xml);Person newJoe = (Person)xstream.fromXML(xml);System.out.println(newJoe.getFirstname();3.3 运行测试类运行上面的Main.java类，输出结果如下：3.4 代码解析下面主要对Main.java中的main方法进行详细地解析.XStream xstream = new XStream();直接实例化一个XStream对象，不用任何参数。这个时候XSteam内部会使用KXml2的解析工具。也就是上面添加的kxml2-2.3.0.jar包。如果不需要使用这个包的话，可以用JAXP的包等。例如：XStream xstream = new XStream(new DomDriver(); XStream xstream = new XStream(new StaxDriver();继续下面的代码：xstream.alias(person, Person.class);xstream.alias(phonenumber, PhoneNumber.class);这两句表示对于xml中的每个结点，所映射的Java类。也就是person结点映射到了Person类；而phonenumber则映射到了PhoneNumber类。下面是实例化对象之类的，比较简单，我们跳过去不将。直接进入：String xml = xstream.toXML(joe);这个就是核心所在，即将一个java对象转成了xml。继续下面的代码：Person newJoe = (Person)xstream.fromXML(xml);这个也是核心所在，将一个xml转成java对象。4 Alias机制XStream的Alias功能是很强大的，也是XStream开发中不可或缺的一个重点功能，下面将通过一些实例来讲解如何应用Alias机制4.1 默认情况，不使用Alias4.1.1 新建相关的java对象类分别新建下面的类package com.thoughtworks.xstream;import java.util.ArrayList;import java.util.List;public class Blog private Author writer; private List entries = new ArrayList(); public Blog(Author writer) this.writer = writer; public void add(Entry entry) entries.add(entry); public List getContent() return entries; package com.thoughtworks.xstream;public class Author private String name;public Author(String name) = name;public String getName() return name;package com.thoughtworks.xstream;public class Entry private String title;private String description;public Entry(String title, String description) this.title = title;this.description = description;4.1.2 建立测试代码如下：package com.thoughtworks.xstream;public class Main public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();System.out.println(xstream.toXML(teamBlog);运行这个主函数，输出结果如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 4.1.3 分析从这个例子看到，如果没有使用任何Alias的话，输出的XML中包含了类的全路径，包含package和class的名称。这一般来说，不是我们想要的结果，可能我们想要的结果是如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 4.2 对class进行alias修改上面的主函数，增加alias，如下：public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();xstream.alias(blog, Blog.class);xstream.alias(author, Author.class);xstream.alias(entry, Entry.class);System.out.println(xstream.toXML(teamBlog);运行，输出结果如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 4.3 对field进行alias从4.2中可以看到，我们可以对Class进行alias。Xstream除了可以对Class进行alias外，还可以对field进行alias。修改上述的main函数，如下：public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();xstream.alias(blog, Blog.class);xstream.alias(author, Author.class);xstream.alias(entry, Entry.class);xstream.aliasField(author, Blog.class, writer);System.out.println(xstream.toXML(teamBlog);运行上面结果，输出如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 4.4 隐含的Collections像上述中的xml，可以看到这个结点： first My first blog entry. 假如我们不需要其中这个结点，也就是想把结点去除，那么就可以使用其implicit collection功能。修改main函数，如下：public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();xstream.alias(blog, Blog.class);xstream.alias(author, Author.class);xstream.alias(entry, Entry.class);xstream.aliasField(author, Blog.class, writer);xstream.addImplicitCollection(Blog.class, entries);System.out.println(xstream.toXML(teamBlog);运行上面函数，输出结果如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 4.5 对package进行aliasXStream另外一个功能是对package进行alias，虽然这个功能比较少用。修改main函数，如下：public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();xstream.aliasPackage(pany, com.thoughtworks);System.out.println(xstream.toXML(teamBlog);运行以上结果，输出如下： Guilherme Silveira first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 5 Converter机制XStream提供了Converter，使我们在objectxml时，能对一些输入输出参数进行类型转换。5.1 简单介绍从上面的xml中看到,blog中有author子结点，看起来比较啰嗦，可能我们想把author子节点作为blog的属性，如下：那么就需要用到属性转换功能。增加AuthorConverter.java，代码如下：package com.thoughtworks.xstream;import com.thoughtworks.xstream.converters.SingleValueConverter;class AuthorConverter implements SingleValueConverter public String toString(Object obj) return (Author) obj).getName(); public Object fromString(String name) return new Author(name); public boolean canConvert(Class type) return type.equals(Author.class); 然后修改主函数，如下：package com.thoughtworks.xstream;public class Main public static void main(String args) Blog teamBlog = new Blog(new Author(Guilherme Silveira);teamBlog.add(new Entry(first, My first blog entry.);teamBlog.add(new Entry(tutorial,Today we have developed a nice alias tutorial. Tell your friends! NOW!);XStream xstream = new XStream();xstream.alias(blog, Blog.class);xstream.alias(author, Author.class);xstream.alias(entry, Entry.class);xstream.aliasField(author, Blog.class, writer);xstream.addImplicitCollection(Blog.class, entries); xstream.useAttributeFor(Blog.class, writer); xstream.aliasField(author, Blog.class, writer); xstream.registerConverter(new AuthorConverter();System.out.println(xstream.toXML(teamBlog);运行上面，输出如下： first My first blog entry. tutorial Today we have developed a nice alias tutorial. Tell your friends! NOW! 5.2 对象转换器ObjectConverter下面讲解ObjectConverter实例。新建如下两个类package com.thoughtworks.xstream.examples;public class Person private String name; public String getName() return name; public void setName(String name) = name; package com.thoughtworks.xstream.examples;import com.thoughtworks.xstream.XStream;public class PersonTest public static void main(String args) Person person = new Person();person.setName(Guilherme);XStream xStream = new XStream();xStream.alias(person, Person.class);System.out.println(xStream.toXML(person);运行以上主函数，输出结果如下： Guilherme现在假如我们需要输出如下的结果： Guilherme那么最简单的办法就是使用aliasFiled方法，如下：package com.thoughtworks.xstream.examples;import com.thoughtworks.xstream.XStream;public class PersonTest public static void main(String args) Person person = new Person();person.setName(Guilherme);XStream xStream = new XStream();xStream.alias(person, Person.class);xStream.aliasField(fullname, Person.class, name);System.out.println(xStream.toXML(person);但是，下面我们将通过ObjectConverter实现上面的功能。新建一个PersonConverter类，代码如下：package com.thoughtworks.xstream.examples;import com.thoughtworks.xstream.converters.Converter;import com.thoughtworks.xstream.converters.MarshallingContext;import com.thoughtworks.xstream.converters.UnmarshallingContext;import com.thoughtworks.xstream.io.HierarchicalStreamReader;import com.thoughtworks.xstream.io.HierarchicalStreamWriter;public class PersonConverter implements Converter public boolean canConvert(Class clazz) return false;public void marshal(Object value, HierarchicalStreamWriter writer,MarshallingContext context) public Object unmarshal(HierarchicalStreamReader reader,UnmarshallingContext context) return null;然后修改canConvert(Class clazz)方法，如下：public boolean canConvert(Class clazz) return clazz.equals(Person.class);这段代码告诉XStream，对于Person.class类型，可以使用PersonConverter，其它类型的Class则不允许使用这个Converter。修改marshal方法，代码如下：public void marshal(Object value, HierarchicalStreamWriter writer, MarshallingContext context) Person person = (Person) value; writer.startNode(fullname); writer.setValue(person.getName(); writer.endNode();当通过了canConvert方法的判断后，就进入marshal方法。上面这段代码告诉XStream，输出xml的writer从fullname结点开始写，然后读取person的值，作为fullname结点的值。继续修改unmarshal方法，代码如下： public Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context) Person person = new Person(); reader.moveDown(); person.setName(reader.getValue(); reader.moveUp(); return person; 顾名思义，unmarshal是在将xml转换成object时调用到，这段代码告诉了XStream，当遇到Person.class时，reader的指针到下一个结点，然后读取结点的值。然后返回到父结点。最后完成的PersonConverter.java代码如下：package com.thoughtworks.xstream.examples;import com.thoughtworks.xstream.converters.Converter;import com.thoughtworks.xstream.converters.MarshallingContext;import com.thoughtworks.xstream.converters.UnmarshallingContext;import com.thoughtworks.xstream.io.HierarchicalStreamReader;import com.thoughtworks.xstream.io.HierarchicalStreamWriter;public class PersonConverter implements Converter public boolean canConvert(Class clazz) return clazz.equals(Person.class);public void marshal(Object value, HierarchicalStreamWriter writer,MarshallingContext context) Person person = (Person) value;writer.startNode(fullname);writer.setValue(person.getName();writer.endNode();public Object unmarshal(HierarchicalStreamReader reader,UnmarshallingContext context) Person person = new Person();reader.moveDown();person.setName(reader.getValue();reader.moveUp();return person;最后，我们修改PersonTest的主函数，添加PersonConverter，如下：public static void main(String args) Person person = new Person();person.setName(Guilherme);XStream xStream = new XStream();xStream.alias(person, Person.class);xStream.registerConverter(new PersonConverter();System.out.println(xStream.toXML(person);运行，输出结果如下： Guilherme5.3 日期转换下面将实现另外一个例子，对日期格式进行转换。新建DateConverter.java，代码如下：package com.thoughtworks.xstream.examples;import java.text.DateFormat;import java.text.ParseException;import java.util.Calendar;import java.util.Date;import java.util.GregorianCalendar;import java.util.Locale;import com.thoughtworks.xstream.converters.ConversionException;import com.thoughtworks.xstream.converters.Converter;import com.thoughtworks.xstream.converters.MarshallingContext;import com.thoughtworks.xstream.converters.UnmarshallingContext;import com.thoughtworks.xstream.io.HierarchicalStreamReader;import com.thoughtworks.xstream.io.HierarchicalStreamWriter;public class DateConverter implements Converter private Locale locale; public DateConverter(Locale locale) super(); this.locale = locale; public boolean canConvert(Class clazz) return Calendar.class.isAssignableFrom(clazz); public void marshal(Object value, HierarchicalStreamWriter writer, MarshallingContext context) Calendar calendar = (Calendar) value; Date date = calendar.getTime(); DateFormat formatter = DateFormat.getDateInstance(DateFormat.FULL, this.loca