ch06-binding_xml_schema.adoc 124 KB
Newer Older
1
//
2
// Copyright (c) 2020, 2021 Contributors to the Eclipse Foundation
3 4
//

Lukas Jungmann's avatar
Lukas Jungmann committed
5
== Binding XML Schema to Java Representations
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

This chapter describes binding of XML schema
components to Java representations. The default binding is identified in
this chapter and the next chapter specifies the customizations that
override default binding.

=== Overview

The abstract model described in [XSD Part 1]
is used to discuss the default binding of each schema component type.
Each schema component is described as a list of properties and their
semantics. References to properties of a schema component as defined in
[XSD Part 1] are denoted using the notation _{schema property}_
throughout this section. References to properties of information items
as defined in [XML-Infoset] are denoted by the notation *[property]*.

All JAXB implementations are required to
implement the default bindings specified in this chapter. However, users
and JAXB implementors can use the global configuration capabilities of
the custom binding mechanism to override the defaults in a portable
manner.

For each binding of a schema component to its
Java representation, there is a description of Java mapping
30 31
annotation(s), described in <<Java Types To XML>>,
to be generated with the Java representation. The
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
standardization of these mapping annotations assist in specifying the
portability of a schema-derived JAXB-annotated classes. All JAXB
implementations are required to be able to unmarshal/marshal another
implementations schema-derived Java value classes by interpreting the
specified mapping annotations. Note that each mapping annotation is
described independent of whether it is the default mapping or a
customized mapping, JAXB implementations are allowed to optimize away
redundant mapping annotations that are the default mapping annotation.

[NOTE]
.Design Note
====
Note that the mapping annotations generated on the schema derived
classes do not capture all aspects from the original schema.
A schema generated from the mapping annotations of the schema derived
classes differs from the original schema used to generate
the schema-derived classes. The original schema is more precise
for validation purposes than the one generated from the schema-derived classes.

====

All examples are non-normative. Note that in
the examples, the schema-derived code does not list all required mapping
annotations. In the interest of being terse, only the mapping
annotations directly connected to the schema component being discussed
are listed in its example.

Lukas Jungmann's avatar
Lukas Jungmann committed
59
=== Simple Type Definition
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76

A schema component using a simple type
definition typically binds to a Java property. Since there are different
kinds of such schema components, the following Java property attributes
(common to the schema components) are specified here and include:

* base type
* collection type if any
* predicate

The rest of the Java property attributes are
specified in the schema component using the simple type definition.

While not necessary to perform by default,
this section illustrates how a simple type definition is bound to a JAXB
mapped class. This binding is necessary to preserve a simple type
definition referred to by `xsi:type` attribute in an Xml instance
77
document. See <<Usage>> for the
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
customization that enables this binding.

==== Type Categorization

The simple type definitions can be categorized as:

* schema built-in datatypes [XSD PART2]
* user-derived datatypes

Conceptually, there is no difference between
the two. A schema built-in datatype can be a primitive datatype. But it
can also, like a user-derived datatype, be derived from a schema
built-in datatype. Hence no distinction is made between the schema
built-in and user-derived datatypes.

The specification of simple type definitions
is based on the abstract model described in Section 4.1, Simple Type
Definition [XSD PART2]. The abstract model defines three varieties of
simple type definitions: atomic, list, union. The Java property
attributes for each of these are described next.

Lukas Jungmann's avatar
Lukas Jungmann committed
99
==== Atomic Datatype
100 101 102

If an atomic datatype has been derived by
restriction using an enumeration facet, the Java property attributes
103
are defined by <<Enum Type>>. Otherwise
104 105 106 107 108 109 110 111 112 113 114 115 116 117
they are defined as described here.

The base type is derived upon the XML
built-in type hierarchy [XSD PART2, Section 3] reproduced below.

.XML Built-In Type Hierarchy
image::images/xmlb-15.png[image]


The above diagram is the same as the one in
[XSD PART2] except for the following:

* Only schema built-in atomic datatypes derived by restriction have been shown.
* The schema built-in atomic datatypes have been annotated with Java data types
118
from the <<a725>> table below.
119 120 121 122 123 124

[NOTE]
.Design Note
====
xs:anyURI is not bound to java.net.URI by default since not all
possible values of xs:anyURI can be passed to the java.net.URI constructor.
125
Using a global JAXB customization described in <<javatype-declaration>>,
126 127 128 129 130 131 132 133 134
a JAXB user can override the default mapping to map xs:anyURI to java.net.URI.

====


The following is a mapping for subset of the
XML schema built-in data types to Java data types. This table is used to
specify the base type later.

135 136
.Java Mapping for XML Schema Built-in Types
[[a725]]
137 138 139 140 141 142 143 144 145 146 147 148 149
[cols="2*",options="header"]
|===
|XML Schema Datatype |Java Datatype
| *xsd:string* | *java.lang.String*
| *xsd:integer* | *java.math.BigInteger*
| *xsd:int* | *int*
| *xsd:long* | *long*
| *xsd:short* | *short*
| *xsd:decimal* | *java.math.BigDecimal*
| *xsd:float* | *float*
| *xsd:double* | *double*
| *xsd:boolean* | *boolean*
| *xsd:byte* | *byte*
Lukas Jungmann's avatar
Lukas Jungmann committed
150
| *xsd:QName* | *javax.xml.namespace.QName* footnote:jaxp[JAXP defines package
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280
`javax.xml.datatype` and `javax.xml.namespace`]
| xsd:dateTime |javax.xml.datatype.XMLGregorianCalendar footnote:jaxp[]
| *xsd:base64Binary* | *byte[]*
| *xsd:hexBinary* | *byte[]*
| xsd:unsignedInt | long
| xsd:unsignedShort | int
| xsd:unsignedByte | short
| xsd:time | javax.xml.datatype.XMLGregorianCalendar footnote:jaxp[]
| xsd:date | javax.xml.datatype.XMLGregorianCalendar footnote:jaxp[]
| xsd:g* | javax.xml.datatype.XMLGregorianCalendar footnote:jaxp[]
| xsd:anySimpleType +
(for xsd:element of this type)footnote:[enable type substitution for element of xsd:anySimpleType] | java.lang.Object
| xsd:anySimpleType +
(for xsd:attribute of this type) | java.lang.String
| xsd:duration | javax.xml.datatype.Duration footnote:jaxp[]
| xsd:NOTATION | javax.xml.namespace.QName footnote:jaxp[]
|===

The base type is determined as follows:

. Map by value space bounding facets +
If the simple type derives from or is `xsd:integer` and has either a
constraining lower and/or upper bounds facet(s) or totalDigits facet,
check if the following optimized binding is possible:
* If the simple type derives from or is
`xsd:short`, `xsd:byte` or `xsd:unsignedByte`, go to step 2.
* If the value space for the simple type is
representable in the range of `java.lang.Integer.MIN_VALUE` and
`java.lang.Integer.MAX_VALUE`, map to java primitive type, `int`.
* If the value space for the simple type is
representable in the range of `java.lang.Long.MIN_VALUE` and
`java.lang.Long.MAX_VALUE`, map to java primitive type, `long`.
* Else go to step 2.
. Map by datatype +
If a mapping is defined for the simple type in Table 6.1, the base type
defaults to its defined Java datatype.
. Map by base datatype +
Otherwise, the base type must be the result obtained by repeating the
step 1 and 2 using the _{base type definition}_. For schema datatypes
derived by restriction, the _{base type definition}_ represents the
simple type definition from which it is derived. Therefore, repeating
step 1 with _{base type definition}_ essentially walks up the XML Schema
built-in type hierarchy until a simple type definition which is mapped
to a Java datatype is found.

The Java property predicate must be as
specified in Simple Type Definition Validation Rules, Section
4.1.4[XSD PART2].

*_Example:_* +
The following schema fragment (taken from
Section 4.3.1, Length [XSD PART2]):

[source,xml,indent=4]
----
<xs:simpleType name="productCode">
  <xs:restriction base="xs:string">
    <xs:length value="8" fixed="true"/>
  </xs:restriction>
</xs:simpleType>
----

The facet length constrains the length of a
product code (represented by `productCode`) to 8 characters (see
section 4.3.1 [XSD PART2] for details).

The Java property attributes corresponding to
the above schema fragment are:

* There is no Java datatype mapping for `productCode`.
So the Java datatype is determined by walking up the
built-in type hierarchy.
* The `{base type definition}` of `productCode`
is `xs:string`. `xs:string` is mapped to `java.lang.String`
(as indicated in the table, and assuming no customization). Therefore,
`productCode` is mapped to the Java datatype `java.lang.String`.
* The predicate enforces the constraints on the length.

===== Notation

Given that the value space of `xsd:NOTATION`
is the set of `xsd:QName`, bind `xsd:NOTATION` type to
`javax.xml.namespace.QName`.

For example, the following schema:

[source,xml]
----
<xs:schema targetNamespace="http://e.org" xmlns:e="http://e.org"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:notation name="jpeg" public="image/jpeg" system="jpeg.exe"/>
  <xs:notation name="png" public="image/png" system="png.exe"/>
  <xs:simpleType name="pictureType">
    <xs:restriction base="xs:NOTATION">
      <xs:enumeration value="e:jpeg"/>
      <xs:enumeration value="e:png"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="Picture">
    <xs:simpleContent>
      <xs:extension base="xs:hexBinary">
        <xs:attribute name="format" type="e:pictureType"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>
----

is mapped to the following Java code:

[source,java]
----
package org.e;
import javax.xml.namespace.QName;
public class Picture {
    void setValue(byte[] value) {...}
    byte[] getValue() {...}
    void setFormat(QName value)\{...}
    QName getFormat() {...}
}
----

With the following usage scenario:

[source,java,indent=4]
----
Picture pic = ...;
pic.setFormat(new QName("http://e.org","jpeg"));
----

Lukas Jungmann's avatar
Lukas Jungmann committed
281
===== Bind to a JAXB mapped class
282 283 284 285

By default, a named simple type definition is
not bound to a Java class. This binding is only necessary to enable the
precise type of an `xsi:type` substitution to be preserved as described
286 287
in <<Type Substitution of a Simple Type Definition>>.
This binding is enabled via the global binding
288
customization attribute _@mapSimpleTypeDef_ specified in
289
<<Usage>>.
290 291 292

The binding of a named simple type definition
to a Java value class is based on the abstract model properties in
293 294
<<Simple Type Definition Schema Component>>.
The Java value class must be defined as specified here,
295 296 297 298 299 300
unless the ref attribute is specified on the `<jaxb:class>` declaration,
in which case the schema compiler will simply assume that the nominated
class is already bound to this simple type.

* *name*: name is the Java identifier
obtained by mapping the XML name _{name}_ using the name mapping
301 302
algorithm, specified in <<The Name to Identifier Mapping Algorithm>>.
Note that anonymous simple type
303 304 305 306 307 308 309 310 311 312
definitions are never bound to a Java value class.
* *package*: The schema-derived Java value class is generated
into the Java package that represents the binding of _{target namespace}_
* *outer class name*: There is no outer class name for a global
simple type definition.
* *base class*: Due to a constraint specified for @XmlValue
in Section 8, this class can not extend any other class. The derivation
by restriction hierarchy for simple type definitions can not be captured
in the schema-derived Java value class.
* *value property*: Same as the binding of simple content in
313
<<Simple Content Binding>> to an @XmlValue
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
annotated JAXB property.

The next two examples illustrate the binding
of a simple type definition to a Java value class when the appropriate
JAXB schema customization is enabled.

