JAXB示例

以下部分描述了如何使用包含在JAXB RI包中的示例应用程序。JAXB RI包可以从http://jaxb.java.net下载和安装。示例位于jaxb-ri-install/samples/目录中。这些示例演示并构建了JAXB的关键特性和概念。请按照所述的顺序进行操作。

阅读完本节后，您应该对JAXB感到足够熟悉，能够：

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

本文档描述了三组示例：

• 基本示例（修改编组、解组、验证）演示了基本的JAXB概念，如使用默认设置和绑定进行解组、编组和验证XML内容。
• 自定义示例（内联自定义、数据类型转换器、外部自定义）演示了自定义XML模式到Java对象的默认绑定的各种方式。
• Java到模式示例演示了如何使用注释将Java类映射到XML模式。

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

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

以下表格简要描述了基本的、自定义的和Java-to-Schema JAXB示例。

表格：基本的JAXB示例

表格：自定义JAXB示例

表格：Java-to-Schema JAXB示例

JAXB编译器选项

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

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

xjc [-选项 ...] <模式文件/URL/目录/包>... [-b >绑定信息文件<] ...

如果指定了 目录，将编译目录中的所有模式文件。如果指定了 包，将编译 /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

指定用于<jxb:javaType>和<xjc:superClass>自定义的客户端应用程序类文件的位置。

-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. Generated 注解标记生成的代码。

-episode FILE

为单独编译生成 episode 文件。

JAXB Schema Generator选项

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

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

schemagen [-d 路径] 
    [java源文件]

-d 路径选项指定处理器生成的和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, 用于标识产品的代码 -->

<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 复杂类型 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 接口以表示 Java 内容树中的 XML 内容的工厂方法。
• 方法名是通过连接以下内容生成的：
  • 字符串常量 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);