JAXB Examples

以下各节描述如何使用 JAXB RIBinding 包中包含的示例应用程序。 JAXB RIBinding 包可从http://jaxb.java.net获得。下载并安装 JAXB RIBinding 软件。这些示例位于 jaxb-ri-install /samples/目录中。这些示例演示并构建在关键的 JAXB 功能和概念上。按照显示的 Sequences 执行以下步骤。

阅读本节后，您应该对 JAXB 感到足够自在，可以：

• 从 XMLPattern 生成 JAXB Java 类

• 使用派生于 Pattern 的 JAXB 类来解组和封送 Java 应用程序中的 XML 内容

• 使用 Pattern 派生的 JAXB 类创建 Java 内容树

• 在解组期间和运行时验证 XML 内容

• 自定义 JAXBPattern 到 Java 绑定

本文档描述了三组示例：

• 基本示例(Modify Marshal，Unmarshal Validate)展示了基本的 JAXB 概念，例如使用默认设置和绑定来解组，编组和验证 XML 内容。

• 定制示例(Customize Inline，Datatype Converter，External Customize)展示了各种定制 XMLPattern 到 Java 对象的默认绑定的方法。

• java-to-schema 示例显示了如何使用 注解 将 Java 类 Map 到 XMLPattern。

基本和自定义示例目录包含几个基本文件：

• po\.xsd是 XMLPattern，它用作 JAXB 绑定编译器的 Importing，并且将从中生成 Pattern 派生的 JAXB Java 类。对于“定制内联和数据类型转换器”示例，此文件包含内联绑定定制。

• po\.xml是包含示例 XML 内容的 Purchase Order XML 文件，在每个示例中，它都是未编组到 Java 内容树中的文件。在每个示例中，该文件几乎相同。在内容上存在细微差别，以突出显示不同的 JAXB 概念。

• Main\.java是每个示例的主要 Java 类。

• build\.xml是为您提供方便的 Ant 项目文件。使用 Ant 工具自动生成，编译和运行 Pattern 派生的 JAXB 类。 build\.xml文件在各个示例中有所不同。

• inline\-customize示例中的MyDatatypeConverter\.java是用于提供自定义数据类型转换的 Java 类。

• “外部定制”示例中的binding\.xjb是一个外部绑定声明文件，该文件传递给 JAXB 绑定编译器以自定义默认的 JAXB 绑定。

下表简要描述了基本的，自定义的和 java-to-schema JAXB 示例。

表：基本的 JAXB 示例

Example Name	Description
Modify Marshal	演示如何修改 Java 内容树。
Unmarshal Validate	演示如何在编组期间启用验证。

表：定制 JAXB 示例

Example Name	Description
Customize Inline	演示如何通过在 XMLPattern 中使用内联 注解 来自定义默认的 JAXB 绑定。
Datatype Converter	说明了 XML simpleType定义与 Java 数据类型的替代性更简洁的绑定，类似于 Customize Inline 示例。
External Customize	说明如何使用外部绑定声明文件将只读 Pattern 的绑定定制传递给 JAXB 绑定编译器。

表：Java 到 Pattern 的 JAXB 示例

Example Name	Description
Create Marshal	演示如何使用 ObjectFactory 类创建 Java 内容树并将其编组为 XML 数据。它还演示了如何向 JAXB List 属性添加内容。
XmlAccessorOrder	说明如何在 Java 类中使用@XmlAccessorOrder和@XmlType\.propOrderMap注解 来控制 Java 内容对 XML 内容进行编组或解组的 Sequences。
XmlAdapter	说明如何使用interfaceXmlAdapter和注解@XmlJavaTypeAdapter提供自定义 XML 内容到HashMap(字段)的自定义 Map，该字段使用整数(int)作为键和字符串(String)作为值。
XmlAttribute	说明如何使用 注解@XmlAttribute定义要作为 XML 属性处理的属性或字段。
XmlRootElement	说明如何使用 注解@XmlRootElement为相应类的 XMLPattern 类型定义 XML 元素名称。
XmlSchemaType Class	说明如何使用 注解@XmlSchemaType来定制属性或字段到 XML 内置类型的 Map。
XmlType	说明如何使用 注解@XmlType将类或enum类型 Map 到 XMLPattern 类型。

