自定义 JAXB 绑定
- 自定义概述
- 内联和外部自定义

自定义 JAXB 绑定

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

以下部分描述了基于 Basic 示例中演示的概念的几个示例。

本节的目的是说明如何使用自定义绑定声明自定义 JAXB 绑定，使用以下两种方法之一进行：

作为 XML 模式中的内联注释
作为传递给 JAXB 绑定编译器的外部文件中的语句

与基本 JAXB 示例中的示例不同，后者侧重于各个Main.java类文件中的 Java 代码，此处的示例主要关注对 XML 架构的定制生成模式派生的 Java 绑定类。

Note: JAXB binding customizations currently must be made by hand. One of the goals of the JAXB technology is to standardize the format of binding declarations, thereby making it possible to create customization tools and to provide a standard interchange format between JAXB implementations.

本节介绍可以对 JAXB 绑定和验证方法进行的自定义。有关更多信息，请参阅 JAXB 规范。

在大多数情况下，JAXB 绑定编译器生成的默认绑定就足够了。但是，有些情况下您可能希望修改默认绑定。其中一些包括：

为模式派生的 JAXB 包，类，方法和常量创建 API 文档：通过向模式添加自定义 Javadoc 工具注释，您可以解释特定于实现的概念，指南和规则。
为缺省 XML 名称到 Java 标识符映射无法自动处理的情况提供语义上有意义的自定义名称;例如：
- 解决名称冲突（如 _JAXB 规范*的附录 D.2.1 中所述）。请注意，JAXB 绑定编译器会检测并报告所有名称冲突。
- 为非有效 Java 标识符的类型安全枚举常量提供名称;例如，枚举整数值。
- 为绑定到 Java 属性或类的未命名模型组的 Java 表示提供更好的名称。
- 提供比默认情况下从目标命名空间 URI 派生的更有意义的包名。
覆盖默认绑定;例如：
- 指定必须将模型组绑定到类而不是列表。
- 指定固定属性可以绑定到 Java 常量。
- 将 XML Schema 内置数据类型的指定缺省绑定覆盖为 Java 数据类型。在某些情况下，您可能希望引入一个替代 Java 类，它可以表示内置 XML Schema 数据类型的其他特性。

自定义概述

本节介绍一些核心 JAXB 定制概念：

内联和外部自定义
范围，继承和优先级
自定义语法
自定义命名空间前缀

内联和外部自定义

默认 JAXB 绑定的自定义以绑定声明的形式传递给 JAXB 绑定编译器。这些绑定声明可以通过以下两种方式之一进行：

作为源 XML 模式中的内联注释
作为外部绑定自定义文件中的声明

对于某些人来说，使用内联自定义更容易，因为您可以在应用它们的架构的上下文中查看自定义。相反，使用外部绑定自定义文件可以自定义 JAXB 绑定而无需修改源模式，并使您可以轻松地将自定义应用于多个模式文件。

Note: You can combine the two types of customizations. For example, you could include a reference to an external binding customizations file in an inline annotation. However, you cannot declare both an inline and external customization on the same schema element.

以下各节将更详细地介绍这些类型的自定义中的每一种：

内联自定义

通过 XML 模式文件中的内联绑定声明进行的 JAXB 绑定的自定义采用< xsd：appinfo>的形式。嵌入在模式< xsd：annotation>中的元素元素（ xsd：是 XML 模式名称空间前缀，如 W3C _XML 模式第 1 部分：结构*中所定义）。以下示例显示了内联自定义的一般形式：

<xs:annotation>
    <xs:appinfo>
        <!--
        ...
        binding declarations     .
        ...
        -->
    </xs:appinfo>
</xs:annotation>

自定义应用于在架构中声明它们的位置。例如，特定元素级别的声明仅适用于该元素。请注意，XML 架构名称空间前缀必须与< annotation>一起使用。和< appinfo>声明标签。在前面的示例中， xs：用作命名空间前缀，因此声明被标记为< xs：annotation>和< xs：appinfo> 。

外部绑定自定义文件

通过使用包含绑定声明的外部文件对 JAXB 绑定进行自定义，采用以下示例中显示的一般形式：

