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 胖五(pangwu86@gmail.com)
 */
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 胖五(pangwu86@gmail.com)
 */
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 胖五(pangwu86@gmail.com)
 */
public abstract class SingleValueTypeConverter implements Converter {

	public boolean isSingleValueType() {
		return true;
	}

}

 

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

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

 

 

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

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

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

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

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

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