JAXB 编译器选项

JAXB XJCPattern 绑定编译器将源 XMLPattern 转换或绑定到 Java 编程语言中的一组 JAXB 内容类。在 JAXB RIBinding 包中，编译器类xjc的提供方式为：在 Solaris/Linux 上为xjc\.sh，在 Windows 上为xjc\.bat。 xjc类包含在 JDK 类库中(在 tools.jar 中)。

xjc\.sh和xjc\.bat都使用相同的命令行选项。您可以通过不带任何选项或使用\-helpswitch调用脚本来显示快速使用说明。语法如下：

xjc [-options ...] <schema file/URL/dir/jar>... [-b >bindinfo<] ...

如果指定dir，将编译目录中的所有架构文件。如果指定jar，将编译/META-INF/sun-jaxb.episode 绑定文件。

xjc命令行选项如下：

• \-nv

  • 不要对 ImportingPattern 或多个 Pattern 执行严格的验证。默认情况下，xjc在处理之前对源 Pattern 进行严格验证。注意，这并不意味着绑定编译器将不执行任何验证；它只会执行不太严格的验证。

• \-extension

  • 默认情况下，XJC 绑定编译器严格执行 JAXB 规范的“兼容性”一章中概述的规则。在默认(严格)Pattern 下，您还只能使用规范中定义的绑定自定义项。通过使用\-extensionswitch，可以使用 JAXB 供应商扩展。

• \-b个文件

  • 指定一个或多个要处理的外部绑定文件。 (每个绑定文件必须具有自己的\-bswitch.)外部绑定文件的语法很灵活。您可能只有一个绑定文件，其中包含针对多个架构的自定义，或者您可以将自定义拆分为多个绑定文件。另外，在命令行上 Pattern 文件和绑定文件的 Sequences 无关紧要。

• \-d目录

  • 默认情况下，XJC 绑定编译器在当前目录中生成 Java 内容类。使用此选项可以指定备用输出目录。该目录必须已经存在； XJC 绑定编译器不会为您创建一个。

• \-p套餐

  • 指定备用输出目录。默认情况下，XJC 绑定编译器将在当前目录中生成 Java 内容类。输出目录必须已经存在； XJC 绑定编译器不会为您创建一个。

• \-httpproxy代理

  • 指定 HTTP/HTTPS 代理。格式为\[ user \[: password \]@\] proxyHost \[: proxyPort \]。参考实现仍然支持旧的\-host和\-port选项，以实现向后兼容，但已弃用了它们。

• \-httpproxyfile f

  • 类似于\-httpproxy选项，但在文件中使用参数来保护密码。

• \-classpath arg

  • 指定在哪里可以找到\<jxb:javaType\>和\<xjc:superClass\>定制使用的 Client 端应用程序类文件。

• \-catalog个文件

  • 指定目录文件以解析外部实体引用。支持 TR9401，XCatalog 和 OASIS XML 目录格式。有关更多信息，请参见 XML 实体和 URI 解析器文档或检查 catalog-resolver 示例应用程序。

• \-readOnly

  • 强制 XJC 绑定编译器将生成的 Java 源标记为只读。默认情况下，XJC 绑定编译器不会对其生成的 Java 源文件进行写保护。

• \-npa

  • 禁止将软件包级别的 注解 生成到\*\*/package\-info\.java中。使用此switch会使生成的代码将这些 注解 内部化为其他生成的类。

• \-no\-header

  • 禁止使用时间戳生成文件头。