<jxb:bindings schemaLocation = "xs:anyURI">
    <jxb:bindings node = "xs:string">*
        <!-- binding declaration -->
    <jxb:bindings>
</jxb:bindings>

schemaLocation是对远程模式的 URI 引用。
节点是一个 XPath 1.0 表达式，用于标识与给定绑定声明关联的schemaLocation中的模式节点。

例如，JAXB 绑定声明文件中的第一个schemaLocation / 节点声明指定了模式名称和根模式节点：

<jxb:bindings schemaLocation="po.xsd" node="/xs:schema">
</jxb:bindings>

随后的schemaLocation / 节点声明，例如前一个模式示例中名为ZipCodeType的simpleType元素，采用以下形式：

<jxb:bindings node="//xs:simpleType [@name=’ZipCodeType’]">

绑定自定义文件格式

绑定自定义文件必须是 ASCII 文本。名称或扩展名无关紧要;虽然本章中使用的典型扩展是.xjb 。

将自定义文件传递给 JAXB 绑定编译器

包含绑定声明的自定义文件使用以下语法传递给 JAXB 绑定编译器xjc ：

xjc -b 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 名称空间的属性：

&lt;jxb:bindings version="1.0" 
    xmlns:jxb="http://java.sun.com/xml/ns/jaxb" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema"&gt;

必须使用jxb：bindings声明指定schemaLocation和node属性，以 XPath 表示法显式标识绑定声明所适用的远程模式：
- schemaLocation指定对远程模式的 URI 引用。
- 节点指定 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 绑定。

下图说明了自定义声明的继承和优先级。具体来说，金字塔顶部的声明继承并取代它们下面的声明。

组件声明继承自和取代定义声明;定义声明继承并取代 Schema 声明;和 Schema 声明继承并取代全局声明。

图：自定义范围继承和优先级

Customization Scope Inheritance and Precedence

自定义语法

以下部分介绍了四种类型的 JAXB 绑定声明的语法，XML-to-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可以是索引或任何实现java.util.List的完全限定类名。
fixedAttributeAsConstantProperty可以是true ， false ， 1或0 。默认值为false 。
generateIsSetMethod可以是真，假， 1或0 。默认值为false 。
enableFailFastCheck可以是true ， false ， 1或0 。如果enableFailFastCheck为true或1并且 JAXB 实现支持此可选检查，则在设置属性时执行类型约束检查。默认值为false 。请注意，JAXB 实现不支持 failfast 验证。
choiceContentProperty可以是true ， false ， 1或0 。默认值为false 。当bindingStyle是elementBinding时， choiceContentProperty无关。因此，如果bindingStyle指定为elementBinding ，则choiceContentProperty必须导致无效的自定义。
underscoreBinding可以是asWordSeparator或asCharInWord 。默认值为asWordSeparator 。
typesafeEnumBase可以是 QNames 列表，每个 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>声明仅在顶级模式元素的注释元素中有效。只能存在< globalBindings>的单个实例。任何给定模式或绑定声明文件中的声明。如果一个源模式包含或导入第二个源模式，则< globalBindings>必须在第一个源模式中声明声明。

架构绑定声明

使用< schemaBindings>声明模式范围自定义。 。架构范围自定义的语法是：

<schemaBindings>
[ <package> package </package> ]
[ <nameXmlTransform> ... </nameXmlTransform> ]*
</schemaBindings>
<package 
    [ name = "packageName" ]
    [ <javadoc> ... </javadoc> ]
</package>
<nameXmlTransform>
[ <typeName 
    [ suffix="suffix" ]
    [ prefix="prefix" ] /> ]
[ <elementName 
    [ suffix="suffix" ]
    [ prefix="prefix" ] /> ]
[ <modelGroupName 
    [ suffix="suffix" ]
    [ prefix="prefix" ] /> ]
[ <anonymousTypeName 
    [ suffix="suffix" ]
    [ prefix="prefix" ] /> ]
</nameXmlTransform>

如上所示，< schemaBinding>声明包括两个子组件：

