Java 中文官方教程 2022 版（四十九）(1)

JAXB 示例

原文：docs.oracle.com/javase/tutorial/jaxb/intro/examples.html

以下部分描述如何使用包含在 JAXB RI 捆绑包中的示例应用程序。JAXB RI 捆绑包可从jaxb.java.net获取。下载并安装 JAXB RI 捆绑包。示例位于jaxb-ri-install/samples/目录中。这些示例演示并构建了关键的 JAXB 功能和概念。请按照呈现的顺序执行这些步骤。

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

• 从 XML 模式生成 JAXB Java 类
  
• 在 Java 应用程序中使用基于模式的 JAXB 类解组和组合 XML 内容
  
• 使用基于模式的 JAXB 类创建 Java 内容树
  
• 在解组期间和运行时验证 XML 内容
  
• 自定义 JAXB 模式到 Java 绑定
  

本文描述了三组示例：

• 基本示例（修改 Marshal、Unmarshal Validate）演示了基本的 JAXB 概念，如使用默认设置和绑定来解组、组合和验证 XML 内容。
  
• 自定义示例（Customize Inline、Datatype Converter、External Customize）演示了将 XML 模式默认绑定到 Java 对象的各种自定义方式。
  
• java-to-schema 示例展示了如何使用注解将 Java 类映射到 XML 模式。
  

**注意：**基本和自定义示例基于采购订单场景。每个示例使用一个 XML 文档po.xml，根据一个 XML 模式po.xsd编写。这些文档源自由 David C. Fallside 编辑的W3C XML Schema Part 0: Primer。

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

• po.xsd是作为 JAXB 绑定编译器输入的 XML 模式，将从中生成基于模式的 JAXB Java 类。对于自定义内联和数据类型转换器示例，此文件包含内联绑定自定义。
  
• po.xml是包含示例 XML 内容的采购订单 XML 文件，在每个示例中解组为 Java 内容树。这个文件在每个示例中几乎相同；为了突出不同的 JAXB 概念，存在轻微的内容差异。
  
• Main.java是每个示例的主要 Java 类。
  
• build.xml是一个 Ant 项目文件，为您提供方便。使用 Ant 工具自动生成、编译和运行基于模式的 JAXB 类。build.xml文件在示例之间有所不同。
  
• inline-customize示例中的MyDatatypeConverter.java是一个 Java 类，用于提供自定义数据类型转换。
  
• External Customize 示例中的binding.xjb是一个外部绑定声明文件，传递给 JAXB 绑定编译器以自定义默认的 JAXB 绑定。
  

以下表简要描述了基本、定制和 Java 到模式 JAXB 示例。

表：基本 JAXB 示例

表：定制 JAXB 示例

表：Java 到模式 JAXB 示例

JAXB 编译器选项

JAXB XJC 模式绑定编译器将源 XML 模式转换或绑定到 Java 编程语言中的一组 JAXB 内容类。编译器类xjc提供为：在 Solaris/Linux 上为xjc.sh，在 Windows 上为xjc.bat在 JAXB RI 捆绑包中。xjc类包含在 JDK 类库中（在 tools.jar 中）。

xjc.sh和xjc.bat都接受相同的命令行选项。您可以通过在没有任何选项或使用-help开关的情况下调用脚本来显示快速使用说明。语法如下：

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

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

xjc命令行选项如下：

-nv

不执行输入模式或模式的严格验证。默认情况下，xjc 在处理之前会对源模式进行严格验证。请注意，这并不意味着绑定编译器不会执行任何验证；它只会执行较少严格的验证。

-extension

默认情况下，XJC 绑定编译器严格执行 JAXB 规范的兼容性章节中概述的规则。在默认（严格）模式下，您也只能使用规范中定义的绑定自定义。通过使用-extension开关，您可以使用 JAXB 供应商扩展。

-b file

指定一个或多个要处理的外部绑定文件。（每个绑定文件必须有自己的-b开关。）外部绑定文件的语法是灵活的。您可以有一个包含多个模式的自定义的单个绑定文件，或者您可以将自定义拆分为多个绑定文件。此外，命令行中模式文件和绑定文件的顺序无关紧要。

-d dir

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

-p package

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

-httpproxy proxy

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

-httpproxyfile f

类似于-httpproxy选项，但将参数放在文件中以保护密码。

-classpath arg