• \-target \(2\.0\|2\.1\)

  • 表现得像 XJC 2.0 或 2.1，并生成不使用任何 XJC 2.2 功能的代码。

• \-enableIntrospection

  • 启用 Booleangetter/setter 的正确生成，以启用 Bean 自省 api。

• \-contentForWildcard

  • 为具有多个 xs：any 派生元素的类型生成 content 属性。

• \-xmlschema

  • 将 ImportingPattern 视为 W3C XMLPattern(默认)。如果未指定此switch，则将 ImportingPattern 视为 W3C XMLPattern。

• \-verbose

  • 在编译器输出中特别冗 Long。

• \-quiet

  • 禁止编译器输出，例如进度信息和警告。

• \-help

  • 显示编译器switch的简要摘要。

• \-version

  • 显示编译器版本信息。

• \-fullversion

  • 显示编译器完整版本信息。

• \-Xinject\-code

  • 将指定的 Java 代码片段注入到生成的代码中。

• \-Xlocator

  • 为生成的代码启用源位置支持。

• \-Xsync\-methods

  • 使用synchronized关键字生成访问器方法。

• \-mark\-generated

  • 使用\-@javax\.annotation\.生成的 注解 标记生成的代码。

• \-episode FILE

  • 生成情节文件以进行单独编译。

JAXBPattern 生成器选项

JAXBPattern 生成器schemagen为 Java 类中引用的每个命名空间创建一个 Pattern 文件。可以使用平台的bin目录中的相应schemagen shell 脚本来启动 Pattern 生成器。Pattern 生成器仅处理 Java 源文件。如果您的 Java 源引用了其他类，则必须从您的系统 CLASSPATH 环境变量中访问这些源；否则，生成架构时将发生错误。无法控制生成的 Pattern 文件的名称。

您可以通过不带任何选项的脚本调用或使用\-help选项来显示快速使用说明。语法如下：

schemagen [-d path] 
    [java-source-files]

\-d path 选项指定处理器生成的类文件和javac生成的类文件的位置。

关于架构到 Java 的绑定

当针对基本示例中使用的po\.xsd XMLPattern(Unmarshal Read，Modify Marshal，Unmarshal Validate)运行 JAXB 绑定编译器时，JAXB 绑定编译器会生成一个名为primer\.po的 Java 程序包，其中包含下表中所述的类。

表：基本示例中的 Pattern 派生的 JAXB 类

Class	Description
primer/po/Items\.java	绑定到名为Items的架构complexType的公共interface。
primer/po/ObjectFactory\.java	公共类扩展com\.sun\.xml\.bind\.DefaultJAXBContextImpl；用于创建指定interface的实例。例如，ObjectFactory createComment\(\)方法实例化Comment对象。
primer/po/PurchaseOrderType\.java	绑定到名为PurchaseOrderType的架构complexType的公共interface。
primer/po/USAddress\.java	绑定到名为USAddress的架构complexType的公共interface。

下表描述了这些类及其对基本示例的源 XML 架构的特定绑定。

表：基本示例的 Pattern 到 Java 绑定