< package> ...< / package>指定包的名称，如果需要，还指定模式派生类的 API 文档的位置。
< nameXmlTransform> ...< / nameXmlTransform>指定要应用的自定义。

类绑定声明

< class>绑定声明使您可以自定义架构元素与 Java 内容接口或 Java 元素接口的绑定。 < 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> ]
</property>
<baseType>
    <javaType> ... </javaType>
</baseType>

名称定义自定义值propertyName ;它必须是有效的 Java 标识符。
collectionType定义自定义值propertyCollectionType ，它是属性propertyCollectionType的集合类型。如果指定，该属性可以是索引或任何实现java.util.List的完全限定类名。
fixedAttributeAsConstantProperty定义自定义值fixedAttributeAsConstantProperty 。该值可以是真，假， 1或0 。
generateIsSetMethod定义generateIsSetMethod的自定义值。该值可以是真，假， 1或0 。
enableFailFastCheck定义自定义值enableFailFastCheck 。该值可以是真，假， 1或0 。请注意，JAXB 实现不支持 failfast 验证。
< javadoc>为属性的 getter 方法自定义 Javadoc 工具注释。

javaType 绑定声明

< javaType>声明提供了一种自定义 XML 数据类型与 Java 数据类型之间的转换的方法。 XML 提供的数据类型比 Java 多，因此< javaType>声明使您可以在默认 JAXB 绑定无法充分表示架构时指定自定义数据类型绑定。

目标 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允许将命名空间上下文指定为 print 或 parse 方法的第二个参数;可以是真，假， 1或0 。默认情况下，此属性为false ，在大多数情况下，无需更改它。
parseMethod是解组时要调用的解析方法的名称。
printMethod是编组期间要调用的打印方法的名称。

< javaType>声明可用于：

A < globalBindings>声明
简单类型定义的注释元素， GlobalBindings和< basetype>声明
< property>声明