[#a816]
.Simple type definition
[source,xml,indent=4]
----
<xs:simpleType name="productCode">
  <xs:restriction base="xs:string">
    <xs:length value="8" fixed="true"/>
  </xs:restriction>
</xs:simpleType>
----

.Binding of <<a816>>
[source,java,indent=4]
----
@XmlType(name="productCode")
public class ProductCode {
    @XmlValue
    String getValue();
    void setValue(String value);
}
----

Lukas Jungmann's avatar
Lukas Jungmann committed
342
===== Annotations for standard XML datatypes
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358

By default, a schema-derived JAXB property
bound from one of the following standard XML datatypes is annotated with
the specified mapping annotation.

[cols="2*",options="header"]
|===
| `*Schema Type*` | `*JAXB Property Annotation*`
| `xsd:ID` | `@XmlID`
| `xsd:IDREF` | `@XmlIDREF`
| `ref:swaRef` | `@XmlAttachmentRef`
|===

Note that JAXB schema customizations could
override these default binding.

Lukas Jungmann's avatar
Lukas Jungmann committed
359
==== Enum Type
360 361 362 363 364 365 366

The default mapping for a named atomic type
that is derived by restriction with enumeration facet(s) and whose
restriction base type (represented by _{base type definition}_) is
`xs:String` footnote:[Exception cases that
do not bind to enum type: when the base type is or derives from `xs:ID`
and `xs:IDREF`. Rationale for not binding these type definitions to an
367
enum type is in <<Customizable Schema Elements>>.] or derived from it is mapped to an
368
enum type. The *[typesafeEnumBase]* attribute customization described in
369
<<globalbindings-declaration>>, enables
370 371 372
global configuration to alter what Xml built-in datatypes are bound by
default to an enum type. An anonymous simple type definition is never
bound to an enum class by default, but it can be customized as described
373
in <<typesafeenum-declaration>> to bind to an enum type.
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398

===== Example binding

An example is provided first followed by a
more formal specification.

XML Schema fragment:

[source,xml,indent=4]
----
<xs:simpleType name="USState">
  <xs:restriction base="xs:NCName">
    <xs:enumeration value="AK"/>
    <xs:enumeration value="AL"/>
  </xs:restriction>
</xs:simpleType>
----

The corresponding enum type binding is:

[source,java,indent=4]
----
public enum USState {
    AK, AL;
    public String value() { return name(); }
Lukas Jungmann's avatar
Lukas Jungmann committed
399
    public static USState fromValue(String value) {...}
400 401 402 403 404 405 406
};
----

===== Enum type binding

The characteristics of an _enum type_ are
derived in terms of the properties of the
407
<<Simple Type Definition Schema Component>> as follows:
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423

The enum type binding is defined as follows:

* *name*: The default name of the enum type,
_enumType_, is computed by applying the XML Name to Java identifier
mapping algorithm to the _{name}_ of the simple type definition. There
is no mechanism to derive a name for an anonymous simple type
definition, the customization must provide the *name*.
* *package name*: The package name is
determined from the _{targetnamespace}_ of the schema that directly
contains the simple type definition.
* *outer class name*:
** There is no *outer class name* for a global
simple type definition.
** There is no *outer class name* when schema
customization, *[jaxb:globalBindings]* _@localScoping_ , specified in
424
Section <<Usage>>, has a value of
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
_toplevel_.
** The *outer class name* for an anonymous
simple type definition is computed by traversing up the anonymous simple
type definitions ancestor tree until the first ancestor is found that
is:
*** an XML component that is mapped to a Java value class, the *outer
class name* is composed of the concatenation of this Java value classs
*outer class name*, "**.**", and its *name*.
*** a global declaration or definition is reached. There is no *outer
class name* for this case.
* *enum constants*: Specified in next section.

Note that since a Java enum type is
essentially a final class, it is not possible for it to be subclassed.
Thus, any derivations of a simple type definition bound to an enum type
can not be captured by an equivalent Java inheritance relationship.

The schema-derived enum is annotated, either
explicitly or by default mapping annotations, with the mapping
annotation @XmlEnum, specified in Section 8. The @XmlEnum annotation
elements are derived in terms of the abstract model properties for a
446 447
simple type definition summarized in
<<Simple Type Definition Schema Component>> as follows:
448 449 450 451 452 453 454 455 456 457 458 459 460 461 462

.Annotate enum type with @XmlEnum element-value pairs
[cols="2*",options="header"]
|===
| @XmlEnum element | @XmlEnum value
| name | simple type definition's {name}
| namespace | {target namespace}
| value | the java type binding of the simple type definition’s _{base type definition}_
|===

===== Enum Constant

An enum constant is derived for each
enumeration facet of the atomic type definition. The characteristics of
an _enum constant_ of the enum type are derived in terms of the properties
463
of the <<Enumeration Facet Schema Component>> as follows:
464 465 466

* *name*: The name is either specified via
customization, `jaxb:typesafeEnumMember` described in
467 468
<<usage-7>>, or the name is computed as
specified in <<xml-enumvalue-to-java-identifier-mapping>>.
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
* *type*: The Java type binding of the simple
type definition’s _{base_type_definition}_.
* *value* : The conversion of string
_{value}_ to *type*. *Value* is manipulated via the following
generated enum type methods:

 public        type         value();
 public static enumTypeName fromValue(type value);

To assist an application in manipulating the
enum constants that comprise an enum type, all enum types have the
following two implicitly declared static methods as specified in Section
8.9 in [JLS3]. The enum type’s static method `values()` returns an array
of all enum constants. The static method `valueOf(String name)` returns
the enum constant represented by the name parameter.

===== XML Enumvalue-[[a863]]to-Java Identifier Mapping

The default name for the enum constant is
based on mapping of the XML enumeration value to a Java identifier as
described below.

The XML enumeration value _{value}_ is
mapped to a Java Identifier using the algorithm specified in
493 494
<<Deriving a legal Java identifier from an enum facet value>>.
If there is a collision among the generated
495 496
constant fields *name* or if it is not possible to generate a legal Java
identifier for one or more of the generated constant field names, see
497
<<typesafeenummembername>> for customization options to resolve this error case.
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515

===== Enum Constant Name differs from its Value

For all cases where there exist at least one
enumeration constant name that is not the same as the enumeration
constant’s value, the generated enum type must have a final value field
that is set by the enum type’s constructor. The code generation template
is the following:

.At least one enum constant name differs from its value.
[source,java]
----
public enum enumType {
    EnumConstantName1(EnumConstantValue1),
    ...
    EnumConstantNameX(EnumConstantValueX);
    public EnumConstantValueType value() { return value; }
    public static enumType fromValue(EnumConstantValueType val)
Lukas Jungmann's avatar
Lukas Jungmann committed
516
        {...}
517 518 519 520 521 522 523 524 525 526 527 528 529 530

    final private EnumConstantValueType value;
    private enumType(EnumConstantValueType value) {
        this.value = value;
    }
}
----

.Code template when enum constant name is same as its enum constant value.
[source,java,subs="+quotes,+macros"]
----
public enum enumType {
    EnumConstantName1, ..., EnumConstantNameX;
    public Stringfootnote:[Note for this case, the _enumConstantValueType_ is always `java.lang.String`.] value() { return name(); }
Lukas Jungmann's avatar
Lukas Jungmann committed
531
    public static enumType fromValue(String value) {...}
532 533 534 535 536 537 538 539
}
----

The schema-derived enum constant is
annotated, either explicitly or by default mapping annotations, with the
mapping annotation specified in Section 8. The `@XmlEnumValue`
annotation elements are derived in terms of the abstract model
properties for a enumerated facet summarized in
540
<<Enumeration Facet Schema Component>> as
541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580
follows:

.Annotate enum constant with @XmlEnumValue element-value pairs
[cols="2*",options="header"]
|===
| @XmlEnumValue element | @XmlEnumValue value
| value | Enumeration facet’s {value}
|===


Given following schema fragment:

.Schema-derived enum type when enumeration facet’s value does not match enum constant name.

[source,xml,indent=4]
----
<xs:simpleType name="Coin">
  <!-- Assume jaxb customization that binds Coin to an enumType -->
  <xs:restriction base="xs:int"> +
    <!-- Assume jaxb customization specifying enumConstantName -->
    <xs:enumeration value="1"/> <!-- name="penny"-->
    <xs:enumeration value="5"/> <!-- name="nickel"-->
    <xs:enumeration value="10"/><!-- name="dime"-->
    <xs:enumeration value="25"/><!-- name="quarter-->
  </xs:restriction>
</xs:simpleType>
----

Schema-derived enum type:

[source,java,indent=4]
----
@XmlEnum(value="java.lang.Integer.class")
public enum Coin {
    @XmlEnumValue("1") PENNY(1),
    @XmlEnumValue("5") NICKEL(5),
    @XmlEnumValue("10") DIME(10),
    @XmlEnumValue("25") QUARTER(25);

    public int value() { return value; }
Lukas Jungmann's avatar
Lukas Jungmann committed
581
    public static Coin fromValue(int value) {...}
582 583 584 585 586 587

    private final Integer value;
    Coin(int value) { this.value = value; }
}
----

Lukas Jungmann's avatar
Lukas Jungmann committed
588
==== List
589 590 591 592 593 594 595 596 597 598 599 600 601

A list simple type definition can only
contain list items of atomic or union datatypes. The item type within
the list is represented by the schema property _{item type definition}_.

The Java property attributes for a list
simple type definition are:

* The _base type_ is derived from the _{item type definition}_ as follows.
If the Java datatype for _{item type definition}_ is a Java primitive type,
then the base type is the wrapper
class for the Java primitive type. Otherwise, the Java datatype is
derived from the XML datatype as specified in
602
<<Atomic Datatype>> and <<Enum Type>>.
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624
* The _collection type_ defaults to an
implementation of `java.util.List`. Note that this specification does
not specify the default implementation for the interface
`java.util.List`, it is implementation dependent.
* The _predicate_ is derived from the “Simple
Type Definition Validation Rules,” in section 4.1.4,[XSD PART2].

*_Example:_* +
For the following schema fragment:

[source,xml,indent=4]
----
<xs:simpleType name="xs:USStateList">
  <xs:list itemType="xs:string"/>
</xs:simpleType>
----

The corresponding Java property attributes
are:

* The _base type_ is derived from _{item type definition}_
which is XML datatype, `_"xs:string"_` , thus the Java
625
datatype is `java.util.String` as specified in <<a725>>.
626 627 628
* The _collection type_ defaults to an implementation of `java.util.List`.
* The _predicate_ only allows instances of
_base type_ to be inserted into the list. When failfast check is being
629
performedfootnote:[<<Usage>>
630
describes the `enableFailFastCheck` customization and
631
<<Validation>> defines fail-fast
632 633 634 635 636 637 638 639 640
checking.], the list’s mutation methods apply the
property’s predicate to any non-`null` value before adding that value
to the list or replacing an existing element’s value with that value;
the predicate may throw a `TypeConstraintException`.

The schema-derived property is annotated,
either explicitly or by default mapping annotations, with the mapping
annotation @XmlList, specified in Section 8.

Lukas Jungmann's avatar
Lukas Jungmann committed
641
==== Union Property
642 643 644 645 646 647 648 649 650 651 652 653 654 655

A union property _prop_ is used to bind a
union simple type definition schema component. A union simple type
definition schema component consists of union members which are schema
datatypes. A union property, is therefore, realized by:

[source,java,indent=8]
----
public Type getId();
public void setId(Type value);
----

where `_Id_` is a metavariable that represents
the Java method identifier computed by applying the name mapping
656
algorithm described in <<The Name to Identifier Mapping Algorithm>> to _prop_ .
657 658 659 660 661

The _base type_ is String. If one of the
member types is derived by list, then the Union property is represented
as the appropriate collection property as specified by the customization
`<jaxb:globalBindings>` *@collectionType* value, specified in
662
<<Usage>>.
663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702

* The `getId` method returns the set value.
If the property has no set value then the value `null` is returned. The
value returned is Type.
* The `setId` method sets the set value. +
If value is `null`, the property’s _set value_ is discarded. Prior to
setting the property’s value when TypeConstraint validation is enabled,
a non-`null` value is validated by applying the property’s predicate,
which may throw a `TypeConstraintException`. No setter is generated if
the union is represented as a collection property.

*_Example: Default Binding: Union_*

The following schema fragment:
[source,xml,indent=4]
----
<xs:complexType name="CTType">
  <xs:attribute name="state" type="ZipOrName"/>
</xs:complexType>
<xs:simpleType name="ZipOrName"
               memberTypes="xs:integer xs:string"/>
----

is bound to the following Java representation.

[source,java]
----
public class CTType {
    String getState() {...}
    void setState(String value) {...}
}
----

==== Union

A simple type definition derived by a union
is bound using the union property with the following Java property
attributes:

* the _base type_ as specified in
703
<<Union Property>>.
704 705 706 707 708 709
* if one of the member types is derived by `<xs:list>`,
then the union is bound as a Collection property.
* The _predicate_ is the schema constraints
specified in “Simple Type Definition Validation Rules,” Section 4.1.4
[XSD PART2].

Lukas Jungmann's avatar
Lukas Jungmann committed
710
=== Complex Type Definition
711

Lukas Jungmann's avatar
Lukas Jungmann committed
712
==== Aggregation of Java Representation
713 714 715 716 717 718 719 720 721

A Java representation for the entire schema
is built based on aggregation. A schema component aggregates the Java
representation of all the schema components that it references. This
process is done until all the Java representation for the entire schema
is built. Hence a general model for aggregation is specified here once
and referred to in different parts of the specification.

The model assumes that there is a schema
Lukas Jungmann's avatar
Lukas Jungmann committed
722
component _SP_ which references another schema component _SC_. The Java
723
representation of _SP_ needs to aggregate the Java representation of
Lukas Jungmann's avatar
Lukas Jungmann committed
724
_SC_. There are two possibilities:
725

Lukas Jungmann's avatar
Lukas Jungmann committed
726 727
* _SC_ is bound to a property set.
* _SC_ is bound to a Java datatype or a Java value class.
728 729 730 731 732 733 734 735 736

Each of these is described below.

===== Aggregation of Datatype/Class

If a schema component _SC_ is bound to a Java
datatype or a Java value class, then _SP_ aggregates _SC’s_ Java
representation as a simple property defined by:

Lukas Jungmann's avatar
Lukas Jungmann committed
737
* *name*: the name is the class/interface
738 739 740
name or the Java datatype or a name determined by SP. The name of the
property is therefore defined by the schema component which is
performing the aggregation.
Lukas Jungmann's avatar
Lukas Jungmann committed
741
* *base type*: If SC is bound to a Java
742 743 744
datatype, the base type is the Java datatype. If SC is bound to a Java
value class, then the base type is the class name, including a dot
separated list of class names within which SC is nested.
Lukas Jungmann's avatar
Lukas Jungmann committed
745 746
* *collection type*: There is no collection type.
* *predicate*: There is no predicate.
747

Lukas Jungmann's avatar
Lukas Jungmann committed
748
===== Aggregation of Property Set
749 750 751 752 753 754 755 756 757 758

If _SC_ is bound to a property set, then _SP_
aggregates by adding _SC’s_ property set to its own property set.

Aggregation of property sets can result in
name collisions. A name collision can arise if two property names are
identical. A binding compiler must generate an error on name collision.
Name collisions can be resolved by using customization to change a
property name.

Lukas Jungmann's avatar
Lukas Jungmann committed
759
==== Java value class
760

Lukas Jungmann's avatar
Lukas Jungmann committed
761
The binding of a complex type
762
definition to a Java value class is based on the abstract model
763
properties in <<Complex Type Definition Schema Component>>. The Java value class must be defined as specified
764 765 766
here, unless the ref attribute is specified on the _<jaxb:class>_
customization, in which case the schema compiler will simply assume that
the nominated class is already bound to this complex
Lukas Jungmann's avatar
Lukas Jungmann committed
767
type.footnote:[Note that
768
<<Binding of an anonymous complex type definition>> defines the name and package property for anonymous type
Lukas Jungmann's avatar
Lukas Jungmann committed
769
definitions occurring within an element declaration.]
770

Lukas Jungmann's avatar
Lukas Jungmann committed
771 772
* *name*: name is the Java identifier
obtained by mapping the XML name _{name}_ using the name mapping
773 774 775 776
algorithm, specified in <<The Name to Identifier Mapping Algorithm>>.
For the handling of an anonymous complex
type definition, see <<Binding of an anonymous complex type definition>>
for how a *name* value is derived
777
from its parent element declaration.
Lukas Jungmann's avatar
Lukas Jungmann committed
778 779
* *package*:
** For a global complex type definition, the
780
derived Java value class is generated into the Java package that
Lukas Jungmann's avatar
Lukas Jungmann committed
781 782
represents the binding of _{target namespace}_
** For the value of *package* for an anonymous
783
complex type definition, see <<Binding of an anonymous complex type definition>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
784 785
* *outer class name*:
** There is no outer class name for a global
786
complex type definition.
787
** <<Binding of an anonymous complex type definition>> defines how to derive this
788 789
property from the element declaration that contains the anonymous
complex type definition.
Lukas Jungmann's avatar
Lukas Jungmann committed
790 791 792
* *base class*: A complex type definition
can derive by restriction or extension (i.e. _{derivation method}_ is
either "extension" or "restriction"). However, since there is no concept
793
in Java programming similar to restriction, both are handled the same.
Lukas Jungmann's avatar
Lukas Jungmann committed
794 795 796 797 798 799 800 801
If the _{base type definition}_ is itself mapped to a Java value class
(Ci2), then the base class must be Ci2. This must be realized as:
+
--
[source,java]
----
public class Ci1 extends Ci2 {
    .....
802
}
Lukas Jungmann's avatar
Lukas Jungmann committed
803 804 805
----
--
+
806 807 808
See example of derivation by extension at the
end of this section.

Lukas Jungmann's avatar
Lukas Jungmann committed
809 810 811 812
* *abstract*: The generated Java class is
abstract when the complex type definition’s _{abstract}_ property is
`true`.
* *property set*: The Java representation of
813
each of the following must be aggregated into Java value class’s
814
property set (<<Aggregation of Java Representation>>).
Lukas Jungmann's avatar
Lukas Jungmann committed
815
** A subset of _{attribute uses}_ is
816
constructed. The subset must include the schema attributes corresponding
Lukas Jungmann's avatar
Lukas Jungmann committed
817
to the `<xs:attribute>` children and the _{attribute uses}_ of the
818
schema attribute groups resolved by the <ref> attribute. Every
819
attribute’s Java representation (<<Attribute use>>)
Lukas Jungmann's avatar
Lukas Jungmann committed
820 821
in the set of attributes computed above must be aggregated.
** If the optional _{attribute wildcard}_ is
822
present, either directly or indirectly, a property defined by
823
<<Attribute Wildcard>> is generated.
Lukas Jungmann's avatar
Lukas Jungmann committed
824 825
** The Java representation for _{content type}_ must be aggregated.
+
826
For a “Complex Type Definition with complex
Lukas Jungmann's avatar
Lukas Jungmann committed
827
content,” the Java representation for _{content type}_ is specified in
828
<<content-model-particle-model-group-wildcard>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
829
+
830
For a complex type definition which is a “Simple Type Definition with
Lukas Jungmann's avatar
Lukas Jungmann committed
831
simple content,” the Java representation for _{content type}_ is
832
specified in <<Simple Content Binding>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
833
** If a complex type derives by restriction,
834 835 836 837 838
there is no requirement that Java properties representing the attributes
or elements removed by the restriction to be disabled. This is because
(as noted earlier), derivation by restriction is handled the same as
derivation by extension.
* When the complex type definition’s
Lukas Jungmann's avatar
Lukas Jungmann committed
839 840
_{abstract}_ property is `false`, a factory method is generated in the
package’s `ObjectFactory` class introduced in
841
<<Java Package>>. The factory method
842 843
returns the type of the Java value class. The name of the factory method
is generated by concatenating the following components:
Lukas Jungmann's avatar
Lukas Jungmann committed
844 845
** The string constant `create`.
** The _name_ of the Java value class.
846 847 848

The schema-derived Java value class is
annotated, either explicitly or by default mapping annotations, with the
849
mapping annotation @XmlType, specified in <<xmltype-3>>. The @XmlType annotation
850
elements are derived in terms of the abstract model properties for a
851 852
complex type definition summarized in
<<Complex Type Definition Schema Component>> as follows:
853

854 855
.Annotate Java value class with @XmlType element-value pairs
[[a956]]
856 857
[width="100%",cols="50%,50%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
858 859 860 861 862
| @XmlType element | @XmlType value
| name | complex type definition's {name}
| namespace | {target namespace}
| propOrder a | When \{content type} is element-only
{content model} and top-level {compositor} is xs:sequence, ordered
863
list of JAXB property names representing order of xs:elements in
Lukas Jungmann's avatar
Lukas Jungmann committed
864
{content model}.
865
 +
Lukas Jungmann's avatar
Lukas Jungmann committed
866

867 868 869 870
All other cases do not need to set propOrder.

|===

Lukas Jungmann's avatar
Lukas Jungmann committed
871
*_Example:_* Complex Type: Derivation by Extension
872 873 874

XML Schema Fragment (from XSD PART 0 primer):

Lukas Jungmann's avatar
Lukas Jungmann committed
875 876 877 878 879 880 881 882
[source,xml,indent=4]
----
<xs:complexType name="Address">
  <xs:sequence>
    <xs:element name="name" type="xs:string"/>
    <xs:element name="street" type="xs:string"/>
    <xs:element name="city" type="xs:string"/>
  </xs:sequence>
883
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
884 885 886 887 888 889 890 891 892
<xs:complexType name="USAddress">
  <xs:complexContent>
    <xs:extension base="ipo:Address">
      <xs:sequence>
        <xs:element name="state" type="xs:string"/>
        <xs:element name="zip" type="xs:integer"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
893
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
894
----
895 896 897

Default Java binding:

Lukas Jungmann's avatar
Lukas Jungmann committed
898 899 900 901 902 903 904 905 906
[source,java,indent=4]
----
public class Address {
    String getName() {...}
    void setName(String) {...}
    String getStreet() {...}
    void setStreet(String) {...}
    void getCity() {...}
    void setCity(String) {...}
907 908 909 910
}

import java.math.BigInteger;

Lukas Jungmann's avatar
Lukas Jungmann committed
911 912 913 914 915 916 917 918 919 920
public class USAdress extends Address {
    String getState() {...}
    void setState(String) {...} {
    BigInteger getZip() {...}
    void setZip(BigInteger) {...}
}

class ObjectFactory {
    Address createAddress() {...}
    USAddress createUSAddress() {...}
921
}
Lukas Jungmann's avatar
Lukas Jungmann committed
922
----
923

Lukas Jungmann's avatar
Lukas Jungmann committed
924
===== Simple Content Binding
925 926 927 928 929 930

====== Binding to Property

By default, a complex type definition with
simple content is bound to a Java property defined by:

Lukas Jungmann's avatar
Lukas Jungmann committed
931 932
* *name*: The property name must be `value`.
* *base type, predicate, collection type*:
933
As specified in [XSD Part 1], when a complex type has simple content,
Lukas Jungmann's avatar
Lukas Jungmann committed
934
the content type (_{content type}_) is always a simple type schema
935
component. And a simple type component always maps to a Java datatype
936
(<<Simple Type Definition>>). Values of
937
the following three properties are copied from that Java type:
Lukas Jungmann's avatar
Lukas Jungmann committed
938 939 940
** base type
** predicate
** collection type
941 942 943

The schema-derived JAXB property representing
simple content is annotated, either explicitly or by default mapping
944
annotations, with the mapping annotation @XmlValue, specified in <<xmlvalue>>.
945

Lukas Jungmann's avatar
Lukas Jungmann committed
946
*_Example:_* Simple Content: Binding To Property
947 948

XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
949 950 951 952 953 954 955 956
[source,xml,indent=4]
----
<xs:complexType name="internationalPrice">
  <xs:simpleContent>
    <xs:extension base="xs:decimal">
      <xs:attribute name="currency" type="xs:string"/>
    </xs:extension>
  </xs:simpleContent>
957
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
958
----
959 960 961

Default Java binding:

Lukas Jungmann's avatar
Lukas Jungmann committed
962 963 964 965 966 967 968 969 970 971 972
[source,java,indent=4]
----
class InternationalPrice {
    /** Java property for simple content */
    @XmlValue
    java.math.BigDecimal getValue() {...}
    void setValue(java.math.BigDecimal value) {...}

    /** Java property for attribute */
    String getCurrency() {...}
    void setCurrency(String) {...}
973
}
Lukas Jungmann's avatar
Lukas Jungmann committed
974
----
975 976 977

==== xsd:anyType

Lukas Jungmann's avatar
Lukas Jungmann committed
978
`xsd:anyType` is the root of the type
979
definition hierarchy for a schema. All complex type definitions in a
Lukas Jungmann's avatar
Lukas Jungmann committed
980
schema implicitly derive from `xsd:anyType`. Given that the JAXB
981 982
architecture does not define a common base class for all JAXB class
bindings of complex type definitions, the only possible binding property
Lukas Jungmann's avatar
Lukas Jungmann committed
983
base type binding for `xsd:anyType` is to `java.lang.Object`. This
984
binding enables all possible type and element substitutions for an
Lukas Jungmann's avatar
Lukas Jungmann committed
985
element of type `xsd:anyType`.
986 987

.Binding of element with type _xsd:anyType_
Lukas Jungmann's avatar
Lukas Jungmann committed
988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004
[source,xml,indent=4]
----
<xs:element name="anyContent/> <!-- @type defaults to xs:anyType -->
<xs:complexType name="base">
  <xs:sequence>
    <xs:element ref="anyContent/>
    <xs:element name="anyContentAgain" type="xs:anyType"/>
  </xs:sequence>
</xs:complexType>
----
[source,java,indent=4]
----
public class Base {
    void setAnyContent(Object obj);
    Object getAnyContent();
    void setAnyContentAgain(Object obj);
    Object getAnyContentAgain();
1005
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1006
----
1007 1008

A schema author defines an element to be of
Lukas Jungmann's avatar
Lukas Jungmann committed
1009 1010
type `xs:anyType` to defer constraining an element to a particular type
to the xml document author. Through the use of `xsi:type` attribute or
1011
element substitution, an xml document author provides constraints for an
Lukas Jungmann's avatar
Lukas Jungmann committed
1012 1013
element defined as `xs:anyType`. The JAXB unmarshaller is able to
unmarshal a schema defined `xsd:anyType` element that has been
1014 1015
constrained within the xml document to an easy to access JAXB mapped
class. However, when the xml document does not constrain the
Lukas Jungmann's avatar
Lukas Jungmann committed
1016
`xs:anyType` element, JAXB unmarshals the unconstrained content to an
1017 1018 1019
element node instance of a supported DOM API.

Type substitution is covered in more detail
1020 1021 1022 1023
in <<Type Substitution of a Complex Type Definition>>
and <<Type Substitution of a Simple Type Definition>>.
Element substitution is covered in more detail in
<<Bind to a Simple Element property>>.
1024 1025 1026 1027 1028

=== Attribute Group Definition

There is no default mapping for an attribute
group definition. When an attribute group is referenced, each attribute
Lukas Jungmann's avatar
Lukas Jungmann committed
1029
in the attribute group definition becomes a part of the _[attribute uses]_
1030 1031
property of the referencing complex type definition. Each attribute is
mapped to a Java property as described in
1032
<<Attribute use>>. If the attribute group
1033
definition contains an attribute wildcard, denoted by the
Lukas Jungmann's avatar
Lukas Jungmann committed
1034
`xs:anyAttribute` element, then the referencing complex type definition
1035
will contain a property providing access to wildcard attributes as
1036
described in <<Attribute Wildcard>>.
1037

Lukas Jungmann's avatar
Lukas Jungmann committed
1038
=== Model Group Definition
1039 1040 1041 1042 1043

When a named model group definition is
referenced, the JAXB property set representing its content model is
aggregated into the Java value class representing the complex type
definition that referenced the named model group definition as
1044
illustrated in <<a999>>.
1045

1046 1047
.Binding for a reference to a model group definition.
[[a999]]
1048
image::images/xmlb-16.svg[image]
1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059

This binding style results in the same
properties occurring within both Java value classs A and C to represent
the referenced Model Group Bs content model.

When a model group definitions content model
contains an XML Schema component that is to be bound to a Java value
class, element class or enum type, it is desirable to only create a
single Java representation, not one for each complex content that
references the named model group definition. This default binding from a
model group definitions content model is defined in
1060
<<Deriving Class Names for Named Model Group Descendants>>.
1061

Lukas Jungmann's avatar
Lukas Jungmann committed
1062
To meet the Jakarta XML Binding goal of predictable
1063 1064
unmarshalling of invalid XML content, the JAXB 1.0 customization for
binding a model group to a JAXB mapped class is no longer supported.
1065
<<Flexible Unmarshalling>> details the rationale behind this change.
1066 1067 1068 1069

==== Bind to a set of properties

A non-repeating reference to a model group
Lukas Jungmann's avatar
Lukas Jungmann committed
1070
definition, when the particle referencing the group has _{max occurs}_
1071
equal to one, results in a set of content properties being generated to
1072 1073
represent the content model. <<content-model-particle-model-group-wildcard>>
describes how a content model
1074 1075 1076 1077 1078 1079
is bound to a set of properties and has examples of the binding.

==== Bind to a list property

A reference to a model group definition from
a particle with a repeating occurrence is bound by default as specified
1080
in <<Bind a repeating occurrence model group>>.
1081 1082 1083

*_Example:_* +
Schema fragment contains a particle that
Lukas Jungmann's avatar
Lukas Jungmann committed
1084
references the model group definition has a _{maxOccurs}_ value greater
1085 1086
than one.

Lukas Jungmann's avatar
Lukas Jungmann committed
1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
[source,xml,indent=4]
----
<xs:group name="AModelGroup">
  <xs:choice>
    <xs:element name="A" type="xs:int"/>
    <xs:element name="B" type="xs:float"/>
  </xs:choice>
</xs:group>

<xs:complexType name="foo">
  <xs:sequence>
    <xs:group ref="AModelGroup" maxOccurs="unbounded"/>
    <xs:element name="C" type="xs:float"/>
  </xs:sequence>
1101
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
1102
----
1103 1104 1105

Derived Java representation:

Lukas Jungmann's avatar
Lukas Jungmann committed
1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116
[source,java,indent=4]
----
public class Foo {
    /** A valid general content property of AModelGroup content model.*/
    @XmlElements({
        @XmlElement(type=Integer.class, name="A"),
        @XmlElement(type=Float.class, name="B")})
    java.util.List<Object> getAModelGroup() {...}

    float getC() {...}
    void setC(float value) {...}
1117
};
Lukas Jungmann's avatar
Lukas Jungmann committed
1118
----
1119

Lukas Jungmann's avatar
Lukas Jungmann committed
1120
==== Deriving Class Names for Named Model Group Descendants
1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137

When a model group definitions content model
contains XML Schema components that need to be bound to a Java class or
interface, this section describes how to derive the package and name for
the Java value class, enum type or element class derived from the
content model of the model group definition. The binding of XML Schema
components to Java classes/interfaces is only performed once when the
model group definition is processed, not each time the model group
definition is referenced as is done for the property set of the model
group definition.

XML Schema components occurring within a
model group definitions content model that are specified by this
chapter and the customization chapter to be bound to a Java value class,
interface or typesafe enum class are bound as specified with the
following naming exceptions:

Lukas Jungmann's avatar
Lukas Jungmann committed
1138
* *package*: The element class, Java value
1139 1140
class or typesafe enum class is bound in the Java package that
represents the target namespace containing the model group definition.
Lukas Jungmann's avatar
Lukas Jungmann committed
1141
* *name*: The name of the interface or
1142 1143 1144 1145
class is generated as previously specified with one additional step to
promote uniqueness between interfaces/classes promoted from a model
group definition to be bound to a top-level class within a Java package.
By default, a prefix for the interface/class name is computed from the
Lukas Jungmann's avatar
Lukas Jungmann committed
1146 1147 1148 1149
model group definitions _{name}_ using the XML name to Java identifier
algorithm. If the schema customization *[jaxb:globalBindings]*
_@localScoping_ has a value of _toplevel_, then a prefix is not
generated from the model group definitions _{name}_.
1150 1151 1152 1153

For example, given a model group definition
named _Foo_ containing an element declaration named _bar_ with an
anonymous complex type definition, the anonymous complex type definition
Lukas Jungmann's avatar
Lukas Jungmann committed
1154
is bound to a Java value class with the name _FooBar_. The following
1155 1156 1157
figure illustrates this example.

.Default binding for anonymous type def within a model group definition.
1158
image::images/xmlb-17.svg[image]
1159 1160 1161 1162 1163


Note that even customization specified Java
value class, interface or typesafe enum class names are prepended with
the model group definitions name. Thus, if a model group definition
Lukas Jungmann's avatar
Lukas Jungmann committed
1164 1165 1166
named `Foo` contains an anonymous simple type definition with a typesafe
enum class customization name of `Colors`, the enum type name is
`FooColors`.
1167 1168 1169 1170 1171

=== Attribute Declaration

An attribute declaration is bound to a Java
property when it is referenced or declared, as described in
1172
<<Attribute use>>, from a complex type definition.
1173

Lukas Jungmann's avatar
Lukas Jungmann committed
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212
==== Bind global attribute to a QName Constant

To assist the dynamic access to schema-defined global attributes
described in Section 6.9, Attribute Wildcard", a global attribute
declaration is bound to a JAXB QName constant, derived in terms of
the properties of the “Attribute Declaration Schema Component”
as follows:

* A _package name_, which is either computed from the attribute
declaration _{target namespace}_ or specified by binding
customization of the target namespace or a specified package
name for components that are scoped to no target namespace.
* The _name_ of the generated constant is derived from
the element declaration _{name}_ using the XML Name to Java
identifier mapping algorithm for a constant name or
specified by a binding customization of the attribute’s name.
* The QName constant is a JAXB constant property in class _ObjectFactory_.
* The QName constant value is initialized using the attribute declaration’s
_{target namespace}_ and _{name}_.

.Bind global attribute declaration to a JAXB QName constant
[source,xml,indent=4]
----
<xs:schema targetNamespace="http://e.org" xmlns:a="http://e.org">
  <xs:attribute name="isOpen" type="xs:boolean"/>
</xs:schema>
----
[source,java,indent=4]
----
package org.e;
public class ObjectFactory {
    /** <xs:attribute name="{http://e.org}isOpen" type="xs:boolean"/> */
    public static final javax.xml.namespace.QName IS_OPEN =
                new QName("http://e.org", "isOpen");
...
}
----

=== Element Declaration
1213 1214 1215 1216

This section describes the binding of an XML
element declaration to a Java representation. For a description of how
this binding has changed since the previous version, see
1217
<<Java Element Representation Summary>>.
1218 1219 1220 1221 1222 1223 1224
This section introduces why a JAXB technology user has to use instances
of JAXB element as opposed to instances of Java datatypes or Java value
class when manipulating XML content.

An XML element declaration is composed of the
following key components:

Lukas Jungmann's avatar
Lukas Jungmann committed
1225 1226 1227
* its qualified name is _{target namespace}_ and _{name}_
* its value is an instance of the Java class binding of its _{type definition}_
* whether the element’s content is _{nillable}_
1228 1229

Typically, an instance of
Lukas Jungmann's avatar
Lukas Jungmann committed
1230 1231
`jakarta.xml.bind.JAXBElement<T>`, returned by an element factory method,
represents an element declaration’s key components. An instance of a
1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244
Java value class or content interface represents only the value of an
element. Commonly in JAXB binding, the Java representation of XML
content enables one to manipulate just the value of an XML element, not
an actual element instance. The binding compiler statically associates
the XML element qualified name to a content property and this
information is used at unmarshal/marshal time. For cases where the
element name can be dynamically altered at runtime, the JAXB user needs
to manipulate elements, not element values. The following schema/derived
Java code example illustrates this point.

*_Example:_* +

Given the XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
1245 1246 1247 1248 1249 1250 1251 1252
[source,xml,indent=4]
----
<xs:complexType name="chair_kind">
  <xs:sequence>
    <xs:element name="has_arm_rest" type="xs:boolean"/>
  </xs:sequence>
</xs:complexType>
----
1253 1254

Schema-derived Java value class:
Lukas Jungmann's avatar
Lukas Jungmann committed
1255 1256 1257 1258 1259
[source,java,indent=4]
----
public class ChairKind {
    boolean isHasArmRest() {...}
    void setHasArmRest(boolean value) {...}
1260
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1261
----
1262

Lukas Jungmann's avatar
Lukas Jungmann committed
1263
A user of the Java value class `ChairKind`
1264
never has to create a Java instance that both has the value of local
Lukas Jungmann's avatar
Lukas Jungmann committed
1265 1266 1267 1268 1269
element `has_arm_rest` and knows that its XML element name is
`has_arm_rest`. The user only provides the value of the element to the
content-property `hasArmRest`. A JAXB implementation associates the
content-property `hasArmRest` with XML element name `has_arm_rest` when
marshalling an instance of `ChairKind`.
1270 1271 1272 1273

The next schema/derived Java code example
illustrates when XML element information can not be inferred by the
derived Java representation of the XML content. Note that this example
1274
relies on binding described in <<Bind wildcard schema component>>.
1275

Lukas Jungmann's avatar
Lukas Jungmann committed
1276
*_Example:_*
1277

Lukas Jungmann's avatar
Lukas Jungmann committed
1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292
[source,xml,indent=4]
----
<xs:complexType name="chair_kind">
  <xs:sequence>
    <xs:any/>
  </xs:sequence>
</xs:complexType>
----

[source,java,indent=4]
----
public class ChairKind {
    @XmlAnyElement(lax="true")
    java.lang.Object getAny() {...}
    void setAny(java.lang.Object elementOrValue) {...}
1293
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1294
----
1295 1296

For this example, the user can provide an
Lukas Jungmann's avatar
Lukas Jungmann committed
1297
Element instance to the `any` content-property that contains both the
1298
value of an XML element and the XML element name since the XML element
Lukas Jungmann's avatar
Lukas Jungmann committed
1299
name could not be statically associated with the content-property `any`
1300 1301
when the Java representation was derived from its XML Schema
representation. The XML element information is dynamically provided by
1302 1303
the application for this case. <<content-model-particle-model-group-wildcard>>
cover additional circumstances when one can use JAXB elements.
1304

Lukas Jungmann's avatar
Lukas Jungmann committed
1305
==== Bind to _JAXBElement<T>_ Instance
1306 1307

The characteristics of the generated
Lukas Jungmann's avatar
Lukas Jungmann committed
1308
ObjectFactory element factory method that returns an `JAXBElement<T>`
1309
instance are derived in terms of the properties of the
1310
<<Element Declaration Schema Component>> as follows:
1311 1312

* The element factory method is generated
Lukas Jungmann's avatar
Lukas Jungmann committed
1313 1314
into the `ObjectFactory` class in the Java package that represents the
binding of the element declaration’s _{target namespace}_.
1315
* The element factory method returns an
Lukas Jungmann's avatar
Lukas Jungmann committed
1316 1317
instance of `jakarta.xml.bind.JAXBElement<T>`, where `T` is the Java
value class representing the _{type definition}_ of the element
1318 1319 1320
declaration. The factory method sets the element name of the returned
instance to the element declaration’s fully qualified name.
* The element factory method has a single
Lukas Jungmann's avatar
Lukas Jungmann committed
1321 1322
parameter that is an instance of type `T`, where `T` is the Java value
class representing the _{type definition}_ of the element declaration.
1323 1324
* The name of the factory method is generated
by concatenating the following components:
Lukas Jungmann's avatar
Lukas Jungmann committed
1325 1326
** The string constant `create`.
** By default, if the element declaration is
1327 1328
nested within another XML Schema component, then the concatenation of
all outer Java class names representing those XML Schema components. If
Lukas Jungmann's avatar
Lukas Jungmann committed
1329
the schema customization *[jaxb:globalBindings]*  _@localScoping_ has a
1330
value of toplevel, skip this step.
Lukas Jungmann's avatar
Lukas Jungmann committed
1331 1332
** A name that is generated from the element
declaration's _{name}_ using the XML Name to Java identifier name
1333
mapping algorithm specified in <<The Name to Identifier Mapping Algorithm>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1334 1335
* The `JAXBElement<T>` property for nil
test whether an element’s content model is `xsi:nil="true"`.
1336 1337

For example, an element declaration named
Lukas Jungmann's avatar
Lukas Jungmann committed
1338 1339 1340
`Foo` with a type of `xs:int` that is nested within the content
model of complex type definition `Bar` would have the following factory
method generated in the containing Java package's `ObjectFactory` class:
1341

Lukas Jungmann's avatar
Lukas Jungmann committed
1342 1343 1344 1345
[source,java,indent=8]
----
JAXBElement<Integer> createBarFoo(Integer value) {...}
----
1346 1347 1348 1349 1350 1351

Default binding rules require an element
declaration to be bound to element factory method under the following
conditions:

* All non-abstract, named element
Lukas Jungmann's avatar
Lukas Jungmann committed
1352 1353
declarations with global _{scope}_ are bound to an element factory method
that returns an `JAXBElement<T>` instance. The rationale is that any
1354 1355 1356 1357
global element declaration can occur within a wildcard context and one
might want to provide element instances, not instances of the element’s
type, the element’s value, for this case.
* All local element declarations, having a
Lukas Jungmann's avatar
Lukas Jungmann committed
1358
_{scope}_ of a complex type definition, occurring within content that is
1359 1360
mapped to a general content property of JAXB elements must have an
element factory method generated. General content property is specified
1361
in <<General content property>>. An
1362 1363
example of when a content model is mapped to a general content property,
forcing the generation of element declarations is at
1364
<<Examples>>.
1365 1366 1367

The schema-derived element factory method is
annotated, either explicitly or by default mapping annotations, with the
Lukas Jungmann's avatar
Lukas Jungmann committed
1368 1369
mapping annotation `@XmlElementDecl`, specified in Section 8. The
`@XmlElementDecl` annotation elements are derived in terms of the
1370
abstract model properties for an element declaration summarized in
1371
<<Element Declaration Schema Component>> as follows:
1372 1373 1374 1375

.Annotate element instance factory with @XmlElementDecl element-value pairs.
[width="100%",cols="50%,50%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
1376 1377 1378 1379 1380 1381 1382 1383 1384
| @XmlElementDecl element |@XmlElementDecl value
| name | element declaration's _{name}_
| namespace | _{target namespace}_
| scope | If _{scope}_ is _global_, `JAXBElement.GlobalScope.class` else the JAXB
Java value class representing the __{scope}__ing complex type definition.
| substitutionHeadName | If optional _{substitution group affiliation}_ exists,
its local name.
| substitutionHeadNamespace | If optional _{substitution group affiliation}_ exists,
its namespace.
1385 1386
|===

Lukas Jungmann's avatar
Lukas Jungmann committed
1387
The element declaration’s _{type}_ can
1388
result in additional JAXB annotations being generated on the element
1389 1390 1391
instance factory. For more details, see <<Annotations for standard XML datatypes>>
and @XmlList in
<<list>>.
1392 1393 1394 1395 1396

The schema-derived ObjectFactory class
containing the @XmlElementDecl annotations is annotated with
@XmlRegistry annotation.

Lukas Jungmann's avatar
Lukas Jungmann committed
1397
==== Bind to Element Class
1398

1399
<<class-declaration>> customization enables the binding of an element declaration
1400 1401
with a named type definition to a schema-derived Element class. The
characteristics of the schema-derived Element class are derived in terms
1402
of the properties of the <<Element Declaration Schema Component>> as follows:
1403

Lukas Jungmann's avatar
Lukas Jungmann committed
1404 1405
* The _name_ of the generated Java Element
class is derived from the element declaration _{name}_ using the XML Name
1406 1407
to Java identifier mapping algorithm for class names.
* Each generated Element class must extend
Lukas Jungmann's avatar
Lukas Jungmann committed
1408
the Java value class `jakarta.xml.bind.JAXBElement <T>`. The next bullet
1409
specifies the schema-derived Java class name to use for generic
Lukas Jungmann's avatar
Lukas Jungmann committed
1410 1411 1412 1413 1414
parameter `T`.
* If the element declaration’s _{type definition}_ is
** Anonymous
+
Generic parameter `T` from the second bullet
1415 1416
is set to the schema-derived class represented the anonymous type
definition generated as specified in Section 6.7.3.
Lukas Jungmann's avatar
Lukas Jungmann committed
1417 1418 1419 1420 1421 1422 1423 1424 1425
** Named
+
Generic parameter `T` from the second bullet is
set to the Java class representing the element declaration’s
_{type definition}_.
* The `ObjectFactory` method to create an
instance of _name_ has a single parameter that is an instance of type `T`.
By default, the name of the ObjectFactory method is derived by
concatenating _outerClassNames_ and _name_. When schema customization,
1426 1427
*[jaxb:globalBindings]* _@localScoping,_ specified in <<Usage>>,
has a value of _toplevel_,
1428
then the outer Classnames are ommitted from the factory method name.
Lukas Jungmann's avatar
Lukas Jungmann committed
1429 1430 1431 1432 1433
* If _{scope}_ is
** *Global*: The derived Element class is
generated into the Java package that represents the binding of
_{target namespace}_.
** *A Complex Type Definition*: By default,
1434
the derived Element class is generated within the Java value class
Lukas Jungmann's avatar
Lukas Jungmann committed
1435
represented by the complex type definition value of _{scope}_. When
1436 1437
_@localScoping_ is _toplevel_ , the derived element class is generated
as a toplevel class.
Lukas Jungmann's avatar
Lukas Jungmann committed
1438 1439 1440
* The property for nil test whether element’s content model is `xsi:nil="true"`.
* Optional _{value constraint}_ property with
pair of `default` or `fixed` and a value. +
1441 1442 1443 1444 1445
If a default or fixed value is specified, the data binding system must
substitute the default or fixed value if an empty tag for the element
declaration occurs in the XML content.

A global binding customization,
1446 1447
*@generateElementClass*, specified in <<globalbindings-declaration>>
enables this binding over the default
1448 1449
binding specified in the previous subsection.

Lukas Jungmann's avatar
Lukas Jungmann committed
1450
==== Binding of an anonymous complex type definition
1451 1452 1453 1454 1455 1456

An anonymous complex type definition is bound
to a generated schema-derived Java value class by default.

The naming characteristics of the generated
Java value class is derived in terms of the properties of the
1457
<<Element Declaration Schema Component>> as follows:
1458

Lukas Jungmann's avatar
Lukas Jungmann committed
1459 1460 1461
* The _name_ of the generated Java value class
is derived from the element declaration _{name}_ using the XML Name to
Java identifier.
1462 1463
* The _package_ of the generated Java value
class is the same as the package derived from the element declaration’s
Lukas Jungmann's avatar
Lukas Jungmann committed
1464
_{target namespace}_.
1465
* The _outer class names_ of the generated
Lukas Jungmann's avatar
Lukas Jungmann committed
1466 1467 1468
Java value class is determined by the element declaration’s _{scope}_.
If _{scope}_ is:
** Global +
1469
There is no outer class name.
Lukas Jungmann's avatar
Lukas Jungmann committed
1470
** A Complex Type Definition +
1471 1472
By default, the derived Java value class is generated nested within the
Java value class represented by the complex type definition value of
Lukas Jungmann's avatar
Lukas Jungmann committed
1473 1474 1475 1476
_{scope}_. The derived Java value is not generated nested when schema
customization *[globalBindings]* has attribute _@localScoping_ with a
value of _toplevel_.
* _base class_: Same as defined in
1477
<<Java value class>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1478
*  _property set_: As defined in
1479
<<Java value class>>.
1480
* A type factory method is generated in the
Lukas Jungmann's avatar
Lukas Jungmann committed
1481
package’s `ObjectFactory` class introduced in
1482
<<Java Package>>. The factory method
1483 1484
returns the type of the Java value class. The name of the factory method
is generated by concatenating the following components:
Lukas Jungmann's avatar
Lukas Jungmann committed
1485 1486
** The string constant `create`.
** If the element declaration containing the
1487 1488 1489
anonymous complex type definition is nested within another complex type
definition representing a value class and [globalBindings] @localScoping
has a value of _nested_ , then the concatenation of all outer Java class
Lukas Jungmann's avatar
Lukas Jungmann committed
1490 1491
names. This step is skipped when @localScoping has a value of _toplevel_.
** The _name_ of the Java value class.
1492 1493

The schema-derived value class is annotated
1494 1495 1496
with the mapping annotation `@XmlType`, specified in
<<xmltype-2>>. The `@XmlType` annotation
elements are set as described in <<a956>> with one
Lukas Jungmann's avatar
Lukas Jungmann committed
1497
exception: `@XmlType.name()` is set to the empty string.
1498 1499

As long as the element declaration is not one
1500 1501
of the exception cases specified in
<<Bind Element Declaration to JAXBElement>>, the schema-derived value
Lukas Jungmann's avatar
Lukas Jungmann committed
1502 1503
class is annotated with the mapping annotation `@XmlRootElement`
specified in Section 8. The `@XmlRootElement` annotation elements are
1504 1505
derived in terms of the abstract model properties for the referenced
global element declaration summarized in
1506
<<Element Declaration Schema Component>> as follows:
1507 1508

.Annotate JAXB Mapped Class with @XmlRootElement element-value pairs
1509

1510 1511
[width="100%",cols="50%,50%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
1512 1513
| @XmlRootElement element | @XmlRootElement value
|namespace a| When element declaration _{target namespace}_ is absent, +
1514 1515 1516 1517
(i.e. unqualified local element declaration), @XmlElement.namespace() is
not set. +

Otherwise, set @XmlElement.namespace() to
Lukas Jungmann's avatar
Lukas Jungmann committed
1518
value of _{target namespace}_. (either a qualified local element
1519 1520 1521 1522 1523
declaration or a reference to a global element)

Note: same result could be achieved with
package level annotation of @XmlSchema and not setting
@XmlElement.namespace.
Lukas Jungmann's avatar
Lukas Jungmann committed
1524
| name | element declaration _{name}_
1525 1526
|===

Lukas Jungmann's avatar
Lukas Jungmann committed
1527
*_Example:_*
1528 1529

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
1530 1531 1532 1533 1534 1535 1536 1537
[source,xml,indent=4]
----
<xs:element name="foo">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="bar" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>
1538
</xs:element>
Lukas Jungmann's avatar
Lukas Jungmann committed
1539
----
1540 1541

Derived Java code:
Lukas Jungmann's avatar
Lukas Jungmann committed
1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558
[source,java,indent=4]
----
/* Value class representing element
declaration with an anonymous complex type definition. */
@XmlType(name="")
@XmlRootElement(namespace="", name="foo")
public class Foo {
    int getBar() {...}
    void setBar(int value) {...}
};
class ObjectFactory {
    // type factory method
    Foo              createFoo() {...}
    // element factory method
    JAXBElement<Foo> createFoo(Foo value) {...}
}
----
1559

Lukas Jungmann's avatar
Lukas Jungmann committed
1560
===== Bind Element Declaration to JAXBElement
1561 1562

An element declaration with an anonymous
Lukas Jungmann's avatar
Lukas Jungmann committed
1563
complex type definition is not bound to a `@XmlRootElement`,annotated
1564 1565 1566 1567 1568 1569 1570 1571 1572 1573
schema-derived class when the element declaration is:

* nillable
* the head element or a member of a
substitution group
* non-global (i.e. declared within a complex
type definition)

When one or more of the above conditions are
met, the schema-derived class representing the anonymous complex type
Lukas Jungmann's avatar
Lukas Jungmann committed
1574 1575
definition must not be annotated with `@XmlRootElement`. Instead, an
element factory that returns `JAXBElement<__anonymousTypeValueClass__>`
1576
may be generated as specified in <<bind-to-jaxbelementt-instance>>.
1577

Lukas Jungmann's avatar
Lukas Jungmann committed
1578
*_Example:_*
1579 1580

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
1581 1582 1583 1584 1585 1586 1587 1588 1589 1590
[source,xml,indent=4]
----
<xs:element name="foo" nillable="true">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="bar" type="xs:int"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>
----
1591 1592

Derived Java code:
Lukas Jungmann's avatar
Lukas Jungmann committed
1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607
[source,java,indent=4]
----
/* Value class representing anonymous complex type definition. */
@XmlType(name="")
public class Foo {
    int getBar() {...}
    void setBar(int value) {...}
};
@XmlRegistry
class ObjectFactory {
    // type factory method
    Foo              createFoo() {...}
    // element factory method
    @XmlElementDecl(name="foo", namespace="", nillable="true")
    JAXBElement<Foo> createFoo(Foo value) {...}
1608
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1609
----
1610 1611 1612 1613 1614

==== Bind to a Property

A local element declaration is bound by
default to a Java property as described in
1615
<<Properties>>. The characteristics of the
1616
Java property are derived in terms of the properties of the
1617 1618
<<Element Declaration Schema Component>>
and <<Particle Schema Component>> as follows:
1619

Lukas Jungmann's avatar
Lukas Jungmann committed
1620 1621
* The _name_ of the Java property is derived
from the _{element declaration}_ property’s _{name}_ property using the
1622
XML Name to Java Identifier mapping algorithm described in
1623
<<The Name to Identifier Mapping Algorithm>>.
1624
* A _base type_ for the Java property is
Lukas Jungmann's avatar
Lukas Jungmann committed
1625 1626
derived from the `{element declaration}` property’s `{type
definition}` property as described in binding of Simple Type Definition
1627 1628
in <<Simple Type Definition>>. or
<<Complex Type Definition>>. If the base
Lukas Jungmann's avatar
Lukas Jungmann committed
1629 1630
type is initially a primitive type and this JAXB property is _optional_,
the *[jaxb:globalBinding]* customization `@optionalProperty` controls
1631
the binding of an optional primitive property as described in
1632
<<Usage>>.
1633
* An optional _predicate_ for the Java
Lukas Jungmann's avatar
Lukas Jungmann committed
1634 1635
property is constructed from the `{element declaration}` property’s
`{type definition}` property as described in the binding of simple type
1636
definition to a Java representation.
Lukas Jungmann's avatar
Lukas Jungmann committed
1637 1638 1639
* An optional _collection type_ for the Java property is derived from:
** `{element declaration}` property’s
`{type definition}` property as described in the binding of simple type
1640
definition to a Java representation
Lukas Jungmann's avatar
Lukas Jungmann committed
1641
**  the `{particle}` property’s `{max occurs}`
1642 1643 1644 1645 1646 1647
value being greater than one.
* Element defaulting +
The default value is derived from the element declaration’s \{value
constraint} property’s value. Unlike attribute defaulting, an element
only defaults when there is an empty element tag in an xml document. The
element’s default value is captured by mapping annotation
Lukas Jungmann's avatar
Lukas Jungmann committed
1648
`@XmlElement.defaultValue()`. The unmarshaller sets the property to
1649 1650
this default value when it encounters an empty element tag. The
marshaller can output an empty element tag whenever the element’s
Lukas Jungmann's avatar
Lukas Jungmann committed
1651
`@XmlValue` property value is the same as its defaulted value..
1652 1653 1654
* A local element declaration that binds to a
JAXB property with a primitive base type is bound as an _optional_ JAXB
property if the element declaration is a member of a choice model group
Lukas Jungmann's avatar
Lukas Jungmann committed
1655 1656
or the element declaration’s particle has optional occurrence, `{min
occurs}` value is `"0"`, or belongs to a model group that has optional
1657 1658 1659
occurrence. By default, the optional JAXB property binds the property’s
base type to the Java wrapper class for the primitive type. One can test
and set the absence of an optional property using null. The
Lukas Jungmann's avatar
Lukas Jungmann committed
1660
*[jaxb:globalBinding]* customization `@optionalProperty` controls
1661
alternative bindings of an optional primitive property as described in
1662
<<Usage>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1663 1664
* If the element declaration’s _{nillable}_
property is `"true"` , the base type for the Java property is mapped to
1665
the corresponding Java wrapper class for the Java primitive type.
Lukas Jungmann's avatar
Lukas Jungmann committed
1666 1667
Setting the property to the `null` value indicates that the property has
been set to the XML Schema concept of `@xs:nil="true"`.
1668 1669 1670 1671 1672 1673 1674

This Java property is a member of the Java
value class that represents the binding of the complex type definition
containing the local element declaration or reference to global element.

The schema-derived JAXB property getter
method is annotated, either explicitly or by default mapping
Lukas Jungmann's avatar
Lukas Jungmann committed
1675
annotations, with the mapping annotation `@XmlElement`, specified in
1676
<<xmlelement>>. The `@XmlElement` annotation elements are
1677 1678
derived in terms of the abstract model properties for the referenced
global element declaration summarized in
1679
<<Element Declaration Schema Component>> as follows:
1680 1681 1682 1683

.Annotate JAXB Property with @XmlElement element-value pairs
[width="100%",cols="50%,50%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
1684 1685
| @XmlElement element | @XmlElement value
|namespace a| When element declaration _{target namespace}_ is absent, +
1686 1687 1688 1689
(i.e. unqualified local element declaration), @XmlElement.namespace() is
not set. +

Otherwise, set @XmlElement.namespace() to
Lukas Jungmann's avatar
Lukas Jungmann committed
1690
value of _{target namespace}_. (either a qualified local element
1691 1692 1693 1694 1695
declaration or a reference to a global element)

Note: same result could be achieved with
package level annotation of @XmlSchema and not setting
@XmlElement.namespace.
Lukas Jungmann's avatar
Lukas Jungmann committed
1696 1697 1698 1699
| name | element declaration _{name}_
| nillable | element declaration _{nillable}_
| defaultValue |if element declaration _{value constraint}_ is not absent,
set defaultValue() to _{value constraint}_ ’s value.
1700 1701
|===

1702
<<a1240>> illustrates how to
1703 1704
define an element substitution group and to reference the head element
of the substitution group within an Xml Schema.
1705 1706 1707
<<a1242>> illustrates the Java bindings of the element substation
enabled schema. <<a1244>> demonstrates element
substitution using the JAXB API. <<a1246>>
1708 1709
illustrates invalid element substitution handling.

Lukas Jungmann's avatar
Lukas Jungmann committed
1710
===== Type Substitution of a Complex Type Definition
1711

1712
<<Complex Type Definition>> describes that when a complex type definition is mapped to
1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724
Java value class that the type definition derivation hierarchy is
preserved in the Java class hierarchy. This preservation makes it quite
natural for Java to support the Xml Schema mechanism type substitution
across all complex type definitions.

Performing an invalid type substitution is
not detected as a fail-fast check when setting the JAXB property or
checked as part of marshalling the element declaration. Invalid type
substitution can be checked by optional validation that can be enabled
as part of unmarshalling or marshalling process.

The following three code examples illustrate
Lukas Jungmann's avatar
Lukas Jungmann committed
1725
how type substitution is supported in JAXB for a complex type
1726 1727
definition hierarchy.

1728 1729
.Xml Schema example containing type derivation hierarchy
[[a1152]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750
[source,xml,indent=4,subs=+quotes]
----
<xs:schema targetNamespace="travel:acme" xmlns:a="travel:acme">

  <!-- Define type definition derivation hierarchy -->
  <xs:complexType name="**TransportType**">...</xs:complexType>
  <xs:complexType name="**PlaneType**">
    <xs:extension base="a:TransportType">...</xs:complexType>
  <xs:complexType name="**AutoType**">
    <xs:extension base="a:TransportType">...</xs:complexType>
  <xs:complexType name="**SUV**">
    <xs:extension base="a:AutoType">...</xs:complexType>

  <xs:complexType name="**itinerary**">
    <xs:sequence>
      <!-- Type substitution possible for "transport". -->
      <xs:element name="**transport**" type="**TransportType**"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>
----
1751

1752 1753
.Java binding of Xml Schema from <<a1240>>
[[a1154]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770
[source,java,indent=4,subs=+quotes]
----
package travel.acme;

// Type derivation hierarchy from schema is preserved in Java binding.
public class *TransportType* {...}
public class *PlaneType* extends TransportType {...}
public class *AutoType* extends TransportType {...}
public class *SUV* extends AutoType {...}

public class ObjectFactory {
    // Type Factories
    TransportType createTransportType() {...}
    AutoType createAutoType() {...}
    PlaneType createPlaneType() {...}
    TrainType createSUV() {...}
}
1771

Lukas Jungmann's avatar
Lukas Jungmann committed
1772 1773 1774 1775
public class Itinerary {
    // Simple property supports type substitution.
    *TransportType* getTransport() {...}
    void setTransport(**TransportType** value)
1776
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1777
----
1778

1779
.Type substitution using Java bindings from <<a1242>>
Lukas Jungmann's avatar
Lukas Jungmann committed
1780 1781 1782 1783 1784
[source,java,indent=8,subs=+quotes]
----
ObjectFactory of = ...;
Itinerary itinerary = of.createItinerary();
itinerary.setTransport(of.createTransportType); // Typical Use
1785

Lukas Jungmann's avatar
Lukas Jungmann committed
1786 1787 1788 1789 1790
*// Type Substitution*
// transport marshalled as <e:transport xsi:type="e:AutoType">
itinerary.setTransport(of.createAutoType());

// transport marshalled as <e:transport xsi:type="e:PlaneType">
1791
itinerary.setTransport(of.createPlaneType());
Lukas Jungmann's avatar
Lukas Jungmann committed
1792
----
1793

Lukas Jungmann's avatar
Lukas Jungmann committed
1794
===== Type Substitution of a Simple Type Definition
1795 1796 1797 1798 1799 1800 1801 1802

An XML element declaration having a simple
type definition is bound most naturally to a JAXB property with a base
type that is a primitive Java datatype. Unfortunately, this strongly
typed binding conflicts with fully supporting type substitution of a
simple type definition. Unlike the JAXB binding of complex type
definitions, the simple type derivation hierarchy is not preserved when
binding builtin XML Schema simple type definitions to corresponding Java
1803 1804
datatypes as specified in <<Atomic Datatype>>.
Since there is not a natural Java inheritance hierarchy to
1805 1806 1807 1808
support simple type substitution, a JAXB property customization is
required to enable optimal support of simple type substitution.

For example, the most natural binding of an
Lukas Jungmann's avatar
Lukas Jungmann committed
1809 1810 1811 1812 1813 1814 1815
XML Schema built-in datatype `xs:int` is to the Java primitive datatype,
`int`. However, simple type substitution implies that an `xs:short` or
a complex type definition that derives by extension from `xs:int` can be
type substituted for an `xs:int` within an XML document using the
`xsi:type` attribute. The strongly typed JAXB property with Java type
`int` would never allow for a Java value class for the complex type to
be assigned to a JAXB property of type `int`.
1816 1817 1818 1819 1820 1821 1822

By default, unmarshalling handles simple type
substitution by assigning the relevant part of the type substituted
content to the JAXB property. When the value of the xsi:type attribute
resolves to:

* a type that derives by restriction from the
Lukas Jungmann's avatar
Lukas Jungmann committed
1823
element’s schema type.
1824 1825 1826
The substituted value is always parsable into a legal value of the base
type of the JAXB property being type substituted.
* a complex type that derives by extension
Lukas Jungmann's avatar
Lukas Jungmann committed
1827 1828 1829
from element’s schema type. The JAXB binding
of the substituted complex type definition must have
one JAXB property annotated with an `@XmlValue` that is assignable to
1830 1831 1832 1833 1834 1835 1836
the type substituted JAXB property’s base type. Attribute(s) associated
with the complex type definition can not be preserved by the default
binding.

The rationale behind the default binding is
that substitution of a simple type definition occurs rarely. The default
JAXB binding is more convenient and precise for programmer to use. Its
Lukas Jungmann's avatar
Lukas Jungmann committed
1837
one drawback is that it does not faithfully preserve `xsi:type`
1838 1839 1840 1841 1842
occurring in an XML document.

To enable more comprehensive support of
simple type substituting of an XML element with a simple type
definition, the JAXB property customization specified in
1843 1844
<<generalizespecialize-basetype-with-attribute-name>> enables
setting the property’s base type to the more
Lukas Jungmann's avatar
Lukas Jungmann committed
1845 1846
general type of `java.lang.Object`. This binding allows for retention of
the XML document `xsi:type` and attributes associated with complex type
1847
definition substituted for an XML element with a simple type definition.
Lukas Jungmann's avatar
Lukas Jungmann committed
1848 1849
When an `xsi:type` value refers to a type definition not registered with
`JAXBContext` instance, the content is unmarshalled as the element’s
1850 1851 1852 1853
schema type.

To preserve an application-defined simple
type definition involved in simple type substitution, it must be mapped
1854 1855
to a JAXB mapped class as described in <<Bind to a JAXB mapped class>>.
This can be achieved for all simple type
Lukas Jungmann's avatar
Lukas Jungmann committed
1856 1857
definitions in a schema using the customization `<jaxb:globalBinding
mapSimpleTypeDefs="true"/>` or it can be achieved per simple type
1858
definition using <jaxb:class> customization. An invalid simple type
Lukas Jungmann's avatar
Lukas Jungmann committed
1859
substitution can be detected by JAXP validation enabled at unmarshal
1860 1861 1862 1863 1864 1865
or marshal time

Below are examples of the type substitution
of an XML element’s simple type definition for the default and
customized binding.

1866 1867
.Schema fragment to illustrate simple type substitution
[[a1168]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887
[source,xml,indent=4,subs=+quotes]
----
<xsd:element name="Price">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      _<!-- element price subject to type substitution -->_
      <xsd:element name="price" type="xsd:int"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>
<xsd:complexType name="AmountType">
  <xsd:simpleContent> _<!-- type substitutable for xs:int -->_
    <xsd:extension base="xsd:int">
      <xsd:attribute name="currency" type="xsd:string"/>
    </xsd:extension>
  </xsd:simpleContent>
</xsd:complexType>
<xsd:simpleType name="AppInt">
  <xsd:restriction base="xsd:int"/>
1888
</xsd:simpleType>
Lukas Jungmann's avatar
Lukas Jungmann committed
1889
----
1890

1891 1892
.XML documents with simple type substitution
[[a1170]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1893 1894 1895 1896 1897
[source,xml,indent=4,subs=+quotes]
----
<product>
  <name>hotdog</name>
  <price>3</price>
1898 1899
</product>

Lukas Jungmann's avatar
Lukas Jungmann committed
1900 1901 1902
<product>
  <name>peanuts</name>
  <price **xsi:type="short"**>4</price>
1903 1904
</product>

Lukas Jungmann's avatar
Lukas Jungmann committed
1905 1906 1907
<product>
  <name>popcorn</name>
  <price **xsi:type="AppInt"**>5</price>
1908 1909
</product>

Lukas Jungmann's avatar
Lukas Jungmann committed
1910 1911 1912
<product>
  <name>sushi</name>
  <price **xsi:type="AmountType"** currency="yen">500</price>
1913
</product>
Lukas Jungmann's avatar
Lukas Jungmann committed
1914
----
1915 1916 1917

====== Default Handling of Simple Type Substitution

1918 1919
.Default JAXB binding of <<a1168>>
[[a1176]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1920 1921 1922 1923 1924 1925 1926
[source,java,indent=4]
----
public class AmountType {
    @XmlValue
    int getValue() {...} void setValue(int value) {...}
    String getCurrency() {...} void setCurrency(String value) {...}
}
1927

Lukas Jungmann's avatar
Lukas Jungmann committed
1928 1929 1930 1931
@XmlRootElement(namespace="", name="product")
public class Product {
    int getPrice() {...} void setPrice(int value) {...}
    int getName() {...} void setName(String value) {...}
1932
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1933
----
1934 1935

Unmarshalling XML document fragments from
1936
<<a1170>> into <<a1176>> JAXB binding of element `product` results in the
Lukas Jungmann's avatar
Lukas Jungmann committed
1937
`xsi:type` and attributes associated with JAXB mapped class `Price`
1938
being lost as part of the unmarshal process. This loss is illustrated by
1939
comparing <<a1179>> with <<a1204>>.
1940

1941 1942
.Product instances from unmarshalling XML docs from <<a1170>>
[[a1179]]
1943 1944
[width="100%",cols="20%,20%,20%,20%,20%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
1945 1946 1947 1948 1949 1950 1951 1952
| document xsi:type | Product.name +
value | Product.price +
value | Product.price +
type | marshal Product.price xsi:type
| | hotdog | 3 | int |
| xs:short | peanuts | 4 | int |
| AppInt | popcorn | 5 | int |
| AmountType | sushi | 500 | int |
1953 1954 1955 1956
|===

====== Simple Type Substitution enabled by JAXB customizations.

Lukas Jungmann's avatar
Lukas Jungmann committed
1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969
The simple type definition `AppInt` is mapped
to a JAXB class either by `<jaxb:class>` customization or by
`<jaxb:globalBindings mapSimpleTypeDef="true"/>`. The JAXB property
`Product.Price` is mapped to a JAXB property with a general base type of
`java.lang.Object` with following external JAXB schema customization:

[source,xml,indent=4]
----
<jaxb:bindings schemaLocation="CODE EXAMPLE"
        node="//xsd:element[@name=price]">
  <jaxb:property>
    <jaxb:baseType name="java.lang.Object" />
  </jaxb:property>
1970
</jaxb:bindings>
Lukas Jungmann's avatar
Lukas Jungmann committed
1971
----
1972

1973
specified in <<generalizespecialize-basetype-with-attribute-name>>.
1974

1975 1976
.Customized JAXB binding of <<a1168>>
[[a1201]]
Lukas Jungmann's avatar
Lukas Jungmann committed
1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988
[source,java,indent=4]
----
public class AmountType {
    @XmlValue
    int getValue() {...} void setValue(int value) {...}
    String getCurrency() {...} void setCurrency(String value) {...}
}

public class AppInt {
    @XmlValue
    int getValue() {...} void setValue(int value) {...}
}
1989

Lukas Jungmann's avatar
Lukas Jungmann committed
1990 1991 1992 1993 1994
public class Product {
    // enable simple type substitution with base type of Object
    @XmlElement(type=java.lang.Integer.class)
    Object getPrice() {...} void setPrice(Object value) {...}
    int getName() {...} void setName(String value) {...}
1995
}
Lukas Jungmann's avatar
Lukas Jungmann committed
1996
----
1997 1998

Unmarshalling XML document fragments from
1999 2000 2001
<<a1170>>
into <<a1201>>
JAXB binding of element `product` preserves
Lukas Jungmann's avatar
Lukas Jungmann committed
2002
the `xsi:type` and attributes associated with JAXB mapped class
2003
`AmountType` is illustrated in <<a1204>>.
2004

2005 2006
.Product instances from unmarshalling XML docs from <<a1170>>
[[a1204]]
2007 2008
[width="100%",cols="20%,20%,20%,20%,20%",options="header",]
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
2009 2010
| document xsi:type | Product.name +
value | Product. +
2011
price +
Lukas Jungmann's avatar
Lukas Jungmann committed
2012
value | Product. +
2013
price +
Lukas Jungmann's avatar
Lukas Jungmann committed
2014
Java type | Marshal +
2015 2016
Product. +
price +
Lukas Jungmann's avatar
Lukas Jungmann committed
2017 2018 2019 2020 2021 2022
xsi:type
| | hotdog | 3 | Integer |
| xs:short | peanuts | 4 | Short | xs:short
| AppInt | popcorn | 5 | AppInt | AppInt
| AmountType | sushi | {value=500, +
currency=”yen”} | AmountType | AmountType
2023 2024
|===

Lukas Jungmann's avatar
Lukas Jungmann committed
2025
==== Bind to a Simple Element property
2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037

Element substitution group is an Xml Schema
mechanism that enables the substitution of one named element for
another. This section uses terms and concepts described in Section 4.6
of [XSD Part 0] and normatively defined in Section 2.2.2.2 of [XSD Part
1].

The following constraints assist in defining
the Java binding that enables element substitution group:

. Element substitution is only possible for a
reference to a global element.
Lukas Jungmann's avatar
Lukas Jungmann committed
2038
.. Assuming the absence of the Xml Schema
2039 2040 2041 2042 2043
constraints on substitution, any global element can be made the head
element of a substitution group.
. All elements in a substitution group must
derive from or have the same type definition as the head element.

Lukas Jungmann's avatar
Lukas Jungmann committed
2044
To support element substitution, for
2045 2046
each global element reference to a head element of a substitution group
or to an abstract element, it is necessary to generate the Element
2047
property bindings defined in <<Element Property>>.footnote:[Element substitution
Lukas Jungmann's avatar
Lukas Jungmann committed
2048 2049 2050 2051
extensibility does allow element substitution(s) to be defined in a
separate schema than a global element reference occurs. When schemas are
not compiled at same time, the schema to java binding declaration,
<jaxb:property generateElementProperty=”true”/> described in
2052
<<usage-4>> forces the generation of an
Lukas Jungmann's avatar
Lukas Jungmann committed
2053 2054
element property for a global element reference, independent of it not
belonging to a element substitution group.] This property enables the overriding
2055 2056
of the schema-specified element name bound to a JAXB property by setting
and getting the JAXB element representation,
Lukas Jungmann's avatar
Lukas Jungmann committed
2057 2058
`jakarta.xml.bind.JAXBElement<T>`. The name property of the `JAXBElement<T>`
instance overrides the schema specified element declaration name.
2059 2060 2061 2062
To enable the passing of any element that could be part of the element
substitution group, it is necessary to accept any JAXBElement derivation
that extends Java binding of the head element’s type definition. Using
the upper bounded wildcard notation for a generic JAXBElement container,
Lukas Jungmann's avatar
Lukas Jungmann committed
2063
`JAXBElement<? extends T>`, the element property is able to get and set
2064 2065 2066 2067 2068 2069
any element that has an element value that is a subtype of T. Compile
time checking will not allow invalid JAXBElement derivations to be
passed to the Element property setter. When the element type is correct
but the element name is not part of the substitution group, this invalid
scenario can only be caught at runtime by validation or optional
fail-fast checking by the element property
Lukas Jungmann's avatar
Lukas Jungmann committed
2070 2071 2072 2073
setter.footnote:[The desire to reduce
the overall number of schema-derived classes generated by default
influenced the decision to default to binding an element declaration to
an element instance factory. A customization described in
2074
<<globalbindings-declaration>> exists
Lukas Jungmann's avatar
Lukas Jungmann committed
2075 2076 2077
that binds each element declaration to a Java element class so element
substitution checking can be enforced entirely by strongly typed method
signatures.]
2078 2079 2080

The schema-derived Element property getter
method is annotated, either explicitly or by default mapping
Lukas Jungmann's avatar
Lukas Jungmann committed
2081 2082
annotations, with the mapping annotation `@XmlElementRef`, specified in
Section 8.10.3, “@XmlElementRef”. The `@XmlElementRef` annotation
2083 2084
elements are derived in terms of the abstract model properties for the
referenced global element declaration summarized in
2085
<<Element Declaration Schema Component>> as follows:
2086 2087

.Annotate Element Property with @XmlElementRef element-value pairs
Lukas Jungmann's avatar
Lukas Jungmann committed
2088
[cols="1,1",options="header",]
2089
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
2090 2091 2092 2093
| @XmlElementRef element | @XmlElementRef value
| value | jakarta.xml.bind.JAXBElement.class
| namespace | referenced element declaration _{target namespace}_
| name | referenced element declaration _{name}_
2094 2095
|===

2096
<<a1240>> illustrates how to
2097 2098
define an element substitution group and to reference the head element
of the substitution group within an Xml Schema.
2099 2100 2101 2102
<<a1242>> illustrates the Java bindings of the element substation
enabled schema. <<a1244>>
demonstrates element substitution using the JAXB API.
<<a1246>> illustrates invalid element substitution handling.
2103

2104 2105
.Xml Schema example containing an element substitution group
[[a1240]]
Lukas Jungmann's avatar
Lukas Jungmann committed
2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125
[source,xml,indent=4]
----
<xs:schema targetNamespace="travel:acme" xmlns:a="travel:acme">

  <!-- See type definition derivation hierarchy defined in CODE EXAMPLE for
complexType definitions TransportType, PlaneType, AutoType and SUV.-->
  <!-- Define element substitution group. a:transport is head element. -->
  <xs:element name="transport" type="a:TransportType"/>
  <xs:element name="plane" type="a:PlaneType" substitutionGroup="a:transport" />
  <xs:element name="auto" type="a:AutoType" substitutionGroup="a:transport" />

  <xs:complexType name="itinerary">
    <xs:sequence>
      <!-- Global element reference.
           References head element of element substitution group. -->
      <xs:element ref="a:transport"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>
----
2126

2127 2128
.Avoid binding of Xml Schema from <<a1240>>
[[a1242]]
Lukas Jungmann's avatar
Lukas Jungmann committed
2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142
[source,java,indent=4]
----
package travel.acme;
public class ObjectFactory {
    // Type Factories
    TransportType createTransportType();
    AutoType createAutoType();
    PlaneType createPlaneType();
    TrainType createSUVType();

    // Element Instance Factories
    JAXBElement<AutoType> createAuto(AutoType value);
    JAXBElement<PlaneType> createPlane(PlaneType value);
    JAXBElement<TransportType> createTrain(TransportType value);
2143 2144
}

Lukas Jungmann's avatar
Lukas Jungmann committed
2145 2146 2147 2148 2149 2150 2151 2152 2153
// See Java binding of type derivation hierarchy in CODE EXAMPLE 6-5

public class Itinerary {
    // Element substitution supported by See [Element Property]
    JAXBElement<? extends TransportType> getTransport();
    void setTransport(JAXBElement<? extends TransportType> value);
}
----

2154 2155
.Element substitution using Java bindings from <<a1242>>
[[a1244]]
Lukas Jungmann's avatar
Lukas Jungmann committed
2156 2157 2158 2159 2160
[source,java,indent=8,subs=+quotes]
----
ObjectFactory of = ...;
Itinerary itinerary = of.createItinerary();
itinerary.setTransport(of.createTransportType()); // Typical use.
2161

Lukas Jungmann's avatar
Lukas Jungmann committed
2162 2163 2164
**// Element substitution:**
__// Substitute <e:auto> for schema specified <e:transport>.__
itinerary.setTransport(of.createAuto(of.createAutoType()));
2165

Lukas Jungmann's avatar
Lukas Jungmann committed
2166 2167
__// Substitute <e:plane> for schema specified <e:transport>__
itinerary.setTransport(of.createPlane(of.createPlaneType()));
2168

Lukas Jungmann's avatar
Lukas Jungmann committed
2169 2170 2171 2172 2173
**// Combination of element and type substitution:**
__// Substitutes <e:auto xsi:type="e:SUV"> for <e:transport>__
itinerary.setTransport(of.createAuto(of.createSUV()));
----

2174 2175
.Invalid element substitution using Java bindings from <<a1242>>
[[a1246]]
Lukas Jungmann's avatar
Lukas Jungmann committed
2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198
[source,xml,indent=4]
----
<!-- Add elements not part of element substitution group. -->
<xs:element name="apple" type="xsd:string"/>
<xs:complexType name="spaceShuttle">
  <xs:extension base="a:TransportType">...</xs:complexType>
<xs:element name="spaceShuttle" type="a:spaceShuttleType">
----

[source,java,indent=8,subs=+quotes]
----
ObjectFactory of = ...;
Itinerary itinerary = of.createItinerary();
**// Invalid element substitution**
**// compile time error: method not found**
// Element apple of type JAXBElement<String> does not match
// bounded wildcard JAXBElement<? extends TransportType>.
itinerary.setTransport(of.createApple("granny smith"));

**// Invalid element substitution detected by validation.**
// Element spaceShuttle not part of substitution group.
// Adding _substitutionGroup="transport"_ to line 4 fixes this.
itinerary.setTranport(
2199
of.createSpaceShuttle(of.createSpaceShuttleType()));
Lukas Jungmann's avatar
Lukas Jungmann committed
2200
----
2201 2202 2203 2204 2205 2206 2207

==== Bind to an Element Collection property

A repeating occurrence element declaration
that is element substitutable binds solely to a JAXB Collection property
of JAXBElement.

2208
.Bind repeating occurrence element substitution variant of <<a1240>>
Lukas Jungmann's avatar
Lukas Jungmann committed
2209 2210 2211 2212 2213 2214 2215 2216 2217 2218
[source,xml,indent=4,subs=+quotes]
----
<!--deleted schema that remains same -->
<xs:complexType name="itinerary">
  <xs:sequence>
    **<!-- Repeating occurance to substitutable global element reference. -->**
    <xs:element ref="a:transport" **maxOccurs="unbounded"** />
  </xs:sequence>
</xs:complexType>
----
2219

Lukas Jungmann's avatar
Lukas Jungmann committed
2220 2221 2222 2223 2224
Java Binding:
[source,java,indent=4]
----
public class Itinerary {
    List<JAXBElement<? extends TransportType>> getTransport();
2225
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2226
----
2227

Lukas Jungmann's avatar
Lukas Jungmann committed
2228
=== Attribute use
2229 2230 2231

A ‘required’ or ‘optional’ attribute use is
bound by default to a Java property as described in
2232
<<Properties>>. The characteristics of the
2233
Java property are derived in terms of the properties of the
2234
<<Attribute Use Schema Component>> and <<Attribute Declaration Schema Component>>
2235 2236
as follows:

Lukas Jungmann's avatar
Lukas Jungmann committed
2237 2238
* The _name_ of the Java property is derived
from the _{attribute declaration}_ property’s _{name}_ property using the
2239
XML Name to Java Identifier mapping algorithm described in
2240
<<The Name to Identifier Mapping Algorithm>>.
2241
* A _base type_ for the Java property is
Lukas Jungmann's avatar
Lukas Jungmann committed
2242 2243
derived from the `{attribute declaration}` property’s `{type
definition}` property as described in binding of Simple Type Definition
2244
in <<Simple Type Definition>>. If the
2245
base type is initially a primitive type and this JAXB property is
Lukas Jungmann's avatar
Lukas Jungmann committed
2246 2247
_optional_ , the *[jaxb:globalBinding]* customization
`@optionalProperty` controls the binding of an optional primitive
2248
property as described in <<Usage>>.
2249
* An optional _predicate_ for the Java
Lukas Jungmann's avatar
Lukas Jungmann committed
2250 2251
property is constructed from the `{attribute declaration}` property’s
`{type definition}` property as described in the binding of simple type
2252 2253
definition to a Java representation.
* An optional _collection type_ for the Java
Lukas Jungmann's avatar
Lukas Jungmann committed
2254 2255
property is derived from the `{attribute declaration}` property’s
`{type definition}` property as described in the binding of simple type
2256 2257
definition to a Java representation.
* The _default value_ for the Java property
Lukas Jungmann's avatar
Lukas Jungmann committed
2258 2259
is the _value_ from the attribute use’s _{value constraint}_ property. If
the optional _{value constraint}_ is absent, the default value for the
2260 2261
Java property is the Java default value for the base type.
* The JAXB property is _optional_ when the
Lukas Jungmann's avatar
Lukas Jungmann committed
2262
attribute use’s `{required}` property is `false`.
2263 2264 2265 2266 2267 2268 2269

This Java property is a member of the Java
value class that represents the binding of the complex type definition
containing the attribute use

The JAXB property getter for this attribute
is annotated, either explicitly or via default mapping, with the mapping
2270
annotation @XmlAttribute, specified in <<xmlattribute>>. The @XmlAttribute
2271
element values are derived in terms of the properties of the
2272 2273
<<Attribute Use Schema Component>> and
<<Attribute Declaration Schema Component>>
2274 2275
as follows:

2276 2277
.Annotate Attribute property getter method with @XmlAttribute annotation
[[a1262]]
Lukas Jungmann's avatar
Lukas Jungmann committed
2278
[cols="1,1",options="header",]
2279
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
2280 2281 2282 2283 2284 2285
| @XmlAttribute element | @XmlAttribute value
| name | attribute declaration's _{name}_
| namespace | if attribute declaration’s _{target namespace}_ absent,
set to “” +
otherwise, set to _{target namespace}_
| required | attribute use's _{required}_
2286 2287
|===

Lukas Jungmann's avatar
Lukas Jungmann committed
2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301
[NOTE]
.Design Note
====
Since the target namespace is not being considered when mapping
an attribute to a Java property, two distinct attributes
that have the same _{name}_ property but not the same _{target namespace}_
will result in a Java property naming collision.
As specified generically in Section D.2.1, “Collisions and conflicts”,
the binding compiler detect this name collision between
the two distinct properties and reports the error.
The user can provide a customization that provides an alternative
Java property name to resolve this situation.

====
2302 2303 2304 2305

*_Example:_* +

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
2306 2307 2308 2309
[source,xml,indent=4]
----
<xs:complexType name="USAddress">
  <xs:attribute name="country" type="xs:string"/>
2310
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
2311
----
2312 2313

Default derived Java code:
Lukas Jungmann's avatar
Lukas Jungmann committed
2314 2315 2316 2317 2318 2319
[source,java,indent=4]
----
public class USAddress {
    @XmlAttribute(name="country", targetNamespace="", required="false");
    public String getCountry() {...}
    public void setCountry(String value) {...}
2320
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2321
----
2322

Lukas Jungmann's avatar
Lukas Jungmann committed
2323
==== Bind to a Java Constant property
2324 2325

Rather than binding to a read/write JAXB
Lukas Jungmann's avatar
Lukas Jungmann committed
2326
property, an attribute use with a `fixed` _{value constraint}_ property
2327
can be bound to a Java Constant property. This mapping is not performed
Lukas Jungmann's avatar
Lukas Jungmann committed
2328 2329 2330
by default since `fixed` is only a validation constraint. The user must
set the binding declaration attribute `fixedAttributeToConstantProperty`
on `<jaxb:globalBinding>` element as specified in
2331 2332
<<usage>> or on`<jaxb:property>` element
as specified in <<usage-4>> to enable this
2333 2334 2335 2336 2337
mapping.

*_Example:_* +

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
2338 2339
[source,xml,indent=4]
----
2340
<xs:annotation><xs:appinfo>
Lukas Jungmann's avatar
Lukas Jungmann committed
2341 2342 2343 2344
  <jaxb:globalBindings fixedAttributeAsConstantProperty="true"/>
</xs:appinfo></xs:annotation>
<xs:complexType name="USAddress">
  <xs:attribute name="country" type="xs:NMTOKEN" fixed="US"/>
2345
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
2346
----
2347 2348 2349 2350 2351

If the appropriate binding schema
customization enables mapping a fixed XML value to Java constant
property, the following Java code fragment is generated.

Lukas Jungmann's avatar
Lukas Jungmann committed
2352 2353 2354 2355 2356 2357
[source,java,indent=4]
----
public class USAddress {
    @XmlAttribute
    public static final String COUNTRY="US";
    ...
2358
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2359
----
2360 2361 2362

The schema-derived constant for this fixed
attribute is annotated, either explicitly or via default mapping, with
Lukas Jungmann's avatar
Lukas Jungmann committed
2363
the mapping annotation `@XmlAttribute`. The elements of `@XmlAttribute`
2364
are set as described in <<a1262>>.
2365 2366 2367 2368 2369 2370 2371 2372 2373

Note that if derivation by restriction
constrains an existing attribute declaration to be fixed, this
refinement must not be bound to a constant property. The initial binding
of the attribute to a JAXB property remains the only binding of the
attribute in the Java class hierarchy.

===== Contributions to Local Structural Constraint

Lukas Jungmann's avatar
Lukas Jungmann committed
2374
If the attribute use’s _{required}_ property
2375 2376 2377 2378
is true, the local structural constraint for an instance of the Java
value class requires that the corresponding Java property to be set when
the Java value class instance is validated.

Lukas Jungmann's avatar
Lukas Jungmann committed
2379
==== Binding an IDREF component to a Java property
2380 2381

An element or attribute with a type of
Lukas Jungmann's avatar
Lukas Jungmann committed
2382 2383 2384
`xs:IDREF` refers to the element in the instance document that has an
attribute with a type of `xs:ID` or derived from type `xs:ID` with the
same value as the `xs:IDREF` value. Rather than expose the Java
2385
programmer to this XML Schema concept, the default binding of an
Lukas Jungmann's avatar
Lukas Jungmann committed
2386 2387
`xs:IDREF` component maps it to a Java property with a base type of
`java.lang.Object`. The caller of the property setter method must be
2388 2389
sure that its parameter is identifiable. An object is considered
identifiable if one of its properties is derived from an element or
Lukas Jungmann's avatar
Lukas Jungmann committed
2390 2391
attribute that is or derives from type `xs:ID`. The JAXB mapped class
must have one property annotated with an `@XmlID` program annotation as it
2392
is specified in Section 8. There is an expectation that all instances
Lukas Jungmann's avatar
Lukas Jungmann committed
2393 2394 2395 2396 2397
provided as values for properties’ representing an `xs:IDREF` should
have the Java property representing the `xs:ID` of the instances set
before the content tree containing both the `xs:ID` and `xs:IDREF` is
marshalled. If a property representing an `xs:IDREF` is set with an
object that does not have its `xs:ID` set, the `NotIdentifiableEvent` is
2398 2399
reported by marshalling.

Lukas Jungmann's avatar
Lukas Jungmann committed
2400 2401
* The _name_ of the Java property is derived
from the _{name}_ property _of the attribute or element_ using the XML Name
2402
to Java Identifier mapping algorithm described in
2403
<<The Name to Identifier Mapping Algorithm>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2404 2405
* A _base type_ for the Java property is java.lang.Object.
* There is no _predicate_ for a property representing an `xs:IDREF`.
2406 2407
* An optional _collection type_
* Default and fixed values can not be
Lukas Jungmann's avatar
Lukas Jungmann committed
2408
supported for an attribute with type `xs:IDREF`.
2409 2410 2411 2412 2413 2414 2415 2416 2417

The schema-derived JAXB property representing
xs:IDREF(s) is annotated, either explicitly or by default mapping
annotations, with the mapping annotation @XmlIDREF, specified in Section
8.

*_Example:_* +

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430
[source,xml,indent=4,subs=+quotes]
----
<xs:complexType name="Book">
  <xs:sequence>
    __<xs:element name="author" type="xs:IDREF"/>__
    <!-- ... -->
  </xs:sequence>
</xs:complexType>
<xs:complexType name="AuthorBio">
  <xs:sequence> <!-- ... --> </xs:sequence>
  __<xs:attribute name="name" type="xs:ID"/>__
</xs:complexType>
----
2431 2432

Schema-derived Java value class:
Lukas Jungmann's avatar
Lukas Jungmann committed
2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448
[source,java,indent=4]
----
public class Book {
    @XmlIDREF
    java.lang.Object getAuthor() {...}

    /** Parameter referencedObj should have an attribute or
     * child element with base type of xs:ID by validation
     * or marshal time.
     */
    void setAuthor(java.lang.Object referencedObj) {...}
}
public class AuthorBio {
    @XmlID
    String getName() {...}
    void setName(String value) {...}
2449
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2450
----
2451 2452 2453 2454

Demonstration of a Java content instance
referencing another instance:

Lukas Jungmann's avatar
Lukas Jungmann committed
2455 2456 2457 2458 2459 2460 2461 2462
[source,java,indent=8]
----
Book book = ...;
AuthorBio authorBio = ...;
book.setAuthor(authorBio);
authorBio.setName("<some authors name>");
// The content instance root used to validate or marshal book must
// also include "authorBio" as a child element somewhere.
2463
// A Java content instance is not included
Lukas Jungmann's avatar
Lukas Jungmann committed
2464
----
2465

Lukas Jungmann's avatar
Lukas Jungmann committed
2466
Note that `ID` and `IDREF` mechanisms do not
2467 2468
incorporate type definitions that can be referenced. To generate
stronger typing for a JAXB property representing an IDREF, the schema
2469 2470 2471
customization described in <<Generalize/Specialize baseType with attribute @name>>
can be used to specialize the binding. <<exidrefcust,Specialize binding of an IDREF via customization>>
illustrates the generation of stronger typing for the above example.
2472

Lukas Jungmann's avatar
Lukas Jungmann committed
2473
=== Attribute Wildcard
2474 2475 2476 2477 2478 2479 2480 2481 2482 2483

Attribute wildcard is an extensibility
feature in XML Schema. It enables an XML document author to introduce
attribute(s) to an element that were not statically associated with the
element’s complex type definition. Obviously, it is not possible to bind
such an attribute to a strongly typed JAXB property as the previous
section describes for attribute use schema component. The JAXB binding
of a complex type definition that contains an attribute wildcard,
directly or indirectly, provides dynamic access to the wildcard
attributes via the following property:
Lukas Jungmann's avatar
Lukas Jungmann committed
2484 2485
[source,java,indent=8]
----
2486 2487 2488
// Return, by reference, a mapping of
attribute QName and String. +
Map<QName, String> getOtherAttributes();
Lukas Jungmann's avatar
Lukas Jungmann committed
2489
----
2490 2491 2492 2493 2494 2495 2496
The returned attribute map provides dynamic
access to wildcard attributes associated with a complex type definition.
The key to the map is the attribute’s QName and the key’s value is the
String value of the attribute.

The schema-derived property getter method is
annotated, either explicitly or by default mapping annotations, with the
Lukas Jungmann's avatar
Lukas Jungmann committed
2497
mapping annotation `@XmlAnyAttribute`, specified in Section 8.
2498 2499 2500 2501 2502 2503

The following code examples show the JAXB
binding for xs:anyAttribute and how to manipulate wildcard attributes
using this binding.

.Bind anyAttribute to a JAXB property
Lukas Jungmann's avatar
Lukas Jungmann committed
2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521
[source,xml,indent=4,subs=+quotes]
----
<xs:schema targetNamespace="http://a.org">
  <xs:complexType name="**widget**">
    <xs:anyAttribute/>
    <xs:attribute name="color" type="xs:string"/>
  </xs:complexType>
</xs:schema>
----
[source,java,indent=4,subs=+quotes]
----
package org.a;
import javax.xml.namespace.QName;
import java.util.Map;
public class **Widget**  {
    String getColor() {...}
    void setColor(String value) {...}
    @XmlAnyAttribute Map<QName, String> **getOtherAttributes** () {...}
2522
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2523
----
2524 2525

.Dynamic access to wildcard attribute and attribute use
Lukas Jungmann's avatar
Lukas Jungmann committed
2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547
[source,java,indent=4]
----
import jakarta.xml.bind.DatatypeConverter;
Widget w = ...;
Map attrs = w.getOtherAttributes();

// access schema-defined global attribute associated with
// complexType defintion widget via attribute wildcard.
QName IS_OPEN = new QName("http://example.org", "isOpen");
boolean isOpen = DatatypeConverter.parseBoolean(attrs.get(IS_OPEN));

// set wildcard attribute value
attrs.put(IS_OPEN, DatatypeConverter.printBoolean(false));

// semantically the same results setting attribute use via
// dynamic or static setter for attribute use.
attrs.put(new QName("color"), "red");

// iterate over wildcard attributes
for (Map.Entry<QName,String> e: attrs.entrySet()) {
System.out.println("Attribute: " + e.getKey() +
                   " Value:" + e.getValue());
2548
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2549
----
2550

Lukas Jungmann's avatar
Lukas Jungmann committed
2551
=== Redefine
2552 2553 2554 2555 2556 2557 2558 2559 2560 2561

Redefinition allows an existing XML Schema
component to be “renamed” and its new definition takes the place of the
old one. The binding of the redefined schema components, simple and
complex type definitions and model and attribute group declarations, are
described in the following subsections.

==== Bind Redefined Simple Type Definition

As introduced in
2562
<<Simple Type Definition>>, a schema
2563 2564 2565 2566 2567 2568 2569 2570 2571 2572
component using a simple type definition typically binds to a JAXB
property. The base type, collection type and predicate of the JAXB
property are derived from the simple type definition. Thus, the redefine
of a simple type definition results in the redefinition of the simple
type definition being used to derive the base type, collection type and
predicate of the JAXB property.

The one exception to this binding is that a
simple type definition with enum facets is sometimes bound to an enum
type. A redefined simple type definition that binds to an enum type, as
2573
described in <<Enum Type>>, is not bound
2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586
to a Java representation, only the redefinition is bound to an enum
type.

==== Bind Redefined Complex Type Definition

A redefinition of a type definition must use
the original type definition as its base type definition. The redefined
complex type definition is bound to a Java value class or interface name
that prepends “_” to the class name. The redefinition complex type
definition is bound to a class that extends the JAXB class that
represents the redefined complex type definition.

.Binding of a redefined complex type definition
Lukas Jungmann's avatar
Lukas Jungmann committed
2587 2588 2589 2590 2591 2592 2593 2594 2595 2596
[source,xml,indent=4]
----
File: v1.xsd:
<!-- Extracted from Section 4.2.2 of [XSD1] -->
<xs:complexType name="personName">
  <xs:sequence>
    <xs:element name="title" type="xs:string" minOccurs="0"/>
    <xs:element name="forename" type="xs:string"
                minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
2597 2598
</xs:complexType>

Lukas Jungmann's avatar
Lukas Jungmann committed
2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609
File: v2.xsd:
<xs:redefine schemaLocation="v1.xsd">
  <xs:complexType name="personName">
    <xs:complexContent>
      <xs:extension base="personName">
        <xs:sequence>
          <xs:element name="generation" minOccurs="0"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
2610
</xs:redefine>
Lukas Jungmann's avatar
Lukas Jungmann committed
2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626
----
Java binding:
[source,java,indent=4]
----
// binding of file v1.xsd complex type definition for personName
@XmlType(name="_PersonName")
public class _PersonName {
    void setTitle(String value); String getTitle();
    List<String> getForename();
}
// binding of v2.xsd redefinition for complex type personName
@XmlType(name="PersonName")
public class PersonName extends _PersonName {
    void setGeneration(Object value); Object getGeneration();
}
----
2627 2628 2629 2630 2631 2632 2633

==== Bind Redefined Group Definition

The attribute or model group redefinition is
used instead of the initial group definition to construct the property
set of the content model(s) that reference the redefined attribute or
model group definition. The construction of a property set is described
2634
in <<Java value class>>.
2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646

Since there is no binding of an attribute or
model group definition to a Java representation, no other special case
handling is required for this binding.

=== Identity Constraint

An identity constraint does not represent any
data, it represents a constraint that is enforced by validation. These
constraints can be checked by optional validation that can be enabled at
either unmarshal and/or marshal time.

Lukas Jungmann's avatar
Lukas Jungmann committed
2647
=== Content Model - Particle, Model Group, Wildcard
2648 2649 2650

This section describes the possible Java
bindings for the content model of a complex type definition schema
Lukas Jungmann's avatar
Lukas Jungmann committed
2651
component with a _{content type}_ property of `mixed` or `element-only`.
2652
The possible element content(s) and the valid ordering between those
Lukas Jungmann's avatar
Lukas Jungmann committed
2653
contents are constrained by the _{particles}_ describing the complex type
2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665
definition’s content model. The Java binding of a content model is
realized by the derivation of one or more content-properties to
represent the element content constrained by the model group. Section
6.12.1 through 6.12.7 describes the _element binding_ of a content
model.

==== Element binding style

The ideal Java binding would be to map each
uniquely named element declaration occurring within a content model to a
single JAXB property. The model group schema component constraint,
element declarations consistent, specified in [XSD-Part 1] ensures that
Lukas Jungmann's avatar
Lukas Jungmann committed
2666 2667
all element declarations/references having the same {target namespace}
and {name} must have the same top-level type definition. This model
2668 2669
allows the JAXB technology user to specify only the content and the JAXB
implementation infers the valid ordering between the element content
Lukas Jungmann's avatar
Lukas Jungmann committed
2670 2671 2672
based on the _{particles}_ constraints in the source schema.

However, there do exist numerous scenarios that this ideal binding is not
2673 2674 2675
possible for parts of the content model or potentially the entire
content model. For these cases, default binding has a fallback position
of representing the element content and the ordering between the content
Lukas Jungmann's avatar
Lukas Jungmann committed
2676
using a _general content model_. The scenarios where one must fallback
2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687
to the general content model will be identified later in this
subsection.

==== Bind each element declaration name to a JAXB property

This approach relies on the fact that a model
group merely provide constraints on the ordering between children
elements and the user merely wishes to provide the content. It is
easiest to introduce this concept without allowing for repeating
occurrences of model groups within a content model. Conceptually, this
approach presents all element declarations within a content model as a
Lukas Jungmann's avatar
Lukas Jungmann committed
2688
set of element declaration __{name}__’s. Each one of the __{name}__’s is
2689 2690 2691 2692 2693 2694
mapped to a content-property. Based on the element content that is set
by the JAXB application via setting content-properties, the JAXB
implementation can compute the order between the element content using
the following methods.

Computing the ordering between element
Lukas Jungmann's avatar
Lukas Jungmann committed
2695
content within *[children]* of an element information item
2696 2697 2698

* Schema constrained fixed ordering or
semantically insignificant ordering
Lukas Jungmann's avatar
Lukas Jungmann committed
2699
+
2700 2701 2702 2703 2704 2705 2706 2707
The sequence in the schema represents an
ordering between children elements that is completely fixed by the
schema. Schema-constrained ordering is not exposed to the Java
programmer when mapping each element in the sequence to a Java property.
However, it is necessary for the marshal/unmarshal process to know the
ordering. No new ordering constraints between children elements can be
introduced by an XML document or Java application for this case.
Additionally, the Java application does not need to know the ordering
Lukas Jungmann's avatar
Lukas Jungmann committed
2708
between children elements. When the compositor is `all`, the ordering
2709 2710 2711 2712 2713
between element content is not specified semantically and any ordering
is okay. So this additional case can be handled the same way.

* Schema only constrains content and does not
significantly constrain ordering
Lukas Jungmann's avatar
Lukas Jungmann committed
2714
+
2715 2716 2717 2718 2719
If the ordering between the children elements
is significant and must be accessible to the Java application, then the
ordering is naturally preserved in Java representation via a collection.
Below are examples where schema provides very little help in
constraining order based on content.
Lukas Jungmann's avatar
Lukas Jungmann committed
2720 2721 2722 2723 2724
+
--
[source,xml,indent=4]
----
<xs:choice maxOccurs="unbounded"> ... </xs:choice>
2725
<xs:sequence maxOccurs="unbounded"> ... </xs:sequence>
Lukas Jungmann's avatar
Lukas Jungmann committed
2726 2727
----
--
2728

Lukas Jungmann's avatar
Lukas Jungmann committed
2729
==== General content property
2730 2731 2732 2733 2734

A general content property is, as its name
implies, the most general of all content properties. Such a property can
be used with any content specification, no matter how complex. A general
content property is represented as a List property as introduced in
2735
<<List Property>>. Unlike the prior
2736 2737 2738 2739 2740 2741 2742 2743
approach where the JAXB implementation must infer ordering between the
element content, this approach always requires the JAXB technology user
to specify a valid ordering of element and text content. This approach
has the benefit of providing the application with more control over
setting and knowing the order between element content.

A general content property is capable of
representing both element information items and character data items
Lukas Jungmann's avatar
Lukas Jungmann committed
2744
occurring within *[children]* of an element information item. Character
2745 2746 2747 2748
data is inserted into the list as java.lang.String values. Element data
is added to the list as instances of JAXB element. To support wildcard
content occurring as part of a general content property, xml data
content with no static Java binding is added and accessed from the list
Lukas Jungmann's avatar
Lukas Jungmann committed
2749
as instances of `org.w3c.org.dom.Node`.
2750 2751 2752 2753 2754 2755 2756

The schema-derived Collection property getter
method is annotated, either explicitly or by default mapping
annotations, with the mapping annotations reflecting what content is
within the Collection.

* If the content model is mixed, the property
2757 2758
is annotated as `@XmlMixed`. See <<Bind mixed content>> for details.
* <<Collection of Element types>> describes an optimized binding of a collection of
2759
element values, instead of a collection of JAXB elements annotated with
Lukas Jungmann's avatar
Lukas Jungmann committed
2760
`@XmlElementRefs(@XmlElementRef, ...)`.
2761
* If optimized binding can not be used, each
Lukas Jungmann's avatar
Lukas Jungmann committed
2762
element in the content model is represented by an `@XmlElementRef`,
2763 2764
described in <<Bind to a Simple Element property>>.
If there is more than one element annotations needed, they
Lukas Jungmann's avatar
Lukas Jungmann committed
2765
must occur as elements in the map annotation `@XmlElementRefs` specified
2766 2767
in Section 8.10.3, “@XmlElementRef”.

Lukas Jungmann's avatar
Lukas Jungmann committed
2768
===== Collection of Element types
2769 2770 2771 2772 2773 2774

If the content model for a general content
property meets all of the following constraints, the collection can be
optimized to be a list of value classes instead of a list of JAXB
elements.

Lukas Jungmann's avatar
Lukas Jungmann committed
2775
* If the content model is not mixed and does not contain a wildcard.
2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786
* If none of the element declarations in the
content model are abstract or the head of an element substitution group.
* If none of the element declarations in the
content model have a xml datatype that is or derives from xs:list or
xs:IDREF.
* For all element declarations in the content
model, there does not exist two distinct element declarations whose
types bind to the same Java datatype.
* If not more than one element declaration in
the content model is nillable.

Lukas Jungmann's avatar
Lukas Jungmann committed
2787 2788 2789 2790
Such a collection is annotated with `@XmlElements` annotation,
specified in Section 8, that contains a
`@XmlElement` annotation for each unique Java datatype within the
collection. The `@XmlElement` annotation associates an element name with
2791 2792
each unique Java datatype in the collection

Lukas Jungmann's avatar
Lukas Jungmann committed
2793
===== Examples
2794 2795

*_Example 1:_ Complex content model of Elements with primitive types* +
Lukas Jungmann's avatar
Lukas Jungmann committed
2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815
[source,xml,indent=4]
----
<xs:complexType name="Base">
  <xs:choice maxOccurs="unbounded">
    <xs:element name="A" type="xs:string"/>
    <xs:element name="B" type="xs:string"/>
    <xs:element name="C" type="xs:int"/>
  </xs:choice>
</xs:complexType>
----
[source,java,indent=4]
----
public class ObjectFactory \{
    // Element instance factories.
    JAXBElement<String> createBaseA(String value) {...}
    JAXBElement<String> createBaseB(String value) {...}
    JAXBElement<Integer> createBaseC(Integer value) {...}
    // Type factories
    Base createBase() {...}
}
2816

Lukas Jungmann's avatar
Lukas Jungmann committed
2817 2818 2819 2820 2821 2822 2823 2824 2825 2826
public class Base {
    /**
     * A general content list that can contain
     * element instances representing A, B and/or C.
     */
    @XmlElementRefs({
        @XmlElementRef(name="A", value=JAXBElement.class),
        @XmlElementRef(name="B", value=JAXBElement.class),
        @XmlElementRef(name="C", value=JAXBElement.class)})
    List<JAXBElement> getAOrBOrC()\{...}
2827
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2828
----
2829 2830 2831

*_Example 2:_ Optimized Binding to a Collection of Element Types* +
XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
2832 2833 2834 2835 2836 2837 2838 2839 2840
[source,xml,indent=4]
----
<xs:complexType name="AType"/>
<xs:complexType name="BType"/>
<xs:complexType name="FooBar">
  <xs:choice maxOccurs="unbounded">
    <xs:element name="foo" type="AType"/>
    <xs:element name="bar" type="BType"/>
  </xs:choice>
2841
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
2842
----
2843

Lukas Jungmann's avatar
Lukas Jungmann committed
2844 2845 2846 2847 2848
Default derived Java code:
[source,java,indent=4]
----
public class AType {...}
public class BType {...}
2849

Lukas Jungmann's avatar
Lukas Jungmann committed
2850 2851 2852 2853 2854
class ObjectFactory {
    // element instance factories only
    JAXBElement<AType> createFooBarFoo(AType value);
    JAXBElement<BType> createFooBarBar(BType value);
}
2855

Lukas Jungmann's avatar
Lukas Jungmann committed
2856 2857 2858 2859 2860 2861
public class FooBar {
    /** Collection of element types: AType and BType. */
    @XmlElements({
        @XmlElement(value=AType.class, name="Foo"),
        @XmlElement(value=BType.class, name="Bar")})
    List<Object> getFooOrBar() {...}
2862
};
Lukas Jungmann's avatar
Lukas Jungmann committed
2863
----
2864

Lukas Jungmann's avatar
Lukas Jungmann committed
2865
==== Bind mixed content
2866

Lukas Jungmann's avatar
Lukas Jungmann committed
2867 2868
When a complex type definition’s _{content type}_
is “mixed,” its character and element information content is
2869
bound to general content list as described in
2870
<<General content property>>. Character
Lukas Jungmann's avatar
Lukas Jungmann committed
2871
information data is inserted as instances of `java.lang.String` into a
2872 2873 2874 2875
JAXB collection property.

The schema-derived Collection property getter
method is annotated, either explicitly or by default mapping
Lukas Jungmann's avatar
Lukas Jungmann committed
2876
annotations, with the mapping annotation `@XmlMixed`, specified in
2877 2878 2879 2880 2881
Section 8.

*_Example:_* +

Schema fragment loosely derived from mixed
Lukas Jungmann's avatar
Lukas Jungmann committed
2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893
content example from [XSD Part 0].
[source,xml,indent=4]
----
<xs:element name="letterBody">
  <xs:complexType mixed="true">
    <xs:sequence>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="quantity" type="xs:positiveInteger"/>
      <xs:element name="productName" type="xs:string"/>
      <!-- etc. -->
    </xs:sequence>
  </xs:complexType>
2894
</xs:element>
Lukas Jungmann's avatar
Lukas Jungmann committed
2895
----
2896 2897

Derived Java code:
Lukas Jungmann's avatar
Lukas Jungmann committed
2898 2899 2900 2901 2902 2903 2904 2905 2906 2907
[source,java,indent=4]
----
import java.math.BigInteger;
class ObjectFactory {
    // element instance factories only
    JAXBElement<LetterBody> createLetterBody(LetterBody value);
    JAXBElement<String> createLetterBodyName(String value);
    JAXBElement<BigInteger> createLetterBodyQuantity(BigInteger value);
    JAXBElement<String> createLetterBodyProductName(String value);
}
2908

Lukas Jungmann's avatar
Lukas Jungmann committed
2909 2910 2911 2912 2913 2914 2915 2916 2917 2918
public class LetterBody implements JAXBElement<LetterBody> {
    /** Mixed content can contain instances of Element classes
        Name, Quantity and ProductName. Text data is represented as
        java.util.String for text. */
    @XmlMixed
    @XmlElementRefs( {
        @XmlElementRef(name="productName", type=JAXBElement.class),
        @XmlElementRef(name="quantity", type=JAXBElement.class),
        @XmlElementRef(name="name", type=JAXBElement.class)})
    List getContent() {...}
2919
}
Lukas Jungmann's avatar
Lukas Jungmann committed
2920
----
2921 2922

The following instance document
Lukas Jungmann's avatar
Lukas Jungmann committed
2923 2924 2925 2926 2927 2928
[source,xml,indent=4]
----
<letterBody>
Dear Mr.<name>Robert Smith</name>
Your order of <quantity>1</quantity> <productName>Baby
Monitor</productName> shipped from our warehouse. ....
2929
</letterBody>
Lukas Jungmann's avatar
Lukas Jungmann committed
2930
----
2931 2932

could be constructed using JAXB API.
Lukas Jungmann's avatar
Lukas Jungmann committed
2933 2934 2935 2936 2937 2938 2939
[source,java,indent=4]
----
LetterBody lb = ObjectFactory.createLetterBody(null);
List gcl = lb.getContent();
gcl.add("Dear Mr.");
gcl.add(ObjectFactory.createLetterBodyName("Robert Smith")); 
gcl.add("Your order of ");
2940
gcl.add(ObjectFactory.
Lukas Jungmann's avatar
Lukas Jungmann committed
2941 2942
    createLetterBodyQuantity(new BigInteger("1")));
gcl.add(ObjectFactory.createLetterBodyProductName("Baby Monitor"));
2943
gcl.add("shipped from our warehouse");
Lukas Jungmann's avatar
Lukas Jungmann committed
2944
----
2945 2946

Note that if any element instance is placed
Lukas Jungmann's avatar
Lukas Jungmann committed
2947 2948
into the general content list, _gcl_, that is not an instance of
`LetterBody.Name`, `LetterBody.Quantity` or `LetterBody.ProductName`,
2949 2950
validation would detect the invalid content model. With the fail fast
customization enabled, element instances of the wrong type are detected
Lukas Jungmann's avatar
Lukas Jungmann committed
2951
when being added to the general content list, _gcl_.
2952

Lukas Jungmann's avatar
Lukas Jungmann committed
2953
==== Bind wildcard schema component
2954

Lukas Jungmann's avatar
Lukas Jungmann committed
2955
A wildcard is mapped to a simple content-property with:
2956

Lukas Jungmann's avatar
Lukas Jungmann committed
2957 2958
* Content-property name set to the constant “`any`”.
A binding schema customization could provide a more
2959
semantically meaningful content-property name.
Lukas Jungmann's avatar
Lukas Jungmann committed
2960 2961
* Content-property _base type_ set to
`java.lang.Object` by default.
2962 2963
Wildcard content is represented as one of the
following:
Lukas Jungmann's avatar
Lukas Jungmann committed
2964 2965 2966 2967 2968
.. JAXB element +
Either an instance of `jakarta.xml.bind.JAXBElement<T>` or a JAXB class
annotated with `@XmlRootElement`. +
Corresponds to a recognized global element tag name registered with
the instance `jakarta.xml.bind.JAXBContext`, meaning the schema(s)
2969
describing the element content is registered with the _JAXBContext_
2970
instance, see <<JAXBContext>> on how
Lukas Jungmann's avatar
Lukas Jungmann committed
2971 2972 2973 2974 2975 2976 2977
bindings are registered with a `JAXBContext` instance.,
.. instance of `jakarta.xml.bind.JAXBElement`. +
Corresponds to an unknown element name but a recognized type
definition specified by *_@xsi:type_* on the element. JAXBElement
_declaredType_ is set to `java.lang.Object` since the unknown element
declaration’s default type is `xs:anyType`.
.. element node instance of a supported xml infoset API. +
2978 2979
Necessary to represent Xml data content that does not have a schema
defined element or type definition. Such content is allowed by element
Lukas Jungmann's avatar
Lukas Jungmann committed
2980 2981 2982
*xs:any* with attribute *@processContents="lax"* or "`*skip*`".
* See content-property predicate for a wildcard.
* If the `maxOccurs` is greater than one, the
2983 2984
content property is mapped to a collection property. The default
collection property is a List property of base type java.lang.Object.
Lukas Jungmann's avatar
Lukas Jungmann committed
2985
* There is no _default value_.
2986 2987 2988 2989 2990 2991 2992 2993 2994

Since the schema does not contain any
information about the element content of a wildcard content, even the
content-property, by default, can not infer an XML element tag for
wildcard element content.

The schema-derived property getter method for
representing wildcard content is annotated, either explicitly or by
default mapping annotations, with the mapping annotation
Lukas Jungmann's avatar
Lukas Jungmann committed
2995
`@XmlAnyElement`, specified in Section 8. The @XmlAnyElement annotation
2996
element values are derived in terms of the abstract model properties for
2997
wildcard summarized in <<Wildcard Schema Component>> as follows:
2998 2999

.Annotate JAXB property with @XmlAnyElement element-value pairs
Lukas Jungmann's avatar
Lukas Jungmann committed
3000
[cols="1,1",options="header"]
3001
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
3002 3003 3004
| @XmlAnyElement element | @XmlAnyElement element value
| lax | If wildcard schema component’s _{process contents}_ is `lax` or `strict_`, +
set `@XmlAnyElement.lax()` to `true`. +
3005
 +
Lukas Jungmann's avatar
Lukas Jungmann committed
3006 3007
else if _{process contents}_ is `skip`, set `@XmlAnyElement.lax()` to `false`.
| value | `jakarta.xml.bind.annotation.W3CDomHandler.class`
3008 3009
|===

Lukas Jungmann's avatar
Lukas Jungmann committed
3010
==== Bind a repeating occurrence model group
3011 3012

A choice or sequence model group, containing
Lukas Jungmann's avatar
Lukas Jungmann committed
3013
more than one member, with a repeating occurrence, `maxOccurs` attribute
3014 3015 3016
greater than one, is bound to a general content property in the
following manner:

Lukas Jungmann's avatar
Lukas Jungmann committed
3017 3018 3019
* Content-property _name_ is derived in following ways:
** If a named model group definition is being
referenced, the value of its _{name}_ property is mapped to a Java
3020
identifier for a method using the algorithm specified in
3021
<<The Name to Identifier Mapping Algorithm>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
3022
** To derive a content property _name_ for
3023
unnamed model group, see <<Deriving an identifier for a model group>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
3024 3025
* Content-property _base type_ set to
`java.lang.Object`. A binding schema customization could provide a more
3026
specialized java class.
Lukas Jungmann's avatar
Lukas Jungmann committed
3027
* Content-property _predicate_ validates the
3028 3029 3030
order between element instances in the list and whether the occurrence
constraints for each element instance type is valid according to the
schema.
Lukas Jungmann's avatar
Lukas Jungmann committed
3031
* Since the `maxOccurs` is always greater
3032 3033
than one, the content property is mapped to a collection property. The
default collection property is a List property.
Lukas Jungmann's avatar
Lukas Jungmann committed
3034
* There is no _default value_.
3035 3036

The schema-derived collection property is
3037 3038
annotated as specified in <<General content property>>
and <<Collection of Element types>>.
3039

Lukas Jungmann's avatar
Lukas Jungmann committed
3040
*_Local structural Constraints_*
3041 3042 3043 3044 3045 3046

The list content property’s value must
satisfy the content specification of the model group. The ordering and
element contents must satisfy the constraints specified by the model
group.

Lukas Jungmann's avatar
Lukas Jungmann committed
3047
==== Content Model Default Binding
3048 3049 3050 3051

The following rules define _element_ binding
style for a complex type definition’s content model.

Lukas Jungmann's avatar
Lukas Jungmann committed
3052
. If _{content type}_ is mixed, bind the
3053
entire content model to a general content property with the
Lukas Jungmann's avatar
Lukas Jungmann committed
3054
content-property name `"content"`. See
3055
<<Bind mixed content>> for more details.
Lukas Jungmann's avatar
Lukas Jungmann committed
3056 3057
. If (1) a particle has _{max occurs}_ >1 and
(2) its _{term}_ is a model group and (3) all the particles in the model
3058 3059
group have \{terms} that bind to different Java datatypes, bind to a
collection of element types. See complete list of constraints required
3060
to perform this optimized binding in <<Collection of Element types>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
3061 3062
. If (1) a particle has _{max occurs}_ >1 and
(2) its _{term}_ is a model group, then that particle and its descendants
3063
are mapped to one general content property that represents them. See
3064
<<Bind a repeating occurrence model group>> for details.
3065
. Process all the remaining particles (1)
Lukas Jungmann's avatar
Lukas Jungmann committed
3066 3067
whose _{term}_ are wildcard particles and (2) that did not belong to a
repeating occurrence model group bound in step 2. If there is only one
3068 3069
wildcard, bind it as specified in <<Bind wildcard schema component>>.
If there is more than one, then fallback to
3070
representing the entire content model as a single general content
3071
property. See <<General content property>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
3072
. Process all particles (1) whose _{term}_ are
3073
element declarations and (2) that do not belong to a repeating
Lukas Jungmann's avatar
Lukas Jungmann committed
3074 3075 3076 3077 3078
occurrence model group bound in step 2.
+
First, we say a particle has a label _L_ if it
refers to an element declaration whose _{name}_ is _L_. Then, for all the
possible pair of particles _P_ and _P’_ in this set, if the following
3079
constraints are not met:
Lukas Jungmann's avatar
Lukas Jungmann committed
3080 3081 3082
+
--
.. If _P_ and _P’_ have the same label, then they
3083
must refer to the same element declaration.
Lukas Jungmann's avatar
Lukas Jungmann committed
3084
.. If _P_ and _P’_ refer to the same element
3085
reference, then its closest common ancestor particle may not have
Lukas Jungmann's avatar
Lukas Jungmann committed
3086 3087 3088
sequence as its _{term}_.
--
+
3089 3090 3091 3092 3093
If either of the above constraints are
violated, it is not possible to map each element declaration to a unique
content property. Fallback to representing the entire content model as a
single general content property.

Lukas Jungmann's avatar
Lukas Jungmann committed
3094
+
3095
Otherwise, create a content property for each
Lukas Jungmann's avatar
Lukas Jungmann committed
3096
label _L_ as follows:
3097

Lukas Jungmann's avatar
Lukas Jungmann committed
3098 3099
* The content property _name_ is derived from label name _L_.
* The _base type_ will be the Java type to
3100
which the referenced element declaration maps.
Lukas Jungmann's avatar
Lukas Jungmann committed
3101
* The content property _predicate_ reflects the
3102
occurrence constraint.
Lukas Jungmann's avatar
Lukas Jungmann committed
3103 3104 3105
* The content property _collection type_
defaults to `‘list’` if there exist a particle with label _L_ that has
_{maxOccurs}_ > 1.
3106
* For the default value, if all particles
Lukas Jungmann's avatar
Lukas Jungmann committed
3107
with label _L_ has a _{term}_ with the same _{value constraint}_ default or
3108 3109 3110 3111 3112
fixed value, then this value. Otherwise none.

Below is an example demonstrating of not
meeting the uniqueness constraints of 5(a) and 5(b) specified above.

Lukas Jungmann's avatar
Lukas Jungmann committed
3113 3114 3115 3116 3117 3118 3119 3120
[source,xml,indent=4]
----
<xs:sequence>
  <xs:choice>
    <xs:element ref="ns1:bar"/> (A)
    <xs:element ref="ns2:bar"/> (B)
  </xs:choice>
  <xs:element ref="ns1:bar"/> (C)
3121
</xs:sequence>
Lukas Jungmann's avatar
Lukas Jungmann committed
3122
----
3123

Lukas Jungmann's avatar
Lukas Jungmann committed
3124
The pair _(A,B)_ violates the first clause
3125
because they both have the label “bar” but they refer to different
Lukas Jungmann's avatar
Lukas Jungmann committed
3126 3127
element declarations. The pair _(A,C)_ violates the second clause because
their nearest common ancestor particle is the outermost `<sequence>`.
3128 3129 3130 3131 3132 3133 3134 3135 3136
This model group fragment is bound to a general content property.

===== Default binding of content model “derived by extension”

If a content-property naming collision occurs
between a content-property that exists in an base complex type
definition and a content-property introduced by a “derive by extension”
derived complex type definition, the content-properties from the
colliding property on are represented by a general content property with
Lukas Jungmann's avatar
Lukas Jungmann committed
3137
the default property name `rest`.
3138

Lukas Jungmann's avatar
Lukas Jungmann committed
3139
*_Example:_* derivation by extension content model with a content-property collision.
3140 3141

Given XML Schema fragment:
Lukas Jungmann's avatar
Lukas Jungmann committed
3142 3143 3144 3145 3146 3147 3148 3149
[source,xml,indent=4]
----
<xs:complexType name="Base">
  <xs:sequence>
    <xs:element name="A" type="xs:int"/>
    <xs:element name="B" type="xs:int"/>
  </xs:sequence>
</xs:complexType>
3150

Lukas Jungmann's avatar
Lukas Jungmann committed
3151 3152 3153 3154 3155 3156 3157 3158
<xs:complexType name="Derived">
  <xs:complexContent>
    <xs:extension base="Base">
      <xs:sequence>
        <xs:element name="A" type="xs:int"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
3159
</xs:complexType>
Lukas Jungmann's avatar
Lukas Jungmann committed
3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171
----

Default binding derived Java codefootnote:[Specifying a
customization of the local element declaration A within Derived complex
type to a different property name than A would avoid the fallback
position for this case.]:
[source,java,indent=4]
----
public class Base {
    int getA() {...} void setA(int) {...}
    int getB() {...} void setB(int) {...}
}
3172

Lukas Jungmann's avatar
Lukas Jungmann committed
3173 3174 3175 3176 3177 3178 3179
public class Derived extends Base {
    /**
     * Instances of Derived.A must be placed in this general
     * content propert that represents the rest of the content
     * model. */
    List getRest() {...}
}
3180

Lukas Jungmann's avatar
Lukas Jungmann committed
3181 3182 3183
class ObjectFactory {
    // element instance factories only
    JAXBElement<Integer> createDerivedA(Integer value) {...}
3184
}
Lukas Jungmann's avatar
Lukas Jungmann committed
3185
----
3186

Lukas Jungmann's avatar
Lukas Jungmann committed
3187
===== Bind single occurrence choice group to a choice content property
3188

Lukas Jungmann's avatar
Lukas Jungmann committed
3189 3190
Setting the `choiceContentProperty` attribute
of `<jaxb:globalBindings>` as specified in
3191
<<Usage>> enables this customized binding
3192 3193 3194 3195 3196 3197 3198
option.

A non-repeating choice model group is bound
to a simple property. The simple choice content property is derived from
a choice model group as follows:

* The choice content property name is either
Lukas Jungmann's avatar
Lukas Jungmann committed
3199
the referenced model group definition _{name}_ or obtained using the
3200
algorithm specified in <<Deriving an identifier for a model group>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
3201
* The choice content property `base type` is
3202
the first common supertype of all items within the choice model group,
Lukas Jungmann's avatar
Lukas Jungmann committed
3203 3204 3205 3206 3207 3208
with `java.lang.Object` always being a common root for all Java
objects.footnote:[Note that primitive
Java types must be represented by their Java wrapper classes when base
type is used in the choice content property method signatures. Also, all
sequence descendants of the choice are treated as either a general
content property or are mapped to their own value class.]
3209 3210 3211 3212 3213 3214 3215 3216
* The predicate
* The collection type defaults to List if one
or more items in the choice model group bind to List.
* No default value.

A choice property consists of the following
methods:

Lukas Jungmann's avatar
Lukas Jungmann committed
3217 3218
* The `getChoiceID` method returns the set
value. If the property has no set value then the value `null` is
3219 3220
returned. Note that a set value of a primitive Java type is returned as
an instance of the corresponding Java wrapper class.
Lukas Jungmann's avatar
Lukas Jungmann committed
3221 3222
* The `setChoiceID` method has a single
parameter that is the type of the choice content property `base type`.
3223

Lukas Jungmann's avatar
Lukas Jungmann committed
3224 3225 3226
The `globalBindings` and property
customization attribute, `choiceContentProperty`, enables this
customized binding. The customization is specified in
3227
<<globalbindings-declaration>>.
3228 3229 3230

*_Example:_* +

Lukas Jungmann's avatar
Lukas Jungmann committed
3231 3232 3233 3234 3235 3236
XML Schema representation of a choice model group.
[source,xml,indent=4]
----
<xs:choice>
  <xs:element name="foo" type="xs:int"/>
  <xs:element name="bar" type="xs:string"/>
3237
</xs:choice>
Lukas Jungmann's avatar
Lukas Jungmann committed
3238
----
3239 3240 3241

Derived choice content property method
signatures:
Lukas Jungmann's avatar
Lukas Jungmann committed
3242 3243 3244 3245 3246
[source,java,indent=8]
----
void setFooOrBar(Object) {...}
Object getFooOrBar() {...}
----
3247

Lukas Jungmann's avatar
Lukas Jungmann committed
3248
=== Modifying Schema-Derived Code
3249 3250 3251 3252 3253 3254 3255 3256 3257 3258

There exist a number of use cases on why a
developer would find it beneficial to modify schema-derived classes.
Here are some of those use cases.

* Add functionality to schema-derived
classes. +
Since schema-derived classes are derived from a data description
language, the derived classes only represent data and have no
object-level functionality.
Lukas Jungmann's avatar
Lukas Jungmann committed
3259 3260
* Add polymorphic methods to Java class hierarchy generated
from XML Schema type definition derivation hierarchy.
3261 3262 3263 3264 3265 3266
* Initialize a JAXB property or field
representing an XML element with a default value. Regretfully, XML
Schema element defaulting is insufficient to accomplish this. Note that
XML Schema attribute defaulting is sufficient and does not require this
approach.

Lukas Jungmann's avatar
Lukas Jungmann committed
3267
The JAXB schema-derived class was
3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283
designed to be easily understandable and modifiable by a developer. For
many development environments, it is not sufficient to only run the
schema compiler once due to modification of the schema-derived classes.
Since schemas evolve over time, it is desirable to have the ability to
regenerate schema-derived classes from an updated schema while
preserving modification made by a developer. Given the complexities of
supporting this capability, a JAXB implementation is not required to
support regeneration from a schema into previously modified
schema-derived classes. External tools, such as an IDE, could assist in
supporting the sophisticated task of regeneration of a modified
schema-derived class in the future. To enable tools to support
regeneration, a JAXB implementation is required to have an option for
generating an annotation that enables a portable means for
distinguishing between developer code and generated code in a
schema-derived class.The next section describes the portable format for
distinguishing between generated and developer added/modified methods
Lukas Jungmann's avatar
Lukas Jungmann committed
3284
and/or fields in a schema-derived class.
3285 3286 3287 3288

==== Distinguish between generated and user added code

A schema compiler must have an option to
Lukas Jungmann's avatar
Lukas Jungmann committed
3289
generate the Jakarta Annotation, `@jakarta.annotation.Generated`
3290
annotation, specified in [CA], on every generated class, method and
Lukas Jungmann's avatar
Lukas Jungmann committed
3291 3292
field. If a developer does modify an `@Generated` annotated method or
field, they must denote this modification by deleting the `@Generated`
3293
annotation. If a developer adds a new method or field, it will not have
Lukas Jungmann's avatar
Lukas Jungmann committed
3294
an `@Generated` annotation on it. Based on these conventions, a JAXB
3295 3296 3297 3298 3299 3300
implementation in conjunction with an IDE or other external tool, would
be able to support regeneration of schema-derived code while preserving
developer additions/modifications to methods and fields in a
schema-derived class.

When schema compiler option to generate
Lukas Jungmann's avatar
Lukas Jungmann committed
3301
`@Generated` annotation is selected, the table describes the annotation
3302 3303 3304
to be generated.

.Annotate generated class, field and property with @Generated element-value pairs
Lukas Jungmann's avatar
Lukas Jungmann committed
3305
[cols="1,1",options="header"]
3306
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
3307 3308 3309 3310 3311
| @Generated element | @Generated element value
| value | fully qualified class name of schema compiler
| date | date of generation of schema-derived class.
Value must follow the ISO 8601 standard.
| comment | optional. Is implementation specific.
3312 3313 3314 3315 3316 3317 3318 3319 3320
|===

=== Default Binding Rule Summary

Note that this summary is non-normative and
all default binding rules specified previously in the chapter take
precedence over this summary.

* Bind the following to Java package:
Lukas Jungmann's avatar
Lukas Jungmann committed
3321 3322 3323
** XML Namespace URI
* Bind the following XML Schema components to Java value class:
** Named complex type
3324
* Bind to typesafe enum class:
Lukas Jungmann's avatar
Lukas Jungmann committed
3325 3326
** A named simple type definition with a
basetype that derives from `"xs:NCName"` and has enumeration facets.
3327
* Bind the following XML Schema components to
Lukas Jungmann's avatar
Lukas Jungmann committed
3328 3329 3330
an element instance factory that returns `jakarta.xml.bind.JAXBElement<T>`
** A global element declaration with a named type definition.
** Local element declaration with a named type
3331
definition that can be inserted into a general content list.
Lukas Jungmann's avatar
Lukas Jungmann committed
3332 3333
* Bind the following XML Schema components to a Java Element class
** A global element declaration with anonymous
3334
type definition to a Java value class.
Lukas Jungmann's avatar
Lukas Jungmann committed
3335
** Local element declaration with anonymous
3336 3337
type definition that can be inserted into a general content list.
* Bind to Java property
Lukas Jungmann's avatar
Lukas Jungmann committed
3338 3339 3340
** Attribute use
** Particle with a term that is an element reference or local element declaration.
+
3341 3342 3343
Additionally, generate an element property
for an element reference to the head element of a substitution group.
* Bind to JAXB property: +
Lukas Jungmann's avatar
Lukas Jungmann committed
3344 3345
`getOtherAttributes(): java.util.Map<QName, String>`
** Attribute Wildcard occurring directly or
3346 3347 3348
indirectly via an attribute group reference in a complex type
definition.
* Bind model group and wildcard content with
Lukas Jungmann's avatar
Lukas Jungmann committed
3349 3350 3351
a repeating occurrence and complex type definitions with `mixed`
_{content type}_ to:
** A general content property - a List
3352 3353 3354 3355 3356
content-property that holds Java instances representing element
information items and character data items. To support dynamic Xml
content that validates against xs:any processContents=”lax” or “skip”,
allow instances of org.w3c.dom.Node into the list.

Lukas Jungmann's avatar
Lukas Jungmann committed
3357
.Summarize default XSD to Java binding for Figure 5.1 and Figure 5.2
3358
[[table614]]
Lukas Jungmann's avatar
Lukas Jungmann committed
3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380
[cols="1,1",options="header"]
|===
| XML Schema | Java Representation
| Schema targetNamespace | Package
| Global Element Declaration with named type definition | ObjectFactory.elementInstanceFactory method returning JAXBElement<T>
Value must follow the ISO 8601 standard.
| Global Complex Type Definition (Named) | value class/class + ObjectFactory.typeInstanceFactory method
a| Global Simple Type Definition

* derive base of string
* has @enum facet(s) | enum type
| SimpleType facets | ConstraintPredicate
a| Attribute Uses

Local Element Declaration | Property
a| facet *@maxOccurs > 1* xsd:list | PropertyStyle List
a| **@fixed**PropertyStyle | Constant
| Global Element Declaration with anonymous type definition | value class for anonymous type + ObjectFactory.typeInstanceFactory + ObjectFactory.elementInstanceFactory method
| Element reference to SubstitutionGroup Head maxOccurs = “1” | Simple + Element property
| Element reference to SubstitutionGroup Head maxOccurs > “1” | List<JAXBElement<T>>
|===