Java-to-Schema Examples
Java-to-Schema 示例显示了如何使用 注解 将 Java 类 Map 到 XMLPattern。
j2s-create-marshal Example
j2s-create-marshal 示例说明了 Java 到 Pattern 的数据绑定。它演示了 JAXB 带 注解 的类的编组和解组,还演示了如何使用从 JAXBMap 的类生成的 Pattern 文件在解组时启用 JAXP 1.3 验证。
架构文件bc\.xsd
是使用以下命令生成的:
schemagen src/cardfile/*.java
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/
目录,然后键入以下内容:
ant
j2s-xmlAccessorOrder Example
j2s-xmlAccessorOrder 示例显示了如何使用@XmlAccessorOrder
和@XmlType\.propOrder
注解来指示 Java 内容对 XML 内容进行编组和解组的 Sequences。
通过 Java 到架构的 Map,JavaBean 的属性和字段被 Map 为 XML Schema 类型。类元素被 Map 为 XML Schema 复杂类型或 XML Schema 简单类型。当前未指定生成 Pattern 类型的默认元素 Sequences,因为 Java 反射不强加返回 Sequences。缺少可靠的元素排序会对应用程序的可移植性产生负面影响。您可以使用两个 注解@XmlAccessorOrder
和@XmlType\.propOrder
来定义必须在 JAXB 提供程序之间可移植的应用程序的架构元素 Sequences。
使用@XmlAccessorOrder 注解定义架构元素 Sequences
@XmlAccessorOrder
注解 强加了两个元素排序算法AccessorOrder\.UNDEFINED
或AccessorOrder\.ALPHABETICAL
之一。 AccessorOrder\.UNDEFINED
是默认设置。Sequences 取决于系统的反射实现。 AccessorOrder\.ALPHABETICAL
算法按照java\.lang\.String\.CompareTo\(String anotherString\)
确定的字典 Sequences 对元素进行排序。
您可以在类对象上为 注解 类型ElementType\.PACKAGE
定义@XmlAccessorOrder
注解。在包装上定义@XmlAccessorOrder
注解时,格式规则的范围对于包装中的每个类都是活动的。在类上定义时,规则在该类的内容上有效。
一个包中可以有多个@XmlAccessorOrder
注解。最里面的(类)注解 优先于外面的 注解。例如,如果在一个程序包中定义了@XmlAccessorOrder\(AccessorOrder\.ALPHABETICAL\)
,并且在该程序包中的一个类上定义了@XmlAccessorOrder\(AccessorOrder\.UNDEFINED\)
,则该类的生成 Pattern 类型的内容将以未指定的 Sequences,而在其中的每个其他类,则生成 Pattern 类型的内容包装将按字母 Sequences 排列。
使用@XmlType 注解定义架构元素 Sequences
可以为类定义@XmlType
注解。 @XmlType
注解 中的 注解 元素propOrder\(\)
使您可以在生成的 Pattern 类型中指定内容 Sequences。在类上使用@XmlType\.propOrder
注解指定内容 Sequences 时,必须在参数列表中指定该类中的所有公共属性和公共字段。您要保留在参数列表之外的任何公共属性或字段都必须使用@XmlAttribute
或@XmlTransient
注解 进行 注解。
@XmlType\.propOrder
的默认内容 Sequences 为\{\}
或\{""\}
,未激活。在这种情况下,活动@XmlAccessorOrder
注解 优先。当@XmlType\.propOrder
注解指定了类内容 Sequences 时,它优先于该类或包上的任何活动@XmlAccessorOrder
注解。如果在类上指定了@XmlAccessorOrder
和@XmlType\.propOrder\(A, B, \.\.\.\)
注解,则无论 注解 语句的 Sequences 如何,propOrder
始终优先。例如,在下面的代码段中,@XmlAccessorOrder
注解 位于@XmlType\.propOrder
注解 之前。
@XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
@XmlType(propOrder={"name", "city"})
public class USAddress {
// ...
public String getCity() {return city;}
public void setCity(String city) {this.city = city;}
public String getName() {return name;}
public void setName(String name) {this.name = name;}
// ...
}
在下面的代码段中,@XmlType\.propOrder
注解 位于@XmlAccessorOrder
注解 之前。
@XmlType(propOrder={"name", "city"})
@XmlAccessorOrder(AccessorOrder.ALPHABETICAL)
public class USAddress {
// ...
public String getCity() {return city;}
public void setCity(String city) {this.city = city;}
public String getName() {return name;}
public void setName(String name) {this.name = name;}
// ...
}
在这两种情况下,propOrder
优先,并且生成以下相同的架构内容:
<xs:complexType name="usAddress">
<xs:sequence>
<xs:element
name="name"
type="xs:string"
minOccurs="0"/>
<xs:element
name="city"
type="xs:string"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
示例中的架构内容排序
采购订单代码示例使用包和类级别的@XmlAccessorOrder
注解 以及类的@XmlType\.propOrder
注解 演示了架构内容排序的效果。
类别package\-info\.java
将@XmlAccessorOrder
定义为ALPHABETICAL
。该规则以生成的架构内容 Sequences 影响类PurchaseOrderType
中的公共字段shipTo
和billTo
。 USAddress
类在该类上定义@XmlType\.propOrder
注解,该 注解 演示了用户定义的属性 Sequences 取代了生成的 Pattern 中的ALPHABETICAL
Sequences。
可以在 jaxb-ri-install /samples/j2s\-xmlAccessorOrder/build/schemas/
目录中找到生成的 Pattern 文件。
使用 Ant 构建和运行 j2s-xmlAccessorOrder 示例
要使用 Ant 编译并运行 j2s-xmlAccessorOrder 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlAccessorOrder/
目录并键入以下内容:
ant
j2s-xmlAdapter Example
j2s-xmlAdapter 示例演示了如何使用XmlAdapter
interface和@XmlJavaTypeAdapter
注解 来提供 XML 内容到HashMap
(字段)的自定义 Map,该字段使用int
作为键和String
作为值。
interfaceXmlAdapter
和 注解@XmlJavaTypeAdapter
用于在解组和编组期间对数据类型进行特殊处理。存在多种 XML 数据类型,它们的表示形式不容易 Map 到 Java 中(例如xs:DateTime
和xs:Duration
),而 Java 类型不能正确 Map 到 XML 表示形式中。例如,java\.util\.Collection
(例如List
)和java\.util\.Map
(例如HashMap
)的实现或非 JavaBean 类的实现。
针对此类情况,提供了XmlAdapter
interface和@XmlJavaTypeAdapter
注解。这种组合提供了一种可移植的机制,用于将 XML 内容读入和写入 Java 应用程序。
XmlAdapter
interface定义用于数据读取和写入的方法。
/*
* ValueType - Java class that provides an
* XML representation of the data.
* It is the object that is used for marshalling and
* unmarshalling.
*
* BoundType - Java class that is used to
* process XML content.
*/
public abstract class XmlAdapter<ValueType,BoundType> {
// Do-nothing constructor for the derived classes.
protected XmlAdapter() {}
// Convert a value type to a bound type.
public abstract BoundType unmarshal(ValueType v);
// Convert a bound type to a value type.
public abstract ValueType marshal(BoundType v);
}
您可以使用@XmlJavaTypeAdapter
注解将特定的XmlAdapter
实现与Target
类型,PACKAGE
,FIELD
,METHOD
,TYPE
或PARAMETER
关联。
j2s-xmlAdapter 示例显示了如何使用XmlAdapter
将 XML 内容 Map 到(自定义)HashMap
和从中 Map 出来。 KitchenWorldBasket
类中的HashMap
对象basket
使用int
类型的键和String
类型的值。这些数据类型应反映在读写的 XML 内容中,因此 XML 内容应如下例所示:
<basket>
<entry key="9027">glasstop stove in black</entry>
<entry key="288">wooden spoon</entry>
</basket>
为 Java 类型HashMap
生成的默认架构不能反映所需的格式。
<xs:element name="basket">
<xs:complexType>
<xs:sequence>
<xs:element
name="entry"
minOccurs="0"
maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element
name="key"
minOccurs="0"
type="xs:anyType"/>
<xs:element
name="value"
minOccurs="0"
type="xs:anyType"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
在默认的HashMap
Pattern 中,key 和 value 都是元素,并且都是数据类型anyType
。 XML 内容如下所示:
<basket>
<entry>
<key>9027</key>
<value>glasstop stove in black</value>
</entry>
<entry>
<key>288</key>
<value>wooden spoon</value>
</entry>
</basket>
要解决此问题,该示例使用两个 Java 类PurchaseList
和PartEntry
,它们反映了解组和编组内容所需的架构格式。为这些类生成的 XMLPattern 如下:
<xs:complexType name="PurchaseListType">
<xs:sequence>
<xs:element
name="entry"
type="partEntry"
nillable="true"
maxOccurs="unbounded"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="partEntry">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute
name="key"
type="xs:int"
use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
AdapterPurchaseListToHashMap
类实现XmlAdapter
interface。在KitchenWorldBasket
类中,@XmlJavaTypeAdapter
注解 用于将AdapterPurchaseListToHashMap
与字段HashMap
basket
配对。这种配对导致AdapterPurchaseListToHashMap
的编组或解组方法被调用,以对KitchenWorldBasket
进行任何相应的编组或解组操作。
使用 Ant 构建和运行 j2s-xmlAdapter 示例
要使用 Ant 编译并运行 j2s-xmlAdapter 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlAdapter/
目录并键入以下内容:
ant
j2s-xmlAttribute Example
j2s-xmlAttribute 示例显示了如何使用@XmlAttribute
注解定义将被视为 XML 属性的属性或字段。
@XmlAttribute
注解 将字段或 JavaBean 属性 Map 到 XML 属性。施加以下规则:
-
静态 final 字段 Map 到 XML 固定属性。
-
当字段或属性是集合类型时,该集合类型的项必须 Map 到架构简单类型。
-
当字段或属性不是集合类型时,该类型必须 Map 为架构简单类型。
遵循 JavaBean 编程范例时,属性由字段名称上的get
和set
前缀定义。
int zip;
public int getZip(){return zip;}
public void setZip(int z){zip=z;}
在 bean 类中,可以选择在以下三个组件之一上设置@XmlAttribute
注解:字段,setter 方法或 getter 方法。如果您在字段上设置@XmlAttribute
注解,则必须重命名 setter 方法,否则在编译时会发生命名冲突。如果在其中一种方法上设置@XmlAttribute
注解,则必须在 setter 或 getter 方法上都将其设置,但不能同时在两者上都设置。
XmlAttribute 示例显示了如何在静态 final 字段,字段而不是相应的 bean 方法之一,bean 属性(方法)以及除集合类型以外的字段上使用@XmlAttribute
注解。在USAddress
类中,字段,国家和邮政编码被标记为属性。 setZip
方法被禁用以避免编译错误。属性状态在 setter 方法上被标记为属性。您可以改用 getter 方法。在类PurchaseOrderType
中,字段cCardVendor
是非集合类型。满足成为简单类型的要求;它是enum
类型。
使用 Ant 构建和运行 j2s-xmlAttribute 示例
要使用 Ant 编译并运行 j2s-xmlAttribute 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlAttribute/
目录,然后键入以下内容:
ant
j2s-xmlRootElement Example
j2s-xmlRootElement 示例演示了使用@XmlRootElement
注解 为相应类的 XMLPattern 类型定义 XML 元素名称。
@XmlRootElement
注解 将类或enum
类型 Map 到 XML 元素。用于解组和编组的每种顶级 Java 类型至少需要一个元素定义。如果没有元素定义,则没有 XML 内容处理的起始位置。
@XmlRootElement
注解 使用类名称作为默认元素名称。您可以使用 注解 属性name
更改默认名称。如果这样做,则将指定的名称用作元素名称和类型名称。元素和类型名称不同是一种常见的方案实践。您可以使用@XmlType
注解设置元素类型名称。
@XmlRootElement
注解的名称空间属性用于定义元素的名称空间。
使用 Ant 构建和运行 j2s-xmlRootElement 示例
要使用 Ant 编译并运行 j2s-xmlRootElement 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlRootElement/
目录并键入以下内容:
ant
j2s-xmlSchemaType Example
j2s-xmlSchemaType 示例演示了使用 注解@XmlSchemaType
来定制属性或字段到 XML 内置类型的 Map。
@XmlSchemaType
注解可用于将 Java 类型 Map 到 XML 内置类型之一。在将 Java 类型 Map 到九种日期/时间原始数据类型之一时,此注解最有用。
在包级别定义@XmlSchemaType
注解 时,标识既需要 XML 内置类型名称,又需要相应的 Java 类型类。字段或属性上的@XmlSchemaType
定义优先于包定义。
XmlSchemaType 类示例演示如何在包级别,字段和属性上使用@XmlSchemaType
注解。文件TrackingOrder
具有两个字段orderDate
和deliveryDate
,它们被定义为XMLGregorianCalendar
类型。生成的 Pattern 会将这些元素定义为 XML 内置类型gMonthDay
。此关系在package\-info\.java
文件中的包装上定义。文件TrackingOrder
中的字段shipDate
也定义为XMLGregorianCalendar
类型,但是@XmlSchemaType
注解 语句覆盖包定义,并将字段指定为date
类型。属性方法getTrackingDuration
将 Pattern 元素定义为基本类型duration
,而不是 Java 类型String
。
使用 Ant 构建和运行 j2s-xmlSchemaType 示例
要使用 Ant 编译并运行 j2s-xmlSchemaType 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlSchemaType/
目录并键入以下内容:
ant
j2s-xmlType Example
j2s-xmlType 示例演示了@XmlType
注解 的用法。 @XmlType
注解 将类或enum
类型 Map 到 XMLPattern 类型。
一个类必须具有公共零参数构造函数或静态零参数工厂方法,才能被此 注解Map。解组期间使用这些方法之一来创建类的实例。工厂方法可以位于工厂类或现有类中。
对于使用哪种方法进行编组,有一个优先 Sequences:
-
如果 注解 中标识了工厂类,则还必须标识该类中的相应工厂方法,并将使用该方法。
-
如果 注解 中标识了工厂方法,但未标识工厂类,则工厂方法必须位于当前类中。即使存在公共零参数构造函数方法,也将使用 factory 方法。
-
如果 注解 中未标识任何工厂方法,则该类必须包含公共零参数构造函数方法。
在此示例中,工厂类为多个类提供了零 arg 工厂方法。类别OrderContext
上的@XmlType
注解 引用了工厂类别。解组器在此类中使用已标识的工厂方法。
public class OrderFormsFactory {
public OrderContext newOrderInstance() {
return new OrderContext()
}
public PurchaseOrderType {
newPurchaseOrderType() {
return new newPurchaseOrderType();
}
}
@XmlType(name="oContext",
factoryClass="OrderFormsFactory",
factoryMethod="newOrderInstance")
public class OrderContext {
public OrderContext() {
// ...
}
}
}
在此示例中,在类中定义了工厂方法,该方法还包含标准的类构造。由于定义了factoryMethod
值而未定义factoryClass
,因此在解组期间将使用工厂方法newOrderInstance
。
@XmlType(name="oContext",
factoryMethod="newOrderInstance")
public class OrderContext {
public OrderContext() {
// ...
}
public OrderContext newOrderInstance() {
return new OrderContext();
}
}
使用 Ant 构建和运行 j2s-xmlType 示例
要使用 Ant 编译并运行 j2s-xmlType 示例,请在终端窗口中,转到 jaxb-ri-install /samples/j2s\-xmlType/
目录并键入以下内容:
ant