有关< javaType>的示例，请参阅 [MyDatatypeConverter类](#bnbch)。声明和DatatypeConverterInterface接口在自定义数据类型转换器类中实现。

Typesafe 枚举绑定声明

类型安全枚举声明提供了将 XML simpleType元素映射到 Java 类型安全枚举类的本地化方法。您可以使用两种类型的类型安全枚举声明：

< typesafeEnumClass>允许您将整个simpleType类映射到typesafe enum类。
< typesafeEnumMember>允许您将simpleType类的选定成员映射到typesafe enum类。

在这两种情况下，这种类型的定制有两个主要限制：

只能使用此绑定声明自定义具有枚举方面的simpleType定义。
此自定义一次仅适用于单个simpleType定义。要在全局级别上映射类似simpleType定义的集合，请使用< globalBindings>中的typesafeEnumBase属性。声明，如全局绑定声明中所述。

< typesafeEnumClass>的语法定制是：

<typesafeEnumClass 
    [ name = "enumClassName" ]
    [ <typesafeEnumMember> ... </typesafeEnumMember> ]*
    [ <javadoc> enumClassJavadoc </javadoc> ]
</typesafeEnumClass>

名称必须是有效的 Java 标识符，并且必须没有包前缀。
您可以拥有零个或多个< typesafeEnumMember>嵌入在< typesafeEnumClass>中的声明声明。
< javadoc>自定义枚举类的 Javadoc 工具注释。

< typesafeEnumMember>的语法定制是：

<typesafeEnumMember 
    name = "enumMemberName">
    [ value = "enumMemberValue" ]
    [ <javadoc> enumMemberJavadoc </javadoc> ]
</typesafeEnumMember>

必须始终指定名称，并且必须是有效的 Java 标识符。
值必须是源模式中指定的枚举值。
< javadoc>为枚举常量自定义 Javadoc 工具注释。

对于内联注释，< typesafeEnumClass>必须在< simpleType>的注释元素中指定声明。元素。 < typesafeEnumMember>必须在枚举成员的注释元素中指定。这使得枚举成员可以独立于枚举类进行定制。

有关类型安全枚举设计模式的信息，请参阅 Oracle 技术网上 Joshua Bloch _ 有效 Java 编程*的示例章节。。

javadoc 绑定声明

< javadoc>声明允许您向模式派生的 JAXB 包，类，接口，方法和字段添加自定义 Javadoc 工具注释。注意< javadoc>声明不能全局应用;它们仅作为其他绑定自定义的子元素有效。

< javadoc>的语法定制是：

<javadoc>
    Contents in <b>Javadoc<\b> format.
</javadoc>

要么

<javadoc>
    <<![CDATA[Contents in <b>Javadoc<\b> format ]]>
</javadoc>

请注意< javadoc>中的文档字符串。在包级别应用的声明必须包含< body>开启和关闭标签;例如：

<jxb:package 
    name="primer.myPo">
    <jxb:javadoc>
        <![CDATA[<body>
            Package level documentation for generated package primer.myPo.
        </body>]]>
    </jxb:javadoc>
</jxb:package>

自定义命名空间前缀

所有标准 JAXB 绑定声明必须以一个映射到 JAXB 名称空间 URI http://java.sun.com/xml/ns/jaxb 的名称空间前缀开头。例如，在该样例中，使用jxb：。为此，您希望使用标准 JAXB 绑定声明自定义的任何模式必须在模式文件的顶部包含 JAXB 名称空间声明和 JAXB 版本号。例如，在po.xsd中的 Customize Inline 示例中，名称空间声明如下：

<xsd:schema 
    xmlns:xsd= "http://www.w3.org/2001/XMLSchema"
    xmlns:jxb= "http://java.sun.com/xml/ns/jaxb"
    jxb:version="1.0">

带有jxb名称空间前缀的绑定声明采用以下形式：

<xsd:annotation>
    <xsd:appinfo>
    <jxb: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 类文件，它实现< javaType>指定的打印和解析方法。po.xsd中的自定义。
Main.java是 Customize Inline 示例中的主类文件，它使用 JAXB 编译器生成的模式派生类。

使用 Ant 构建并运行自定义内联示例

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

ant

本示例中的关键自定义和自定义MyDatatypeConverter.java类将在下一节中详细介绍。

自定义架构

Customize Inline 示例中使用的自定义架构位于文件 jaxb-ri-install /samples/inline-customize/po.xsd中。自定义位于< xsd：annotation>标签。

全球约束声明

以下代码示例显示po.xsd中的globalBindings声明：

<jxb:globalBindings
    fixedAttributeAsConstantProperty="true"
    collectionType="java.util.Vector"
    typesafeEnumBase="xsd:NCName"
    choiceContentProperty="false"
    typesafeEnumMemberName="generateError"
    bindingStyle="elementBinding"
    enableFailFastCheck="false"
    generateIsSetMethod="false"
    underscoreBinding="asCharInWord"/>

在此示例中，除collectionType外，所有值都设置为默认值。

将fixedAttributeAsConstantProperty设置为 true 表示所有固定属性都应绑定到 Java 常量。默认情况下，固定属性将映射到简单属性或集合属性，以较合适的方式。
将collectionType设置为java.util.Vector指定生成的实现类中的所有列表在内部表示为向量。请注意，为collectionType指定的类名必须实现java.util.List ，并且可由newInstance调用。
如果typesafeEnumBase设置为xsd：string ，则它是一种全局方式，用于指定直接或间接从xsd：string 派生的所有简单类型定义并且具有枚举方面，必须默认绑定到类型安全枚举。如果typesafeEnumBase设置为空字符串（“”），则默认情况下简单类型定义不会绑定到类型安全枚举类。 typesafeEnumBase的值可以是除xsd：boolean和两种二进制类型之外的任何原子简单类型定义。
JAXB 实现不支持enableFailFastCheck属性。

注意：使用 typesafe enum 类可以将模式枚举值映射到 Java 常量，这样就可以对 Java 常量而不是字符串值进行比较。

架构绑定声明

以下代码显示po.xsd中的模式绑定声明：

<jxb:schemaBindings>
<jxb:package name="primer.myPo">
    <jxb:javadoc>
        <![CDATA[<body>
            Package level documentation for generated package primer.myPo.
        </body>]]>
    </jxb:javadoc>
</jxb:package>
    <jxb:nameXmlTransform>
        <jxb:elementName suffix="Element"/>
    </jxb:nameXmlTransform>
</jxb:schemaBindings>

< jxb：package name =“primer.myPo”/>指定primer.myPo作为生成模式派生类的包。
< jxb：nameXmlTransform>指定默认情况下所有生成的 Java 元素接口都将Element附加到生成的名称。例如，当针对此模式运行 JAXB 编译器时，将生成元素接口CommentElement和PurchaseOrderElement 。相比之下，如果没有这种自定义，默认绑定会生成Comment和PurchaseOrder 。如果架构在不同的符号空间中使用相同的名称，则此自定义很有用;例如，在全局元素和类型定义中。在这种情况下，此自定义使您可以使用一个声明来解决冲突，而不必使用单独的绑定声明单独解决每个冲突。
< jxb：javadoc>为primer.myPo包指定了自定义的 Javadoc 工具注释。注意，与< javadoc>不同。类级别的声明，如下例所示，开启和关闭< body>< javadoc>时必须包含标签。声明是在包级别进行的。

类绑定声明

以下代码显示po.xsd中的类绑定声明：

<xsd:complexType name="PurchaseOrderType">
    <xsd:annotation>
        <xsd:appinfo>
            <jxb:class name="POType">
                <jxb:javadoc>
                    A &lt;b>Purchase Order&lt;/b>
                    consists of addresses and items.
                </jxb:javadoc>
            </jxb:class>
        </xsd:appinfo>
    </xsd:annotation>
    <!-- ... -->
</xsd:complexType>

模式派生POType类的 Javadoc 工具注释将包含描述“A& lt; b> Purchase Order& lt; / b>由地址和项目组成。” & lt;用于逃离< b>上的开口支架。 HTML 标签。

Note: When a <class> customization is specified in the appinfo element of a complexType definition, as shown in the previous example, the complexType definition is bound to a Java content interface.

后来在po.xsd中，另一个< javadoc>自定义在此类级别声明，但这次使用CDATA转义 HTML 字符串：

<xsd:annotation>
    <xsd:appinfo>
        <jxb:class>
            <jxb:javadoc>
                <![CDATA[
                    First line of documentation for a
                    <b>USAddress</b>.]]>
            </jxb:javadoc>
        </jxb:class>
    </xsd:appinfo>
</xsd:annotation>

Note: If you want to include HTML tags in a <jaxb:javadoc> customization, you must enclose the data within a CDATA section or escape all left angle brackets using <. See XML 1.0 2nd Edition for more information.

属性绑定声明

这里特别感兴趣的是generateIsSetMethod定制，它会导致生成另外两个属性方法isSetQuantity和unsetQuantity 。这些方法使客户端应用程序能够区分模式默认值和实例文档中显式发生的值。

例如，在po.xsd中：

<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" 
                        default="10">
                        <xsd:annotation>
                            <xsd:appinfo>
                                <jxb:property 
                                    generateIsSetMethod="true"/>
                            </xsd:appinfo>
                        </xsd:annotation>
                        <!-- ... -->
                    </xsd:complexType>
            </xsd:element>
    </xsd:sequence>
</xsd:complexType>

@generateIsSetMethod适用于数量元素，该元素绑定到Items.ItemType接口中的属性。 unsetQuantity和isSetQuantity方法在Items.ItemType接口中生成。

`MyDatatypeConverter` Class

类 jaxb-ri-install / samples / inline-customize / src / inlinecustomize / primer / MyDatatypeConverter ，如下例所示，提供了一种自定义 XML 数据转换的方法使用< javaType>的 Java 数据类型的类型定制。

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);
    }
};

