现在建网站多少钱,软件开发的本质,佛山市城乡住房建设局网站首页,郑州哪家做网站最好原文#xff1a;docs.oracle.com/javase/tutorial/reallybigindex.html JAXB 示例 原文#xff1a;docs.oracle.com/javase/tutorial/jaxb/intro/examples.html 以下部分描述如何使用包含在 JAXB RI 捆绑包中的示例应用程序。JAXB RI 捆绑包可从jaxb.java.net获取。下载并安装… 原文docs.oracle.com/javase/tutorial/reallybigindex.html 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 示例
示例名称描述Modify Marshal演示如何修改 Java 内容树。Unmarshal Validate演示如何在解组期间启用验证。
表定制 JAXB 示例
示例名称描述Customize Inline演示如何通过在 XML 模式中使用内联注解来定制默认的 JAXB 绑定。Datatype Converter演示了将 XML simpleType定义绑定到 Java 数据类型的替代、更简洁的绑定方法类似于内联定制示例。External Customize演示如何使用外部绑定声明文件来传递对 JAXB 绑定编译器的只读模式进行绑定自定义。
表Java 到模式 JAXB 示例
示例名称描述Create Marshal演示如何使用 ObjectFactory 类创建 Java 内容树并将其编组为 XML 数据。还演示了如何向 JAXB 列表属性添加内容。XmlAccessorOrder演示如何在 Java 类中使用XmlAccessorOrder和XmlType.propOrder映射注解来控制 Java 类型在编组或解组 XML 内容时的顺序。XmlAdapter演示如何使用接口XmlAdapter和注解XmlJavaTypeAdapter为使用整数int作为键和字符串String作为值的HashMap字段提供自定义映射 XML 内容的方法。XmlAttribute演示如何使用注解XmlAttribute来定义一个属性或字段作为 XML 属性处理。XmlRootElement演示如何使用注解XmlRootElement为相应类的 XML 模式类型定义 XML 元素名称。XmlSchemaType Class演示如何使用注解XmlSchemaType来自定义属性或字段与 XML 内置类型的映射。XmlType演示如何使用注解XmlType将一个类或enum类型映射到 XML 模式类型。
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
指定用于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.生成的注释标记生成的代码。
-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 类
类描述primer/po/Items.java公共接口绑定到名为Items的complexType模式。primer/po/ObjectFactory.java公共类扩展com.sun.xml.bind.DefaultJAXBContextImpl 用于创建指定接口的实例。 例如ObjectFactory的createComment()方法实例化Comment对象。primer/po/PurchaseOrderType.java公共接口绑定到名为PurchaseOrderType的complexType模式。primer/po/USAddress.java公共接口绑定到名为USAddress的complexType模式。
这些类及其与基本示例源 XML 模式的特定绑定在以下表中描述。
表基本示例的模式到 Java 绑定
XML SchemaJAXB Binding
|
xsd:schema xmlns:xsdhttp://www.w3.org/2001/XMLSchema |
xsd:complexType namePurchaseOrderTypexsd:sequencexsd:element nameshipTo typeUSAddress/xsd:element namebillTo typeUSAddress/xsd:element refcomment minOccurs0/xsd:element nameitemstypeItems//xsd:sequencexsd:attribute nameorderDatetypexsd:date/
/xsd:complexType
PurchaseOrderType.java
|
xsd:complexType nameUSAddressxsd:sequencexsd:element namename typexsd:string/xsd:element namestreet typexsd:string/xsd:element namecity typexsd:string/xsd:element namestate typexsd:string/xsd:element namezip typexsd:decimal//xsd:sequencexsd:attribute namecountry typexsd:NMTOKEN fixedUS/
/xsd:complexType
USAddress.java
|
xsd:complexType nameItemsxsd:sequencexsd:element nameitem minOccurs1 maxOccursunbounded
Items.java
|
xsd:complexTypexsd:sequencexsd:element nameproductName typexsd:string/xsd:element namequantityxsd:simpleTypexsd:restriction basexsd:positiveIntegerxsd:maxExclusive value100//xsd:restriction/xsd:simpleType/xsd:elementxsd:element nameUSPrice typexsd:decimal/xsd:element refcomment minOccurs0/xsd:element nameshipDate typexsd:date minOccurs0//xsd:sequencexsd:attribute namepartNum typeSKU userequired/
/xsd:complexType
Items.ItemType
|
/xsd:element
/xsd:sequence
/xsd:complexType |
!-- Stock Keeping Unit, a code for identifying products -- |
xsd:simpleType nameSKUxsd:restriction basexsd:stringxsd: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.ItemTypeObjectFactory 创建了方法 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);
基本示例 原文docs.oracle.com/javase/tutorial/jaxb/intro/basic.html 本节描述了基本的 JAXB 示例修改 Marshal、Unmarshal Validate演示了如何 将 XML 文档解组为 Java 内容树并访问其中包含的数据。 修改 Java 内容树。 使用 ObjectFactory 类创建 Java 内容树然后将其编组为 XML 数据。 在解组期间执行验证。 在运行时验证 Java 内容树。
修改 Marshal 示例
修改 Marshal 示例演示了如何修改 Java 内容树。 jaxb-ri-install/samples/modify-marshal/src/Main.java 类声明导入了三个标准 Java 类五个 JAXB 绑定框架类和 primer.po 包 import java.io.FileInputStream;
import java.io.IOException;
import java.math.BigDecimal;import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;import primer.po.*; 创建一个用于处理在 primer.po 中生成的类的 JAXBContext 实例。
JAXBContext jc JAXBContext.newInstance( primer.po ); 创建一个 Unmarshaller 实例并解组 po.xml 文件。 Unmarshaller u jc.createUnmarshaller();
PurchaseOrder po (PurchaseOrder)u.unmarshal(new FileInputStream(po.xml)); 使用 set 方法修改内容树中 address 分支中的信息。 USAddress address po.getBillTo();
address.setName(John Bob);
address.setStreet(242 Main Street);
address.setCity(Beverly Hills);
address.setState(CA);
address.setZip(new BigDecimal
address.setName(John Bob);
address.setStreet(242 Main Street);
address.setCity(Beverly Hills);
address.setState(CA);
address.setZip(new BigDecimal(90210)); 创建一个 Marshaller 实例并将更新后的 XML 内容编组到 system.out。使用 setProperty API 指定输出编码在本例中为格式化易读的 XML。 Marshaller m jc.createMarshaller();
m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
m.marshal(po, System.out);
使用 Ant 构建和运行修改 Marshal 示例
要使用 Ant 编译和运行修改 Marshal 示例在终端窗口中转到 jaxb-ri-install/samples/modify-marshal/ 目录并输入以下内容
ant
Unmarshal Validate 示例
Unmarshal Validate 示例演示了如何在解组期间启用验证。请注意JAXB 提供了在解组期间进行验证但不在编组期间进行验证的功能。有关验证的更多详细信息请参阅更多关于验证。 jaxb-ri-install/samples/unmarshal-validate/src/Main.java 类声明导入了一个标准 Java 类十一个 JAXB 绑定框架类和 primer.po 包 import java.io.File;import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import javax.xml.bind.UnmarshalException;
import javax.xml.bind.Unmarshaller;
import javax.xml.bind.ValidationEvent;
import javax.xml.bind.ValidationEventHandler;
import javax.xml.bind.ValidationEventLocator;import static javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI;
import javax.xml.validation.SchemaFactory;
import javax.xml.validation.Schema;import primer.po.*; 创建一个用于处理在 primer.po 包中生成的类的 JAXBContext 实例。 JAXBContext jc JAXBContext.newInstance(primer.po); 创建一个 Unmarshaller 实例。 Unmarshaller u jc.createUnmarshaller(); 默认的 JAXB Unmarshaller ValidationEventHandler 已启用以将验证警告和错误发送到 system.out。默认配置导致在遇到第一个验证错误时解组操作失败。 u.setValidating( true ); 尝试将 po.xml 文件解组为 Java 内容树。在此示例中po.xml 文件包含一个故意的错误。 PurchaseOrder po (PurchaseOrder)u.unmarshal(new FileInputStream(po.xml)); 默认验证事件处理程序处理验证错误生成输出到 system.out然后抛出异常。 } catch( UnmarshalException ue ) {System.out.println(Caught UnmarshalException);
} catch( JAXBException je ) { je.printStackTrace();
} catch( IOException ioe ) {ioe.printStackTrace();
}
使用 Ant 构建和运行 Unmarshal Validate 示例。
要使用 Ant 编译和运行 Unmarshal Validate 示例在终端窗口中转到 jaxb-ri-install/samples/unmarshal-validate/ 目录并输入以下内容
ant
自定义 JAXB 绑定 原文docs.oracle.com/javase/tutorial/jaxb/intro/custom.html 以下部分描述了几个示例这些示例是基于基本示例中演示的概念构建的。
本节的目标是演示如何使用自定义绑定声明来自定义 JAXB 绑定可以通过以下两种方式之一进行 作为内联注释在 XML 模式中 作为传递给 JAXB 绑定编译器的外部文件中的语句
与基本 JAXB 示例中的示例不同该示例侧重于在生成基于模式的 Java 绑定类之前对 XML 模式进行的自定义。 注意 JAXB 绑定自定义目前必须手动完成。JAXB 技术的目标之一是标准化绑定声明的格式从而可以创建自定义工具并在 JAXB 实现之间提供标准的交换格式。 本节介绍了可以对 JAXB 绑定和验证方法进行的自定义。更多信息请参见JAXB 规范。
为什么要自定义
在大多数情况下由 JAXB 绑定编译器生成的默认绑定就足够了。然而有些情况下您可能希望修改默认绑定。其中一些情况包括 为基于模式的 JAXB 包、类、方法和常量创建 API 文档通过向您的模式添加自定义 Javadoc 工具注释您可以解释与您的实现特定的概念、指南和规则。 为默认的 XML 名称到 Java 标识符映射无法自动处理的情况提供语义上有意义的自定义名称例如 为解决名称冲突如 JAXB 规范 的附录 D.2.1 中所述。请注意JAXB 绑定编译器会检测并报告所有名称冲突。 为类型安全枚举常量提供名称这些名称不是有效的 Java 标识符例如枚举整数值。 为未命名模型组的 Java 表示提供更好的名称当它们绑定到 Java 属性或类时。 提供比默认从目标命名空间 URI 派生的包名称更有意义的名称。 覆盖默认绑定例如 指定模型组必须绑定到类而不是列表。 指定一个固定属性可以绑定到一个 Java 常量。 覆盖 XML 模式内置数据类型到 Java 数据类型的指定默认绑定。在某些情况下您可能希望引入一个替代的 Java 类该类可以表示内置 XML 模式数据类型的其他特征。
自定义概述
本节解释了一些核心的 JAXB 自定义概念 内联和外部自定义 范围、继承和优先级 自定义语法 定制命名空间前缀
内联和外部定制
对默认 JAXB 绑定的定制以传递给 JAXB 绑定编译器的绑定声明的形式进行。这些绑定声明可以通过以下两种方式进行 作为源 XML 模式中的内联注释 作为外部绑定定制文件中的声明
对于一些人来说使用内联定制更容易因为您可以在应用于的模式的上下文中看到您的定制。相反使用外部绑定定制文件使您能够定制 JAXB 绑定而无需修改源模式并且使您能够轻松地将定制应用于多个模式文件。 注意 您可以结合两种类型的定制。例如您可以在内联注释中包含对外部绑定定制文件的引用。但是您不能在同一模式元素上同时声明内联和外部定制。 这些类型的定制在以下各节中有更详细的描述
内联定制
通过在 XML 模式文件中使用内联绑定声明进行的 JAXB 绑定定制采用了嵌入在模式xsd:annotation元素中的xsd:appinfo元素的形式xsd:是 XML 模式命名空间前缀在 W3C XML Schema Part 1: Structures中定义。内联定制的一般形式如下例所示
xs:annotationxs:appinfo!--...binding declarations ....--/xs:appinfo
/xs:annotation
定制是应用在模式中声明的位置。例如对特定元素级别的声明仅适用于该元素。请注意必须在annotation和appinfo声明标签中使用 XML 模式命名空间前缀。在前面的例子中xs:被用作命名空间前缀因此声明被标记为xs:annotation和xs:appinfo。
外部绑定定制文件
通过使用包含绑定声明的外部文件进行的 JAXB 绑定定制采用了以下示例中显示的一般形式
jxb:bindings schemaLocation xs:anyURIjxb:bindings node xs:string*!-- binding declaration --jxb:bindings
/jxb:bindings schemaLocation是指向远程模式的 URI 引用。 node是一个 XPath 1.0 表达式用于标识与给定绑定声明相关联的schemaLocation中的模式节点。
例如在 JAXB 绑定声明文件中第一个schemaLocation/node声明指定了模式名称和根模式节点
jxb:bindings schemaLocationpo.xsd node/xs:schema
/jxb:bindings
后续的schemaLocation/node声明例如前一个模式示例中名为ZipCodeType的simpleType元素采用以下形式
jxb:bindings node//xs:simpleType [name’ZipCodeType’]
绑定定制文件格式
绑定定制文件必须是 ASCII 文本。名称或扩展名并不重要尽管在本章中使用的典型扩展名是.xjb。
将定制文件传递给 JAXB 绑定编译器
包含绑定声明的定制文件通过以下语法传递给 JAXB 绑定编译器xjc
xjc -b file schema
其中file是绑定自定义文件的名称schema是要传递给绑定编译器的模式的名称。
您可以拥有一个包含多个模式的自定义的单个绑定文件或者您可以将自定义分成多个绑定文件例如
xjc schema1.xsd schema2.xsd schema3.xsd \-b bindings123.xjb
xjc schema1.xsd schema2.xsd schema3.xsd \-b bindings1.xjb \-b bindings2.xjb \-b bindings3.xjb
请注意命令行上模式文件和绑定文件的顺序无关紧要尽管每个绑定自定义文件在命令行上必须在其自己的-b开关之前。
有关xjc编译器选项的更多信息请参见 JAXB 编译器选项。
外部绑定自定义的限制
有几条规则适用于在外部绑定自定义文件中进行的绑定声明而不适用于在源模式中内联进行的类似声明 绑定自定义文件必须以jxb:bindings version属性开头以及 JAXB 和 XMLSchema 命名空间的属性 jxb:bindings version1.0 绑定声明适用的远程模式必须通过使用jxb:bindings声明明确在 XPath 表示法中标识指定schemaLocation和node属性 schemaLocation指定远程模式的 URI 引用。 node指定一个 XPath 1.0 表达式用于标识schemaLocation中的模式节点给定的绑定声明与之相关联在绑定自定义文件中的初始jxb:bindings声明的情况下此节点通常为/xs:schema。
同样必须使用 XPath 表示法指定要应用自定义的模式中的各个节点例如
jxb:bindings node//xs:complexType [name’USAddress’]
在这种情况下绑定编译器将自定义应用于节点就好像声明被嵌入在节点的xs:appinfo元素中一样。
总结这些规则外部绑定元素jxb:bindings仅在以下三种情况下被 JAXB 绑定编译器识别并处理 当其父元素是xs:appinfo元素时。 当它是另一个jxb:bindings元素的祖先时。 当它是文档的根元素时。将jxb:bindings元素作为其根的 XML 文档称为外部绑定声明文件。
范围、继承和优先级
默认的 JAXB 绑定可以在四个不同级别或范围上进行自定义或覆盖。
以下图示了自定义声明的继承和优先级。具体来说金字塔顶部的声明继承并取代下面的声明。
组件声明继承并取代定义声明定义声明继承并取代模式声明模式声明继承并取代全局声明。
图自定义范围继承和优先级 自定义语法
JAXB 绑定声明的四种类型的语法XML 到 Java 数据类型绑定声明的语法以及自定义命名空间前缀的语法在以下部分中描述。 全局绑定声明 模式绑定声明 类绑定声明 属性绑定声明 javaType 绑定声明 Typesafe 枚举绑定声明 javadoc 绑定声明
全局绑定声明
全局范围的自定义使用 globalBindings 声明。全局范围自定义的语法如下
globalBindings[ collectionType collectionType ][ fixedAttributeAsConstantProperty true | false | 1 | 0 ][ generateIsSetMethod true | false | 1 | 0 ][ enableFailFastCheck true | false | 1 | 0 ][ choiceContentProperty true | false | 1 | 0 ][ underscoreBinding asWordSeparator | asCharInWord ][ typesafeEnumBase typesafeEnumBase ][ typesafeEnumMemberName generateName | generateError ][ enableJavaNamingConventions true | false | 1 | 0 ][ bindingStyle elementBinding | modelGroupBinding ][ javaType ... /javaType ]*
/globalBindings collectionType 可以是 indexed 或实现 java.util.List 的任何完全限定类名。 fixedAttributeAsConstantProperty 可以是 true, false, 1, 或 0。默认值为 false。 generateIsSetMethod 可以是 true, false, 1, 或 0。默认值为 false。 enableFailFastCheck 可以是 true, false, 1, 或 0。如果 enableFailFastCheck 是 true 或 1并且 JAXB 实现支持此可选检查那么在设置属性时将执行类型约束检查。默认值为 false。请注意JAXB 实现不支持快速失败验证。 choiceContentProperty 可以是 true, false, 1, 或 0。默认值为 false。当 bindingStyle 是 elementBinding 时choiceContentProperty 不相关。因此如果指定 bindingStyle 为 elementBinding那么 choiceContentProperty 必须导致无效的自定义。 underscoreBinding 可以是 asWordSeparator 或 asCharInWord。默认值为 asWordSeparator。 typesafeEnumBase 可以是一组 QNames每个都必须解析为简单类型定义。默认值为 xs:NCName。有关将 simpleType 定义本地化映射到 Java typesafe enum 类的信息请参见 Typesafe 枚举绑定声明。 typesafeEnumMemberName 可以是 generateError 或 generateName。默认值为 generateError。 enableJavaNamingConventions 可以是 true, false, 1, 或 0。默认值为 true。 bindingStyle 可以是 elementBinding 或 modelGroupBinding。默认值为 elementBinding。 javaType 可以是零个或多个 javaType 绑定声明。有关更多信息请参见 javaType 绑定声明。
globalBindings 声明仅在顶层 schema 元素的 annotation 元素中有效。在任何给定的模式或绑定声明文件中只能有一个 globalBindings 声明的实例。如果一个源模式包含或导入第二个源模式则 globalBindings 声明必须在第一个源模式中声明。
模式绑定声明
模式范围的自定义使用 schemaBindings 声明。模式范围自定义的语法如下
schemaBindings
[ package package /package ]
[ nameXmlTransform ... /nameXmlTransform ]*
/schemaBindingspackage [ name packageName ][ javadoc ... /javadoc ]
/packagenameXmlTransform
[ typeName [ suffixsuffix ][ prefixprefix ] / ]
[ elementName [ suffixsuffix ][ prefixprefix ] / ]
[ modelGroupName [ suffixsuffix ][ prefixprefix ] / ]
[ anonymousTypeName [ suffixsuffix ][ prefixprefix ] / ]
/nameXmlTransform
如上所示schemaBinding 声明包括两个子组件 package.../package 指定了包的名称如果需要的话还可以指定模式派生类的 API 文档的位置。 nameXmlTransform.../nameXmlTransform 指定要应用的自定义。
类绑定声明
class 绑定声明使您能够自定义模式元素与 Java 内容接口或 Java Element 接口的绑定。class 声明可用于自定义 用于模式派生的 Java 接口的名称 用于模式派生的 Java 内容接口的实现类
class 自定义的语法是
class [ name className][ implClass implClass ] [ javadoc ... /javadoc ]
/class name 是派生 Java 接口的名称。它必须是有效的 Java 接口名称不能包含包前缀。包前缀从当前包的值继承。 implClass 是 className 的实现类的名称必须包含完整的包名称。 javadoc 元素为模式派生的 Java 接口指定了 Javadoc 工具注释。在此输入的字符串必须使用 CDATA 或 来转义嵌入的 HTML 标记。
属性绑定声明
property 绑定声明使您能够自定义 XML 模式元素与其 Java 表示作为属性的绑定。自定义的范围可以是在定义级别或组件级别具体取决于 property 绑定声明的指定位置。
property 自定义的语法是
property[ name propertyName][ collectionType propertyCollectionType ][ fixedAttributeAsConstantProperty true |false | 1 | 0 ][ generateIsSetMethod true | false | 1 | 0 ][ enableFailFastCheck true | false | 1 | 0 ][ baseType ... /baseType ][ javadoc ... /javadoc ]
/propertybaseTypejavaType ... /javaType
/baseType name 定义了自定义值 propertyName它必须是有效的 Java 标识符。 collectionType 定义了自定义值 propertyCollectionType即属性的集合类型 propertyCollectionType。如果指定属性可以是 indexed 或任何实现 java.util.List 的完全限定类名。 fixedAttributeAsConstantProperty 定义了自定义值 fixedAttributeAsConstantProperty。该值可以是 true、false、1 或 0。 generateIsSetMethod 定义了自定义值 generateIsSetMethod。该值可以是 true、false、1 或 0。 enableFailFastCheck 定义了自定义值 enableFailFastCheck。该值可以是 true、false、1 或 0。请注意JAXB 实现不支持快速失败验证。 javadoc 自定义了属性的 getter 方法的 Javadoc 工具注释。
javaType 绑定声明
javaType 声明提供了一种自定义将 XML 数据类型转换为 Java 数据类型的方法。XML 提供的数据类型比 Java 更多因此当默认的 JAXB 绑定无法充分表示您的模式时javaType 声明使您能够指定自定义数据类型绑定。
目标 Java 数据类型可以是 Java 内置数据类型或特定于应用程序的 Java 数据类型。如果将特定于应用程序的 Java 数据类型用作目标则您的实现还必须为解组和组合数据提供解析和打印方法。为此JAXB 规范支持 parseMethod 和 printMethod parseMethod 在解组过程中被调用将输入文档中的字符串转换为目标 Java 数据类型的值。 在组合过程中printMethod 被调用以将目标类型的值转换为词法表示。
如果您更喜欢定义自己的数据类型转换JAXB 定义了一个静态类 DatatypeConverter以帮助解析和打印 XML Schema 内置数据类型的有效词法表示。
javaType 自定义的语法为
javaType name *javaType*[ xmlType *xmlType* ][ hasNsContext true | false ][ parseMethod *parseMethod* ][ printMethod *printMethod* ] name 是要将 xmlType 绑定到的 Java 数据类型。 xmlType 是要将 javaType 绑定到的 XML Schema 数据类型的名称当 javaType 声明的父级为 globalBindings 时此属性是必需的。 hasNsContext 允许指定命名空间上下文作为打印或解析方法的第二个参数可以是 true、false、1 或 0。默认情况下此属性为 false在大多数情况下无需更改。 parseMethod 是在解组过程中调用的解析方法的名称。 printMethod 是在组合过程中调用的打印方法的名称。
javaType 声明可用于 一个 globalBindings 声明 用于简单类型定义、GlobalBindings 和 basetype 声明的注释元素 一个 property 声明
请参见MyDatatypeConverter 类 了解在自定义数据类型转换器类中如何实现 javaType 声明和 DatatypeConverterInterface 接口的示例。
类型安全枚举绑定声明
类型安全枚举声明提供了一种将 XML simpleType 元素映射到 Java typesafe enum 类的本地化方式。您可以进行两种类型的类型安全枚举声明 typesafeEnumClass 允许您将整个 simpleType 类映射到 typesafe enum 类。 typesafeEnumMember 允许您将 simpleType 类的选定成员映射到 typesafe enum 类。
在这两种情况下对此类型的自定义有两个主要限制 只有具有枚举约束的 simpleType 定义才能使用此绑定声明进行自定义。 此自定义仅适用于一次仅有一个 simpleType 定义。要在全局级别映射一组相似的 simpleType 定义请在 globalBindings 声明中使用 typesafeEnumBase 属性如全局绑定声明中所述。
typesafeEnumClass 自定义的语法为
typesafeEnumClass [ name enumClassName ][ typesafeEnumMember ... /typesafeEnumMember ]*[ javadoc enumClassJavadoc /javadoc ]
/typesafeEnumClass name 必须是有效的 Java 标识符并且不能有包前缀。 您可以在typesafeEnumClass声明中嵌入零个或多个typesafeEnumMember声明。 javadoc定制了枚举类的 Javadoc 工具注释。
typesafeEnumMember定制的语法是
typesafeEnumMember name enumMemberName[ value enumMemberValue ][ javadoc enumMemberJavadoc /javadoc ]
/typesafeEnumMember name必须始终指定并且必须是有效的 Java 标识符。 value必须是源模式中指定的枚举值。 javadoc定制了枚举常量的 Javadoc 工具注释。
对于内联注释必须在simpleType元素的注释元素中指定typesafeEnumClass声明。必须在枚举成员的注释元素中指定typesafeEnumMember。这使得枚举成员可以独立于枚举类进行定制。
有关类型安全枚举设计模式的信息请参阅Joshua Bloch 的Effective Java Programming在 Oracle Technology Network 上的示例章节。。
javadoc 绑定声明
javadoc声明允许您向基于模式的 JAXB 包、类、接口、方法和字段添加自定义 Javadoc 工具注释。请注意javadoc声明不能全局应用它们只能作为其他绑定定制的子元素有效。
javadoc定制的语法是
javadocContents in bJavadoc\b format.
/javadoc
或
javadoc![CDATA[Contents in bJavadoc\b format ]]
/javadoc
请注意应用于包级别的javadoc声明中的文档字符串必须包含body开放和关闭标签例如
jxb:package nameprimer.myPojxb:javadoc![CDATA[bodyPackage level documentation for generated package primer.myPo./body]]/jxb:javadoc
/jxb:package
定制命名空间前缀
所有标准的 JAXB 绑定声明必须以映射到 JAXB 命名空间 URI java.sun.com/xml/ns/jaxb 的命名空间前缀为前缀。例如在此示例中使用了jxb:。为此您想要使用标准 JAXB 绑定声明自定义的任何模式必须在模式文件的顶部包含 JAXB 命名空间声明和 JAXB 版本号。例如在 Customize Inline 示例的po.xsd中命名空间声明如下
xsd:schema xmlns:xsd http://www.w3.org/2001/XMLSchemaxmlns:jxb http://java.sun.com/xml/ns/jaxbjxb:version1.0
具有jxb命名空间前缀的绑定声明采用以下形式
xsd:annotationxsd:appinfojxb:globalBindings *binding declarations* /jxb:schemaBindings...*binding declarations* ..../jxb:schemaBindings/xsd:appinfo
/xsd:annotation
请注意在此示例中globalBindings和schemaBindings声明用于分别指定全局范围和模式范围的定制。这些定制范围在范围、继承和优先级中有更详细的描述。
内联定制示例
Customize Inline 示例演示了通过内联注释对名为po.xsd的 XML 模式进行的一些基本定制。此外该示例实现了一个自定义数据类型转换器类MyDatatypeConverter.java展示了处理自定义数据类型转换的javaType定制中的打印和解析方法。
总结这个示例 po.xsd是一个包含内联绑定定制的 XML 模式。 MyDatatypeConverter.java 是一个 Java 类文件实现了 po.xsd 中 javaType 自定义中指定的打印和解析方法。 Main.java 是自定义内联示例中的主要类文件使用了由 JAXB 编译器生成的模式派生类。
使用 Ant 构建和运行自定义内联示例
要使用 Ant 编译和运行自定义内联示例在终端窗口中转到 jaxb-ri-install/samples/inline-customize/ 目录并输入以下内容
ant
此示例中的关键自定义和自定义的 MyDatatypeConverter.java 类在下一节中有更详细的描述。
自定义模式
在自定义内联示例中使用的自定义模式位于文件 jaxb-ri-install/samples/inline-customize/po.xsd 中。自定义内容位于 xsd:annotation 标签中。
全局绑定声明
以下代码示例显示了 po.xsd 中的 globalBindings 声明
jxb:globalBindingsfixedAttributeAsConstantPropertytruecollectionTypejava.util.VectortypesafeEnumBasexsd:NCNamechoiceContentPropertyfalsetypesafeEnumMemberNamegenerateErrorbindingStyleelementBindingenableFailFastCheckfalsegenerateIsSetMethodfalseunderscoreBindingasCharInWord/
在此示例中除了 collectionType 外所有值都设置为默认值。 将 fixedAttributeAsConstantProperty 设置为 true 表示所有固定属性应绑定到 Java 常量。默认情况下固定属性映射到更合适的简单属性或集合属性。 将 collectionType 设置为 java.util.Vector 指定生成实现类中所有列表在内部表示为向量。请注意您为 collectionType 指定的类名必须实现 java.util.List 并且可以通过 newInstance 调用。 如果将 typesafeEnumBase 设置为 xsd:string这是一种全局方式指定所有直接或间接从 xsd:string 派生并具有枚举约束的 simple 类型定义默认绑定到 typesafe enum。如果将 typesafeEnumBase 设置为空字符串 ()则不会将任何 simple 类型定义默认绑定到 typesafe enum 类。typesafeEnumBase 的值可以是除 xsd:boolean 和两种二进制类型之外的任何原子简单类型定义。 JAXB 实现不支持 enableFailFastCheck 属性。 注意 使用类型安全的枚举类使您能够将模式枚举值映射到 Java 常量这样就可以对 Java 常量进行比较而不是对字符串值进行比较。
模式绑定声明
以下代码显示了 po.xsd 中的模式绑定声明
jxb:schemaBindings
jxb:package nameprimer.myPojxb:javadoc![CDATA[bodyPackage level documentation for generated package primer.myPo./body]]/jxb:javadoc
/jxb:packagejxb:nameXmlTransformjxb:elementName suffixElement//jxb:nameXmlTransform
/jxb:schemaBindings jxb:package nameprimer.myPo/ 指定 primer.myPo 作为生成模式派生类的包。 jxb:nameXmlTransform指定所有生成的 Java 元素接口默认附加Element到生成的名称。例如当针对此模式运行 JAXB 编译器时将生成元素接口CommentElement和PurchaseOrderElement。相比之下没有此自定义 默认绑定会生成Comment和PurchaseOrder。如果模式在不同的符号空间中使用相同的名称例如在全局元素和类型定义中此自定义可帮助您解决冲突而不必使用单独的绑定声明逐个解决每个冲突。 jxb:javadoc指定了primer.myPo包的自定义 Javadoc 工具注释。请注意与在类级别显示的javadoc声明不同当在包级别进行javadoc声明时必须包含开头和结尾的body标签。
类绑定声明
以下代码显示了po.xsd中的类绑定声明
xsd:complexType namePurchaseOrderTypexsd:annotationxsd:appinfojxb:class namePOTypejxb:javadocA lt;bPurchase Orderlt;/bconsists of addresses and items./jxb:javadoc/jxb:class/xsd:appinfo/xsd:annotation!-- ... --
/xsd:complexType
为基于模式的POType类编写的 Javadoc 工具注释将包含描述一个lt;b采购订单lt;/b包括地址和商品。 其中lt;用于转义b HTML 标签中的开括号。 注意 当在complexType定义的appinfo元素中指定class自定义时如前面的示例所示complexType定义将绑定到 Java 内容接口。 在po.xsd中另一个javadoc自定义在此类级别声明但这次使用CDATA转义 HTML 字符串
xsd:annotationxsd:appinfojxb:classjxb:javadoc![CDATA[First line of documentation for abUSAddress/b.]]/jxb:javadoc/jxb:class/xsd:appinfo
/xsd:annotation 注意 如果要在jaxb:javadoc自定义中包含 HTML 标签必须将数据放在CDATA部分中或使用lt;转义所有左尖括号。有关更多信息请参阅XML 1.0 第 2 版。 属性绑定声明
这里特别感兴趣的是generateIsSetMethod自定义它导致生成两个额外的属性方法isSetQuantity和unsetQuantity。这些方法使客户端应用程序能够区分模式默认值和在实例文档中明确出现的值。
例如在po.xsd中
xsd:complexType nameItemsxsd:sequencexsd:element nameitem minOccurs1 maxOccursunboundedxsd:complexTypexsd:sequencexsd:element nameproductName typexsd:string/xsd:element namequantity default10xsd:annotationxsd:appinfojxb:property generateIsSetMethodtrue//xsd:appinfo/xsd:annotation!-- ... --/xsd:complexType/xsd:element/xsd:sequence
/xsd:complexType
generateIsSetMethod适用于quantity元素该元素绑定到Items.ItemType接口中的属性。在Items.ItemType接口中生成了unsetQuantity和isSetQuantity方法。
MyDatatypeConverter类
类jaxb-ri-install/samples/inline-customize/src/inlinecustomize/primer/MyDatatypeConverter如下例所示提供了一种自定义将 XML 数据类型与 Java 数据类型之间的转换的方法使用javaType自定义。
package primer;
import java.math.BigInteger;
import javax.xml.bind.DatatypeConverter;public class MyDatatypeConverter {public static short parseIntegerToShort(String value) {BigInteger result DatatypeConverter.parseInteger(value);return (short)(result.intValue());}public static String printShortToInteger(short value) {BigInteger result BigInteger.valueOf(value);return DatatypeConverter.printInteger(result);}public static int parseIntegerToInt(String value) {BigInteger result DatatypeConverter.parseInteger(value);return result.intValue();}public static String printIntToInteger(int value) {BigInteger result BigInteger.valueOf(value);return DatatypeConverter.printInteger(result);}
};
以下代码显示了如何在 po.xsd 中的 javaType 声明中引用 MyDatatypeConverter 类
xsd:simpleType nameZipCodeType
xsd:annotationxsd:appinfojxb:javaType nameintparseMethodprimer.MyDatatypeConverter.parseIntegerToIntprintMethodprimer.MyDatatypeConverter.printIntTo Integer //xsd:appinfo
/xsd:annotationxsd:restriction basexsd:integerxsd:minInclusive value10000/xsd:maxInclusive value99999//xsd:restriction
/xsd:simpleType
在此示例中jxb:javaType 绑定声明覆盖了此类型的默认 JAXB 绑定为 java.math.BigInteger。对于 Customize Inline 示例ZipCodeType 的限制特别是有效的美国邮政编码限于五位数字使得所有有效值都可以适应 Java 基本数据类型 int。还要注意因为 jxb:javaType nameint/ 在 ZipCodeType 中声明所以该定制适用于所有引用此 simpleType 定义的 JAXB 属性包括 getZip 和 setZip 方法。
DataType Converter 示例
DataType Converter 示例类似于 Customize Inline 示例。与 Customize Inline 示例一样DataType Converter 示例中的定制是通过在应用程序的 XML 模式 po.xsd 中使用内联绑定声明来实现的。
Customize Inline 和 DataType Converter 示例的全局、模式和包以及大多数类自定义是相同的。DataType Converter 示例与 Customize Inline 示例不同之处在于用于将 XML 数据转换为 Java int 数据类型的 parseMethod 和 printMethod。
具体而言DataType Converter 示例不是使用自定义的 MyDataTypeConverter 类中的方法执行这些数据类型转换而是使用 javax.xml.bind.DatatypeConverter 提供的内置方法
xsd:simpleType nameZipCodeTypexsd:annotationxsd:appinfojxb:javaType nameintparseMethodjavax.xml.bind.DatatypeConverter.parseIntprintMethodjavax.xml.bind.DatatypeConverter.printInt//xsd:appinfo/xsd:annotationxsd:restriction basexsd:integerxsd:minInclusive value10000/xsd:maxInclusive value99999//xsd:restriction
/xsd:simpleType
使用 Ant 构建和运行 DataType Converter 示例
要使用 Ant 编译和运行 DataType Converter 示例在终端窗口中转到 jaxb-ri-install/samples/datatypeconverter/ 目录并输入以下内容
ant
绑定声明文件
以下各节提供有关绑定声明文件的信息 JAXB 版本、命名空间和模式属性 全局和模式绑定声明 类声明
JAXB 版本、命名空间和模式属性
所有 JAXB 绑定声明文件必须以以下内容开头 JAXB 版本号 命名空间声明 模式名称和节点
bindings.xjb 中的版本、命名空间和模式声明如下
jxb:bindings version1.0jxb:bindings schemaLocationpo.xsd node/xs:schema!-- ...*binding-declarations* ... --/jxb:bindings!-- schemaLocationpo.xsd node/xs:schema --
/jxb:bindings
JAXB 版本号
具有根元素 jaxb:bindings 的 XML 文件被视为外部绑定文件。根元素必须指定其绑定声明必须遵守的 JAXB 版本属性具体来说根 jxb:bindings 元素必须包含 jxb:version 声明或 version 属性。相比之下当进行内联绑定声明时JAXB 版本号作为 xsd:schema 声明的属性
xsd:schema jxb:version1.0
命名空间声明
如 JAXB 版本、命名空间和模式属性中所示外部绑定声明文件中的命名空间声明包括 JAXB 命名空间和 XMLSchema 命名空间。请注意此示例中使用的前缀实际上可以是任何您想要的重要的是在文件中后续声明中一致使用您在此定义的任何前缀。
模式名称和模式节点
代码中的第四行在 JAXB 版本、命名空间和模式属性中指定了此绑定声明文件适用的模式的名称以及首次生效的模式节点。此文件中的后续绑定声明可以引用模式中的特定节点但此第一个声明应该涵盖整个模式例如在bindings.xjb中
jxb:bindings schemaLocationpo.xsd node/xs:schema
全局和模式绑定声明
bindings.xjb中的全局模式绑定声明与数据类型转换器示例中的po.xsd中的相同。唯一的区别是因为po.xsd中的声明是内联完成的您必须将它们嵌入到xs:appinfo元素中而这些元素又嵌入到xs:annotation元素中。以这种方式嵌入声明在外部绑定文件中是不必要的。
jxb:globalBindingsfixedAttributeAsConstantPropertytruecollectionTypejava.util.VectortypesafeEnumBasexs:NCNamechoiceContentPropertyfalsetypesafeEnumMemberNamegenerateErrorbindingStyleelementBindingenableFailFastCheckfalsegenerateIsSetMethodfalseunderscoreBindingasCharInWord/jxb:schemaBindingsjxb:package nameprimer.myPojxb:javadoc![CDATA[bodyPackage level documentation for generated packageprimer.myPo./body]]/jxb:javadoc/jxb:packagejxb:nameXmlTransformjxb:elementName suffixElement//jxb:nameXmlTransform/jxb:schemaBindings
相比之下数据类型转换器示例中po.xsd中使用的语法是
xsd:annotationxsd:appinfojxb:globalBindings...*binding-declarations*...jxb:schemaBindings...*binding-declarations*.../jxb:schemaBindings/xsd:appinfo
/xsd:annotation
类声明
bindings.xjb中的类级绑定声明与数据类型转换器示例中的po.xsd中的类似声明有两个不同之处 与bindings.xjb中的所有其他绑定声明一样您不需要将自定义嵌入到模式xsd:appinfo元素中。 您必须指定应用自定义的模式节点。此类型声明的一般语法为 jxb:bindings node//*node-type*[name’*node-name*’]
例如以下代码显示了名为USAddress的complexType的绑定声明。
jxb:bindings node//xs:complexType [name’USAddress’]jxb:classjxb:javadoc![CDATA[First line of documentation for a bUSAddress/b.]]/jxb:javadoc/jxb:classjxb:bindings node.//xs:element [name’name’]jxb:property nametoName/
/jxb:bindingsjxb:bindings node.//xs:element [name’zip’]jxb:property namezipCode/
/jxb:bindings
/jxb:bindings
!-- node//xs:complexType[name’USAddress’] --
请注意在此示例中USAddress是子元素name和zip的父元素因此/jxb:bindings标签将子元素和类级javadoc声明的bindings声明括起来。
外部自定义示例
外部自定义示例与数据类型转换器示例相同只是外部自定义示例中的绑定声明是使用外部绑定声明文件而不是内联在源 XML 模式中完成的。
外部自定义示例中使用的绑定自定义文件是jaxb-ri-install/samples/external-customize/binding.xjb。
本节将bindings.xjb中的自定义声明与 XML 模式po.xsd中的数据类型转换器示例中使用的类似声明进行比较。这两组声明实现完全相同的结果。
使用 Ant 构建和运行外部自定义示例
要使用 Ant 编译和运行外部自定义示例在终端窗口中转到jaxb-ri-install/samples/external-customize/目录并输入以下内容
ant
Java-to-Schema 示例 原文docs.oracle.com/javase/tutorial/jaxb/intro/j2schema.html Java-to-Schema 示例展示了如何使用注解将 Java 类映射到 XML 模式。
j2s-create-marshal 示例
j2s-create-marshal 示例演示了 Java-to-schema 数据绑定。它演示了对带有 JAXB 注解的类进行编组和解组并展示了如何在解组时使用从 JAXB 映射类生成的模式文件启用 JAXP 1.3 验证。
schema 文件bc.xsd是通过以下命令生成的
schemagen src/cardfile/*.java
cp schema1.xsd bc.xsd
请注意schema1.xsd被复制到bc.xsdschemagen不允许您指定自己选择的模式名称。
使用 Ant 构建和运行 j2s-create-marshal 示例
要使用 Ant 编译和运行 j2s-create-marshal 示例在终端窗口中转到jaxb-ri-install/samples/j2s-create-marshal/目录并输入以下内容
ant
j2s-xmlAccessorOrder 示例
j2s-xmlAccessorOrder 示例展示了如何使用XmlAccessorOrder和XmlType.propOrder注解来指定 Java 类型在编组和解组时的 XML 内容顺序。
使用 Java-to-schema 映射JavaBean 的属性和字段被映射到 XML 模式类型。类元素被映射为 XML 模式复杂类型或 XML 模式简单类型。生成的模式类型的默认元素顺序目前未指定因为 Java 反射不强制返回顺序。可靠的元素排序的缺失对应用程序的可移植性产生负面影响。您可以使用两个注解XmlAccessorOrder和XmlType.propOrder为必须跨 JAXB 提供程序可移植的应用程序定义模式元素排序。
使用XmlAccessorOrder注解定义模式元素排序
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 注解定义模式元素顺序
XmlType 注解可以定义在一个类上。XmlType 注解中的 propOrder() 元素使您能够指定生成的模式类型中的内容顺序。当您在一个类上使用 XmlType.propOrder 注解来指定内容顺序时类中的所有公共属性和公共字段必须在参数列表中指定。您希望保留在参数列表之外的任何公共属性或字段必须用 XmlAttribute 或 XmlTransient 注解进行标注。
XmlType.propOrder 的默认内容顺序为 {} 或 {}不活动。在这种情况下活动的 XmlAccessorOrder 注解优先。当类内容顺序由 XmlType.propOrder 注解指定时它优先于类或包上的任何活动的 XmlAccessorOrder 注解。如果在一个类上指定了 XmlAccessorOrder 和 XmlType.propOrder(A, B, ...) 注解那么 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 nameusAddressxs:sequencexs:element namename typexs:string minOccurs0/xs:element namecity typexs:string minOccurs0//xs:sequence
/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/ 目录并输入以下内容
ant
j2s-xmlAdapter 示例
j2s-xmlAdapter 示例演示了如何使用XmlAdapter接口和XmlJavaTypeAdapter注解为使用int作为键和String作为值的HashMap字段提供自定义映射的 XML 内容的组合和解组。
接口XmlAdapter和注解XmlJavaTypeAdapter用于在解组和组合期间对数据类型进行特殊处理。有各种 XML 数据类型其表示方式不容易映射到 Java例如xs:DateTime和xs:Duration以及 Java 类型不正确地映射到 XML 表示。例如java.util.Collection如List和java.util.Map如HashMap的实现或非 JavaBean 类。
为这类情况提供了XmlAdapter接口和XmlJavaTypeAdapter注解。这种组合提供了一个可移植的机制用于将 XML 内容读取和写入 Java 应用程序。
XmlAdapter接口定义了数据读取和写入的方法。
/** 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 XmlAdapterValueType,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 内容映射到自定义HashMap中并从中组合出来。类KitchenWorldBasket中的HashMap对象basket使用int类型的键和String类型的值。这些数据类型应该反映在读取和写入的 XML 内容中因此 XML 内容应如下示例所示
basketentry key9027glasstop stove in black/entryentry key288wooden spoon/entry
/basket
为 Java 类型HashMap生成的默认模式不反映所需的格式。
xs:element namebasketxs:complexTypexs:sequencexs:element nameentry minOccurs0 maxOccursunboundedxs:complexTypexs:sequencexs:element namekey minOccurs0typexs:anyType/xs:element namevalue minOccurs0 typexs:anyType//xs:sequence/xs:complexType/xs:element/xs:sequence/xs:complexType
/xs:element
在默认的HashMap模式中键和值都是元素并且是anyType数据类型。XML 内容如下所示
basketentrykey9027/keyvalueglasstop stove in black/value/entryentrykey288/keyvaluewooden spoon/value/entry
/basket
要解决这个问题示例使用了两个 Java 类PurchaseList和PartEntry它们反映了用于解组和组合内容的所需模式格式。为这些类生成的 XML 模式如下
xs:complexType namePurchaseListTypexs:sequencexs:element nameentry typepartEntrynillabletrue maxOccursunboundedminOccurs0//xs:sequence
/xs:complexTypexs:complexType namepartEntryxs:simpleContentxs:extension basexs:stringxs:attributenamekey typexs:intuserequired//xs:extension/xs:simpleContent
/xs:complexType
类AdapterPurchaseListToHashMap实现了XmlAdapter接口。在类KitchenWorldBasket中使用XmlJavaTypeAdapter注解将AdapterPurchaseListToHashMap与字段HashMap basket配对。这种配对导致在KitchenWorldBasket上进行任何对应的组合或解组操作时将调用AdapterPurchaseListToHashMap的组合或解组方法。
使用 Ant 构建和运行 j2s-xmlAdapter 示例
要使用 Ant 编译和运行 j2s-xmlAdapter 示例在终端窗口中转到jaxb-ri-install/samples/j2s-xmlAdapter/目录然后输入以下内容
ant
j2s-xmlAttribute 示例
j2s-xmlAttribute 示例展示了如何使用XmlAttribute注解来定义一个属性或字段被视为 XML 属性。
XmlAttribute注解将字段或 JavaBean 属性映射到 XML 属性。强加以下规则 静态最终字段映射到 XML 固定属性。 当字段或属性是集合类型时集合类型的项目必须映射到模式简单类型。 当字段或属性不是集合类型时类型必须映射到模式简单类型。
遵循 JavaBean 编程范式时属性由字段名上的get和set前缀定义。
int zip;
public int getZip(){return zip;}
public void setZip(int z){zipz;}
在 bean 类中您可以选择在三个组件之一上设置XmlAttribute注解字段、setter 方法或 getter 方法。如果在字段上设置XmlAttribute注解则必须重命名 setter 方法否则将在编译时出现命名冲突。如果在其中一个方法上设置XmlAttribute注解则必须在 setter 或 getter 方法上设置但不能同时设置在两者上。
XmlAttribute 示例展示了如何在静态最终字段上使用XmlAttribute注解在字段而不是相应的 bean 方法上使用在 bean 属性方法上使用以及在不是集合类型的字段上使用。在类USAddress中字段 country 和 zip 被标记为属性。setZip方法被禁用以避免编译错误。属性 state 在 setter 方法上被标记为属性。您也可以使用 getter 方法。在类PurchaseOrderType中字段cCardVendor是非集合类型。它符合简单类型的要求它是一个enum类型。
使用 Ant 构建和运行 j2s-xmlAttribute 示例
要使用 Ant 编译和运行 j2s-xmlAttribute 示例在终端窗口中转到jaxb-ri-install/samples/j2s-xmlAttribute/目录并键入以下内容
ant
j2s-xmlRootElement 示例
j2s-xmlRootElement 示例演示了如何使用XmlRootElement注解为相应类的 XML 模式类型定义 XML 元素名称。
XmlRootElement注解将类或enum类型映射到 XML 元素。每个用于解组和组装的顶级 Java 类型都需要至少一个元素定义。如果没有元素定义XML 内容处理就没有起始位置。
XmlRootElement注解使用类名作为默认元素名。您可以通过使用注解属性name来更改默认名称。如果这样做指定的名称将用作元素名和类型名。元素和类型名称不同是常见的模式实践。您可以使用XmlType注解来设置元素类型名称。
XmlRootElement注解的命名空间属性用于为元素定义命名空间。
使用 Ant 构建和运行 j2s-xmlRootElement 示例
要使用 Ant 编译和运行 j2s-xmlRootElement 示例在终端窗口中转到jaxb-ri-install/samples/j2s-xmlRootElement/目录并输入以下内容
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中在包中定义。文件TrackingOrder中的shipDate字段也被定义为XMLGregorianCalendar类型但XmlSchemaType注解语句覆盖了包定义并指定该字段为date类型。属性方法getTrackingDuration定义模式元素被定义为原始类型duration而不是 Java 类型String。
使用 Ant 构建和运行 j2s-xmlSchemaType 示例
要使用 Ant 编译和运行 j2s-xmlSchemaType 示例在终端窗口中转到jaxb-ri-install/samples/j2s-xmlSchemaType/目录并输入以下内容
ant
j2s-xmlType 示例
j2s-xmlType 示例演示了如何使用XmlType注解。XmlType注解将一个类或一个enum类型映射到一个 XML Schema 类型。
一个类必须具有公共零参数构造函数或静态零参数工厂方法以便通过此注解进行映射。在解组期间其中一个方法用于创建类的实例。工厂方法可以位于工厂类中或现有类中。
有一个关于解组使用哪种方法的优先顺序 如果注解中标识了工厂类则该类中还必须标识相应的工厂方法并且该方法将被使用。 如果注解中标识了工厂方法但未标识工厂类则工厂方法必须位于当前类中。即使存在公共零参数构造方法也将使用工厂方法。 如果注解中未标识工厂方法则类必须包含一个公共零参数构造方法。
在这个例子中一个工厂类为几个类提供了零参数的工厂方法。类OrderContext上的XmlType注解引用了工厂类。解组器在这个类中使用了标识的工厂方法。
public class OrderFormsFactory {public OrderContext newOrderInstance() {return new OrderContext()}public PurchaseOrderType {newPurchaseOrderType() {return new newPurchaseOrderType();}}XmlType(nameoContext,factoryClassOrderFormsFactory,factoryMethodnewOrderInstance)public class OrderContext {public OrderContext() {// ...}}
}
在这个例子中一个工厂方法在一个类中被定义该类还包含一个标准的类构造。因为factoryMethod的值被定义了而没有定义factoryClass所以在解组时会使用工厂方法newOrderInstance。
XmlType(nameoContext, factoryMethodnewOrderInstance)
public class OrderContext {public OrderContext() {// ...}public OrderContext newOrderInstance() {return new OrderContext();}
}
使用 Ant 构建和运行 j2s-xmlType 示例
要使用 Ant 编译和运行 j2s-xmlType 示例在终端窗口中进入jaxb-ri-install/samples/j2s-xmlType/目录并输入以下内容
ant
