【转】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>

 

文章出处：http://www.diybl.com/course/3_program/java/javajs/200853/112204.html