XBlink1.0.0版用户手册

公告:

由于googlecode的wiki编辑较为复杂，官网文档还需重新整理格式，这里先写一个1.0.0版的使用手册，让大家先了解下具体的使用。

 

用户API

 

对于XBlink作为普通用户只需要了解5或8个类即可，其他的都是内部使用，无需关心细节。

必备的：

两个核心类 XBlink.java XBConfig.java 

三个注解类 XBlinkAlias.java XBlinkAsAttribute.java XBlinkOmitField.java

XBlink

提供了序列化反序列方法，还有几个特殊的设置项。

 

PS：以下提及的输出指File，Ouputstream，Writer，输入指字符串，File，Inputstream，Readrer。

toXml

一种是只需一个参数（序列化的对象），结果返回对应XML字符串。

一种是需要两个参数（序列化的对象，输出），不再返回字符串，直接将结果写到输出。

fromXml

一种是只需一个参数（输入），根据输入将其提供的XML进行反序列化，返回对象。

一种是需要三个参数（输入，参考类，参考对象），其中参考类与参考对象可以二选其一，就是最终你想返回的类型是什么，你就放进去就好了，就会以此为依据，进行反序列操作，返回对象。

 

 

toAny 与 fromAny

这是一个扩展点，这个等后续版本实现了再详细讲解。

如果你特别想知道它能做什么

那么这样说吧，下面两个方法是等效的。

 

 

 

// 生成XML文件
XBlink.toXml(obj);

// 生成XML文件
XBlink.toAny(obj, "xml");

 

 

setGlobalXBConfig 与 setTransientXBConfig

设置运行时配置项，关于XBConfig请看后面介绍。

setGlobalXBConfig 是设置全局的，一直适用。

setTransientXBConfig 是设置一次性的，用过即抛，跟套套一个性质。

 

registerClassToBeUsed 与 registerClassesToBeUsed

注册你将要进行序列化的类。

如果不注册，XBlink是可以正常工作的，不过生成的XML会带有一部分类信息，看上去会不那么自然（怎么个不自然法你试一试便知），所以想要XML更合适阅读，推荐在一个static块中一次性注册所有可能要用的类。

例如：

 

static {
	// 注册一次即可
	Class<?>[] clzs = { Person.class, PhoneNumber.class };
	XBlink.registerClassesToBeUsed(clzs);
}

 

 

registerConverter

注册一个自定义转换器。

这个请参考后面的扩展点来理解。

 

XBConfig

提供了几个选项，可以设定你输出的文档一些特性。

newXBConfig

 

生成一个新的配置项。

setUseRelativePath

设置是否使用相对路径。默认是相对路径。

如果你序列化的类中存在循环引用的情况，那在写引用对象时，会输出类似下面这样一个节点。

 

<objA ref="../../objB/objA" />

 

 

 

ref记录的其相对当前节点的位置。

当然如果你设置使用绝对路径，那就会输入下面这样。

 

<objA ref="/objF/objE/objG/objB/objA" />

 

 

反正是可以帮你正确的找到引用对象的。

具体的实现思路可以看ME之前写的一篇文章。

 

setIgnoreTransient

是否忽略设置为transient类型的字段。

默认忽略，因为JAVA的序列化就是这样认为的。

忽略的意思就是序列化时无视它，不多解释了。

setIgnoreNull

是否忽略值为null的字段。

默认忽略，也就是不输出了，因为反序列化时它也是null，也不用设置回去。

当然如果你非要在XML显示的告诉你这里有个字段并且它是空，那你就设置一下好了。

setCompact

设置生成的文本是否采用紧凑模式。

默认为否，会采用更适合人类阅读的格式，也就是有换行，制表符等标识的文档。

如果设为true，那你就会得到仅一行的文档，当然它的体积会小很多，也会让反序列化更快，所以更适合用在生产环境中。

 

——————————————————

后续版本中这个类会提供更多的可配置项

XBlinkAlias

可以在类上或字段上设置别名。

至于效果直接看下面，事实胜于雄辩。

定义一个Child类：

 

@XBlinkAlias("孩子")
public class Child {

        @XBlinkAlias("姓名")
        private String name;

        @XBlinkAlias("年龄")
        private int age;

	// 省略构造器与其他方法
}

 

 

测试用例：

 

Child child = new Child();
child.setName("Tom");
child.setAge(10);

System.out.println(XBlink.toXml(child));

 

 

 

结果：

 

<?xml version="1.0" encoding="UTF-8"?>
<孩子>
    <姓名>Tom</姓名>
    <年龄>10</年龄>
</孩子>

 

 

效果很好，有木有！

 

 

XBlinkOmitField

 

