Java-to-Schema 示例

原文： https://docs.oracle.com/javase/tutorial/jaxb/intro/j2schema.html

Java-to-Schema 示例演示如何使用注释将 Java 类映射到 XML 模式。

j2s-create-marshal 示例

j2s-create-marshal 示例说明了 Java 到模式的数据绑定。它演示了 JAXB 注释类的编组和解组，还展示了如何使用从 JAXB 映射类生成的模式文件在解组时启用 JAXP 1.3 验证。

使用以下命令生成模式文件bc.xsd ：

  1. schemagen src/cardfile/*.java
  2. cp schema1.xsd bc.xsd

注意schema1.xsd被复制到bc.xsd ; schemagen不允许您指定所选的架构名称。

使用 Ant 构建并运行 j2s-create-marshal 示例

要在终端窗口中使用 Ant 编译和运行 j2s-create-marshal 示例，请转到 jaxb-ri-install / samples / j2s-create-marshal /目录，输入以下内容：

  1. ant

j2s-xmlAccessorOrder 示例

j2s-xmlAccessorOrder 示例显示了如何使用@XmlAccessorOrder和@XmlType.propOrder注释来指定 XML 内容由 Java 类型编组和解组的顺序。

使用 Java 到模式映射，JavaBean 的属性和字段将映射到 XML 模式类型。类元素映射到 XML Schema 复杂类型或 XML Schema 简单类型。当前未指定生成的模式类型的默认元素顺序，因为 Java 反射不会强制返回订单。缺乏可靠的元素排序会对应用程序的可移植性产生负面影响您可以使用两个注释@XmlAccessorOrder和@XmlType.propOrder来定义必须可跨 JAXB 供应器移植的应用程序的架构元素排序。

使用@XmlAccessorOrder Annotation 定义模式元素排序

@XmlAccessorOrder注释强加了两种元素排序算法之一， AccessorOrder.UNDEFINED或AccessorOrder.ALPHABETICAL 。 AccessorOrder.UNDEFINED是默认设置。顺序取决于系统的反射实现。 AccessorOrder.ALPHABETICAL算法按照java.lang.String.CompareTo（String anotherString）确定的字典顺序对元素进行排序。

您可以在类对象上为注释类型ElementType.PACKAGE定义@XmlAccessorOrder注释。当在包上定义@XmlAccessorOrder注释时，格式化规则的范围对于包中的每个类都是活动的。在类上定义时，该规则对该类的内容有效。

包中可以有多个@XmlAccessorOrder注释。最内层（类）注释优先于外部注释。例如，如果在包上定义@XmlAccessorOrder（AccessorOrder.ALPHABETICAL）并且在该包中的类上定义了@XmlAccessorOrder（AccessorOrder.UNDEFINED），则生成的内容该类的模式类型将以未指定的顺序排列，并且包中每个其他类的生成的模式类型的内容将按字母顺序排列。

使用@XmlType Annotation 定义模式元素排序

可以为类定义@XmlType注释。 @XmlType注释中的注释元素propOrder()使您能够在生成的模式类型中指定内容顺序。在类上使用@ XmlType.propOrder批注指定内容顺序时，必须在参数列表中指定类中的所有公共属性和公共字段。您希望不在参数列表中的任何公共属性或字段必须使用@XmlAttribute或@XmlTransient注释进行注释。

@XmlType.propOrder的默认内容顺序为{}或{“”} ，未激活。在这种情况下，活动@XmlAccessorOrder注释优先。当@XmlType.propOrder注释指定类内容顺序时，它优先于类或包上的任何活动@XmlAccessorOrder注释。如果在类上指定了@XmlAccessorOrder和@ XmlType.propOrder（A，B，...）注释，则propOrder始终优先于注释语句的顺序。例如，在以下代码段中， @XmlAccessorOrder注释位于@ XmlType.propOrder注释之前。

  1. @XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
  2. @XmlType(propOrder={"name", "city"})
  4. public class USAddress {
  5.     // ...
  6.     public String getCity() {return city;}
  7.     public void setCity(String city) {this.city = city;}
  8.     public String getName() {return name;}
  9.     public void setName(String name) {this.name = name;}
  10.     // ...
  11. }

在以下代码段中， @ XmlType.propOrder注释位于@XmlAccessorOrder注释之前。

  1. @XmlType(propOrder={"name", "city"})
  2. @XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
  3. public class USAddress {
  4.     // ...
  5.     public String getCity() {return city;}
  6.     public void setCity(String city) {this.city = city;}
  7.     public String getName() {return name;}
  8.     public void setName(String name) {this.name = name;}
  9.     // ...
  10. }

在这两种情况下， propOrder优先，并生成以下相同的模式内容：

  1. <xs:complexType name="usAddress">
  2.     <xs:sequence>
  3.         <xs:element 
  4.             name="name" 
  5.             type="xs:string" 
  6.             minOccurs="0"/>
  7.         <xs:element 
  8.             name="city" 
  9.             type="xs:string" 
  10.             minOccurs="0"/>
  11.     </xs:sequence>
  12. </xs:complexType>

示例中的模式内容排序

采购订单代码示例使用包和类级别的@XmlAccessorOrder注释以及类上的@ XmlType.propOrder注释来演示模式内容排序的效果。

类package-info.java将@XmlAccessorOrder定义为包的ALPHABETICAL 。类PurchaseOrderType中的公共字段shipTo和billTo受此规则在生成的模式内容顺序中受到影响。类USAddress在类上定义@ XmlType.propOrder注释，该注释演示了生成的模式中用户定义的属性顺序取代ALPHABETICAL顺序。

生成的模式文件可以在 jaxb-ri-install / samples / j2s-xmlAccessorOrder / build / schemas /目录中找到。

使用 Ant 构建并运行 j2s-xmlAccessorOrder 示例

要在终端窗口中使用 Ant 编译和运行 j2s-xmlAccessorOrder 示例，请转到 jaxb-ri-install / samples / j2s-xmlAccessorOrder /目录并键入以下内容：

  1. ant

j2s-xmlAdapter 示例

j2s-xmlAdapter 示例演示了如何使用XmlAdapter接口和@XmlJavaTypeAdapter注释来提供 XML 内容到HashMap的自定义映射（字段）使用int作为键， String作为值。

接口XmlAdapter和注释@XmlJavaTypeAdapter用于在解组和编组期间对数据类型进行特殊处理。有多种 XML 数据类型，其表示不容易映射到 Java（例如， xs：DateTime和xs：Duration ），以及不映射的 Java 类型适当地进入 XML 表示。例如， java.util.Collection （如List ）和java.util.Map （如HashMap ）的实现或者用于非 JavaBean 类。

XmlAdapter接口和@XmlJavaTypeAdapter注释是为这些情况提供的。这种组合提供了一种便携式机制，用于在 Java 应用程序中读写 XML 内容。

XmlAdapter接口定义了数据读写的方法。

  1. /*
  2.  *  ValueType - Java class that provides an 
  3.  *  XML representation of the data. 
  4.  *  It is the object that is used for marshalling and 
  5.  *  unmarshalling.
  6.  *
  7.  *  BoundType - Java class that is used to 
  8.  *  process XML content.
  9.  */
  11. public abstract class XmlAdapter<ValueType,BoundType> {
  13.     // Do-nothing constructor for the derived classes.
  14.     protected XmlAdapter() {}
  16.     // Convert a value type to a bound type.
  17.     public abstract BoundType unmarshal(ValueType v);
  19.     // Convert a bound type to a value type.
  20.     public abstract ValueType marshal(BoundType v);
  21. }