以下代码显示了如何在< javaType>中引用MyDatatypeConverter类。po.xsd中的声明：

<xsd:simpleType name="ZipCodeType">
<xsd:annotation>
    <xsd:appinfo>
    <jxb:javaType name="int"
        parseMethod="primer.MyDatatypeConverter.parseIntegerToInt"
        printMethod="primer.MyDatatypeConverter.printIntTo Integer" />
    </xsd:appinfo>
</xsd:annotation>
    <xsd:restriction base="xsd:integer">
    <xsd:minInclusive value="10000"/>
    <xsd:maxInclusive value="99999"/>
    </xsd:restriction>
</xsd:simpleType>

在此示例中， jxb：javaType绑定声明会将此类型的默认 JAXB 绑定覆盖为java.math.BigInteger 。出于 Customize Inline 示例的目的，对ZipCodeType的限制（具体地说，有效的美国邮政编码限制为五位数）使得所有有效值都可以适合 Java 原始数据类型int 。另请注意，因为< jxb：javaType name =“int”/>在ZipCodeType中声明，自定义适用于引用此simpleType定义的所有 JAXB 属性，包括getZip和setZip方法。

DataType 转换器示例

DataType Converter 示例类似于 Customize Inline 示例。与 Customize Inline 示例一样，数据类型转换器示例中的自定义是通过在应用程序的 XML 模式中使用内联绑定声明来实现的， po.xsd 。