忽略的字段，在字段上设置后，序列化时就会无视他，不解释了。

 

XBlinkAsAttribute

这个应该是XML格式特有的，在一个节点上加上属性。

就用上面那个Child做例子。

修改下：

 

@XBlinkAlias("孩子")
public class Child {

        @XBlinkAlias("姓名")
	@XBlinkAsAttribute
        private String name;

        @XBlinkAlias("年龄")
        private int age;

	// 省略构造器与其他方法
}

 

 

还是那个测试用例，直接看结果：

 

<?xml version="1.0" encoding="UTF-8"?>
<孩子 姓名="Tom">
    <年龄>10</年龄>
</孩子>

 

 

 

—————————邪恶的分割线———————

 

好了，只要你看懂了以上的内容，了解了这5个类的用法，XBlink在使用上90%的问题你已经可以自己解决了，是不是很简单很好用呢。

 

下面将讲解剩下的10%，也就是可以自由扩展的地方。

 

—————————邪恶的分割线———————

 

扩展API

 

一个注解类：XBlinkConverter.java

两个转换器基类：Converter.java SingleValueTypeConverter.java

 

 

XBlinkConverter

在字段上设置后，该字段在序列化时将采用你提供的转换器进行工作。

举个例子哈。

一个日期类型，默认的转换器，生成的格式是 yyyy-MM-dd HH:mm:ss

你希望能使用另一种格式，比如仅需要日期且年在最后位置，格式是MM-dd-yyyy

 

那么你就需要实现一个类，并且继承SingleValueTypeConverter

 

例如下面这样：

 

/**
 * 测试用的一个java.util.Date类型转换器。
 * 
 * @author 胖五([e-mail])
 */
public class MyDateConverter extends SingleValueTypeConverter {

	private static final String DATA_FORMAT_TEMPLATE = "MM-dd-yyyy";

	public Class<?>[] getTypes() {
		return new Class<?>[] { Date.class };
	}

	public boolean canConvert(Class<?> type) {
		return Date.class == type;
	}

	public String obj2Text(Object obj) throws Exception {
		SimpleDateFormat dateFormat = new SimpleDateFormat(DATA_FORMAT_TEMPLATE);
		return dateFormat.format(obj);
	}

	public Object text2Obj(String text) throws Exception {
		SimpleDateFormat dateFormat = new SimpleDateFormat(DATA_FORMAT_TEMPLATE);
		return dateFormat.parseObject(text);
	}

}

 

这样要说下前面的XBlink.registerConverter这个方法。

如果你仅仅想在某个日期上使用自定义格式，那么就加注解就可以了

如果你觉得默认的你想替换掉，所有有日期的地方都用你的格式，那就调用XBlink.registerConverter，它会根据替换掉默认实现。

 

也就是一个控制局部，一个控制全局，任君调遣。

 

 

Converter 与 SingleValueTypeConverter

 

这两个类，你简单看下估计就会明白了。

 

/**
 * 转换器，提供对象<--->文字相互转换的功能。
 * 
 * 注意，这里只负责两者的转换，不要加入输出等操作。
 * 
 * @author 胖五([e-mail])
 */
public interface Converter {

	/**
	 * 返回当前转换器可以处理的对象类型。
	 * 
	 * @return class对象
	 */
	public Class<?>[] getTypes();

	/**
	 * 是否可以转换这种类型。
	 * 
	 * @param type
	 *            类类型
	 * @return 能否成功
	 */
	public boolean canConvert(Class<?> type);

	/**
	 * 是单值类型吗?
	 * 
	 * @return 判断结果
	 */
	public boolean isSingleValueType();

	/**
	 * 将对象转换为文字格式的值。
	 * 
	 * @param obj
	 *            转换对象
	 * @throws Exception
	 *             异常
	 * @return 字符结果
	 */
	public String obj2Text(Object obj) throws Exception;

	/**
	 * 将文字格式的值转换为对象。
	 * 
	 * @param text
	 *            文字格式的值
	 * @throws Exception
	 *             异常
	 * @return 对象
	 */
	public Object text2Obj(String text) throws Exception;

}

 

 

/**
 * 单值类型的共同基类。
 * 
 * @author 胖五([e-mail])
 */
public abstract class SingleValueTypeConverter implements Converter {

	public boolean isSingleValueType() {
		return true;
	}

}

 

再结合下上面的MyDateConverter，相信你一定明白它的作用。

其实本来还提供一个FormValueTypeConverter类，也就是说可以在里面设置格式的转换器，这个更强大，但也更加难以控制，所以当前版本并没有开放出来，等后续版本有了好的解决方案再开放给大家。

 

 

—————————邪恶的分割线———————