您可以使用@XmlJavaTypeAdapter注释将特定XmlAdapter实现与目标类型， PACKAGE ， FIELD相关联]， METHOD ， TYPE或PARAMETER 。

j2s-xmlAdapter 示例演示了如何使用XmlAdapter将 XML 内容映射到（自定义） HashMap中。 HashMap对象，篮子，在类KitchenWorldBasket中，使用int类型的键和类型String [的值。这些数据类型应反映在读取和写入的 XML 内容中，因此 XML 内容应如下例所示：

  1. <basket>
  2.     <entry key="9027">glasstop stove in black</entry>
  3.     <entry key="288">wooden spoon</entry>
  4. </basket>

为 Java 类型HashMap生成的默认架构不反映所需的格式。

  1. <xs:element name="basket">
  2.     <xs:complexType>
  3.         <xs:sequence>
  4.             <xs:element 
  5.                 name="entry" 
  6.                 minOccurs="0" 
  7.                 maxOccurs="unbounded">
  8.                 <xs:complexType>
  9.                     <xs:sequence>
  10.                         <xs:element 
  11.                             name="key" 
  12.                             minOccurs="0"
  13.                             type="xs:anyType"/>
  14.                         <xs:element 
  15.                             name="value" 
  16.                             minOccurs="0" 
  17.                             type="xs:anyType"/>
  18.                     </xs:sequence>
  19.                 </xs:complexType>
  20.             </xs:element>
  21.         </xs:sequence>
  22.     </xs:complexType>
  23. </xs:element>

在默认的HashMap模式中，键和值都是元素，并且是数据类型anyType 。 XML 内容如下所示：

  1. <basket>
  2.     <entry>
  3.         <key>9027</key>
  4.         <value>glasstop stove in black</value>
  5.     </entry>
  6.     <entry>
  7.         <key>288</key>
  8.         <value>wooden spoon</value>
  9.     </entry>
  10. </basket>

为解决此问题，该示例使用两个 Java 类， PurchaseList和PartEntry ，它们反映了解组和编组内容所需的模式格式。为这些类生成的 XML 模式如下：

  1. <xs:complexType name="PurchaseListType">
  2.     <xs:sequence>
  3.         <xs:element 
  4.             name="entry" 
  5.             type="partEntry"
  6.             nillable="true" 
  7.             maxOccurs="unbounded"
  8.             minOccurs="0"/>
  9.     </xs:sequence>
  10. </xs:complexType>
  12. <xs:complexType name="partEntry">
  13.     <xs:simpleContent>
  14.         <xs:extension base="xs:string">
  15.             <xs:attribute
  16.                 name="key" 
  17.                 type="xs:int"
  18.                 use="required"/>
  19.         </xs:extension>
  20.     </xs:simpleContent>
  21. </xs:complexType>

类AdapterPurchaseListToHashMap实现XmlAdapter接口。在类KitchenWorldBasket中， @XmlJavaTypeAdapter注释用于将AdapterPurchaseListToHashMap与字段HashMap 篮子配对。这种配对导致AdapterPurchaseListToHashMap的编组或解组方法被调用KitchenWorldBasket上的任何相应的编组或解组动作。

使用 Ant 构建并运行 j2s-xmlAdapter 示例

要在终端窗口中使用 Ant 编译和运行 j2s-xmlAdapter 示例，请转到 jaxb-ri-install / samples / j2s-xmlAdapter /目录并键入以下内容：

  1. ant

j2s-xmlAttribute 示例

j2s-xmlAttribute 示例显示如何使用@XmlAttribute批注定义要作为 XML 属性处理的属性或字段。

@XmlAttribute批注将字段或 JavaBean 属性映射到 XML 属性。实现以下规则：

  • 静态 final 字段映射到 XML 固定属性。
  • 当字段或属性是集合类型时，集合类型的项必须映射到模式简单类型。
  • 当字段或属性不是集合类型时，类型必须映射到模式简单类型。

遵循 JavaBean 编程范例时，属性由字段名称上的get和设置前缀定义。

  1. int zip;
  2. public int getZip(){return zip;}
  3. public void setZip(int z){zip=z;}

在 bean 类中，您可以选择在以下三个组件之一上设置@XmlAttribute注释：字段，setter 方法或 getter 方法。如果在字段上设置@XmlAttribute注释，则必须重命名 setter 方法，否则编译时会出现命名冲突。如果在其中一个方法上设置@XmlAttribute注释，则必须在 setter 或 getter 方法上设置，但不能在两者上设置。

XmlAttribute 示例演示如何在静态 final 字段，字段而不是相应的 bean 方法之一，bean 属性（方法）和字段上使用@XmlAttribute注释。除了集合类型。在类USAddress中，字段，国家和 zip 被标记为属性。 setZip方法被禁用以避免编译错误。属性状态被标记为 setter 方法的属性。您可以使用 getter 方法。在类PurchaseOrderType中，字段cCardVendor是非集合类型。它符合简单类型的要求;它是enum类型。

使用 Ant 构建并运行 j2s-xmlAttribute 示例

要使用 Ant 编译并运行 j2s-xmlAttribute 示例，请在终端窗口中转到 jaxb-ri-install / samples / j2s-xmlAttribute /目录并键入以下内容：

  1. ant

j2s-xmlRootElement 示例

j2s-xmlRootElement 示例演示了如何使用@XmlRootElement批注为相应类的 XML 模式类型定义 XML 元素名称。

@XmlRootElement注释将类或枚举类型映射到 XML 元素。每个用于解组和编组的顶级 Java 类型至少需要一个元素定义。如果没有元素定义，则没有 XML 内容处理的起始位置。

@XmlRootElement注释使用类名作为默认元素名称。您可以使用注释属性名称更改默认名称。如果这样做，指定的名称将用作元素名称和类型名称。元素和类型名称的通用模式实践是不同的。您可以使用@XmlType注释来设置元素类型名称。

@XmlRootElement批注的 namespace 属性用于定义元素的命名空间。

使用 Ant 构建并运行 j2s-xmlRootElement 示例

要在终端窗口中使用 Ant 编译和运行 j2s-xmlRootElement 示例，请转到 jaxb-ri-install / samples / j2s-xmlRootElement /目录并键入以下内容：

  1. ant

j2s-xmlSchemaType 示例

j2s-xmlSchemaType 示例演示如何使用注释@XmlSchemaType来自定义属性或字段到 XML 内置类型的映射。

@XmlSchemaType注释可用于将 Java 类型映射到 XML 内置类型之一。在将 Java 类型映射到九种日期/时间原始数据类型之一时，此注释最有用。

当在包级别定义@XmlSchemaType注释时，标识需要 XML 内置类型名称和相应的 Java 类型类。字段或属性上的@XmlSchemaType定义优先于包定义。

XmlSchemaType 类示例显示如何在包级别，字段和属性上使用@XmlSchemaType批注。文件TrackingOrder有两个字段， orderDate和deliveryDate ，它们被定义为XMLGregorianCalendar类型。生成的模式将这些元素定义为 XML 内置类型gMonthDay 。此关系在文件package-info.java中的包上定义。文件中的字段shipDateTrackingOrder也被定义为XMLGregorianCalendar类型，但@XmlSchemaType注释语句覆盖包定义并指定字段为日期。属性方法getTrackingDuration定义要定义为基本类型持续时间而不是 Java 类型String的模式元素。

使用 Ant 构建并运行 j2s-xmlSchemaType 示例

要使用 Ant 编译并运行 j2s-xmlSchemaType 示例，请在终端窗口中转到 jaxb-ri-install / samples / j2s-xmlSchemaType /目录并键入以下内容：

  1. ant

j2s-xmlType 示例

j2s-xmlType 示例演示了@XmlType注释的使用。 @XmlType注释将类或枚举类型映射到 XML 架构类型。

类必须具有公共零参数构造器或静态零参数工厂方法才能通过此批注进行映射。在解组期间使用这些方法之一来创建类的实例。工厂方法可以位于工厂类或现有类中。

关于解组使用哪种方法有一个优先顺序：

  • 如果在注释中标识了工厂类，则还必须标识该类中的相应工厂方法，并且将使用该方法。
  • 如果在注释中标识了工厂方法但未标识工厂类，则工厂方法必须位于当前类中。即使存在公共零参数构造器方法，也使用工厂方法。
  • 如果注释中未标识工厂方法，则该类必须包含公共零参数构造器方法。

在此示例中，工厂类为多个类提供零 arg 工厂方法。类OrderContext上的@XmlType注释引用工厂类。 unmarshaller 在此类中使用已识别的工厂方法。

  1. public class OrderFormsFactory {
  3.     public OrderContext newOrderInstance() {
  4.         return new OrderContext()
  5.     }
  7.     public PurchaseOrderType {
  8.         newPurchaseOrderType() {
  9.             return new newPurchaseOrderType();
  10.         }
  11.     }
  13.     @XmlType(name="oContext",
  14.         factoryClass="OrderFormsFactory",
  15.         factoryMethod="newOrderInstance")
  16.     public class OrderContext {
  17.         public OrderContext() {
  18.             // ...
  19.         }
  20.     }
  21. }

在此示例中，工厂方法在类中定义，该类还包含标准类构造。因为定义了factoryMethod值并且没有定义factoryClass ，所以在解组期间使用工厂方法newOrderInstance 。

  1. @XmlType(name="oContext", 
  2.     factoryMethod="newOrderInstance")
  3. public class OrderContext {
  5.     public OrderContext() {
  6.         // ...
  7.     }
  9.     public OrderContext newOrderInstance() {
  10.         return new OrderContext();
  11.     }
  12. }

使用 Ant 构建并运行 j2s-xmlType 示例

要在终端窗口中使用 Ant 编译和运行 j2s-xmlType 示例，请转到 jaxb-ri-install / samples / j2s-xmlType /目录并键入以下内容：

  1. ant