Customize Inline 和 DataType Converter 示例的全局，模式和包以及大多数类自定义都是相同的。数据类型转换器示例与 Customize Inline 示例的不同之处在于parseMethod和printMethod ，用于将 XML 数据转换为 Java int数据类型。

具体而言，数据类型转换器示例使用javax.xml.bind.DatatypeConverter提供的内置方法，而不是使用自定义MyDataTypeConverter类中的方法来执行这些数据类型转换：

<xsd:simpleType name="ZipCodeType">
    <xsd:annotation>
        <xsd:appinfo>
            <jxb:javaType 
                name="int"
                parseMethod="javax.xml.bind.DatatypeConverter.parseInt"
                printMethod="javax.xml.bind.DatatypeConverter.printInt"/>
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:restriction base="xsd:integer">
        <xsd:minInclusive value="10000"/>
        <xsd:maxInclusive value="99999"/>
    </xsd:restriction>
</xsd:simpleType>

使用 Ant 构建并运行数据类型转换器示例

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

ant

绑定声明文件

以下部分提供有关绑定声明文件的信息：

JAXB 版本，命名空间和架构属性
全局和架构绑定声明
类声明

JAXB 版本，命名空间和架构属性

所有 JAXB 绑定声明文件必须以：

JAXB 版本号
命名空间声明
架构名称和节点

bindings.xjb中的版本，命名空间和模式声明如下：

<jxb:bindings 
    version="1.0"
    xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <jxb:bindings 
        schemaLocation="po.xsd" 
        node="/xs:schema">
            <!-- ...
            binding-declarations 
            ... -->
    </jxb:bindings>
    <!-- 
    schemaLocation="po.xsd" 
    node="/xs:schema" -->
</jxb:bindings>

JAXB 版本号

根元素为< jaxb：bindings>的 XML 文件被视为外部绑定文件。根元素必须指定其绑定声明必须符合的 JAXB 版本属性;特别是根< jxb：bindings>元素必须包含< jxb：版本>声明或版本属性。相反，在内联绑定声明时，JAXB 版本号作为< xsd：schema>的属性。声明：

<xsd:schema 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
    jxb:version="1.0">

命名空间声明

如 JAXB 版本，命名空间和架构属性所示，外部绑定声明文件中的命名空间声明包括 JAXB 命名空间和 XMLSchema 命名空间。请注意，此示例中使用的前缀实际上可能是您想要的任何内容;重要的是始终在文件的后续声明中使用您在此处定义的任何前缀。

架构名称和架构节点

JAXB 版本，命名空间和架构属性中代码的第四行指定此绑定声明文件应用于的架构的名称，以及自定义将首先生效的架构节点。此文件中的后续绑定声明可以引用模式中的特定节点，但是第一个声明应该包含整个模式;例如，在bindings.xjb中：

<jxb:bindings schemaLocation="po.xsd" node="/xs:schema">

全局和架构绑定声明

bindings.xjb中的全局模式绑定声明与 DataType Converter 示例中po.xsd中的相同。唯一的区别是因为po.xsd中的声明是内联的，你必须将它们嵌入< xs：appinfo>元素，它们又嵌入< xs：annotation>元素。在外部绑定文件中不需要以这种方式嵌入声明。