XML Schema	JAXB Binding
<xsd:schema xmlns:xsd=
"http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="PurchaseOrderType"> <___+136+> <xsd:element name="shipTo" type="USAddress"/> <xsd:element name="billTo" type="USAddress"/> <xsd:element ref="comment" minOccurs="0"/> <xsd:element name="items" type="Items"/> </xsd:sequence> <xsd:attribute name="orderDate" type="xsd:date"/> </xsd:complexType>	PurchaseOrderType\.java
<xsd:complexType name="USAddress"> <___+138+> <xsd:element name="name" type="xsd:string"/> <xsd:element name="street" type="xsd:string"/> <xsd:element name="city" type="xsd:string"/> <xsd:element name="state" type="xsd:string"/> <xsd:element name="zip" type="xsd:decimal"/> </xsd:sequence> <xsd:attribute name="country" type="xsd:NMTOKEN" fixed="US"/> </xsd:complexType>	USAddress\.java
<xsd:complexType name="Items"> <___+140+> <xsd:element name="item" minOccurs="1" maxOccurs =“ unbounded”>	Items\.java
<___+142+> <___+143+> <xsd:element name="productName" type="xsd:string"/> <xsd:element name="quantity"> <___+144+> <xsd:restriction base="xsd:positiveInteger"> <xsd:maxExclusive value="100"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="USPrice" type="xsd:decimal"/> <xsd:element ref="comment" minOccurs="0"/> <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/> </xsd:sequence> <xsd:attribute name="partNum" type="SKU" use="required"/> </xsd:complexType>	Items\.ItemType
</xsd:element> </xsd:sequence> </xsd:complexType>
<!--库存单位，代号 identifying products -->
<xsd:simpleType name="SKU"> <xsd:restriction base="xsd:string"> <xsd:pattern value="\d{3}-[A-Z]{2}"/> </xsd:restriction> </xsd:simpleType>
</xsd:schema>

架构派生的 JAXB 类

接下来的部分简要说明了 JAXB 绑定编译器为示例生成的以下各个类的功能：

• Items Class

• ObjectFactory Class

• PurchaseOrderType Class

• USAddress Class

Items Class

在Items\.java中：

• Items类是primer\.po包的一部分。

• 该类为Items和ItemType提供公共interface。

• 此类实例化中的内容绑定到 XML ComplexTypes Items及其子元素ItemType。

• Item提供getItem\(\)方法。

• ItemType提供以下方法：

• getPartNum\(\);

  • setPartNum\(String value\);

  • getComment\(\);

  • setComment\(java\.lang\.String value\);

  • getUSPrice\(\);

  • setUSPrice\(java\.math\.BigDecimal value\);

  • getProductName\(\);

  • setProductName\(String value\);

  • getShipDate\(\);

  • setShipDate\(java\.util\.Calendar value\);

  • getQuantity\(\);

  • setQuantity\(java\.math\.BigInteger value\);

ObjectFactory Class

在ObjectFactory\.java中：

• ObjectFactory类是primer\.po包的一部分。

• ObjectFactory提供了用于实例化表示 Java 内容树中的 XML 内容的 Java interface的工厂方法。

• 方法名称是通过 String 联生成的：

• 字符串 常量create。

  • 如果 Java 内容interface嵌套在另一个interface中，则所有外部 Java 类名称。

  • Java 内容interface的名称。

例如，在这种情况下，对于 Java interfaceprimer\.po\.Items\.ItemType，ObjectFactory创建方法createItemsItemType\(\)。

PurchaseOrderType Class

在PurchaseOrderType\.java中：

• PurchaseOrderType类是primer\.po包的一部分。

• 此类实例化中的内容绑定到名为PurchaseOrderType的 XMLPattern 子元素。

• PurchaseOrderType是提供以下方法的公共interface：

• getItems\(\);

  • setItems\(primer\.po\.Items value\);

  • getOrderDate\(\);

  • setOrderDate\(java\.util\.Calendar value\);

  • getComment\(\);

  • setComment\(java\.lang\.String value\);

  • getBillTo\(\);

  • setBillTo\(primer\.po\.USAddress value\);

  • getShipTo\(\);

  • setShipTo\(primer\.po\.USAddress value\);

USAddress Class

在USAddress\.java中：

• USAddress类是primer\.po包的一部分。

• 此类实例化中的内容绑定到名为USAddress的 XMLPattern 元素。

• USAddress是提供以下方法的公共interface：

• getState\(\);

  • setState\(String value\);

  • getZip\(\);

  • setZip\(java\.math\.BigDecimal value\);

  • getCountry\(\);

  • setCountry\(String value\);

  • getCity\(\);

  • setCity\(String value\);

  • getStreet\(\);

  • setStreet\(String value\);

  • getName\(\);

  • setName\(String value\);