本文是對Java Web Service Development Pack 2.0中JAXB部分的翻譯，如有轉載，請聲明！
Java Architecture for XML Binding README
Specification Version:2.0
Reference Implementation(RI) Version:2.0 ea3
JAXB提供了自動(dòng)映射XML文檔和Java對象的API和工具。
JAXB框架可以完成下面的操作：
® 將XML內容Unmarshal成Java表示
® 訪(fǎng)問(wèn)和更新Java表示
® 將XML內容的Java表示Marshal成XML內容
JAXB提供了XML和Java代碼之間的高效并且標準的映射。Java開(kāi)發(fā)人員可以使用JAXB來(lái)簡(jiǎn)化開(kāi)發(fā)，提高效率，因為使用JAXB可以寫(xiě)很少的代碼，并且不需要很精通XML。JAXB使得開(kāi)發(fā)人員可以很容易的使用XML和Web Service技術(shù)來(lái)擴展應用程序。
1. Release Notes JAXB Reference Implementation需要運行在J2SE 5.0或者更高的Java平臺上。需要的JAR文件如下：
2.0運行環(huán)境：為Deploy JAXB2.0客戶(hù)端所需要的JAR文件包括jaxb-api.jar,jaxb-impl.jar,jsr173-1.0_api.jar
1.0運行環(huán)境：為Deploy JAXB1.0客戶(hù)端所需要的JAR文件包括2.0運行環(huán)境+jaxb1-impl.jar
2. XJC工具 雖然在筆者的其他文章中，包含了關(guān)于XJC腳本文件的使用，但是為了保持文章的完整性，將XJC腳本的內容再次追加在本文中。
綁定schema表示生成一系列的Java類(lèi)，這些java類(lèi)表示了schema。所有的JAXB實(shí)現都提供了一個(gè)工具叫做綁定編譯器來(lái)將一個(gè)schema綁定。例如，JAXB參考實(shí)現提供了一個(gè)綁定編譯器，允許通過(guò)腳本來(lái)執行(shell/bat)。假設需要將books.xsd文件進(jìn)行綁定，并且假設是工作與*nix系統，那么綁定的命令如下：
xjc.sh -p test.jaxb books.xsd -d work
選項說(shuō)明：
-p:指定生成的類(lèi)的包名
-d:指定存放類(lèi)的目標目錄
(譯者注：其實(shí)綁定schema還有其他的選項和方法，例如Eclispe的xjc插件等)
C:\Documents and Settings\hp3643>xjc --help
Usage: xjc [-options ...] <schema file/URL/dir> ... [-b <bindinfo>] ... Options:
-nv : 不進(jìn)行輸入schema的嚴格檢查，默認情況下，XJC會(huì )進(jìn)行嚴格的Schema檢查，使用這個(gè)選項可以不進(jìn)行嚴格的Schema檢查，只是進(jìn)行不太嚴格的檢查
-extension : 默認情況下，XJC綁定編譯器強制執行JAXB規范中的兼容性部分的規則，Appendix E.2定義了一些列JAXB v1.0所不支持的W3C XML Schema特性。這時(shí)，就可以使用-extension模式來(lái)支持這些特性。在默認情況下，只能使用規范中定義的綁定自定義。通過(guò)使用-extension選項，可以使用JAXB提供商擴展。
-b <file> : 指定外部綁定文件（每個(gè)<file>要有自己的-b，與出現順序無(wú)關(guān)）
xjc schema1.xsd schema2.xsd schema3.xsd -b bindings123.xjb
xjc schema1.xsd schema2.xsd schema3.xsd -b bindings1.xjb -b bindings2.xjb -b bindings3.xjb
-d <dir> : 生成文件的目標路徑，默認情況下在當前目錄生成Java內容類(lèi)，目標目錄必須已經(jīng)存在，XJC不會(huì )自動(dòng)創(chuàng )建這些目錄
-p <pkg> : 指定目標包名
-httpproxy <proxy> : 設置HTTP/HTTPS代理，格式為[user[:password]@]proxyHost[:proxyPort]
-classpath <arg> : 指定用戶(hù)的類(lèi)路徑
-catalog <file> : 指定范疇文件，用于處理外部實(shí)體應用
支持TR9401, XCatalog, and OASIS XML Catalog格式.
-readOnly : 生成的文件的狀態(tài)為只讀
-npa : 不生成包級別的annotations
-xmlschema : 將輸入當作W3C XML Schema (默認)處理
-relaxng : 將輸入當作RELAXNG (試驗階段，不支持)處理
-relaxng-compact : 將輸入當作RELAXNG comapact語(yǔ)法 (試驗階段，不支持)處理
-dtd : 將輸入當作XML DTD (experimental,unsupported)
-wsdl : 將輸入當作WSDL處理(experimental,unsupported)
-verbose : 額外的顯示
-quiet : 不輸出編譯結果
-help : 顯示幫助信息
-version : 顯示版本信息
Extensions:
-Xlocator : 對生成的代碼啟用源代碼位置支持
-Xsync-methods : 生成訪(fǎng)問(wèn)的方法標志為''synchronized''關(guān)鍵字
-mark-generated : 將生成的代碼標記為@javax.annotation.Generated
windows下運行命令：
F:\eclipse\workspace\JAXBTutorial\src>xjc -p test.jaxb -d . text/jaxp/book.xsd
(譯者注：譯者的系統中安裝了Java(TM) Web Services Developer Pack 2.0，安裝目錄為C:\Sun\jwsdp-2.0，并將C:\Sun\jwsdp-2.0\jaxb\bin添加到了系統的path環(huán)境屬性中)
parsing a schema...
compiling a schema...
test\jaxb\BookCategoryType.java
test\jaxb\BookType.java
test\jaxb\Collection.java
test\jaxb\ObjectFactory.java
運行完上述命令后，會(huì )生成一些類(lèi)。
3. XJC Ant Task
在jwsdp或者其他的jaxb ri庫中，都包含了jaxb-xjc.jar這個(gè)文件，在這個(gè)文件中，包含了XJCTask.class文件，這個(gè)文件可以應用于A(yíng)nt構建工具中。在A(yíng)nt構建腳本(一般為build.xml)中包含如下的語(yǔ)句：
<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
<classpath>
<fileset dir="path/to/jaxb/lib" includes="*.jar" />
</classpath>
</taskdef>
上面的task定義將XJCTask映射到Ant task，并命名為xjc。在樣例程序中包含了如何使用xjc任務(wù)。
該任務(wù)的語(yǔ)法如下：
環(huán)境變量：
ANT OPTS –將命令行參數傳遞給JVM。例如定義系統屬性或者設置最大的Java堆大小。
參數屬性：
xjc支持以下的參數屬性：
schema:xml schema文件。這個(gè)屬性或者<schema>子元素必須包含一個(gè)。
binding:外部綁定文件，應用于schema文件。
package:如果指定了的話(huà)，那么生成的java文件會(huì )放在這個(gè)包下，與命令行參數-p一樣。
destdir:目標目錄，與命令行參數-d一樣。必須屬性。
readonly:是否以只讀方式生成java源文件，默認為false。
extension:如果設置為true，那么XJC綁定表一起會(huì )以擴展方式運行，否則的話(huà)，會(huì )按照嚴格的方式運行。和命令行工具的-extension參數一樣。
catalog:指定分類(lèi)文件來(lái)處理外部實(shí)體引用。
removeOldOutput:和<produces>子元素承兌使用。當設置為yes時(shí)，由<produces>元素指向的文件會(huì )在運行XJC編譯器之前刪除。
source:指定使用哪個(gè)版本的編譯器?？梢允?.0或者2.0.生成的Java代碼會(huì )參考JAXB1.0或者JAXB2.0規范制定的規則。
xjc支持下面的嵌套元素：
schema:同時(shí)編譯一個(gè)或者多個(gè)schema，schema子元素的語(yǔ)法和<fileset>相同。
binding:可以同時(shí)指定一個(gè)或者多個(gè)外部綁定文件，binding子元素的語(yǔ)法和<fileset>相同。
classpath:指定由用戶(hù)指定的類(lèi)路徑。
arg:一些額外的命令行參數。這個(gè)元素可以指定多個(gè)選項：
-nv
-use-runtime
-schema
-dtd
-relaxng
-Xlocator
-Xsync-methods
下面是一些使用XJC Task的例子：
編譯src/myschema.xmd,目標目錄為src，包名為org.acme.foo:
<xjc schema="src/myschema.xsd" target="src" package="org.acme.foo"/>
編譯src下面的所有schema文件，目標目錄為src，包名默認:
<xjc target="src">
<schema dir="src" includes="*.xsd"/>
</xjc>
編譯src下面的所有schema文件，目標目錄為src，綁定為src目錄下的所有xjb文件:
<xjc target="src">
<schema dir="src" includes="*.xsd"/>
<binding dir="src" includes="*.xjb"/>
</xjc>
由于ant默認需要fileset中的文件夾必須存在，所以mkdir是必須的，下面的例子做了一個(gè)up-to-date的檢查，如果abc.xsd有更新的話(huà)，那么src/org/acme/foo和其impl子目錄的文件在編譯之前就會(huì )被刪除，所以不要將自己編寫(xiě)的類(lèi)文件放在上述兩個(gè)目錄中。
<mkdir dir="src/org/acme/foo" />
<xjc target="src" schema="abc.xsd" removeOldOutput="yes" package="org.acme.foo">
<produces dir="src/org/acme/foo" includes="* impl/*" />
</xjc>
更加復雜的up-to-date檢查，如果xsd進(jìn)行了更新，或者dtd文件進(jìn)行了更新，都需要進(jìn)行重新的編譯schema。
<mkdir dir="src/org/acme/foo" />
<xjc target="src" removeOldOutput="yes" package="org.acme.foo">
<schema dir="schema" includes="*.xsd" />
<depends dir="schema" includes="*.dtd" />
<produces dir="build/generated-src/org/acme/foo" includes="**/*" />
</xjc>
使用arg子元素：
<xjc target="src">
<schema dir="src" includes="**/*.xsd" excludes="**/debug.xsd"/>
<arg value="-nv" />
</xjc>
設置環(huán)境變量或者系統屬性：
> set ANT_OPTS=-Dhttp.proxyHost=webcache.east
> set ANT_OPTS=%ANT_OPTS% -Dhttp.proxyPort=8080
> ant
4. SchemaGen工具 schema生成器可以通過(guò)schemagen shell腳本或者bat批處理文件來(lái)運行。目前schema生成器可以處理java源文件或者class文件。
同時(shí)，也提供了Ant task的方式來(lái)運行Schema生成器。
對于不同的操作系統，使用這個(gè)工具的例子如下：
For Solaris/Linux
% path/to/jaxb/bin/schemagen.sh Foo.java Bar.java ...
For WindowsNT/2000/XP
> path\to\jaxb\bin\schemagen.bat Foo.java Bar.java ...
注意：默認的schema文件的文件名為schema1.xsd。
如果Java源文件或者類(lèi)文件需要參考其他的類(lèi)，那么必須可以通過(guò)系統的CLASSPATH來(lái)訪(fǎng)問(wèn)，或者需要指定-classpath選項，否則的話(huà)，會(huì )發(fā)生錯誤。
命令行參數：
Usage: schemagen [options ...] <java files>
Options:
-d <path> :指定將處理器和javac生成的類(lèi)文件放在哪個(gè)目錄中
-cp <path> :用戶(hù)指定文件的目錄
-classpath <path> :用戶(hù)指定文件的目錄
-help :顯示幫助信息
目前schema生成器為Java類(lèi)文件使用的名稱(chēng)空間生成schema文件。沒(méi)有辦法控制生成的schema文件的名字，可以使用Ant任務(wù)來(lái)完成這個(gè)功能。
5. Schema生成器的Ant Task jaxb-xjc.jar文件中包含了SchemaGenTask.class文件，這樣就可以在A(yíng)nt構建工具中使用schema生成器了。SchemaGenTask的定義如下：
<taskdef name="schemagen" classname="com.sun.tools.jxc.SchemaGenTask">
<classpath>
<fileset dir="path/to/jaxb/lib" includes="*.jar" />
</classpath>
</taskdef>
參數屬性：
schemagen支持javac定義的大多數屬性。并且支持下面的參數屬性：
destdir:生成的schema文件的基準目錄。
classpath:和子元素<classpath>功能相同。
schemagen支持所有的javac任務(wù)定義的子元素。
schema：控制生成的schema文件的名字。這個(gè)元素必須設置namespace屬性和file屬性。當這個(gè)元素存在的時(shí)候，指定的namespace的schema文件的名字和file屬性指定的名字相同。文件名和destdir屬性指定的文件名是相對的。當不存在destdir時(shí)，將項目basedir作為destdir?？梢远啻卧O置schema元素。
classpath:和路徑類(lèi)似的結構來(lái)表示classpath。
下面是一些schemagen生成器的例子：
將src目錄下的源文件生成schema文件，保存在build/schemas目錄。
<schemagen srcdir="src" destdir="build/schemas">
使用javac的子元素：
<schemagen destdir="build/schemas">
<src path="src" />
<exclude name="Main.java"/>
</schemagen>
6. JAXB RI Extensions 運行時(shí)屬性：
JAXB RI提供了一些在JAXB規范中沒(méi)有定義的額外的Marshaller屬性，這些屬性可以更好的控制marshalling過(guò)程。但是，這只適用于JAXB RI，不一定適用于其他的JAXB提供者。
名稱(chēng)前綴映射
屬性名：com.sun.xml.bind.namespacePrefixMapper
類(lèi)型：com.sun.xml.bind.marshaller.NamespacePrefixMapper
默認值：無(wú)
JAXB RI提供了一個(gè)方法來(lái)將URI名稱(chēng)空間映射到前綴。下面是通常的過(guò)程：
應用程序開(kāi)發(fā)人員提供一個(gè)com.sun.xml.bind.marshaller.NamespacePrefixMapper的實(shí)現
接著(zhù)將這個(gè)類(lèi)設置為RI指定的com.sun.xml.bind.namespacePrefixMapper屬性
每當marshaller遇到一個(gè)URI，都會(huì )回調映射
當mapper返回值時(shí)，marshaller就會(huì )使用這個(gè)值
com.sun.xml.bind.marshaller.NamespacePrefixMapper類(lèi)需要實(shí)現下面的方法：
public abstract class NamespacePrefixMapper {
/**
* Returns a preferred prefix for the given namespace URI.
*
* This method is intended to be overrided by a derived class.
*
* @param namespaceUri
* The namespace URI for which the prefix needs to be found.
* Never be null. "" is used to denote the default namespace.
* @param suggestion
* When the content tree has a suggestion for the prefix
* to the given namespaceUri, that suggestion is passed as a
* parameter. Typically this value comes from QName.getPrefix()
* to show the preference of the content tree. This parameter
* may be null, and this parameter may represent an already
* occupied prefix.
* @param requirePrefix
* If this method is expected to return non-empty prefix.
* When this flag is true, it means that the given namespace URI
* cannot be set as the default namespace.
*
* @return
* null if there''s no preferred prefix for the namespace URI.
* In this case, the system will generate a prefix for you.
*
* Otherwise the system will try to use the returned prefix,
* but generally there''s no guarantee if the prefix will be
* actually used or not.
*
* return "" to map this namespace URI to the default namespace.
* Again, there''s no guarantee that this preference will be
* honored.
*
* If this method returns "" when requirePrefix=true, the return
* value will be ignored and the system will generate one.
*/
public abstract String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix);
}
如果這個(gè)屬性被設置為null的話(huà)，下面默認的屬性就會(huì )返回：
public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
return suggestion;
}
縮進(jìn)
屬性名：com.sun.xml.bind.indentString
類(lèi)型：java.lang.String
默認值：” ”四個(gè)空格
這個(gè)屬性用來(lái)控制XML的縮進(jìn)。
注意需要設置jaxb.formatted.output屬性來(lái)啟用縮進(jìn)。
轉義字符
屬性名：com.sun.xml.bind.characterEscapeHandler
類(lèi)型：com.sun.xml.bind.marshaller.CharacterEscapeHandler
默認值：null
默認情況下，JAXB RI的實(shí)現會(huì )試著(zhù)轉義字符，這樣的話(huà)，就可以安全的表示輸出編碼。
不過(guò)，由于各種技術(shù)原因，默認的操作可能不會(huì )滿(mǎn)足要求。如果需要處理更敏捷的處理轉義，那么可以按照如下過(guò)程進(jìn)行操作：
實(shí)現com.sun.xml.bind.marshaller.CharacterEscapeHandler接口
創(chuàng )建創(chuàng )建一個(gè)實(shí)例
將實(shí)例設置為marshaller的屬性
默認情況下的轉義是和J2SE SDK的版本相關(guān)，如果運行J2SE SDK 版本1.3或者之前的版本不能滿(mǎn)足轉義需求的話(huà)，可以使用版本1.4或者之后的版本。
XML聲明控制
屬性名：com.sun.xml.bind.xmlDeclaration
類(lèi)型：java.lang.Boolean
默認值：Boolean.TRUE
這是JAXB RI 1.0.x的實(shí)驗屬性，并且被JAXB 2.0標準所采用。2.0 RI會(huì )繼續支持這個(gè)屬性，但是客戶(hù)端的代碼應該使用Marshaller.JAXB_FRAGMENT屬性。
在JAXB 2.0中，調用:
marshaller.setProperty("com.sun.xml.bind.xmlDeclaration", Boolean.FALSE);
和調用
marshaller.setProperty(Marshaller.JAXB_FRAGMENT, Boolean.TRUE);
是等價(jià)的。
啟用片段marshalling可以使得將一個(gè)片段輸出到另外一個(gè)XML的時(shí)候。同樣，當需要輸出類(lèi)似DOCTYPE聲明或者XML樣式表處理指示，參考如下的代碼：
PrintWriter out = ...;
// print out the prolog part by ourselves
out.println("<xml version=''1.0''?>");
out.println("<!DOCTYPE foo SYSTEM ''dummy.dtd''>");
marshaller.setProperty("com.sun.xml.bind.xmlDeclaration", Boolean.FALSE);
marshaller.marshal( jaxbObject, out );
JAXB RI提供了JAXB規范沒(méi)有定義的自定義內容。
這些特性只有在-extension模式下運行綁定編譯器時(shí)才可以使用
所有JAXB RI供應商擴展都定義在
http://java.sun.com/xml/ns/jaxb/xjc名稱(chēng)空間
名稱(chēng)空間中包含了擴展綁定聲明，這將使得全局屬性@jaxb:extensionBindingPrefixes在<xs:schema>元素。這個(gè)屬性的值是以空格分隔的名稱(chēng)空間前綴。
擴展普通的超類(lèi)
<xjc:superClass>自定義屬性可以指定一個(gè)full qualified name作為Java類(lèi)名來(lái)作為所有的生成類(lèi)的超類(lèi)。<xjc:superClass>只可以在<jaxb:globalBindings>：
<xs:schema xmlns:xs="
xmlns:jaxb=" xmlns:xjc=" jaxb:extensionBindingPrefixes="xjc"
jaxb:version="1.0">
<xs:annotation>
<xs:appinfo>
<jaxb:globalBindings>
<xjc:superClass name="org.acme.RocketBooster"/>
</jaxb:globalBindings>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:schema>
還可以擴展共同的接口
和擴展共同的類(lèi)類(lèi)似，只是使用<xjc:superInterface>來(lái)代替<xjc:superClass>。
<xs:schema xmlns:xs=" xmlns:jaxb=" xmlns:xjc=" jaxb:extensionBindingPrefixes="xjc"
jaxb:version="1.0">
<xs:annotation>
<xs:appinfo>
<jaxb:globalBindings generateValueClass="false">
<xjc:superInterface name="org.acme.RocketBooster"/>
</jaxb:globalBindings>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:schema>
7. 關(guān)于Schema
JAXB RI目前支持下面所列舉的Schema語(yǔ)言。下面的一些特性并沒(méi)有在JAXB規范中描述，只是在JAXB RI中才是可用的。
W3C Schema：JAXB 2.0 RI FCS會(huì )100%的支持W3C XML Schema。但是，現在的版本只是一個(gè)臨時(shí)版本，還沒(méi)有實(shí)現全部的功能。本節描述了JAXB 2.0規范。Section 8 描述了Java to XML，Section 6和7描述了XML to Java。
RELAX NG：目前還沒(méi)有支持。
DTD：JAXB RI目前試著(zhù)支持DTD，但是不能保證沒(méi)有問(wèn)題?？梢允褂孟旅娴墓ぞ邅?lái)編譯XML的DTD。
$xjc.sh –dtd test.dtd
