Castor XML 映射文件

概述：
Castor 映射是一种隔离Java对象模型因XML文档格式变化而变化的好方法。

映射信息是由一个XML文档来指定的。这个从Java对象的角度来编写，描述了对象的属性如何转换到XML。映射文件的一个约束是，Castor应该能够在解组时无疑议地把给定的XML元素、属性转换到对象模型。

映射文件描述了每个对象的每个字段如何映射到XML。字段是对象属性的抽象。它可以直接等价于一个公有的类变量或简介等价于一个属性，通过获取器方法（setter和getter）。

可以混合使用映射和Castor默认行为：当Castor处理一个对象或XML数据，但找不到有关信息时，它将依赖它的默认行为。Castor将使用Java反射API来内审Java对象来决定做什么。

注意：Castor不能处理所有可能的映射。在一些复杂的情况下，它可能需要依赖一个XSL转换来以更友好的格式生成XML文档。


编组行为：
对于Castor，一个Java类映射为一个XML element。编组一个对象时：
使用任何的映射信息来查找要创建的element的名字，或者；默认地，使用类名作为element名字。
使用映射文件里的fields信息来决定一个对象的给定属性转换到下列中的一种，且仅一种：
一个属性；
一个元素；
文本内容；
空，如果选择忽略一个特定的field。

这种处理是递归的：如果Castor找到一个属性的类型是任何其他映射文件里指定的，它将使用这个信息来编组对象。

默认地，如果Castor没有找到映射文件里类的映射信息，将内省（introspect ）类，应用默认的规则来猜测字段，编组它们。默认的规则是：
A．所有基本类型和它们的包装类型编组为属性；
B．所有的对象类型编组为元素，带有文本内容活元素内容。


解组行为：
当Castor解组文档时找到一个元素时，将尝试使用映射信息来决定实例化哪个对象。如果没有映射信息，Castor将使用元素名字来猜测要实例化的类名 (for example, for an element named 'test-element', Castor will try to instantiate a class named 'TestElement' if no information is given in the mapping file)。Castor将使用映射文件里的字段映射信息来处理元素内容。

如果类没有在映射文件里描述，Castor将使用Java 的反射内省类，来判断是否存在getter/setter。这些获取器与名为’xxx-yyy’ 的XML元素/属性。

如果没有获取器，Castor将直接获取，在这种情况下，Castor将查找公有域。



映射文件
<mapping>元素
<mapping>元素是映射文件的根元素，它包含：
A．一个可选的description元素；
B．零个或多个<include>机制来重用映射文件；
C．零个或多个<field-handler>来定义定制的、可配置的field处理器；
D．零个或多个<class>描述，每个类我们希望给出映射信息；
E．零个或多个<key-generator>，没有用于XML映射。

一个映射文件看起来是这样的：

<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Mapping DTD Version 1.0//EN"
castor.org
"http://castor.org/mapping.dtd">
<mapping>
<description>Description of the mapping</description>
<include href="other_mapping_file.xml"/>
<!-- mapping for class 'A' -->
<class name="A">
.........
</class>
<!-- mapping for class 'B' -->
<class name="B">
.........
</class>
</mapping>

<class>元素
<class>元素包含映射一个Java 类到XML的所有信息。<class>的内容主要用来描述映射的字段。
属性描述

属性名	描述
name	要映射的类的全限定类名
extends	父类的全限定类名。这个属性应该仅在这个类继承了其他类时使用。如果没有类映射到父类则不应该使用。
depends	用于JDO
auto-complete	如果为true，类将被内省，来确定属性，映射文件里的fields将覆盖内省发现的属性。
identity	JDO
access	JDO
key-generator	JDO

内容描述

description	可选的描述
cache-type	JDO
map-to	如果元素的名字不是类名时使用。默认地，Castor将元素名映射到类名：类名XxxYyy将被转换为xxx-yyyy。如果不希望Castor生成名字，使用<map-to>来指定你希望的名字。<map-to>只用于根元素。
field	零个或多个<field>元素，用于描述被映射Java 类的属性。

<class>元素的例子：

<class name="mypackage.OrderItem>
<map-to xml="item"/>
<field name="id" type="string">
<bind-xml name="identity" node="attribute"/>
</field>
</field name="orderQuantity" type="integer">
<bind-xml name="quantity" node="element"/>
</field>
</class>