指定用于和自定义的客户端应用程序类文件的位置。

-catalog file

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

-readOnly

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

-npa

抑制将包级别注释生成到**/package-info.java中。使用此开关会导致生成的代码将这些注释内部化到其他生成的类中。

-no-header

抑制生成带有时间戳的文件头。

-target (2.0|2.1)

行为类似于 XJC 2.0 或 2.1，并生成不使用任何 XJC 2.2 功能的代码。

-enableIntrospection

启用正确生成布尔值 getter/setter 以启用 Bean Introspection api。

-contentForWildcard

为具有多个 xs:any 派生元素的类型生成内容属性。

-xmlschema

将输入模式视为 W3C XML 模式（默认）。 如果不指定此开关，则将处理输入模式为 W3C XML 模式。

-verbose

在编译器输出中更加详细。

-quiet

抑制编译器输出，如进度信息和警告。

-help

显示编译器开关的简要摘要。

-version

显示编译器版本信息。

-fullversion

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

-Xinject-code

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

-Xlocator

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

-Xsync-methods

生成带有synchronized关键字的访问器方法。

-mark-generated

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

-episode *FILE*

为单独编译生成剧集文件。

JAXB 模式生成器选项

JAXB 模式生成器schemagen为您的 Java 类中引用的每个命名空间创建一个模式文件。 模式生成器可以通过使用适用于您平台的bin目录中的适当schemagen shell 脚本启动。 模式生成器仅处理 Java 源文件。 如果您的 Java 源引用其他类，则这些源必须从系统的 CLASSPATH 环境变量中访问； 否则，在生成模式时将出现错误。 无法控制生成的模式文件的名称。

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

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

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

关于模式到 Java 绑定

当您针对基本示例中使用的po.xsd XML 模式运行 JAXB 绑定编译器（解组读取，修改编组，解组验证）时，JAXB 绑定编译器将生成一个名为primer.po的 Java 包，其中包含下表中描述的类。

表：基本示例中的基于模式的 JAXB 类

这些类及其与基本示例源 XML 模式的特定绑定在以下表中描述。

表：基本示例的模式到 Java 绑定

|

<xsd:schema xmlns:xsd=
 "http://www.w3.org/2001/XMLSchema">

|

<xsd:complexType 
  name="PurchaseOrderType">
  <xsd:sequence>
    <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>

|

<xsd:complexType 
  name="USAddress">
  <xsd:sequence>
    <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>

|

<xsd:complexType 
  name="Items">
  <xsd:sequence>
    <xsd:element 
      name="item" 
      minOccurs="1" 
      maxOccurs="unbounded">

|

<xsd:complexType>
  <xsd:sequence>
    <xsd:element 
      name="productName" 
      type="xsd:string"/>
    <xsd:element 
      name="quantity">
      <xsd:simpleType>
        <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>

|

</xsd:element>
</xsd:sequence>
</xsd:complexType>

|

<!-- Stock Keeping Unit, a code for 
    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 类
  
• ObjectFactory 类
  
• PurchaseOrderType 类
  
• USAddress 类
  

Items 类

在 Items.java 中：

• Items 类是 primer.po 包的一部分。
  
• 该类为 Items 和 ItemType 提供了公共接口。
  
• 此类的实例化内容绑定到 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 类

在 ObjectFactory.java 中：

• ObjectFactory 类是 primer.po 包的一部分。
  
• ObjectFactory 提供了用于在 Java 内容树中实例化表示 XML 内容的 Java 接口的工厂方法。
  
• 方法名是通过连接生成的：

• 字符串常量 create。
  
• 所有外部 Java 类名称，如果 Java 内容接口嵌套在另一个接口中。
  
• Java 内容接口的名称。
  

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

PurchaseOrderType 类

在 PurchaseOrderType.java 中：

• PurchaseOrderType 类是 primer.po 包的一部分。
  
• 此类的实例化内容绑定到名为 PurchaseOrderType 的 XML 模式子元素。
  
• PurchaseOrderType是一个公共接口，提供以下方法：

• 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 类

在 USAddress.java 中：

• USAddress 类是 primer.po 包的一部分。
  
• 此类的实例化内容绑定到名为 USAddress 的 XML 模式元素。
  
• USAddress是一个公共接口，提供以下方法：

• 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);
  

Java 中文官方教程 2022 版（四十九）(2)https://developer.aliyun.com/article/1488530