第 33 章 使用 XML 元素
摘要
XML Schema 元素用于定义 XML 文档中的元素实例。元素在 XML Schema 文档的全局范围内定义，或者它们定义为复杂类型的成员。在全局范围内定义它们时，Apache CXF 将它们映射到可更轻松地操作的 JAXB 元素类。
概述
XML 文档中的一个元素实例由 XML Schema 文档全局范围内 XML Schema 元素 元素定义，以便 Java 开发人员能够更轻松地使用元素，Apache CXF 将全局范围的元素映射到特殊的 JAXB 元素类，或生成与其内容类型匹配的 Java 类。
元素的 map 如何取决于使用 type 属性引用的指定类型定义，或者 元素是使用 in-line 类型定义定义的。使用中类型定义定义的元素映射到 Java 类。
建议元素使用指定类型来定义，因为架构中的其他元素无法重复使用类型。
XML Schema 映射
在 XML Schema 元素中，使用 元素 定义。元素 元素具有一个必需属性。name 指定它出现在 XML 文档中的元素名称。
除了 name 属性 元素元素 外，还具有 表 33.1 “用于定义元素的属性” 中列出的可选属性。
| 属性 | 描述 |
|---|---|
|
| 指定元素的类型。类型可以是任何 XML Schema 原语类型，也可以是合同中定义的任何指定复杂类型。如果没有指定此属性，则需要包含 in-line type 定义。 |
|
|
指定元素是否可以完全从文档中保留。如果将 |
|
|
指定是否在实例文档中使用某一元素。 |
|
| 指定可替换为这个元素的元素名称。有关使用类型替换的详情，请参考 第 37 章 element Substitution。 |
|
| 指定元素的默认值。有关此属性影响代码生成的详情，请参考 “带有默认值的元素的 Java 映射”一节。 |
|
| 为元素指定固定值。 |
例 33.1 “简单 XML Schema 元素定义” 显示简单的元素定义。
例 33.1. 简单 XML Schema 元素定义
<element name="joeFred" type="xsd:string" />
元素也可以使用 in-line type 定义来定义自己的类型。使用 complexType 元素或 simpleType 元素来指定在线类型。指定数据类型是否比较复杂或简单后，您可以使用每种数据类型可用的工具定义任何类型的数据。
例 33.2 “带有在线类型的 XML Schema 元素定义” 显示带有在线类型定义的元素定义。
例 33.2. 带有在线类型的 XML Schema 元素定义
<element name="skate">
<complexType>
<sequence>
<element name="numWheels" type="xsd:int" />
<element name="brand" type="xsd:string" />
</sequence>
</complexType>
</element>带有指定类型的元素的 Java 映射
默认情况下，全局定义的元素映射到 JAXBElement<T > 对象，其中模板类由 element 元素的 type 属性的值决定。对于原语类型，模板类使用 “打包程序类”一节 中描述的打包程序类映射进行派生。对于复杂的类型，生成的 Java 类用于支持复杂类型，用作模板类。
为支持映射并减轻开发人员对元素的 QName 无关，为每个全局定义元素生成一个对象工厂方法，如 例 33.3 “全局范围元素的对象因素方法” 所示。
例 33.3. 全局范围元素的对象因素方法
public class ObjectFactory {
private final static QName _name_QNAME = new QName("targetNamespace", "localName");
...
@XmlElementDecl(namespace = "targetNamespace", name = "localName")
public JAXBElement<type> createname(type value);
}例如： 例 33.1 “简单 XML Schema 元素定义” 中定义的元素会导致对象工厂方法在 例 33.4 “简单元素的对象因素” 中显示。
例 33.4. 简单元素的对象因素
public class ObjectFactory {
private final static QName _JoeFred_QNAME = new QName("...", "joeFred");
...
@XmlElementDecl(namespace = "...", name = "joeFred")
public JAXBElement<String> createJoeFred(String value);
}例 33.5 “使用全局范围元素” 显示了在 Java 中使用全局范围元素的示例。
例 33.5. 使用全局范围元素
JAXBElement<String> element = createJoeFred("Green");
String color = element.getValue();在 WSDL 中使用带有指定类型的元素
如果使用全局范围元素来定义消息部分，则生成的 Java 参数不是 JAXBElement<T> 的实例。相反，它映射到常规的 Java 类型或类。
由于 例 33.6 “WSDL 使用元素作为消息部分” 中显示的 WSDL 片段，生成的方法的参数类型为 String。
例 33.6. WSDL 使用元素作为消息部分
<?xml version="1.0" encoding=";UTF-8"?>
<wsdl:definitions name="HelloWorld"
targetNamespace="http://apache.org/hello_world_soap_http"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://apache.org/hello_world_soap_http"
xmlns:x1="http://apache.org/hello_world_soap_http/types"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<wsdl:types>
<schema targetNamespace="http://apache.org/hello_world_soap_http/types"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"><element name="sayHi">
<element name="sayHi" type="string"/>
<element name="sayHiResponse" type="string"/>
</schema>
</wsdl:types>
<wsdl:message name="sayHiRequest">
<wsdl:part element="x1:sayHi" name="in"/>
</wsdl:message>
<wsdl:message name="sayHiResponse">
<wsdl:part element="x1:sayHiResponse" name="out"/>
</wsdl:message>
<wsdl:portType name="Greeter">
<wsdl:operation name="sayHi">
<wsdl:input message="tns:sayHiRequest" name="sayHiRequest"/>
<wsdl:output message="tns:sayHiResponse" name="sayHiResponse"/>
</wsdl:operation>
</wsdl:portType>
...
</wsdl:definitions>
例 33.7 “使用全局元素的 Java 方法作为部分” 显示为 sayHi 操作生成的方法签名。
例 33.7. 使用全局元素的 Java 方法作为部分
StringsayHiStringin
带有在线类型的元素的 Java 映射
当使用在线类型定义元素时，它按照用于映射其他类型到 Java 的规则映射到 Java。第 34 章 使用简单类型 中描述了简单类型的规则。复杂类型的规则包括在 第 35 章 使用复杂类型 中。
当为带有在线类型定义的元素生成 Java 类时，生成的类使用 @XmlRootElement 注释进行解码。@XmlRootElement 注释具有两个有用的属性： name 和 namespace。这些属性包括在 表 33.2 “@XmlRootElement 注解的属性” 中。
| 属性 | 描述 |
|---|---|
|
|
指定 XML Schema |
|
| 指定定义元素的命名空间。如果此元素在目标命名空间中定义，则不会指定该属性。 |
如果元素满足一个或多个条件，则不会使用 @XmlRootElement 注释：
-
元素的
nillable属性设置为true 元素是替换组的头元素
有关替换组的更多信息，请参阅 第 37 章 element Substitution。
Java 抽象元素的映射
当元素的 abstract 属性被设置为 true 时，不会生成用于实例化类型的实例的对象工厂方法。如果元素是使用在线类型定义的，则生成支持在线类型的 Java 类。
带有默认值的元素的 Java 映射
当元素 的默认 属性被使用 defaultValue 属性添加到生成的 @XmlElementDecl 注释中。例如： 例 33.8 “带有默认值的 XML Schema 元素” 中定义的元素会导致对象工厂方法在 例 33.9 “带有默认值的元素对象因素方法” 中显示。
例 33.8. 带有默认值的 XML Schema 元素
<element name="size" type="xsd:int" default="7"/>
例 33.9. 带有默认值的元素对象因素方法
@XmlElementDecl(namespace = "...", name = "size", defaultValue = "7")
public JAXBElement<Integer> createUnionJoe(Integer value) {
return new JAXBElement<Integer>(_Size_QNAME, Integer.class, null, value);
}