以上就是ME现在能想到的基本用法了，基本上遵循着简单易用的原则来搞的，希望大家喜欢。

还有就是什么对象可以进行序列化，由于时间紧，默认提供的转换器还不够全面，所以有些类型会报错，不过如果你看懂了上面的自定义转换器这节，相信你可以自己解决的。

目前的版本，可以序列化java中常见的类（String，Date等），八种基本类型，枚举类型，一维数组（多维暂时不支持），List，Set，Map。

也就是说对简单的应用应该是富富有余了。

其他的想起什么再补充吧，欢迎提问或提出意见。

评论

15 楼 han0917 2013-12-09  

问下把对象某属性A设置为""，即空串，序列化后xml显示为<A />，有没有办法显示成<A></A>

14 楼 Matol 2013-05-04  

初试了一下，还是很惊喜的。毕竟，程序员最清楚自己需要怎样的工具。
同时呢，还发现了一些问题，希望，能够更加完善，也是必备的功能。

1，文件的连缀用法。比如我用该工具将一个objec生成到了xml文件，然后，又用该工具获取到这个xml文件，再次写入另一个object对象。P：需求是写入的新object，追加在已有的xml文件相应节点之下，而不是重新替换了xml文件。

2，xml文件内容中的object对象，toList<Object> 到java

3,

13 楼 riosk 2012-05-30  

楼主：请问是否可以生成如下形式XML.

<?xml version="1.0" encoding="UTF-8"?> 
<姓名>Tom</姓名>
<年龄>10</年龄>

没有了<孩子>

12 楼 riosk 2012-05-30  

// 生成XML文件  
XBlink.toXml(obj);

11 楼 shenldz 2011-11-29  

楼主，您好。

在使用过程中发现一个问题，重现步骤如下：

1、建立两个javabean类：AXmlBean,BXmlBean, 使它们有相同的别名。

2、使用XBlink.registerClassesToBeUsed(Class<?>[])注册这两个类，注册的时候按顺序AXmlBean, BXmlBean。

3、使用XBlink.fromXml(CharSequence)，根据String得到AXmlBean。此时会抛NullPointException。

Debug了一下，发现原因是由于AXmlBean,BXmlBean两者的别名相同，所以在注册时，放置类对象的map，由于key值是别名的String，所以对注册多个相同别名的javabean而言，最后注册的在该map中会覆盖掉前面的那些。我现在换成使用方法XBlink.fromXml(CharSequence, Class<?>, Object<?>)，每次转换的时候指定被转换的类型。

请问下楼主，这个是我使用不当造成的问题，还是一个需要改进的bug。。。>_<，望答复。

另外，非常感谢楼主编写这个框架，并公开源码。。。祝新年快乐（虽然有点早。。。）

10 楼 鱼乐 2011-10-25  

请问如何闭合标签，
默认生成如下：
<?xml version="1.0" encoding="UTF-8"?>
<孩子 姓名="Tom">
</孩子>

是否可以设置生成如下形式：
<?xml version="1.0" encoding="UTF-8"?>
<孩子 姓名="Tom"/>

9 楼 sourceforge 2011-10-19  

JSON的版本有吗？

8 楼 yin_bp 2011-10-13  

引用

多维暂时不支持

楼主做好还是要支持多维数组啊，毕竟多维数组也是比较常用的数据类型哦，像bboss，xstream都是支持任意类型多维数组序列化/反序列化操作的。另外bboss还能够很好地支持File（二进制文件，文本文件）的序列化\反序列化操作，不知道xblink支持不。

7 楼 pangwu86 2011-10-10  

giianhui 写道

麻烦补充一下下载地址。

请看这里http://www.iteye.com/news/22986
最下面有下载地址

6 楼 giianhui 2011-10-10  

麻烦补充一下下载地址。

5 楼 pangwu86 2011-10-10  

yanweimin7 写道

能否添加将对象序列化为objectoutputstream导出的那样的格式的实现

objectoutputstream的话，定义的对象类必须实现java.io.Serializable接口
也就是JAVA序列化的工作了，跟XBlink的目标不一致。

XBlink序列化的结果，是可以让人阅读的文本格式，非二进制文本。

4 楼 yanweimin7 2011-10-10  

能否添加将对象序列化为objectoutputstream导出的那样的格式的实现

3 楼 pangwu86 2011-10-10  

pangwu86 写道

zozoh 写道

找时间，考虑写个 XIocLoader ......  

啥东东

哦，看明白了，呵呵

2 楼 pangwu86 2011-10-10  

zozoh 写道

找时间，考虑写个 XIocLoader ......  

啥东东

1 楼 zozoh 2011-10-10  

找时间，考虑写个 XIocLoader ......