Jaxb官方文档中文翻译

JAXB提供了自动映射XML文档和Java对象的API和工具。 
JAXB框架可以完成下面的操作： 
1、将XML内容Unmarshal成Java表示 
2、访问和更新Java表示 
3、将XML内容的Java表示Marshal成XML内容

 
JAXB提供了XML和Java代码之间的高效并且标准的映射。Java开发人员可以使用JAXB来简化开发，提高效率，因为使用JAXB可以写很少的代码，并且不需要很精通XML。JAXB使得开发人员可以很容易的使用XML和Web Service技术来扩展应用程序。 
1. Release Notes 
JAXB Reference Implementation需要运行在J2SE 5.0或者更高的Java平台上。需要的JAR文件如下： 
2.0运行环境：为Deploy JAXB2.0客户端所需要的JAR文件包括jaxb-api.jar,jaxb-impl.jar,jsr173-1.0_api.jar 
1.0运行环境：为Deploy JAXB1.0客户端所需要的JAR文件包括2.0运行环境+jaxb1-impl.jar 

2. XJC工具 
虽然在笔者的其他文章中，包含了关于XJC脚本文件的使用，但是为了保持文章的完整性，将XJC脚本的内容再次追加在本文中。 
绑定schema表示生成一系列的Java类，这些java类表示了schema。所有的JAXB实现都提供了一个工具叫做绑定编译器来将一个schema绑定。例如，JAXB参考实现提供了一个绑定编译器，允许通过脚本来执行(shell/bat)。假设需要将books.xsd文件进行绑定，并且假设是工作与*nix系统，那么绑定的命令如下： 
xjc.sh -p test.jaxb books.xsd -d work 

选项说明： 
-p:指定生成的类的包名 
-d:指定存放类的目标目录 
(译者注：其实绑定schema还有其他的选项和方法，例如Eclispe的xjc插件等) 
C:\Documents and Settings\hp3643>xjc --help 
  
Usage: xjc [-options ...] <schema file/URL/dir> ... [-b <bindinfo>] ... 
Options: 
 -nv: 不进行输入schema的严格检查，默认情况下，XJC会进行严格的Schema检查，使用这个选项可以不进行严格的Schema检查，只是进行不太严格的检查 
 -extension: 默认情况下，XJC绑定编译器强制执行JAXB规范中的兼容性部分的规则，Appendix E.2定义了一些列JAXB v1.0所不支持的W3C XML Schema特性。这时，就可以使用-extension模式来支持这些特性。在默认情况下，只能使用规范中定义的绑定自定义。通过使用-extension选项，可以使用JAXB提供商扩展。 
 -b <file>: 指定外部绑定文件（每个<file>要有自己的-b，与出现顺序无关） 
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内容类，目标目录必须已经存在，XJC不会自动创建这些目录 
 -p <pkg>: 指定目标包名 
 -httpproxy <proxy> : 设置HTTP/HTTPS代理，格式为[user[:password]@]proxyHost[:proxyPort] 
 -classpath <arg>: 指定用户的类路径 
 -catalog <file>: 指定范畴文件，用于处理外部实体应用，支持TR9401, XCatalog, and OASIS XML Catalog格式. 
 -readOnly: 生成的文件的状态为只读 
 -npa: 不生成包级别的annotations 
 -xmlschema: 将输入当作W3C XML Schema (默认)处理 
 -relaxng: 将输入当作RELAXNG (试验阶段，不支持)处理 
 -relaxng-compact: 将输入当作RELAXNG comapact语法 (试验阶段，不支持)处理 
 -dtd: 将输入当作XML DTD (experimental,unsupported) 
 -wsdl: 将输入当作WSDL处理(experimental,unsupported) 
 -verbose: 额外的显示 
 -quiet: 不输出编译结果 
 -help: 显示帮助信息 
 -version: 显示版本信息 
  
Extensions: 
 -Xlocator: 对生成的代码启用源代码位置支持 
 -Xsync-methods: 生成访问的方法标志为''synchronized''关键字 
 -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环境属性中) 