<jxb:globalBindings
    fixedAttributeAsConstantProperty="true"
    collectionType="java.util.Vector"
    typesafeEnumBase="xs:NCName"
    choiceContentProperty="false"
    typesafeEnumMemberName="generateError"
    bindingStyle="elementBinding"
    enableFailFastCheck="false"
    generateIsSetMethod="false"
    underscoreBinding="asCharInWord"/>
    <jxb:schemaBindings>
        <jxb:package name="primer.myPo">
            <jxb:javadoc>
                <![CDATA[<body>
                    Package level documentation for generated package
                    primer.myPo.</body>]]>
                </jxb:javadoc>
        </jxb:package>
        <jxb:nameXmlTransform>
            <jxb:elementName suffix="Element"/>
        </jxb:nameXmlTransform>
    </jxb:schemaBindings>

相比之下， po.xsd中用于 DataType Converter 示例的语法是：

<xsd:annotation>
    <xsd:appinfo>
        <jxb:globalBindings
            ...
            binding-declarations
            ...
        <jxb:schemaBindings>
            ...
            binding-declarations
            ...
        </jxb:schemaBindings>
    </xsd:appinfo>
</xsd:annotation>

类声明

bindings.xjb中的类级绑定声明与po.xsd中的数据类型转换器示例中的类似声明有两种不同：

与bindings.xjb中的所有其他绑定声明一样，您无需在架构< xsd：appinfo>中嵌入自定义项。元素。
您必须指定要应用自定义的架构节点。此类声明的一般语法是：
```
&lt; jxb：bindings node =“//  node-type  [@ name =' node-name ' ]“&GT;
```

例如，以下代码显示名为USAddress的complexType的绑定声明。

<jxb:bindings node="//xs:complexType [@name=’USAddress’]">
    <jxb:class>
        <jxb:javadoc>
            <![CDATA[
                First line of documentation for a <b>USAddress</b>.
            ]]>
        </jxb:javadoc>
    </jxb:class>
<jxb:bindings node=".//xs:element [@name=’name’]">
    <jxb:property name="toName"/>
</jxb:bindings>
<jxb:bindings node=".//xs:element [@name=’zip’]">
    <jxb:property name="zipCode"/>
</jxb:bindings>
</jxb:bindings>
<!-- 
    node="//xs:complexType
    [@name=’USAddress’]" -->

注意，在该示例中， USAddress是子元素名称和zip的父亲，因此< / jxb：bindings>标签包含子元素和类级别javadoc声明的绑定声明。

外部自定义示例

外部自定义示例与 DataType Converter 示例相同，只是外部自定义示例中的绑定声明是使用外部绑定声明文件而不是源 XML 架构中的内联进行的。

外部自定义示例中使用的绑定自定义文件是 jaxb-ri-install /samples/external-customize/binding.xjb 。

本节将bindings.xjb中的自定义声明与数据类型转换器示例中 XML 模式po.xsd中使用的类似声明进行比较。这两组声明实现了完全相同的结果。

使用 Ant 构建并运行外部自定义示例

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

ant

自定义 JAXB 绑定

自定义 JAXB 绑定

自定义概述

内联和外部自定义

内联自定义

外部绑定自定义文件

绑定自定义文件格式

将自定义文件传递给 JAXB 绑定编译器

外部绑定自定义的限制

范围，继承和优先顺序

自定义语法

全球约束声明

架构绑定声明

类绑定声明

属性绑定声明

javaType 绑定声明

Typesafe 枚举绑定声明

javadoc 绑定声明

自定义命名空间前缀

自定义内联示例

使用 Ant 构建并运行自定义内联示例

自定义架构

全球约束声明

架构绑定声明

类绑定声明

属性绑定声明

MyDatatypeConverter Class

DataType 转换器示例

使用 Ant 构建并运行数据类型转换器示例

绑定声明文件

JAXB 版本，命名空间和架构属性

JAXB 版本号

命名空间声明

架构名称和架构节点

全局和架构绑定声明

类声明

外部自定义示例

使用 Ant 构建并运行外部自定义示例

`MyDatatypeConverter` Class