java castor_Castor功能与应用参考二
索引
2.1概述
1.示例需求
在运行下文中讲述的示例时，用户需要预先做一些准备工作。用户可以从castor网站上获取最新1.1.2.1版本包括castor-1.1.2.1.zip和castor-1.1.2.1-examples.zip解压到本地目录，在Eclipse中构建一个Java项目。然后将解压目录中的castor-1.1.2.1.jar，lib目录下的commons-logging-1.1.jar，log4j-1.2.13.jar和xerces-J_1.4.0.jar添加到项目的类路径中。
2.Castor XML映射概念
Castor XML 通过Mapping定义的方式简化了Java类和XML文档之间的绑定。尽管可以使用Castor默认的自省方式编组和解编Java对象，但是对于复杂的映射绑定，Mapping定义提供了更加细致的控制。同时，Mapping文件可以在一定程度上解耦合Java对象模型与XML文档，从而避免各自的变化给对方带来的影响。
2.1概述
Mpping文件本身也以XML文档格式定义。Mapping文档以Java对象模型为视角，用于描述Java对象如何映射为XML文档节点，Java对象中的字段属性如何映射为XML文档节点中的子节点或属性。
如上图所示，在Castor中，一个Java类映射为一个XML节点，Java类中的属性字段映射为XML节点下的子节点或者属性。描述上述映射的Mapping文件如下所示：
/p>
"http://castor.org/mapping.dtd">
Description of the mapping
2.2编组过程
在Castor中，一个Java类必须映射为一个XML节点。当Castor编组一个Java对象的过程如下：首先，如果存在映射信息，从映射信息中确定该对象所对应的XML节点名称；如果不存在映射信息，则使用对象的类名作为XML节点名。然后，使用映射文件中字段的映射信息确定Java对象中的一个字段属性如何转换为XML文档中的如下几种存在：
一个属性
一个节点
一个节点的文本
忽略(在映射文件中可以设定不编组某一字段属性，Castor将忽略该字段)
Castor遍历整个Java对象，如果发现一个Class类型的属性，则查找Mapping文件中的节点定义。
如果在Mapping文件中找不到一个类的对应信息，默认情况下，Castor会分析这个类的元数据，采用一组默认的规则来定义要编组的字段属性所映射的XML文档元素。默认规则如下：
所有原始数据类型，包括原始数据类型的对象封装类型(如Boolean，Short等)都编组为XML节点属性；
所有其他对象类型都编组为文本或者节点；
2.3解编过程
在解编过程中，当Castor查找到一个XML文档节点时，Castor首先查找映射信息来决定如何解编XML文档为Java对象。如果不存在映射信息，Castor会使用XML节点的名称决定如何构建类(Class)实例，例如，如果节点的名称为”test-element”，在Mapping文件不存在时，Castor将构建一个名称为”TestElement”的类。然后，Castor根据映射文件中关于字段属性的映射信息处理该XML文档节点下的内容。
3.映射文件定义详解
3.1Mapping文件的根节点
如上例XML Mapping文件所示，Mapping文件的根节点为。节点的Xml Schema定义为：
节点下的节点包括：
一个节点，可选的，用于添加描述信息
一个或多个节点，用于引用其他的映射文件
一个或多个节点，用于描述每一个定义Mapping的Java类
一个或多个节点，该节点在Castor JDO中使用，后续文档将详细解释
Mapping文件举例如下：
/p>
"http://castor.org/mapping.dtd">
Description of the mapping
.........
.........
3.2节点定义
节点的Schema定义如下：
节点包含了Java类与XML文档之间映射的所有信息。其中，详细描述了Java类中各个字段属性与XML文档元素的映射。
3.2.1节点的属性
Øname:映射的Java类名称，使用类的全名，如”com.acme.MyClass”。
Øextends:只有在该类扩展其他类时，使用该参数指定扩展的类。如果被扩展的类未在该Mapping文件中指定，则不能使用该属性。
Ødepends:在Castor JDO中指明类之间的依赖关系，用于表示数据库表中关联表的概念。
Øauto-complete:如果该属性值为”true”，则Castor在处理该类时首先采用自省的方式决定该类的字段属性，然后使用Mapping文件中对该字段属性的设定覆盖自省方式的操作。auto-complete属性可以让Castor的默认自省处理方式与Mapping定义方式很好的结合，从而降低对包含很多字段的类进行复杂的设定操作。
Øidentity:在Castor JDO中使用，用于描述该类实例的主键字段，详细信息参考Castor JDO部分。
Øaccess:在Castor JDO中使用，详细信息参考Castor JDO部分。
Økey-generator:在Castor JDO中使用，详细信息参考Castor JDO部分。
3.2.2节点的子节点
Ødescription：可选的属性，用于对该类添加描述性信息
Øcache-type:只在Castor JDO中使用，详细信息参考Castor JDO部分。
Ømap-to:可选属性，如果XML中节点名称与类(Class)名称不同，则使用该节点设定。默认的，Castor会自动分析XML节点名称和类名称之间的映射，如对于Java类”XxxYyy”，Castor会自动映射为XML节点”xxx-yyy”。如果用户不希望Castor自动生成该名称，则可以使用节点来指定XML映射名称。注意：仅用于XML文档中的根节点。
Øfield：节点下包含零个或多个节点。每个节点用于描述Java类中的一个字段属性。
映射举例
下面的例子将Java类MyClass映射为XML文档中的节点’’:
package mypackage
public class MyClass {
public int foo;
public String getBar() { ... }
public void setBar(String bar) { ... }
}
如果用户希望输出的XML文档格式如下：
...
则用户需要以如下方式设定Mapping映射文件：
...
...
3.3节点定义
节点的Schema定义如下：
节点用于指定给定Java类与XML文档节点的映射。节点只用于XML文档根节点，如果该节点未在Mapping文件中设定，则Castor采用如下处理策略：
Ø在编组过程中，通过Java类名称命名XML文档根节点名，如Java类”XxxYyy”映射为XML节点”xxx-yyy”
Ø在解编过程中，通过XML文档根节点名称确定Java类名称，如XML节点”test-element”映射为Java类”TestElement”
用户可以在castor.properties中指定Castor在Java类名称与XML文档节点名之间的转换策略。节点的属性包括：
Øxml：类映射的XML节点名称Java
Øns-uri:XML节点的名称空间URI
Øns-prefix:XML节点的名称空间前缀
Øelement-definition:True if the descriptor as created from a schema definition that was of type element (as opposed to a definition). This only is useful in the context of source code generation
Øldap-dn:在Castor XML中不使用该属性
Øldap-oc:在Castor XML中不使用该属性
3.4< field>节点定义
< field>节点的Schema定义如下：
节点用于描述如何编组/解编Java对象中的字段属性。Castor可以从节点描述中的”name”属性确定Java字段的名称；可以从节点描述中的”type”和”collection”属性确定Java字段的类型；可以从节点描述中的”direct”，”get-method”和”set-method”属性确定Java字段的访问方法。通过上述信息，Castor能够操作Java类中的字段属性。
Castor通过以下两个规则来判定某一字段的类型签名：
检查节点中的“类型”属性(”type”和”collection”)
如果节点中没有”collection”属性，”type”属性指定的类型即为该字段的Java类型。”type”属性值既可以是Java对象类型的全限定名(包含包名称)，也可以是Castor定义的一系列简称。Castor支持的类型简称列表如下：
简称
原始类型
Java类型
other
N
java.lang.Object
string
N
java.lang.String
integer
Y
java.lang.Integer
long
Y
java.lang.Long
boolean
Y
java.lang.Boolean
double
Y
java.lang.Double
float
Y
java.lang.Float
big-decimal
N
java.math.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
bytes[]
chars
N
char[]
strings
N
string[]
loacle
N
java.util.Locale
Castor会自动将XML文档中的节点内容自动转换为上述Java对象类型。如果设定了”collection”属性，collection属性值遵从下面的对象对象列表：
简称
原始类型
Java类型
array
[]
[]
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集合中的对象为Java类型。对于Hashtable和Map类型的对象，Castor同时存储其键和值。对于其映射，可以使用org.exolab.castor.mapping.MapItem类通过顶层(相对于嵌套类映射)类映射定义和嵌套类映射定义来描述。
检查节点中的“签名”属性(”direct”,”set-method”和”get-method”)
如果”direct”属性设定为true，则在Java类定义中，该字段必须具有如下的声明：
public ;
如果”direct”属性设定为false或者该属性被忽略，Castor会通过该属性的存取方法访问该属性。首先，若设定了'get-method'或'set-method'，Castor会访问如下方法签名：
public ();
或
public void ( value);
若没有设定'get-method'或'set-method'属性，Castor会尝试访问如下签名方法：
public get();
或
public void set( value);
是指Castor检查属性值，将其首字母转换为大写，其他字符保持不变。
collection字段属性处理的例外情况
在默认情况下，’get-method’属性返回集合字段实例，’set-method’属性设定集合字段实例。特例情况如下表所示：
'get-method'
If a 'get-method' is provided for a collection field, Castor - in adition to the default behaviour described above - will deviate from the standard case for the following special prefixes:
public Iterator iterate...();
A 'get-method' starting with the prefix 'iterate' is treated as Iterator method for the given collection field.
public Enumeration enum...();
A 'get-method' starting with 'enum' is treated as Enumeration method for the given collection field.
'set-method'
If 'set-method' is provided for a collection field, Castor - in addition to the default behaviour described above - will accept an 'add' prefix and expect the following signature:
public void add...( value);
This method is called for each collection element while unmarshalling.
3.4.1节点的属性
节点可以包含将Java字段映射为XML元素，数据库表列名称等信息。节点可配置的属性如下：
Øname:该属性是必须的，即使在该映射类中没有该字段属性。如果配置了”direct”属性，”name”属性值必须是映射对象中的一个public字段(该字段必须是public，非static和非transient的类型)。如果没有”direct”和”get-/set-method”属性设定，“name”属性值对应的字段通过该值确定其访问方法(采用Java Bean规范)。
Øtype:该字段属性的Java类型。Castor使用该信息将XML信息转换为Java对象信息(如将字符串转换为整型)，定义该字段访问方法的签名。如果设定了”collection”属性，该属性信息用于指定集合中对象的类型信息。
Ørequired:在编组和解编过程中，该字段是否可选，默认值为false。
Øtransient:如果设定为”true”，该字段在处理过程中将被忽略。
Ødirect:如果为true，该字段在Java类定义中必须是public类型。
Øcollection:如果该字段存在多个，则Castor使用该属性的设定来处理他们。该类型用于定义对应Java类中集合的类型。
Øget-method:可选配置，”name”属性对应Java类字段的访问方法，具体使用参考前文描述。
Øset-method:可选配置，”name”属性对应Java类字段的访问方法，具体使用参考前文描述。
Øcreate-method:工厂方法，用于构建FieldHandler实例。
3.4.2节点的子节点
在XML Mapping中，节点的子节点仅包含一个节点，用于描述如何将该字段属性映射到XML文档元素。
Castor自0.9.5版本以后，支持将一个节点映射为该字段所属Java类构造函数的参数，这种机制通过”set-method”属性来实现。如果需要设定一个字段作为该类对象初始化时构造函数的一个参数，可以设定该字段在Mapping文件中节点的”set-method”属性为”1%”-“9%”。 ”1%”表示构造函数的第一个参数，依次类推。这种机制举例如下：
假定存在如下所示的Java类Foo，Foo类除了具有一个默认的构造函数外，还有一个具有参数的构造函数。
public class Foo {
private int size = 20;
public Foo() { }
public Foo(int size) {
this.size = size;
}
public int getSize() {
return size;
}
public void setSize(int size) {
this.size = size;
}
}
如果用户希望在实例化Foo类时，调用Foo类具有参数的构造函数而不是默认无参构造函数，则通过设定如下的映射文件实现。
Mapping文件中的setMethod=”1%”的设定，会告诉Castor在实例化Foo类时，使用size属性字段作为构造Foo(int)的参数。
注意：如果设定了”set-method”属性，则”get-method”属性也必须设定。
3.5节点定义
节点的用于描述Java字段如何在XML文档中映射展现。在编组和解编过程中均要使用。
节点的Schema定义如下：
3.5.1节点的属性
Øname:XML节点或属性的名称。注意：该属性值必须是QName，可以使用名称空间前缀来表明该节点或属性所属的特定名称空间，该前缀在编组过程中并不保留或使用，只是用来保持文档的格式良好。
Øauto-naming:如果未设定name属性，auto-naming属性用于提示是否Castor自动为该字段构建相应的名称。通常情况下，使用节点中的name属性值作为XML元素的名称。
Øtype: 该节点在XML文档中的 Schema类型，Castor编组框架使用该属性确定对XML节点的处理方式。如”QName”。
Ølocation:允许用户设定XML文档中 “间接路经”上的节点作为该Java字段属性的映射(如该字段所属类的XML节点映射为“AAA”，该节点的名称为“TTT”，但不是“AAA节点的子节点”，而是“AAA”节点的子节点“BBB”节点的子节点，则可以使用location属性映射为XML文档中的“AAA/BBB/TTT”。详细信息参看下述“Loaction属性简介”。
ØQName-prefix:如果该字段对应XML文档节点中的一个QName值，则可以使用该属性设定其前缀。详细信息参考“Castor源代码自动生成章节”。
Øreference:在解编该字段时，指明该字段是否看作一个对象引用。
Ømatches:允许覆盖节点名称的匹配规则。该属性值是一个标准的正则表达式，用于替代”name”属性。如果值为”*”，则可以匹配任何XML节点名称，但是仅当不存在其他字段与XML节点名称匹配时，使用该匹配。
Ønode:表明该字段映射成为XML文档中的属性，节点还是文本元素。默认情况下，原始类型的字段映射成XML属性，其他的映射成为XML节点。
Øtransient:如果其值设定为true，则视该节点为临时的，不做处理。默认继承节点中transient属性值。
3.5.2中使用嵌套的类映射
Castor自0.9.5.3版本开始，节点支持嵌套的类映射定义。该功能在某个类映射信息需要在多个地方指定时非常方便，如映射Hashtable/HashMap/Map等集合类时的情况。具体使用参考下面的例子：
嵌套类举例
3.5.3location属性简介
节点中的location属性允许用户将字段映射为XML文档中的内嵌节点或者在映射节点封装一个节点。封装节点只出现在XML文档结构中，与Mapping文件定义的Java对象没有直接映射关系。下面仍以Foo类为例，
public class Foo {
private Bar bar = null;
public Foo();
public getBar() {
return bar;
}
public void setBar(Bar bar) {
this.bar = bar;
}
}
我们希望将该类映射成为下面所示的XML文档(注：’abc’节点并不存在于Foo或者Bar类的定义中)
;
...
为实现上述映射，我们以如下方式定义Mapping文件
...
...
需要注意的是，“location”属性的值指定的是封装的节点的名称，如果希望封装多层节点，则节点名称之间使用”/”分隔，如下例所示：
此外，用户还需要注意的是，节点中的属性”name”指定的xml元素名称并不是“location”属性中指定的封装节点的一部分。同时，封装节点的父节点总是其所封装字段所在类对象映射的节点。“location”属性同样可以封装XML属性元素，如下所示的映射定义：
生成的XML文档为：
;
4.映射文件使用举例
下面我们以一个完整的例子，说明如何使用Castor的Mapping映射文件实现Java类与XML文档之间的相互转换。
首先，我们定义一个名为”order.xml”的数据文件，我们用这个XML文件描述一个订单，该订单中包含这个订单的客户信息，以及客户在此订单中所订购的货物。一个订单中可以存在多个货物。
order.xml
Jean Smith
2000, Alameda de las Pulgas, San Mateo, CA 94403Stuffed Penguin
10
8.95
Chocolate
5
28.50
Cookie
30
0.85
我们要为该订单定义三个Java类，分别描述该订单，订单的客户和货物。
ØMyOrder：代表该订单
ØClientData：代表订单的客户
ØItem：代表订单中的一项货物
这三个Java类的代码如下所示：
MyOrder.java
importjava.util.Vector;
importjava.util.Enumeration;
publicclassMyOrder {
privateString_ref;
privateClientData _client;
privateVector_items;
privatefloat_total;
publicvoidsetReference(String ref) {
_ref= ref;
}
publicString getReference() {
return_ref;
}
publicvoidsetClientData(ClientData client) {
_client = client;
}
publicClientData getClientData() {
return_client;
}
publicvoidsetItemsList(Vector items) {
_items= items;
}
publicVector getItemsList() {
return_items;
}
publicvoidsetTotal(floattotal) {
_total= total;
}
publicfloatgetTotal() {
return_total;
}
// Do some processing on the data
publicfloatgetTotalPrice() {
floattotal = 0.0f;
for(Enumeration e =_items.elements(); e.hasMoreElements();) {
Item item = (Item) e.nextElement();
total += item._quantity * item._unitPrice;
}
returntotal;
}
}
ClientData.java
publicclassClientData {
privateString_name;
privateString_address;
publicvoidsetName(String name) {
_name= name;
}
publicString getName() {
return_name;
}
publicvoidsetAddress(String address) {
_address= address;
}
publicString getAddress() {
return_address;
}
}
Item.java
publicclassItem {
publicString_reference;
publicint_quantity;
publicfloat_unitPrice;
publicString_description;
}
现在，我们有了预期的XML文档定义，也有了描述文档的Java类定义。下一步，我们定义XML文档与Java类之间的映射。在下面的mapping.xml文件中，我们定义了三个类MyOrder、ClientData和Item的映射。
mapping.xml
/p>
"http://castor.org/mapping.dtd">
具备上述资源后，我们通过下面的Java代码测试Castor通过Mapping映射文件来实现XML文档与Java对象间的相互转换。
main.java
importorg.exolab.castor.mapping.Mapping;
importorg.exolab.castor.xml.Unmarshaller;
importorg.exolab.castor.xml.Marshaller;
importjava.io.FileReader;
importjava.io.OutputStreamWriter;
importorg.xml.sax.InputSource;
publicclassMain {
publicstaticvoidmain(String args[]) {
Mapping mapping =newMapping();
try{
// 1.从Mapping.xml文件中加载映射信息
mapping.loadMapping("mapping.xml");
// 2.解编order.xml文档，构造java对象
Unmarshaller unmar =newUnmarshaller(mapping);
MyOrder order = (MyOrder) unmar.unmarshal(newInputSource(
newFileReader("order.xml")));
// 3.调用Java类MyOrder的对象实例方法，修改该对象实例
floattotal = order.getTotalPrice();
System.out.println("Order total price = "+ total);
order.setTotal(total);
// 4.将修改后的对象实例重新编组为XML文档并输出到控制台
Marshaller marshaller =newMarshaller(newOutputStreamWriter(
System.out));
marshaller.setMapping(mapping);
marshaller.marshal(order);
}catch(Exception e) {
System.out.println(e);
return;
}
}
}
用户可以比较原来的order.xml文档与输出到控制台的XML文档数据的差别，从而体会Castor XML编组框架的功能。
posted on 2007-11-28 11:42 IT扁担 阅读(2636) 评论(0) 编辑 收藏 所属分类: 开源框架