<map-to>元素
<map-to>用于指定给定类关联的元素名。<map-to>只能用于根<class>，如果没有指定此元素，Castor将使用默认规则进行匹配。

属性

名字	描述
xml	类关联的元素的名字
ns-uri	命名空间的URI
ns-prefix	Desired namespace
Element-definition	True if the descriptor as created from a schema definition that was of type element (as opposed to a<complexType> definition). This only is useful in the context of source code generation.
ldap-dn	Not used for Castor XML
ldap-oc	Not used for Castor XML

举例：

<class name="myPackage.OrderItem">
...
<map-to xml="item" />
...
</class>

<field>元素
<field>用于描述希望编组或解组的Java 对象的属性。他包含：
标识（‘name’），类型（由type和collection推断）、获取方法（由‘direct’、‘get-method’,’set-method’推断）。

为了了确定Castor期望的签名，应用了两个简单的规则：
1.<type>决定。如果没有'collection'属性，type就仅仅是指定的Java类型。Type属性可以是全限定的Java 类名或预定义的简称。
类型名简称

简称	基本类型	Java类
other	N	java.lang.Object
string	N	java.lang.String
integer	Y	java.lang.Integer.TYPE
long	Y	java.lang.Long.TYPE
boolean	Y	java.lang.Boolean.TYPE
double	Y	java.lang.Double.TYPE
float	Y	java.lang.Float.TYPE
big-decimal	N	java.lang.BigDecimal
byte	Y	java.lang.Byte.TYPE
date	N	java.util.Date
short	Y	java.lang.Short.TYPE
char	Y	java.lang.Character.TYPE
bytes	N	byte[]
chars	N	char[]
strings	N	String[]
locale	N	java.util.Locale

2.如果指定了collectioin属性，使用下表

名字	类型	默认实现
array	<type_arrtibute>[]	<type_arrtibute>[]
arraylist	java.util.List	java.util.Arraylist
vector	java.util.Vector	java.util.Vector
hashtable	java.util.Hashtable	java.util.Hashtable
collection	java.util.Collection	java.util.Arraylist
set	java.util.Set	java.util.Hashset
map	java.util.Map	java.util.Hashmap
sortedset	java.util.SortedSet	java.util.TreeSet

Collection里对象的类型是<type-attribute>。默认实现是当对象不为空时用来持有集合的。
For hashtable and maps (since 0.9.5.3), Castor will save both key and values. When marshalling output <key> and <value> elements. These names can be controlled by using a top-level or nested class mapping for the org.exolab.castor.mapping.MapItem class.

当指定类型的元素多于一个时有必要使用集合。

内容描述
在XML映射的情景下，field的内容应该有且仅有一个<bind-xml>元素，描述一个给定的字段如何映射到XML文档。
1.映射构造函数的参数
2.定义定制的字段处理器
3.



Location属性
Location属性允许用户映射嵌套的元素或为给定的元素指定一个包装元素。包装元素是出现在XML实例的简单元素，不直接映射到对象或对象模型的字段。
例如，要映射的下面类的一个实例：

public class Foo {
private Bar bar = null;
public Foo();
public getBar() {
return bar;
}
public void setBar(Bar bar) {
this.bar = bar;
}
}

到这样的一个XML实例：

<?xml version="1.0"?>
<foo>;
<abc>
<bar>...</bar>
</abc>
</foo>

（注意abc不是Bar类的一个字段）应该使用下面的映射：

<?xml version="1.0"?>
...
<class name="Foo">
<field name="bar" type="Bar">
<bind-xml name="bar" location="abc"/>
</field>
</class>
...
</mapping>

注意lcation属性，这个属性的值是包装元素的名字。为了使用多于一个的包装元素，name用/分割：<bind-xml name="bar" location="abc/xyz" />

Note that the name of the element is not part of the location itself and that the location is always relative to the class in which the field is being defined. This works for attributes also:

<bind-xml name="bar" location="abc" node="attribute" />
will produce the following:
<?xml version="1.0"?>
<foo>
<abc bar="..."/>;
</foo>

完整的映射文件可参看 映射模式的示例。

欢迎关注我的微信公众号: coderbee笔记。