parsing a schema... 
compiling a schema... 
test\jaxb\BookCategoryType.java 
test\jaxb\BookType.java 
test\jaxb\Collection.java 
test\jaxb\ObjectFactory.java 
运行完上述命令后，会生成一些类。 
  
3. XJC Ant Task 
在jwsdp或者其他的jaxb ri库中，都包含了jaxb-xjc.jar这个文件，在这个文件中，包含了XJCTask.class文件，这个文件可以应用于Ant构建工具中。在Ant构建脚本(一般为build.xml)中包含如下的语句： 
<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任务。 
该任务的语法如下： 
环境变量： 
ANT OPTS –将命令行参数传递给JVM。例如定义系统属性或者设置最大的Java堆大小。 
参数属性： 
xjc支持以下的参数属性： 
schema:xml schema文件。这个属性或者<schema>子元素必须包含一个。 
binding:外部绑定文件，应用于schema文件。 
package:如果指定了的话，那么生成的java文件会放在这个包下，与命令行参数-p一样。 
destdir:目标目录，与命令行参数-d一样。必须属性。 
readonly:是否以只读方式生成java源文件，默认为false。 
extension:如果设置为true，那么XJC绑定表一起会以扩展方式运行，否则的话，会按照严格的方式运行。和命令行工具的-extension参数一样。 
catalog:指定分类文件来处理外部实体引用。 
removeOldOutput:和<produces>子元素承兑使用。当设置为yes时，由<produces>元素指向的文件会在运行XJC编译器之前删除。 
source:指定使用哪个版本的编译器。可以是1.0或者2.0.生成的Java代码会参考JAXB1.0或者JAXB2.0规范制定的规则。 
xjc支持下面的嵌套元素： 
schema:同时编译一个或者多个schema，schema子元素的语法和<fileset>相同。 
binding:可以同时指定一个或者多个外部绑定文件，binding子元素的语法和<fileset>相同。 
classpath:指定由用户指定的类路径。 
arg:一些额外的命令行参数。这个元素可以指定多个选项： 
-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是必须的，下面的例子做了一个up-to-date的检查，如果abc.xsd有更新的话，那么src/org/acme/foo和其impl子目录的文件在编译之前就会被删除，所以不要将自己编写的类文件放在上述两个目录中。 
<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进行了更新，或者dtd文件进行了更新，都需要进行重新的编译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> 
设置环境变量或者系统属性： 
> set ANT_OPTS=-Dhttp.proxyHost=webcache.east 
> set ANT_OPTS=%ANT_OPTS% -Dhttp.proxyPort=8080 
> ant 
  
4. SchemaGen工具 
schema生成器可以通过schemagen shell脚本或者bat批处理文件来运行。目前schema生成器可以处理java源文件或者class文件。 
    同时，也提供了Ant task的方式来运行Schema生成器。 
对于不同的操作系统，使用这个工具的例子如下： 
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源文件或者类文件需要参考其他的类，那么必须可以通过系统的CLASSPATH来访问，或者需要指定-classpath选项，否则的话，会发生错误。 
命令行参数： 
Usage: schemagen [options ...] <java files> 
Options: 
    -d <path>:指定将处理器和javac生成的类文件放在哪个目录中 
    -cp <path>:用户指定文件的目录 
    -classpath <path>:用户指定文件的目录 
    -help:显示帮助信息 
目前schema生成器为Java类文件使用的名称空间生成schema文件。没有办法控制生成的schema文件的名字，可以使用Ant任务来完成这个功能。 
  
5. Schema生成器的Ant Task 
jaxb-xjc.jar文件中包含了SchemaGenTask.class文件，这样就可以在Ant构建工具中使用schema生成器了。SchemaGenTask的定义如下： 
<taskdef name="schemagen" classname="com.sun.tools.jxc.SchemaGenTask"> 
 <classpath> 
    <fileset dir="path/to/jaxb/lib" includes="*.jar" /> 
 </classpath> 
</taskdef>