ch07-customize_xml_schema.adoc 100 KB
Newer Older
1
//
2
// Copyright (c) 2020, 2021 Contributors to the Eclipse Foundation
3 4
//

Thibault Vallin's avatar
Thibault Vallin committed
5
== Customizing XML Schema to Java Representation Binding
6 7 8 9

The default binding of source schema
components to derived Java representation by a binding compiler
sometimes may not meet the requirements of a JAXB application. In such
Lukas Jungmann's avatar
Lukas Jungmann committed
10 11 12
cases, the default binding can be customized using a __binding declaration__.
Binding declarations are specified by a __binding language__,
the syntax and semantics of which are defined in this chapter.
13 14 15 16 17 18 19 20

All JAXB implementations are required to
provide customization support specified here unless explicitly stated as
optional.

=== Binding Language

The binding language is an XML based language
Lukas Jungmann's avatar
Lukas Jungmann committed
21
which defines constructs referred to as __binding declarations__. A binding
22 23 24
declaration can be used to customize the default binding between an XML
schema component and its Java representation.

Lukas Jungmann's avatar
Lukas Jungmann committed
25 26 27
The schema for binding declarations is defined in the namespace
`https://jakarta.ee/xml/ns/jaxb`. This specification uses the
namespace prefix `"jaxb"` to refer to the namespace of binding
28 29
declarations. For example,

Thibault Vallin's avatar
Thibault Vallin committed
30 31
[source,xml,indent=4]
----
32
<jaxb: binding declaration>
Thibault Vallin's avatar
Thibault Vallin committed
33
----
34 35 36 37 38 39 40 41 42 43

A binding compiler interprets the binding
declaration relative to the source schema and a set of default bindings
for that schema. Therefore a source schema need not contain a binding
declarations for every schema component. This makes the job of a JAXB
application developer easier.

There are two ways to associate a binding
declaration with a schema element:

Lukas Jungmann's avatar
Lukas Jungmann committed
44 45
* as part of the source schema (_inline
annotated schema_)
46
* external to the source schema in an
Lukas Jungmann's avatar
Lukas Jungmann committed
47
_external binding declaration_.
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

The syntax and semantics of the binding
declaration is the same regardless of which of the above two methods is
used for customization.

A binding declaration itself does not
identify the schema component to which it applies. A schema component
can be identified in several ways:

* explicitly - e.g. QName, XPath expressions
etc.
* implicitly - based on the context in which
the declaration occurs.

It is this separation which allows the
binding declaration syntax to be shared between inline annotated schema
and the external binding.

Thibault Vallin's avatar
Thibault Vallin committed
66
==== Extending the Binding Language
67 68 69 70 71 72 73 74 75 76 77 78 79

In recognition that there will exist a need
for additional binding declarations than those currently specified in
this specification, a formal mechanism is introduced so all JAXB
processors are able to identify _extension binding declarations_ . An
extension binding declaration is not specified in the _jaxb:_ namespace,
is implementation specific and its use will impact portability.
Therefore, binding customization that must be portable between JAXB
implementations should not rely on particular customization extensions
being available.

The namespaces containing extension binding
declarations are specified to a JAXB processor by the occurrence of the
Lukas Jungmann's avatar
Lukas Jungmann committed
80 81
global attribute `<jaxb:extensionBindingPrefixes>` within an instance of
`<xs:schema>` element. The value of this attribute is a
82 83
whitespace-separated list of namespace prefixes. The namespace bound to
each of the prefixes is designated as a customization declaration
Lukas Jungmann's avatar
Lukas Jungmann committed
84
namespace. Prefixes are resolved on the `<xs:schema>` element that
85 86
carries this attribute. It is an error if the prefix fails to resolve.
This feature is quite similar to the extension-element-prefixes
Lukas Jungmann's avatar
Lukas Jungmann committed
87
attribute in [XSLT 1.0] `http://www.w3.org/TR/xslt10/#extension`,
88 89 90 91 92 93 94 95
introduces extension namespaces for extension instructions and functions
for XSLT 1.0.

This specification does not define any
mechanism for creating or processing extension binding declarations and
does not require that implementations support any such mechanism. Such
mechanisms, if they exist, are implementation-defined.

Thibault Vallin's avatar
Thibault Vallin committed
96
==== Inline Annotated Schema
97 98

This method of customization utilizes on the
Lukas Jungmann's avatar
Lukas Jungmann committed
99 100
`<appinfo>` element specified by the XML Schema [XSD PART 1]. A binding
declaration is embedded within the `<appinfo>` element as illustrated
101 102
below.

Thibault Vallin's avatar
Thibault Vallin committed
103 104 105
[source,xml,indent=4]
----
<xs:annotation>
Lukas Jungmann's avatar
Lukas Jungmann committed
106 107 108
  <xs:appinfo>
    <binding declaration>
  </xs:appinfo>
109
</xs:annotation>
Thibault Vallin's avatar
Thibault Vallin committed
110
----
111 112 113 114

The inline annotation where the binding
declaration is used identifies the schema component.

Thibault Vallin's avatar
Thibault Vallin committed
115
==== External Binding Declaration
116 117 118 119 120

The external binding declaration format
enables customized binding without requiring modification of the source
schema. Unlike inline annotation, the remote schema component to which
the binding declaration applies must be identified explicitly. The
Lukas Jungmann's avatar
Lukas Jungmann committed
121
`<jaxb:bindings>` element enables the specification of a remote schema
122 123 124
context to associate its binding declaration(s) with. Minimally, an
external binding declaration follows the following format.

Thibault Vallin's avatar
Thibault Vallin committed
125 126 127 128 129 130
[source,xml,indent=4]
----
<jaxb:bindings [schemaLocation = "xs:anyURI"]>
    <jaxb:bindings [node = "xs:string"]>
        <binding declaration>
    <jaxb:bindings>
131
</jaxb:bindings>
Thibault Vallin's avatar
Thibault Vallin committed
132
----
133 134

The schemaLocation attribute is optional for
Lukas Jungmann's avatar
Lukas Jungmann committed
135 136
specifying `<jaxb:globalBindings>`, and the _node_ attribute is optional
for specifying `<jaxb:schemaBindings>`. The attributes _schemaLocation_
137 138 139
and _node_ are used to construct a reference to a node in a remote
schema. The binding declaration is applied to this node by the binding
compiler as if the binding declaration was embedded in the nodes
Lukas Jungmann's avatar
Lukas Jungmann committed
140
`<xs:appinfo>` element. The attribute values are interpreted as follows:
141 142 143 144 145 146 147 148

*  _schemaLocation -_ It is a URI reference
to a remote schema.
*  _node_ - It is an XPath 1.0 expression
that identifies the schema node within schemaLocation to associate
binding declarations with.

An example external binding declaration can
149
be found in <<example>>.
150

Thibault Vallin's avatar
Thibault Vallin committed
151
===== Restrictions
152 153

* The external binding element
Lukas Jungmann's avatar
Lukas Jungmann committed
154 155 156 157
`<jaxb:bindings>` is only recognized for processing by a JAXB processor
when its parent is an `<xs:appinfo>` element, it is an ancestor of
another `<jaxb:bindings>` element, or when it is root element of a
document. An XML document that has a `<jaxb:bindings>` element as its
158
root is referred to as an external binding declaration file.
Lukas Jungmann's avatar
Lukas Jungmann committed
159 160
* The top-most `<jaxb:binding>` element
within an `<xs:appinfo>` element or the root element of an external
161 162
binding file must have its _schemaLocation_ attribute set.

Thibault Vallin's avatar
Thibault Vallin committed
163
==== Version Attribute
164 165

The normative binding schema specifies a
Lukas Jungmann's avatar
Lukas Jungmann committed
166
global `version` attribute. It is used to identify the version of the
167 168 169
binding declarations. For example, a future version of this
specification may use the version attribute to specify backward
compatibility. To indicate this version of the specification, the
Lukas Jungmann's avatar
Lukas Jungmann committed
170
`version should` be `"3.0"`.
171
If any other version is specified, it must result in an invalid
172
customization as specified in <<Invalid Customizations>>.
173

Lukas Jungmann's avatar
Lukas Jungmann committed
174
The `version` attribute must be specified in
175 176 177
one of the following ways:

* If customizations are specified in inline
Lukas Jungmann's avatar
Lukas Jungmann committed
178
annotations, the `version` attribute must be specified in `<xs:schema>`
179
element of the source schema. For example,
Lukas Jungmann's avatar
Lukas Jungmann committed
180
+
Thibault Vallin's avatar
Thibault Vallin committed
181 182
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
183
 <xs:schema jaxb:version="3.0">
Thibault Vallin's avatar
Thibault Vallin committed
184
----
185 186

* If customizations are specified in an
Lukas Jungmann's avatar
Lukas Jungmann committed
187 188 189
external binding file, then the `jaxb:version` attribute must be
specified in the root element `<jaxb:bindings>` in the external binding
file. Alternately, a local `version` attribute may be used. Thus the
190
version can be specified either as
Lukas Jungmann's avatar
Lukas Jungmann committed
191
+
Thibault Vallin's avatar
Thibault Vallin committed
192 193
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
194
 <jaxb:bindings version="3.0" ... />
Thibault Vallin's avatar
Thibault Vallin committed
195
----
196
or
Lukas Jungmann's avatar
Lukas Jungmann committed
197
+
Thibault Vallin's avatar
Thibault Vallin committed
198 199
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
200
 <jaxb:bindings jaxb:version="3.0" ... />
Thibault Vallin's avatar
Thibault Vallin committed
201
----
Lukas Jungmann's avatar
Lukas Jungmann committed
202 203 204
+
Specification of both `version` and
`<jaxb:version>` must result in an invalid customization as specified in
205
<<Invalid Customizations>>.
206

Thibault Vallin's avatar
Thibault Vallin committed
207
==== Invalid Customizations
208

Lukas Jungmann's avatar
Lukas Jungmann committed
209 210
A _non conforming_ binding declaration is a
binding declaration in the `jaxb` namespace but does not conform to this
211
specification. A non conforming binding declaration results in a
Lukas Jungmann's avatar
Lukas Jungmann committed
212
_customization error_. The binding compiler must report the customization
213
error. The exact error is not specified here. For additional
214
requirements see <<Compatibility>>.
215 216 217 218 219 220 221 222 223 224 225

The rest of this chapter assumes that non
conforming binding declarations are processed as indicated above and
their semantics are not explicitly specified in the descriptions of
individual binding declarations.

=== Notation

The source and binding-schema fragments shown
in this chapter are meant to be illustrative rather than normative. The
normative syntax for the binding language is specified in
226
<<Normative Binding Schema Syntax>> in
227 228 229
addition to the other normative text within this chapter. All examples
are non-normative.

Lukas Jungmann's avatar
Lukas Jungmann committed
230 231 232 233 234
* Metavariables are in _italics_.
* Optional attributes are enclosed in `[ square="bracket" ]`.
* Optional elements are enclosed in `[ <elementA> ... </elementA> ]`.
* Other symbols: `,` denotes a sequence,
`|` denotes a choice, `+` denotes one or more, `*` denotes
235
zero or more.
Lukas Jungmann's avatar
Lukas Jungmann committed
236
* The prefix `xs:` is used to refer to schema
237 238
components in W3C XML Schema namespace.
* In examples, the binding declarations as
Lukas Jungmann's avatar
Lukas Jungmann committed
239 240
well as the customized code are shown in bold like this:
*<appinfo> <annotation>* or *getAddress()*.
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261

=== Naming Conventions

The naming convention for XML names in the
binding language schema are:

* The first letter of the first word in a
multi word name is in lower case.
* The first letter of every word except the
first one is in upper case.

For example, the XML name for the Java
property basetype is baseType.

=== Customization Overview

A binding declaration customizes the default
binding of a schema element to a Java representation. The binding
declaration defines one or more customization values each of which
customizes a part of Java representation.

Thibault Vallin's avatar
Thibault Vallin committed
262
==== Scope
263 264

When a customization value is defined in a
Lukas Jungmann's avatar
Lukas Jungmann committed
265
binding declaration, it is associated with a _scope_. A scope of a
266 267
customization value is the set of schema elements to which it applies.
If a customization value applies to a schema element, then the schema
Lukas Jungmann's avatar
Lukas Jungmann committed
268
element is said to be _covered_ by the scope of the customization value.
269 270
The scopes are:

Thibault Vallin's avatar
Thibault Vallin committed
271
* *global scope*: A customization value defined
Lukas Jungmann's avatar
Lukas Jungmann committed
272
in `<globalBindings>` has _global scope_. A global scope covers all the
273 274
schema elements in the source schema and (recursively) any schemas that
are included or imported by the source schema.
Thibault Vallin's avatar
Thibault Vallin committed
275
* *schema scope*: A customization value defined
Lukas Jungmann's avatar
Lukas Jungmann committed
276
in `<schemaBindings>` has _schema scope_. A schema scope covers all the
277
schema elements in the target namespace of a schema.
Thibault Vallin's avatar
Thibault Vallin committed
278
* *definition scope*: A customization value in
279
binding declarations of a type definition or global declaration has
Lukas Jungmann's avatar
Lukas Jungmann committed
280
_definition scope_. A definition scope covers all schema elements that
281 282 283
reference the type definition or the global declaration. This is more
precisely specified in the context of binding declarations later on in
this chapter.
Thibault Vallin's avatar
Thibault Vallin committed
284
* *component scope*: A customization value in a
Lukas Jungmann's avatar
Lukas Jungmann committed
285
binding declaration has _component scope_ if the customization value
286 287 288
applies only to the schema element that was annotated with the binding
declaration.

Lukas Jungmann's avatar
Lukas Jungmann committed
289
.Scoping Inheritance and Overriding For Binding Declarations
290
image:images/xmlb-18.svg[image]
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316

The different scopes form a taxonomy. The
taxonomy defines both the inheritance and overriding semantics of
customization values. A customization value defined in one scope is
inherited for use in a binding declaration covered by another scope as
shown by the following inheritance hierarchy:

* a schema element in schema scope inherits a
customization value defined in global scope.
* a schema element in definition scope
inherits a customization value defined in schema or global scope.
* a schema element in component scope
inherits a customization value defined in definition, schema or global
scope.

Likewise, a customization value defined in
one scope can override a customization value inherited from another
scope as shown below:

* value in schema scope overrides a value
inherited from global scope.
* value in definition scope overrides a value
inherited from schema scope or global scope.
* value in component scope overrides a value
inherited from definition, schema or global scope.

Thibault Vallin's avatar
Thibault Vallin committed
317
==== XML Schema Parsing
318 319 320 321 322 323 324 325

Chapter 5 specified the bindings using the
abstract schema model. Customization, on the other hand, is specified in
terms of XML syntax not abstract schema model. The XML Schema
specification [XSD PART 1] specifies the parsing of schema elements into
abstract schema components. This parsing is assumed for parsing of
annotation elements specified here. In some cases, [XSD PART 1] is
ambiguous with respect to the specification of annotation elements.
326
<<Annotation Restrictions>> outlines how
327 328
these are addressed.

Lukas Jungmann's avatar
Lukas Jungmann committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
[NOTE]
.Design Note
====
The reason for specifying using the XML syntax instead of
abstract schema model is as follows. For most part,
there is a one-to-one mapping between schema elements
and the abstract schema components to which they are bound.
However, there are certain exceptions: local attributes and particles.
A local attribute is mapped to two schema components:
{attribute declaration} and {attribute use}. But the XML parsing
process associates the annotation with the {attribute declaration}
not the {attribute use}. This is tricky and not obvious.
Hence for ease of understanding, a choice was made to specify
customization at the surface syntax level instead.

====

346

Lukas Jungmann's avatar
Lukas Jungmann committed
347
=== `<globalBindings>` Declaration
348

Lukas Jungmann's avatar
Lukas Jungmann committed
349 350
The customization values in `"<globalBindings>"`
binding declaration have global scope. This binding
351 352
declaration is therefore useful for customizing at a global level.

Thibault Vallin's avatar
Thibault Vallin committed
353 354 355 356 357 358 359 360 361 362 363 364 365
==== Usage

[source,xml,indent=4]
----
<globalBindings
    [ collectionType = "collectionType" ]
    [ fixedAttributeAsConstantProperty = "true" | "false" | "1" | "0" ]
    [ generateIsSetMethod = "true" | "false" | "1" | "0" ]
    [ enableFailFastCheck = "true" | "false" | "1" | "0" ]
    [ choiceContentProperty = "true" | "false" | "1" | "0" ]
    [ underscoreBinding = "asWordSeparator" | "asCharInWord" ]
    [ typesafeEnumBase = "typesafeEnumBase" ]
    [ typesafeEnumMemberName = "skipGeneration" |
Lukas Jungmann's avatar
Lukas Jungmann committed
366
                               "generateName" | "generateError" ]
Thibault Vallin's avatar
Thibault Vallin committed
367 368 369 370 371 372 373
    [ typesafeEnumMaxMembers = xxxx]
    [ enableJavaNamingConventions = "true" | "false" | "1" | "0" ]
    [ generateElementClass = "false" | "true" | "0" | "1" ]
    [ generateElementProperty = "false" | "true" | "0" | "1" ]
    [ generateValueClass = "true" | "true" | "0" | "1" ]
    [ optionalProperty = "wrapper" | "primitive" | "isSet" ]
    [ mapSimpleTypeDef = "true" | "false" | "1" | "0" ]
Lukas Jungmann's avatar
Lukas Jungmann committed
374
    [ localScoping = "nested" | "toplevel" ] >
Thibault Vallin's avatar
Thibault Vallin committed
375 376
    [ <javaType> ... </javaType> ]*
    [ <serializable uid=xxxx/> ]*
377
</globalBindings>
Thibault Vallin's avatar
Thibault Vallin committed
378
----
379 380 381 382

The following customization values are
defined in global scope:

Lukas Jungmann's avatar
Lukas Jungmann committed
383 384 385 386 387
* `_collectionType_` if specified, must be
either `"indexed"` or any fully qualified class name that implements
`_java.util.List_`. The default value is to any fully qualified class name
that implements `_java.util.List_`.
* `_fixedAttributeAsConstantProperty_` if
388
specified , defines the customization value
Lukas Jungmann's avatar
Lukas Jungmann committed
389 390 391 392 393
`_fixedAttributeAsConstantProperty_`. The value must be one of `"true"`,
`"false"`, `"1"` or `"0"`. The default value is `"false"`.
* `_generateIsSetMethod_` if specified,
defines the customization value of `_generateIsSetMethod_`. The value must
be one of `"true"`, `"false"`, `"1"` or `"0"`. The default value is `"false"`.
394
Consider customizing using the newly introduced _optionalProperty_
Lukas Jungmann's avatar
Lukas Jungmann committed
395 396 397 398 399
before using this JAXB customization.
* `_enableFailFastCheck_` if specified,
defines the customization value `_enableFailFastCheck`_. The value must be
one of `"true"`, `"false"`, `"1"` or `"0"`. If enableFailFastCheck is `"true"` or
`"1"` and the JAXB implementation supports this optional checking, type
400
constraint checking when setting a property is performed as described in
401
<<Properties>>. The default value is `"false"`.
Lukas Jungmann's avatar
Lukas Jungmann committed
402 403 404 405 406 407 408 409 410 411 412 413 414 415
* `_choiceContentProperty_` if
specified, defines the customization value `_choiceContentProperty_`. The
value must be one of `"true"`, `"false"`, `"1"` or `"0"`.
The default value is `"false"`.
* `_underscoreBinding_` if specified, defines
the customization value `_underscoreBinding_`. The value must be one of
`"asWordSeparator"` or `"asCharInWord"`. The default value is
`"asWordSeparator"`.
* `_enableJavaNamingConventions_` if
specified, defines the customization value `_enableJavaNamingConventions_`.
The value must be one of `"true"`, `"false"`, `"1"` or `"0"`.
The default value is `"true"`.
* `_typesafeEnumBase_` if specified, defines
the customization value `_typesafeEnumBase_`. The value must be a list of
416 417
QNames, each of which must resolve to a simple type definition. Only
simple type definitions with an enumeration facet and a restriction base
Lukas Jungmann's avatar
Lukas Jungmann committed
418 419
type listed in `_typesafeEnumBase_` or derived from a type listed in
`_typesafeEnumBase_` is bound to a `_typesafeEnumClass_` by default as
420
specified in <<Enum Type>>. The default
Lukas Jungmann's avatar
Lukas Jungmann committed
421 422 423
value of `_typesafeEnumBase_` is `"xs:string"`.
+
The `_typesafeEnumBase_` cannot contain the
424 425
following simple types and therefore a JAXB implementation is not
required to support the binding of the these types to typesafe
Lukas Jungmann's avatar
Lukas Jungmann committed
426 427 428 429
enumeration class: `_"xs:QName"_`, `_"xs:NOTATIION"_`, `_"xs:base64Binary"_`,
`_"xs:hexBinary"_`, `_"xs:date"_`, `_"xs:time"_`, `_"xs:dateTime"_`, `_"xs:duration"_`,
`_"xs:gDay"_`, `_"xs:gMonth"_`, `_"xs:gYear"_`, `_"xs:gMonthDay"_`, `_"xs:gYearMonth"_`,
`_"xs:IDREF"_`, `_"xs:ID"_`. If any of them are specified, it must result in an
430 431
invalid customization as specified in <<Invalid Customizations>>.
JAXB implementation must be capable of binding
Lukas Jungmann's avatar
Lukas Jungmann committed
432
any other simple type listed in `_typesafeEnumBase_` to a typesafe
433 434
enumeration class.

Lukas Jungmann's avatar
Lukas Jungmann committed
435 436 437
* `_typesafeEnumMemberName_` if specified,
defines the customization value `_typesafeEnumMemberName_`. The value must
be one of `skipGeneration`, `generateError` or `generateName`. The
438
default value is `skipGeneration`. See <<typesafeenummembername>> for details.
Lukas Jungmann's avatar
Lukas Jungmann committed
439
* `_typesafeEnumMaxMembers_` if specified,
440 441
defines the maximum number of enum facets that a simple type definition
can have and be consider to binding to an enum type by default. The
Lukas Jungmann's avatar
Lukas Jungmann committed
442 443
attributes type is `xs:int` and its default value is `256`.
* `_generateElementClass_` if specified as
444
true, a schema-derived Element class, as specified in
445
<<Java Element Class>>, is generated for
446
each element declaration that has an element factory method generated
Lukas Jungmann's avatar
Lukas Jungmann committed
447 448
for it. Its default value is `"false"`.
* `_generateElementProperty_` if specified as
449
true, controls the generation of JAXBElement property. The value must be
Lukas Jungmann's avatar
Lukas Jungmann committed
450
one of `"true"`, `"false"`, `"1"` or `"0"`. The default is absence of the
451
value.
Lukas Jungmann's avatar
Lukas Jungmann committed
452
* `_generateValueClass_` if specified as true, a
453
schema-derived Java value class is generated for each complex type
454 455
definiton.Value class is specified in <<Value Class>>.
If generateValueClass is specified as false, a
456
schema-derived interface and implementation class is generated for each
457 458 459
complex type definition as specified in <<Java Content Interface>>.
The attributes default value is true. See
examples of this binding in <<generateElementClass and generateValueClass>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
460
* zero or more `_javaType_` binding
461
declarations. Each binding declaration must be specified as described in
462
<<javatype-declaration>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
463 464
* zero or one serializable binding declaration.
* `_optionalProperty_` controls how a JAXB property with a
465 466 467 468 469 470 471 472 473
primitive base type that represents an optional non-nillable
element/attribute is bound. If the attribute has the value "wrapper",
then the base type of the JAXB property is the wrapper class for the
primitive type. A user can indicate that this optional property is not
set by calling the setter with null value. If the attributes value is
"primitive", it binds as it did in JAXB 1.0. If the attributes value is
isSet, it binds the optional property using the primitive base type
and also the isSet/unset methods are generated for the optional
property. The attributes default value is wrapper.
Lukas Jungmann's avatar
Lukas Jungmann committed
474
* `_mapSimpleTypeDef_` controls whether a JAXB
475
mapped class should be generated for each simple type definition as
476 477
specified in <<Bind to a JAXB mapped class>>.
This attributes default value is `"false"`. This customization
478
eases preserving simple type substituting precisely as described in
479
<<Type Substitution of a Simple Type Definition>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
480
* `_localScoping_` attribute can have the
481 482 483 484
value of either _nested_ or _toplevel_ . This attribute describes the
JAXB binding of nested XML schema component to either a _nested_
schema-derived JAXB class or a _toplevel_ schema-derived JAXB class. To
avoid naming collisions between nested components, the default value for
Lukas Jungmann's avatar
Lukas Jungmann committed
485 486
this attribute is _nested_. A developer can customize _localScoping_ to
_toplevel_ when schema components nest too deeply or an application
487 488 489 490 491 492
would prefer to not work with nested classes.

The semantics of the above customization
values, if not specified above, are specified when they are actually
used in the binding declarations.

Lukas Jungmann's avatar
Lukas Jungmann committed
493 494 495 496
For inline annotation, a `<globalBindings>`
is valid only in the annotation element of the `<schema>` element. There
must only be a single instance of a `<globalBindings>` declaration in
the annotation element of the `<schema>` element.
497

Thibault Vallin's avatar
Thibault Vallin committed
498
==== Customized Name Mapping
499 500 501

A customization value can be used to specify
a name for a Java object (e.g. class name, package name etc.). In this
Lukas Jungmann's avatar
Lukas Jungmann committed
502
case, a customization value is referred to as a _customization name_.
503 504 505 506 507 508 509 510 511 512

A customization name is always a legal Java
identifier (this is formally specified in each binding declaration where
the name is specified). Since customization deals with customization of
a Java representation to which an XML schema element is bound, requiring
a customization name to be a legal Java identifier rather than an XML
name is considered more meaningful.

A customization name may or may not conform
to the recommended Java language naming conventions. [JLS - Java
513 514
Language Specification, Second Edition, Section 6.8, "Naming
Conventions"]. The customization value _enableJavaNamingConventions_
515 516 517
determines if a customization name is mapped to a Java identifier that
follows Java language naming conventions or not.

Lukas Jungmann's avatar
Lukas Jungmann committed
518 519
If _enableJavaNamingConventions_ is defined and
the value is `"true"` or `"1"`, then the customization name (except for
520 521 522
constant name) specified in the section from where this section is
referenced must be mapped to Java identifier which follows the Java
language naming conventions as specified in
523
<<Conforming Java Identifier Algorithm>>;
524 525
otherwise the customized name must be used as is.

Thibault Vallin's avatar
Thibault Vallin committed
526
==== Underscore Handling
527

Thibault Vallin's avatar
Thibault Vallin committed
528
The *[jaxb:globalBindings]* attribute
529 530 531 532 533
customization _underscoreBinding_ allows for the preservation of
underscore(s) occurring in an XML name when deriving a a Java identifier
from it.

The default value for _@underscoreBinding_ is
Lukas Jungmann's avatar
Lukas Jungmann committed
534
`"asWordSeparator"` and categorizes underscore (_) as a punctuation
535
mark in the XML name to Java identifier algorithm specified in Appendix
536 537
<<The Name to Identifier Mapping Algorithm>>.
The resulting algorithm transforms one or more consecutive
538 539
underscores in an XML name to camel case separated words in the derived
Java class and method names. Examples of this mapping are in
540
<<jcmcn>>.
541

Lukas Jungmann's avatar
Lukas Jungmann committed
542 543
When  _@underscoreBinding_ is
`"asCharInWord"`, underscore (_) is considered a special letter within
544 545
a word. The result is that all underscore characters from the original
XML name are preserved in the derived Java identifier. Example of this
546
mapping are in <<asCharInWord>>.
547

Thibault Vallin's avatar
Thibault Vallin committed
548
==== generateElementClass and generateValueClass
549 550 551 552 553

The following code examples illustrate
default binding to value class and customization to bind to
interface/implementation classes.

Lukas Jungmann's avatar
Lukas Jungmann committed
554
*_Example:_* Default Binding to a value class. +
555 556 557

Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
558 559
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
560 561
<xs:complexType name="USAddress">
  <xs:attribute name="City" type="xs:string"/>
562
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
563
----
Lukas Jungmann's avatar
Lukas Jungmann committed
564 565

Default Value Class:
566

Thibault Vallin's avatar
Thibault Vallin committed
567 568 569 570 571 572 573
[source,java,indent=4]
----
public class USAddress {
    public USAddress() {...}
    public String getCity() {...}
    public void setCity(String value) {...}
    ...
574
}
Thibault Vallin's avatar
Thibault Vallin committed
575
----
Lukas Jungmann's avatar
Lukas Jungmann committed
576 577
Customization `<jaxb:globalBinding generateValueClass="false">`
generates following interface instead of
578 579
default value class:

Lukas Jungmann's avatar
Lukas Jungmann committed
580
*_Example:_* Customized binding to an interface. +
581

Thibault Vallin's avatar
Thibault Vallin committed
582 583 584 585 586
[source,java,indent=4]
----
public interface USAddress {
    String getCity();
    void setCity(String value);
587
}
Thibault Vallin's avatar
Thibault Vallin committed
588
----
589

Lukas Jungmann's avatar
Lukas Jungmann committed
590
*_Example:_* Generation of an Element Class. +
591 592 593

Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
594 595
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
596
<xs:element name="Address" type="USAddress"/>
Thibault Vallin's avatar
Thibault Vallin committed
597 598 599
----
[source,java,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
600
// Default Java binding of global element to element instance factory
Thibault Vallin's avatar
Thibault Vallin committed
601 602
public ObjectFactory {
    JAXBElement<USAddress> createAddress(USAddress value);
603
}
Thibault Vallin's avatar
Thibault Vallin committed
604
----
Lukas Jungmann's avatar
Lukas Jungmann committed
605 606 607

`<jaxb:globalBinding generateElementClass="true"/>` results in generation
of following Element class:
608

Thibault Vallin's avatar
Thibault Vallin committed
609 610 611
[source,java,indent=4]
----
public class Address extends JAXBElement<USAddress> {
612
}
Thibault Vallin's avatar
Thibault Vallin committed
613
----
614

Thibault Vallin's avatar
Thibault Vallin committed
615
==== @typesafeEnumMemberName
616

Lukas Jungmann's avatar
Lukas Jungmann committed
617
If there is a collision among the generated
Thibault Vallin's avatar
Thibault Vallin committed
618
constant fields *name* or if it is not possible to generate a legal Java
619 620
identifier for one or more of the generated constant field names, then
the binding is determined based on the value of @
Lukas Jungmann's avatar
Lukas Jungmann committed
621
`_typesafeEnumMemberName_` of element *[jaxb:globalBindings]*.
622

Lukas Jungmann's avatar
Lukas Jungmann committed
623 624 625
* _skipGeneration_ +
An enum type is not generated. This is the default behavior if
`_typesafeEnumMemberName_` has not been specified. A binding compiler may
626 627
report a warning on why the simple type definition was not bound to an
enum type.
Lukas Jungmann's avatar
Lukas Jungmann committed
628 629
* _generateName_ +
The constant fields *name* is `__"VALUE____<N>"_` where `_<N>_` is 1
630 631
for the first enumeration value and increments by 1 to represent each
value within the XML enumeration.
Lukas Jungmann's avatar
Lukas Jungmann committed
632 633
* _generateError_ +
An error must be reported.
634

Thibault Vallin's avatar
Thibault Vallin committed
635
==== <serializable> Declaration
636 637

When the serializable customization is
Lukas Jungmann's avatar
Lukas Jungmann committed
638 639 640
specified, all schema-derived classes implement `java.io.Serializable`.
Each class is generated with a `serialVersionUID` field set to the value
specified by _@uid_.
641

Thibault Vallin's avatar
Thibault Vallin committed
642 643 644 645
[source,java,indent=4]
----
private static final long serialVersionUID = <value of @uid>;
----
646 647
The JAXB user is required to identify when
schema-derived classes do not follow
Lukas Jungmann's avatar
Lukas Jungmann committed
648
_https://docs.oracle.com/javase/8/docs/platform/serialization/spec/version.html#a6519§[Java
649
serialization class evolution rules]_ and change the generated
Lukas Jungmann's avatar
Lukas Jungmann committed
650
`serialVersionUID` field by changing the *[serializable]* elements
651 652
attribute _@uid_ value.

Thibault Vallin's avatar
Thibault Vallin committed
653
==== @generateElementProperty
654 655 656 657 658 659

Some schemas use both minOccurs="0" on
element as well as nillable="true", causing the generation of
JAXBElement. This customization lets you control this behavior. This
attribute may take two values:

Lukas Jungmann's avatar
Lukas Jungmann committed
660 661 662
* _true_: +
Always generate properties to use JAXBElement, unless overriden by
`<jaxb:property generateElementProperty="false"/>` on individual
663
property.
Lukas Jungmann's avatar
Lukas Jungmann committed
664 665 666 667 668
* _false_: +
When generating properties from `<element nillable=true minOccurs=0/>`,
generate a property not to use JAXBElement, as if the
element declaration were just `<element nillable=true />`, unless
overriden by `<jaxb:property generateElementProperty="true"/>` on
669 670 671 672
individual property. It is an error to specify this customization, when
the property is required to be JAXBElement (such as when a property
contains multiple elements with different names but of the same type.)

Lukas Jungmann's avatar
Lukas Jungmann committed
673
===  `<schemaBindings>` Declaration
674 675

The customization values in
Lukas Jungmann's avatar
Lukas Jungmann committed
676
`<schemaBindings>` binding declaration have schema scope. This binding
677 678
declaration is therefore useful for customizing at a schema level.

Thibault Vallin's avatar
Thibault Vallin committed
679
==== Usage
680

Thibault Vallin's avatar
Thibault Vallin committed
681 682
[source,xml,indent=4]
----
683
<schemaBindings [ map="boolean" ] >
Thibault Vallin's avatar
Thibault Vallin committed
684 685
    [ <package> package </package> ]
    [ <nameXmlTransform> ... </nameXmlTransform>]*
686 687
</schemaBindings>

Thibault Vallin's avatar
Thibault Vallin committed
688 689
<package [ name = "packageName" ]
    [ <javadoc> ... </javadoc> ]
690 691 692
</package>

<nameXmlTransform>
Lukas Jungmann's avatar
Lukas Jungmann committed
693 694 695 696 697 698 699 700
    [ <typeName           [ suffix="suffix" ]
                          [ prefix="prefix" ] /> ]
    [ <elementName        [ suffix="suffix" ]
                          [ prefix="prefix" ] /> ]
    [ <modelGroupName     [ suffix="suffix" ]
                          [ prefix="prefix" ] /> ]
    [ <anonymousTypeName  [ suffix="suffix" ]
                          [ prefix="prefix" ] /> ]
701
</nameXmlTransform>
Thibault Vallin's avatar
Thibault Vallin committed
702
----
703

Lukas Jungmann's avatar
Lukas Jungmann committed
704 705 706
For readability, the `<nameXmlTransform>` and
`<package>` elements are shown separately. However, they are local
elements within the `<schemaBindings>` element.
707 708 709 710

The following customizations are defined in
the schema scope:

Lukas Jungmann's avatar
Lukas Jungmann committed
711 712 713 714
* _map_ if specified, prevents the classes
from being generated from this schema. When the value is `"0"` or `"false"`,
then no class/interface/enum will be generated from this package. _map_
defaults to `"true"`.
715 716 717 718 719

The semantics of the customization value, if
not specified above, are specified when they are actually used in the
binding declarations.

Lukas Jungmann's avatar
Lukas Jungmann committed
720 721 722 723
For inline annotation, a `<schemaBindings>`
is valid only in the annotation element of the `<schema>` element. There
must only be a single instance of a `<schemaBindings>` declaration in
the annotation element of the `<schema>` element.
724 725 726

If one source schema includes (via the
include mechanism specified by XSD PART 1) a second source schema, then
Lukas Jungmann's avatar
Lukas Jungmann committed
727
the `<schemaBindings>` declaration must be declared in the first
728
including source schema. It should be noted that there is no such
Lukas Jungmann's avatar
Lukas Jungmann committed
729 730
restriction on `<schemaBindings>` declarations when one source schema
imports another schema since the scope of `<schemaBindings>` binding
731 732
declaration is schema scope.

Lukas Jungmann's avatar
Lukas Jungmann committed
733
===== package
734 735 736

Usage

Lukas Jungmann's avatar
Lukas Jungmann committed
737 738
* `_name_` if specified, defines the
customization value `_packageName_`. `_packageName_` must be a valid Java
739
package name.
Lukas Jungmann's avatar
Lukas Jungmann committed
740 741
* `_<javadoc>_` if specified, customizes the
package level Javadoc. `_<javadoc>_` must be specified as described in
742 743 744
<<javadoc-declaration>>. The Javadoc
must be generated as specified in <<Javadoc Customization>>.
The Javadoc section customized is the `package
Lukas Jungmann's avatar
Lukas Jungmann committed
745 746 747 748 749 750 751 752 753 754 755 756 757 758 759
section`.

[NOTE]
.Design Note
====
The word package has been prefixed to `_name_` used in the binding declaration.
This is because the attribute or element tag names name is not unique by itself
across all scopes. For e.g., name attribute can be specified
in the <property> declaration. The intent is to disambiguate by reference such as `"packageName"`.

====

The semantics of the `_packageName_` is
specified in the context where it is used. If neither `_packageName_` nor
the `_<javadoc>_` element is specified, then the binding declaration has
760 761
no effect.

Lukas Jungmann's avatar
Lukas Jungmann committed
762
*_Example:_* Customizing Package Name +
763

Thibault Vallin's avatar
Thibault Vallin committed
764 765
[source,xml,indent=4]
----
766
<jaxb:schemaBindings>
Thibault Vallin's avatar
Thibault Vallin committed
767
    <jaxb:package name = "org.example.po" />
768
</jaxb:schemaBindings>
Thibault Vallin's avatar
Thibault Vallin committed
769
----
770

Lukas Jungmann's avatar
Lukas Jungmann committed
771
specifies `"org.example.po"` as the package
772 773
to be associated with the schema.

Thibault Vallin's avatar
Thibault Vallin committed
774
=====  nameXmlTransform
775 776 777 778 779

The use case for this declaration is the UDDI
Version 2.0 schema. The UDDI Version 2.0 schema contains many
declarations of the following nature:

Thibault Vallin's avatar
Thibault Vallin committed
780 781 782 783
[source,xml,indent=4]
----
<xs:element name="bindingTemplate" type="uddi:bindingTemplate"/>
----
784 785 786 787 788 789

The above declaration results in a name
collision since both the element and type names are the same - although
in different XML Schema symbol spaces. Normally, collisions are supposed
to be resolved using customization. However, since there are many
collisions for the UDDI V2.0 schema, this is not a convenient solution.
Lukas Jungmann's avatar
Lukas Jungmann committed
790
Hence the binding declaration `nameXmlTransform` is being provided to
791 792
automate name collision resolution.

Lukas Jungmann's avatar
Lukas Jungmann committed
793 794
The `nameXmlTransform` allows a `_suffix_` and
a `_prefix_` to be specified on a per symbol space basis. The following
795 796
symbol spaces are supported:

Lukas Jungmann's avatar
Lukas Jungmann committed
797
*  `<typeName>` for the symbol space type
798
definitions
Lukas Jungmann's avatar
Lukas Jungmann committed
799
*  `<elementName>` for the symbol space
800
element definitions
Lukas Jungmann's avatar
Lukas Jungmann committed
801
*  `<modelGroupName>` for the symbol space
802
model group definitions.
Lukas Jungmann's avatar
Lukas Jungmann committed
803
*  `<anonymousTypeName>` for customizing Java
Thibault Vallin's avatar
Thibault Vallin committed
804 805 806 807
value class to which an anonymous type is bound.footnote:[XML schema does not
associate anonymous types with a specific symbol space. However,
_nameXmlTransform_ is used since it provides a convenient way to
customize the value class to which an anonymous type is bound.]
808

Lukas Jungmann's avatar
Lukas Jungmann committed
809 810
If `_suffix_` is specified, it must be appended
to all the default XML names in the symbol space. The `_prefix_` if
811 812 813 814 815 816
specified, must be prepended to the default XML name. Furthermore, this
XML name transformation must be done after the XML name to Java
Identifier algorithm is applied to map the XML name to a Java
identifier. The XML name transformation must not be performed on
customization names.

Lukas Jungmann's avatar
Lukas Jungmann committed
817
By using a different `_prefix_` and/or `_suffix_`
818 819 820
for each symbol space, identical names in different symbol spaces can be
transformed into non-colliding XML names.

Lukas Jungmann's avatar
Lukas Jungmann committed
821
`*anonymousTypeName*`
822

Lukas Jungmann's avatar
Lukas Jungmann committed
823
The `<anonymousTypeName>` declaration can be
824
used to customize the suffix and prefix for the Java value class. If
Lukas Jungmann's avatar
Lukas Jungmann committed
825
`_prefix_` is specified, then it must be prepended to the Java value class
826 827 828
name for the anonymous type. If suffix is specified, it must be
appended.

Lukas Jungmann's avatar
Lukas Jungmann committed
829
=== `<class>` Declaration
830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845

This binding declaration can be used to
customize the binding of a schema component to an element class, value
class or interface/implementation class. The customizations can be used
to specify:

* a name for the derived Java class.
* an alternative implementation of
interface/implementation binding.

Specification of an alternate implementation
for an interface allows implementations generated by a tool (e.g. based
on UML) to be used in place of the default implementation generated by a
JAXB provider.

The implementation class may have a
846
dependency upon the runtime of the binding framework. The
847 848 849 850
implementation class may not be portable across JAXB provider
implementations. Hence one JAXB provider implementation is not required
to support the implementation class from another JAXB provider.

Thibault Vallin's avatar
Thibault Vallin committed
851
==== Usage
852

Thibault Vallin's avatar
Thibault Vallin committed
853 854 855
[source,xml,indent=4]
----
<class [ name = "className" ]
Lukas Jungmann's avatar
Lukas Jungmann committed
856 857 858
       [ implClass = "implClass" ]
       [ ref = "className" ] >
       [ <javadoc> ... </javadoc> ]
859
</class>
Thibault Vallin's avatar
Thibault Vallin committed
860
----
861

Lukas Jungmann's avatar
Lukas Jungmann committed
862
* `_className_` is the name of the derived
863 864
value class, if specified. It must be a legal Java class name and must
not contain a package prefix. The package prefix is inherited from the
Lukas Jungmann's avatar
Lukas Jungmann committed
865 866 867
current value of _package_.
* `_implClass_` if specified, is the name of
the implementation class for `_className_` and must include the complete
868
package name. Note that this customization only impacts the return value
Lukas Jungmann's avatar
Lukas Jungmann committed
869 870 871
for `className` s factory method. This customization is ignored when
`new` is used to create instances of a schema-derived Value class.
* `_ref_` if specified, is the name of the
872 873 874
value class that is provided outside the schema compiler. This
customization causes a schema compiler to refer to this external class,
as opposed to generate a definition. It must include the complete
Lukas Jungmann's avatar
Lukas Jungmann committed
875 876 877 878
package name. This attribute is mutually exclusive with the `_className_`
attribute and the `_implClass_` attribute.
* `_<javadoc>_` element, if specified
customizes the Javadoc for the derived value class. `_<javadoc>_` must be
879
specified as described in <<javadoc-declaration>>.
880

Thibault Vallin's avatar
Thibault Vallin committed
881
==== Customization Overrides
882 883 884 885 886

When binding a schema elements Java
representation to a value class or a Java Element class, the following
customization values override the defaults specified in Chapter 5. It is
specified in a common section here and referenced from
887
<<Customizable Schema Elements>>.
888

Lukas Jungmann's avatar
Lukas Jungmann committed
889
* *name*: The name is `_className_` if specified.
Thibault Vallin's avatar
Thibault Vallin committed
890
* *package name:* The name of the package is
Lukas Jungmann's avatar
Lukas Jungmann committed
891 892 893 894 895 896 897
`_packageName_` inherited from a scope that covers this schema element.
+
[NOTE]
.Note
====
The `_packageName_` is only set in the `<package>` declaration. The
scope of `_packageName_` is schema scope and is thus inherited by all
898
schema elements within the schema.
Lukas Jungmann's avatar
Lukas Jungmann committed
899 900 901

====

Thibault Vallin's avatar
Thibault Vallin committed
902
* *javadoc:* The Javadoc must be generated as
903 904
specified in section <<Javadoc Customization>>.
The Javadoc section customized is the `class/interface
Lukas Jungmann's avatar
Lukas Jungmann committed
905
section`.
906

Thibault Vallin's avatar
Thibault Vallin committed
907
==== Customizable Schema Elements
908

Thibault Vallin's avatar
Thibault Vallin committed
909
===== Complex Type Definition
910

Lukas Jungmann's avatar
Lukas Jungmann committed
911
When `<class>` customization specified in the
912 913
annotation element of the complex type definition, the complex type
definition must be bound to a Java value class as specified in
914 915
<<Java value class>> applying the
customization overrides as specified in <<Customization Overrides>>.
916

Lukas Jungmann's avatar
Lukas Jungmann committed
917
*_Example:_* Class Customization: Complex Type Definition To Java value class +
918 919 920

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
921 922 923
[source,xml,indent=4]
----
<xs:complexType name="USAddress">
Lukas Jungmann's avatar
Lukas Jungmann committed
924 925 926 927 928
  <xs:annotation><xs:appinfo>
    <jaxb:class name="MyAddress" />
  </xs:appinfo></xs:annotation>
  <xs:sequence>...</xs:sequence>
  <xs:attribute name="country" type="xs:string"/>
929
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
930
----
931 932 933

Customized code:

Thibault Vallin's avatar
Thibault Vallin committed
934 935 936 937 938 939 940
[source,java,indent=4]
----
// public class USAddress { // Default Code
public class MyAddress { // Customized Code
    public String getCountry() {...}
    public void setCountry(String value) {...}
    ...
941
}
Thibault Vallin's avatar
Thibault Vallin committed
942
----
943

Thibault Vallin's avatar
Thibault Vallin committed
944
===== Simple Type Definition
945

Lukas Jungmann's avatar
Lukas Jungmann committed
946
When `<class>` customization specified in the
947 948
annotation element of a simple type definition, the simple type
definition must be bound to a Java value class as specified in
949
<<Bind to a JAXB mapped class>> applying
950
the customization overrides as specified in
951
<<Customization Overrides>>.
952

Lukas Jungmann's avatar
Lukas Jungmann committed
953
*_Example:_* Class Customization: Simple Type Definition To Java value class +
954 955 956

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
957 958 959
[source,xml,indent=4]
----
<xs:simpleType name="SKU">
Lukas Jungmann's avatar
Lukas Jungmann committed
960 961 962 963
  <xs:annotation><xs:appinfo>
    <jaxb:class/>
  </xs:appinfo></xs:annotation>
  <xs:restriction base=xs:int/>
964
</xs:simpleType>
Thibault Vallin's avatar
Thibault Vallin committed
965
----
966 967 968

Customized code:

Thibault Vallin's avatar
Thibault Vallin committed
969 970 971 972 973 974 975
[source,java,indent=4]
----
public class SKU {
    @XmlValue
    public int getValue() {...}
    public void setValue(int value) {...}
    ...
976
}
Thibault Vallin's avatar
Thibault Vallin committed
977
----
978

Thibault Vallin's avatar
Thibault Vallin committed
979
===== Model Group Definition
980

Lukas Jungmann's avatar
Lukas Jungmann committed
981
It is invalid to place a `<jaxb:class>` customization on a model group.
982

Thibault Vallin's avatar
Thibault Vallin committed
983
===== Model Group
984

Lukas Jungmann's avatar
Lukas Jungmann committed
985
It is invalid to place a `<jaxb:class>` customization on an unnamed model group.
986

Thibault Vallin's avatar
Thibault Vallin committed
987
===== Global Element Declaration
988

Lukas Jungmann's avatar
Lukas Jungmann committed
989
A `_<class>_` declaration is allowed in the
990
annotation element of the global element declaration. However, the
Lukas Jungmann's avatar
Lukas Jungmann committed
991
`_implClass_` attribute is not allowed. The global element declaration
992 993 994
must be bound as specified in <<Bind to Element Class>>
applying the customization overrides specified in
<<Customization Overrides>>.
995

Lukas Jungmann's avatar
Lukas Jungmann committed
996
*_Example:_* Class Customization: Global Element to Class +
997 998 999

XML Schema Fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1000 1001
[source,xml,indent=4]
----
1002
<xs:complexType name="AComplexType">
Lukas Jungmann's avatar
Lukas Jungmann committed
1003 1004 1005 1006
  <xs:sequence>
    <xs:element name="A" type="xs:int"/>
    <xs:element name="B" type="xs:string"/>
  </xs:sequence>
1007 1008
</xs:complexType>

Thibault Vallin's avatar
Thibault Vallin committed
1009
<xs:element name="AnElement" type="AComplexType">
Lukas Jungmann's avatar
Lukas Jungmann committed
1010 1011 1012
  <xs:annotation><xs:appinfo>
    <jaxb:class name="MyElement"/>
  </xs:appinfo></xs:annotation>
1013
</xs:element>
Thibault Vallin's avatar
Thibault Vallin committed
1014
----
1015 1016 1017

Customized code:

Thibault Vallin's avatar
Thibault Vallin committed
1018 1019 1020
[source,java,indent=4]
----
// following class is generated because of customization
1021

Thibault Vallin's avatar
Thibault Vallin committed
1022 1023 1024 1025 1026
public class AComplexType {
    void setA(int value) {...}
    int getA() {...}
    void setB(String value) {...}
    String getB() {...}
1027 1028
}

Thibault Vallin's avatar
Thibault Vallin committed
1029
public class MyElement extends JAXBElement<AComplexType> {...}
1030

Thibault Vallin's avatar
Thibault Vallin committed
1031
public class ObjectFactory {
1032

Thibault Vallin's avatar
Thibault Vallin committed
1033 1034
    // Default code
    // JAXBElement<AnElement> createAnElement(AnElement)\{...}
1035

Thibault Vallin's avatar
Thibault Vallin committed
1036 1037 1038
    // Customized code
    MyElement createMyElement(AnElement) {...}
    ... other factory methods ...
1039 1040

}
Thibault Vallin's avatar
Thibault Vallin committed
1041
----
1042

Thibault Vallin's avatar
Thibault Vallin committed
1043
===== Local Element
1044 1045 1046 1047 1048 1049

A local element is a schema element that
occurs within a complex type definition. A local element is one of:

* local element reference (using the ref
attribute) to a global element declaration.
Lukas Jungmann's avatar
Lukas Jungmann committed
1050
* local element declaration (ref attribute is not used).
1051

Lukas Jungmann's avatar
Lukas Jungmann committed
1052
A `<class>` declaration is allowed in the
1053 1054
annotation element of a local element. <<Annotation Restrictions>>
contains more information regarding the
1055
annotation element for a local element reference. However, the
Lukas Jungmann's avatar
Lukas Jungmann committed
1056
`_implClass_` attribute is not allowed.
1057

Lukas Jungmann's avatar
Lukas Jungmann committed
1058
A `<class>` customization on local element
1059
reference must result in an invalid customization as specified in
1060
<<Invalid Customizations>> since a local
1061 1062
element reference is never bound to a Java Element class.

Lukas Jungmann's avatar
Lukas Jungmann committed
1063
A `<class>` customization on local element
1064 1065
declaration applies only when a local element declaration is bound to a
Java Element class. Otherwise it must result in an invalid customization
1066 1067 1068 1069 1070
as specified in <<Invalid Customizations>>.
If applicable, a local element must be bound as
specified in <<bind-to-jaxbelementt-instance>>
applying the customization overrides as specified in
<<Customization Overrides>>.
1071

Lukas Jungmann's avatar
Lukas Jungmann committed
1072
*_Example:_* Class Customization: Local Element Declaration To Java Element +
1073

1074
The following example is from <<Examples>>.
1075 1076 1077

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1078 1079 1080
[source,xml,indent=4]
----
<xs:complexType name="Base">
Lukas Jungmann's avatar
Lukas Jungmann committed
1081 1082 1083 1084 1085 1086 1087 1088 1089
  <xs:choice maxOccurs="unbounded">
    <xs:element name="A" type="xs:string">
      <xs:annotation><xs:appinfo>
        <jaxb:class name="Bar"/>
      </xs:appinfo></xs:annotation>
    </xs:element>
    <xs:element name="B" type="xs:string"/>
    <xs:element name="C" type="xs:int"/>
  </xs:choice>
1090
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1091
----
1092 1093 1094

Customized code:

Thibault Vallin's avatar
Thibault Vallin committed
1095 1096 1097 1098 1099
[source,java,indent=4]
----
import jakarta.xml.bind.JAXBElement;
public class ObjectFactory {
    // element instance factories only
Lukas Jungmann's avatar
Lukas Jungmann committed
1100 1101
    // JAXBElement<String> createBaseA(String value); // default code
    JAXBElement<String> createBaseBar(String value); // Customized
Thibault Vallin's avatar
Thibault Vallin committed
1102 1103 1104 1105
    JAXBElement<String> createBaseB(String value);
    JAXBElement<Integer> createBaseC(Integer value);
}
public class Base {
Lukas Jungmann's avatar
Lukas Jungmann committed
1106
    static public class Bar extends JAXBElement<String> {...} // Customized code
Thibault Vallin's avatar
Thibault Vallin committed
1107
    /**
Lukas Jungmann's avatar
Lukas Jungmann committed
1108 1109 1110
     * A general content list that can contain element
     * instances of JAXBElement<String> or JAXBElement<Integer>.
     */
Thibault Vallin's avatar
Thibault Vallin committed
1111
    List<Object> getBarOrBOrC() {...}
1112
}
Thibault Vallin's avatar
Thibault Vallin committed
1113
----
1114

Lukas Jungmann's avatar
Lukas Jungmann committed
1115
=== `<property>` Declaration
1116 1117 1118 1119 1120 1121 1122 1123 1124

This binding declaration allows the
customization of a binding of an XML schema element to its Java
representation as a property. This section identifies all XML schema
elements that can be bound to a Java property and how to customize that
binding.

The scope of customization value can either
be definition scope or component scope depending upon which XML schema
Lukas Jungmann's avatar
Lukas Jungmann committed
1125
element the `_<property>_` binding declaration is specified.
1126

Thibault Vallin's avatar
Thibault Vallin committed
1127 1128 1129 1130 1131 1132 1133 1134
==== Usage

[source,xml,indent=4]
----
<property [ name = "propertyName" ]
    [ collectionType = "propertyCollectionType" ]
    [ fixedAttributeAsConstantProperty = "true" | "false" | "1" | "0" ]
    [ generateIsSetMethod = "true" | "false" | "1" | "0" ]
Lukas Jungmann's avatar
Lukas Jungmann committed
1135 1136 1137 1138
    [ enableFailFastCheck = "true" | "false" | "1" | "0" ]
    [ generateElementProperty = "true" | "false" | "1" | "0" ]
    [ attachmentRef = "resolve" | "doNotResolve" | "default" ] >
    [ <baseType name = "fully qualified Java class"> ... </baseType> ]
Thibault Vallin's avatar
Thibault Vallin committed
1139 1140 1141 1142 1143
    [ <javadoc> ... </javadoc> ]
</property>

<baseType name=fully qualified Java class>
    <javaType> ... </javaType>
1144
</baseType>
Thibault Vallin's avatar
Thibault Vallin committed
1145
----
1146

Lukas Jungmann's avatar
Lukas Jungmann committed
1147
For readability, the `<baseType>` element is
1148
shown separately. However, it can be used only as a local element within
Lukas Jungmann's avatar
Lukas Jungmann committed
1149
the `<property>` element.
1150 1151

The use of this declaration is subject to the
1152
constraints specified in <<usage-constraints>>.
1153 1154 1155

The customization values defined are:

Lukas Jungmann's avatar
Lukas Jungmann committed
1156 1157 1158 1159 1160 1161 1162 1163
* `_name_` if specified, defines the
customization value `_propertyName;_` it must be a legal Java identifier.
* `_collectionType_` if specified, defines the
customization value `_propertyCollectionType_` which is the collection
type for the property. `_propertyCollectionType_` if specified, must be
either `"indexed"` or any fully qualified class name that implements
`_java.util.List_`.
* `_fixedAttributeAsConstantProperty_` if
1164
specified , defines the customization value
Lukas Jungmann's avatar
Lukas Jungmann committed
1165 1166 1167 1168 1169 1170 1171 1172 1173
`_fixedAttributeAsConstantProperty_`. The value must be one of
`"true"`, `"false"`, `"1"` or `"0"`.
* `_generateIsSetMethod_` if specified,
defines the customization value of `_generateIsSetMethod_`. The value must
be one of `"true"`, `"false"`, `"1"` or `"0"`.
* `_enableFailFastCheck_` if specified,
defines the customization value `_enableFailFastCheck_`. The value must be
one of `"true"`, `"false"`, `"1"` or `"0"`.
* `@generateElementProperty` if specified,
1174
controls the generation of JAXBElement property. The value must be one
Lukas Jungmann's avatar
Lukas Jungmann committed
1175 1176
of `"true"`, `"false"`, `"1"` or `"0"`. The default is absence of the value.
It is an error for this attribute to be present if this customization is
1177 1178
attached to local or global attribute declarations. This customization
affects the binding as follows. It is an error to specify this
Lukas Jungmann's avatar
Lukas Jungmann committed
1179
customization, when the property is required to be `_JAXBElement_` (such
1180 1181
as when a property contains multiple elements with different names but
of the same type.)
Lukas Jungmann's avatar
Lukas Jungmann committed
1182 1183 1184 1185 1186
** _true_ : Always generate properties to use `_JAXBElement_`.
** _false_ : When generating properties from
`_<element nillable="true" minOccurs="0" />_`, generate a property not to
use JAXBElement, as if the element declaration were just `_<element nillable="true"/>_`.
* `@attachmentRef` has a default value of
1187
default. This mode defers to default processing as specified in
1188
<<binding-ws-i-attachment-profile-refswaref>>. +
1189
 +
Lukas Jungmann's avatar
Lukas Jungmann committed
1190 1191 1192 1193
When `@attachmentRef` value is _resolve_ and the propertys base type is
or derives from `xsd:anyURI`, the schema-derived JAXB property has a
base type of `jakarta.activation.DataHandler` and the property is
annotated with `@XmlAttachmentRef`. +
1194
 +
Lukas Jungmann's avatar
Lukas Jungmann committed
1195 1196 1197 1198 1199 1200 1201
Disabling autoresolving an element/attribute of type `ref:swaRef`: +
When `@attachmentRef` value is _doNotResolve_ and the propertys base
type derives from standard schema type `ref:swaRef`, the schema-derived
JAXB property has the base type `String`, derived from `xsd:anyURI`,
and `@XmlAttachmentRef` is not generated for the property.
* `_<javadoc>_` element, if specified
customizes the Javadoc for the propertys getter method. `_<javadoc>_`
1202
must be specified as described in <<javadoc-declaration>>.
1203

Lukas Jungmann's avatar
Lukas Jungmann committed
1204
==== baseType
1205

Lukas Jungmann's avatar
Lukas Jungmann committed
1206
The `<baseType>` element is intended to allow
1207 1208 1209
the customization of a base type for a JAXB property. This element can
only be a child of <jaxb:property> element.

Thibault Vallin's avatar
Thibault Vallin committed
1210 1211
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
1212
<baseType name="fully qualified Java class>">
Thibault Vallin's avatar
Thibault Vallin committed
1213
    <javaType> ... </javaType>
1214
</baseType>
Thibault Vallin's avatar
Thibault Vallin committed
1215
----
1216 1217


Lukas Jungmann's avatar
Lukas Jungmann committed
1218
The `@name` attribute enables either the
1219
specialization or generalization of the default base type binding for a
Lukas Jungmann's avatar
Lukas Jungmann committed
1220
JAXB property. Child element `<javaType>` is used to convert the default
1221 1222 1223
base type to a Java class. These two mutual exclusive usages of the
<baseType> customization are described below.

Thibault Vallin's avatar
Thibault Vallin committed
1224
===== Conversion using Child element <javaType>
1225

Lukas Jungmann's avatar
Lukas Jungmann committed
1226 1227
Optional child element `_<javaType>_`, if
specified, defines the customization value `_javaType_` and must be
1228 1229
specified as defined in <<javatype-declaration>>.
The customization value defined has component scope. This
1230 1231 1232 1233
customization converts the default base types value for a simple type
definition to the Java class specified by <javaType> name.

The schema-derived JAXB property is annotated
Lukas Jungmann's avatar
Lukas Jungmann committed
1234 1235
with `@XmlJavaTypeAdapter` specified in Section 8.
`@XmlJavaTypeAdapter.value()` is set to a generated
Thibault Vallin's avatar
Thibault Vallin committed
1236 1237 1238
classfootnote:[There is no need to
standardize the name of the generated class since
_@XmlJavaTypeAdapter.value()_ references the class.] that extends
Lukas Jungmann's avatar
Lukas Jungmann committed
1239 1240
`jakarta.xml.bind.annotation.adapter.XmlAdapter`. The generated class
`unmarshal` method must call the <javaType> customizations parse
1241 1242
method, which is specified in <<<javatype-declaration>>.
The generated class `marsha` method must call
1243 1244
the <javaType> customizations print method.

Thibault Vallin's avatar
Thibault Vallin committed
1245
===== Generalize/Specialize baseType with attribute @name
1246

Lukas Jungmann's avatar
Lukas Jungmann committed
1247
The `name` attribute for`<baseType` enables
1248 1249 1250 1251 1252 1253 1254 1255
more precise control over the actual base type for a JAXB property. This
customization enables specifying an alternative base type than the
propertys default base type. The alternative base type must still be in
the same class inheritance hierarchy as the default base type. The
alternative base type must be either a super interface/class or subclass
of the default Java base type for the property. The customization
enables one to specialize or generalize the properties binding.

Lukas Jungmann's avatar
Lukas Jungmann committed
1256
The `name` attribute value must be a fully
1257 1258 1259 1260 1261 1262 1263
qualified Java class name. When the default base type is a primitive
type, consider the default Java base type to be the Java wrapper class
of that primitive type.

Generalizing the basetype using this
customization enables simple type substitution for a JAXB property
representing with too restrictive of a default base type. To enable all
Lukas Jungmann's avatar
Lukas Jungmann committed
1264 1265
possible valid type substitutions, the `name` attribute should be
`java.lang.Object`. However, if for example, it is known that all type
1266
substitutions will share a more specific Java super interface/class than
Lukas Jungmann's avatar
Lukas Jungmann committed
1267
`java.lang.Object`, that Java class name can be used achieve a stronger
1268
typed binding. With this customization, the JAXB annotation generated
Lukas Jungmann's avatar
Lukas Jungmann committed
1269
for the propertys `@XmlElement.type()` or `@XmlAttribute.type()` is
1270 1271 1272 1273 1274
still the default Java datatype for the element/attributes
schema-defined type.

The schema-derived customized JAXB property
is annotated, either explicitly or by default mapping annotations, with
Lukas Jungmann's avatar
Lukas Jungmann committed
1275 1276
the mapping annotation `@XmlElement`, specified in Section 8.10.1. The
`@XmlElement` annotation element type is derived in terms of the
1277
abstract model properties for a element type definition summarized in
1278
<<Element Declaration Schema Component>>
1279 1280
as follows:

Lukas Jungmann's avatar
Lukas Jungmann committed
1281 1282
.Annotate JAXB property with @XmlElement element-value pairs
[cols=",",options="header"]
1283
|===
Lukas Jungmann's avatar
Lukas Jungmann committed
1284 1285
| @XmlElement element | @XmlElement value
| type |the java type binding of the element declarations _{type definition}_
1286 1287 1288
|===

Note that the Java class for
Lukas Jungmann's avatar
Lukas Jungmann committed
1289
`@XmlElement.type()` can differ from the recommended JAXB propertys
1290 1291
base type to enable type substitution of java.lang.Object. This binding
enables unmarshalling of the Elements simple content when it is not
Lukas Jungmann's avatar
Lukas Jungmann committed
1292 1293
qualified with an `xsi:type` as the elements schema-declared type.
`@XmlElement.type()` acts as the default `xsi:type` for a JAXB property
1294 1295 1296 1297 1298
where the propertys base type was generalized to allow for type
substitution of an element declaration with a simple type definition.

Specializing the basetype using this
customization generates stronger typing than default JAXB binding. For
Lukas Jungmann's avatar
Lukas Jungmann committed
1299 1300
example, an XML element or attribute of `xs:IDREF` binds to
`java.lang.Object` by default as specified in
1301 1302
<<Binding an IDREF component to a Java property>>.
If the schema only intends the reference to be to an element
1303 1304 1305
that binds to a specific type, the baseType @name schema customization
can be used to specialize the binding.

1306
[#exidrefcust]
Lukas Jungmann's avatar
Lukas Jungmann committed
1307
*_Example:_* Specialize binding of an IDREF via customization +
1308 1309 1310

Given XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1311 1312 1313
[source,xml,indent=4]
----
<xs:complexType name="Book">
Lukas Jungmann's avatar
Lukas Jungmann committed
1314 1315 1316 1317 1318 1319 1320 1321 1322
  <xs:sequence>
    <xs:element name="author" type="xs:IDREF"/>
      <xs:annotation><xs:appinfo>
        <jaxb:property>
          <jaxb:baseType name=AuthorBio.class/>
        </jaxb:property>
      </xs:appinfo></xs:annotation>
    <!-- ... -->
  </xs:sequence>
Thibault Vallin's avatar
Thibault Vallin committed
1323 1324
</xs:complexType>
<xs:complexType name="AuthorBio">
Lukas Jungmann's avatar
Lukas Jungmann committed
1325 1326
  <xs:sequence><!-- ... --> </xs:sequence>
  <xs:attribute name="name" type="xs:ID"/>
Thibault Vallin's avatar
Thibault Vallin committed
1327 1328
</xs:complexType>
----
1329 1330 1331

Schema-derived Java value class:

Thibault Vallin's avatar
Thibault Vallin committed
1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342
[source,java,indent=4]
----
public class Book {
    @XmlIDREF
    AuthorBio getAuthor() {...}
    void setAuthor(AuthorBio referencedObj) {...}
}
public class AuthorBio {
    @XmlID
    String getName() {...}
    void setName(String value) {...}
1343
}
Thibault Vallin's avatar
Thibault Vallin committed
1344
----
1345

Thibault Vallin's avatar
Thibault Vallin committed
1346
===== Usage Constraints
1347

Lukas Jungmann's avatar
Lukas Jungmann committed
1348
The usage constraints on `<property>` are
1349
specified below. Any constraint violation must result in an invalid
1350
customization as specified in <<Invalid Customizations>>. The usage constraints are:
1351

Lukas Jungmann's avatar
Lukas Jungmann committed
1352
. The `<baseType>` is only allowed with the
1353 1354 1355 1356 1357
following XML schema elements from the
<<Customizable Schema Elements>>:
.. Local Element, <<Local Element>>.
.. Local Attribute, <<Local Attribute>>.
.. ComplexType with simpleContent, <<ComplexType>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1358 1359 1360
. `<baseType>` can either have a name attribute
or a `<javaType>`, they both can not exist at the same time.
. The `_fixedAttributeAsConstantProperty_` is
1361
only allowed with a local attribute, <<Local Attribute>>, that is fixed.
Lukas Jungmann's avatar
Lukas Jungmann committed
1362 1363
. If a `<property>` declaration is associated
with the `<complexType>`, then a `<property>` customization cannot be
1364
specified on the following schema elements that are scoped to
Lukas Jungmann's avatar
Lukas Jungmann committed
1365 1366 1367 1368 1369 1370 1371 1372
`<complexType>`:
+
--
.. Local Element
.. Model group
.. Model Group Reference
--
The reason is that a `<property>` declaration
1373
associated with a complex type binds the content model of the complex
Lukas Jungmann's avatar
Lukas Jungmann committed
1374
type to a general content property. If a `<property>` declaration is
1375 1376 1377
associated with a schema element listed above, it would create a
conflicting customization.

Lukas Jungmann's avatar
Lukas Jungmann committed
1378 1379 1380 1381 1382 1383 1384 1385
[NOTE]
.Design Note
====
A Local Attribute is excluded from the list above.
The reason is that a local attribute is not part of the content model
of a complex type. This allows a local attribute to be customized
(using a <property> declaration) independently
from the customization of a complex types content model.
1386

Lukas Jungmann's avatar
Lukas Jungmann committed
1387 1388 1389
====

*_Example:_* Property Customization: simple type customization +
Thibault Vallin's avatar
Thibault Vallin committed
1390 1391 1392 1393

[source,xml,indent=4]
----
<xs:complexType name="internationalPrice">
Lukas Jungmann's avatar
Lukas Jungmann committed
1394 1395 1396 1397 1398 1399
  ....
  <xs:attribute name="currency" type="xs:string">
    <xs:annotation><xs:appinfo>
      <jaxb:property>
        <jaxb:baseType>
          <jaxb:javaType name="java.math.BigDecimal"
Thibault Vallin's avatar
Thibault Vallin committed
1400 1401
    parseMethod="jakarta.xml.bind.DatatypeConverter.parseInteger"
    printMethod="jakarta.xml.bind.DatatypeConverter.printInteger"/>
Lukas Jungmann's avatar
Lukas Jungmann committed
1402 1403 1404 1405
        </jaxb:baseType>
      </jaxb:property>
    </xs:appinfo></xs:annotation>
  </xs:attribute>
1406
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1407
----
1408 1409 1410

The code generated is:

Thibault Vallin's avatar
Thibault Vallin committed
1411 1412 1413 1414 1415 1416
[source,java,indent=4]
----
public class InternationalPrice {
    // String getCurrency(); default
    java.math.BigDecimal getCurrency() {...} //customized
    public void setCurrency(java.math.BigDecimal val) {...} // customized
1417
}
Thibault Vallin's avatar
Thibault Vallin committed
1418
----
1419

Thibault Vallin's avatar
Thibault Vallin committed
1420
==== Customization Overrides
1421 1422 1423 1424

When binding a schema elements Java
representation to a property, the following customization values
override the defaults specified in Chapter 6. It is specified in a
1425
common section here and referenced from <<Customizable Schema Elements>>.
1426

Lukas Jungmann's avatar
Lukas Jungmann committed
1427
* *name*: If _propertyName_ is defined, then it
1428
is the name obtained by mapping the name as specified in
1429
<<Customized Name Mapping>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1430 1431
* *base type*: The basetype is
`_propertyBaseType_` if defined. The _propertyBaseType_ is defined by a XML
1432
schema element in <<Customizable Schema Elements>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1433 1434 1435
* *collection type*: The collection type is
`_propertyCollectionType_` if specified; otherwise it is the
`_propertyCollectionType_` inherited from a scope that covers this schema
1436
element.
Lukas Jungmann's avatar
Lukas Jungmann committed
1437
* *javadoc*: The Javadoc must be generated as
1438
specified in section <<Javadoc Customization>>. The Javadoc section customized is the `method section`.
Lukas Jungmann's avatar
Lukas Jungmann committed
1439 1440 1441
* If `_propertyBaseType_` is a Java primitive
type and `_propertyCollectionType_` is a class that implements
`java.util.List`, then the primitive type must be mapped to its wrapper
1442 1443 1444 1445
class.

The following does not apply if local
attribute is being bound to a constant property as specified in
1446
<<Local Attribute>>:
1447

1448 1449
* If `_generateIsSetMethod_` is `"true"` or `"1"`, then additional
methods as specified in <<isset-property-modifier>> must be generated.
Lukas Jungmann's avatar
Lukas Jungmann committed
1450
* If `_enableFailFastCheck_` is `"true"` or `"1"`,
1451 1452 1453 1454
then the type constraint checking when setting a property is enforced by
the JAXB implementation. Support for this feature is optional for a JAXB
implementation in this version of the specification.

Thibault Vallin's avatar
Thibault Vallin committed
1455
==== Customizable Schema Elements
1456

Thibault Vallin's avatar
Thibault Vallin committed
1457
===== Global Attribute Declaration
1458

Lukas Jungmann's avatar
Lukas Jungmann committed
1459
A `_<property>_` declaration is allowed in
1460 1461 1462 1463 1464
the annotation element of the global attribute declaration.

The binding declaration does not bind the
global attribute declaration to a property. Instead it defines
customization values that have definition scope. The definition scope
1465 1466
covers all local attributes (<<Local Attribute>>)
that can reference this global attribute declaration. This
1467 1468 1469 1470
is useful since it allows the customization to be done once when a
global attribute is defined instead of at each local attribute that
references the global attribute declaration.

Thibault Vallin's avatar
Thibault Vallin committed
1471
===== Local Attribute
1472 1473 1474 1475 1476 1477 1478 1479 1480 1481

A local attribute is an attribute that occurs
within an attribute group definition, model group definition or a
complex type. A local attribute can either be a

* local attribute reference (using the ref
attribute) to a global attribute declaration.
* local attribute declaration (ref
attribute is not used).

Lukas Jungmann's avatar
Lukas Jungmann committed
1482
A `_<property>_` declaration is allowed in
1483
the annotation element of a local
1484
attribute. <<Annotation Restrictions>>
1485 1486
contains more information regarding the annotation element for a local
attribute reference. The customization values must be defined as
1487
specified in <<usage-4>> and have component
1488 1489
scope.

Lukas Jungmann's avatar
Lukas Jungmann committed
1490 1491 1492
If `_javaType_` is defined, then the
`_propertyBaseType_` is defined to be Java datatype specified in the
`"name"` attribute of the `_javaType_`.
1493

Lukas Jungmann's avatar
Lukas Jungmann committed
1494 1495
* If `_fixedAttributeAsConstantProperty_` is
`"true"` or `"1"` and the local attribute is a fixed, the local
1496
attribute must be bound to a Java Constant property as specified in
1497
<<Bind to a Java Constant property>>
1498
applying customization overrides as specified in
1499
<<Customization Overrides>>. The
Lukas Jungmann's avatar
Lukas Jungmann committed
1500 1501 1502
`_generateIsSetMethod_`, `_choiceContentProperty_`
and `_enableFailFastCheck_` must
be considered to have been set to `"false"`.
1503
* Otherwise, it is bound to a Java property
1504
as specified in <<Attribute use>>
1505
applying customization overrides as specified in
1506
<<Customization Overrides>>.
1507

Lukas Jungmann's avatar
Lukas Jungmann committed
1508
*_Example:_* Customizing Java Constant Property +
1509 1510 1511

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1512 1513
[source,xml,indent=4]
----
1514
<xs:complexType name="USAddress">
Lukas Jungmann's avatar
Lukas Jungmann committed
1515 1516 1517 1518 1519 1520
  <xs:attribute name="country" type="xs:NMTOKEN" fixed="US">
    <xs:annotation><xs:appinfo>
      <jaxb:property name="MY_COUNTRY"
                     fixedAttributeAsConstantProperty="true"/>
    </xs:appinfo></xs:annotation>
  </xs:attribute>
1521
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1522
----
1523 1524 1525

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1526 1527 1528 1529
[source,java,indent=4]
----
public class USAddress {
    public static final String MY_COUNTRY = "US"; // Customized Code
1530
}
Thibault Vallin's avatar
Thibault Vallin committed
1531
----
1532

Lukas Jungmann's avatar
Lukas Jungmann committed
1533
*_Example 2:_* Customizing to other Java Property +
1534 1535 1536

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1537 1538
[source,xml,indent=4]
----
1539
<xs:complexType name="USAddress"> +
Lukas Jungmann's avatar
Lukas Jungmann committed
1540 1541 1542 1543 1544
  <xs:attribute name="country" type="xs:string">
    <xs:annotation><xs:appinfo>
      <jaxb:property name="MyCountry"/>
    </xs:appinfo></xs:annotation>
  </xs:attribute>
1545
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1546
----
1547 1548 1549

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1550 1551 1552 1553 1554 1555 1556
[source,java,indent=4]
----
public class USAddress {
    // public getString getCountry(); // DefaultCode
    // public void setCountry(string value);//Default Code
    public String getMyCountry() {...} //Customized Code
    public void setMyCountry(String value) {...}// Customized Code
1557
}
Thibault Vallin's avatar
Thibault Vallin committed
1558
----
1559

Lukas Jungmann's avatar
Lukas Jungmann committed
1560
*_Example 3:_* Generating IsSet Methods +
1561 1562 1563

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1564 1565
[source,xml,indent=4]
----
1566
<xs:attribute name="account" type = "xs:int">
Lukas Jungmann's avatar
Lukas Jungmann committed
1567 1568 1569
  <xs:annotation><xs:appinfo>
    <jaxb:property generateIsSetMethod="true"/>
  </xs:appinfo></xs:annotation>
1570
</xs:attribute>
Thibault Vallin's avatar
Thibault Vallin committed
1571
----
1572 1573 1574

Customized code:

Thibault Vallin's avatar
Thibault Vallin committed
1575 1576
[source,java,indent=4]
----
1577 1578
public int getAccount();
public void setAccount(int account);
Thibault Vallin's avatar
Thibault Vallin committed
1579 1580 1581
public boolean isSetAccount(); // Customizedcode
public void unsetAccount(); // Customizedcode
----
1582

Thibault Vallin's avatar
Thibault Vallin committed
1583
===== Global Element Declaration
1584

Lukas Jungmann's avatar
Lukas Jungmann committed
1585
A `_<property>_` declaration is allowed in the
1586 1587 1588 1589 1590 1591
annotation element of a global element declaration. However, the usage
is constrained as follows:

The binding declaration does not bind the
global element declaration to a property. Instead it defines
customization values that have definition scope. The definition scope
1592 1593
covers all local elements (<<Local Element>>)
that can reference this global element declaration. This is
1594 1595 1596 1597
useful since it allows the customization to be done once when a global
element is defined instead of at each local element that references the
global element declaration.

Thibault Vallin's avatar
Thibault Vallin committed
1598
===== Local Element
1599 1600 1601 1602 1603 1604 1605 1606 1607

A local element is a schema element that
occurs within a complex type definition. A local element is one of:

* local element reference (using the ref
attribute) to a global element declaration.
* local element declaration (ref attribute
is not used).

Lukas Jungmann's avatar
Lukas Jungmann committed
1608
A `<property>` declaration is allowed in the
1609 1610
annotation element of a local element. <<Annotation Restrictions>>
contains more information regarding the
1611 1612 1613
annotation element for a local element reference.

The customization values must be defined as
1614
specified in <<usage-4>> and have component
1615 1616
scope.

Lukas Jungmann's avatar
Lukas Jungmann committed
1617 1618 1619
If `_javaType_` is defined, then the
`_propertyBaseType_` is defined to be Java datatype specified in the
`"name"` attribute of the `_javaType_`.
1620 1621

The local element must be bound as specified
1622
in <<Content Model Default Binding>>
1623
applying customization overrides as specified in
1624
<<Customization Overrides>>.
1625

1626
See example in <<propex3>> in section <<Model Group>>.
1627

Thibault Vallin's avatar
Thibault Vallin committed
1628
===== Wildcard
1629

Lukas Jungmann's avatar
Lukas Jungmann committed
1630
A `<property>` declaration is allowed in the
1631
annotation element of the wildcard schema component. The customization
1632
values must be defined as specified in <<usage-4>> and have component scope.
1633 1634

The wildcard schema component must be bound
1635 1636 1637
to a property as specified in <<Bind wildcard schema component>>
applying customization overrides as
specified in <<Customization Overrides>>.
1638

Lukas Jungmann's avatar
Lukas Jungmann committed
1639
*_Example:_* The following schema example is from UDDI V2.0 +
1640

Thibault Vallin's avatar
Thibault Vallin committed
1641 1642
[source,xml,indent=4]
----
1643
<xs:complexType name="businessEntityExt">
Lukas Jungmann's avatar
Lukas Jungmann committed
1644 1645 1646 1647 1648 1649 1650 1651 1652 1653
  <xs:sequence>
    <xs:any namespace="##other"
            processContents="strict"
            minOccurs="1" maxOccurs="unbounded">
      <xs:annotation><xs:appinfo>
        <jaxb:property name="Extension"/>
      </xs:appinfo></xs:annotation>
    </xs:any>
    ....
  </xs:sequence>
1654
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1655
----
1656 1657 1658

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1659 1660 1661 1662 1663 1664
[source,java,indent=4]
----
public class BusinessEntityExt {
    ...
    // List getAny(); // Default Code
    List getExtension() {...} // Customized Code
1665
}
Thibault Vallin's avatar
Thibault Vallin committed
1666
----
1667

Thibault Vallin's avatar
Thibault Vallin committed
1668
===== Model Group
1669

Lukas Jungmann's avatar
Lukas Jungmann committed
1670 1671 1672
A `<property>` binding declaration is allowed
in the annotation element of the compositor (i.e. `<choice>`,
`<sequence>` or `<all>`). The customization values must be defined as
1673
specified in <<usage-4>> and have component
1674 1675 1676 1677 1678
scope.

The customized binding of a model group is
determined by the following:

Lukas Jungmann's avatar
Lukas Jungmann committed
1679 1680 1681
* `choiceContentProperty` attribute in `<globalBindings>`.
. If _propertyBaseType_ is defined and a
`<property>` declaration is also present, then the customization
1682 1683
overrides specified in <<Customization Overrides>>
must be applied by the model groups parent schema element
1684
to the property used to aggregate the Java value class.
Lukas Jungmann's avatar
Lukas Jungmann committed
1685
. If _propertySet_ is defined, then the model
1686
groups parent schema element must aggregate the property set as
1687
specified in <<Aggregation of Property Set>>.
1688

1689
*_Example 1:_* [[propex1, Example 1]]Property Customization: Model Group To ChoiceContent Property +
1690 1691 1692

XML Schema fragment

Thibault Vallin's avatar
Thibault Vallin committed
1693 1694 1695
[source,xml,indent=4]
----
<xs:annotation><xs:appinfo>
Lukas Jungmann's avatar
Lukas Jungmann committed
1696
  <jaxb:globalBindings choiceContentProperty="true"/>
1697
</xs:appinfo></xs:annotation>
Thibault Vallin's avatar
Thibault Vallin committed
1698
<xs:complexType name=AType>
Lukas Jungmann's avatar
Lukas Jungmann committed
1699 1700 1701 1702
  <xs:choice>
    <xs:element name="foo" type="xs:int"/>
    <xs:element name="bar" type="xs:string"/>
  </xs:choice>
1703
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1704
----
1705 1706 1707

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1708 1709 1710 1711
[source,java,indent=4]
----
class ObjectFactory {
    JAXBElement<Integer> createAtypeFoo(Integer value);
Lukas Jungmann's avatar
Lukas Jungmann committed
1712
    JAXBElement<String>  createAtypeBar(String value);
1713
}
Thibault Vallin's avatar
Thibault Vallin committed
1714 1715 1716 1717 1718
public class AType {
    void setFooOrBar(Object o) {...}    //customized code
    Object getFooOrBar() {...}          //customized code
}
----
1719

Lukas Jungmann's avatar
Lukas Jungmann committed
1720
The `choiceContentProperty` is required to
1721 1722
bind the choice model group to a choice content property.

1723
*_Example 2:_* [[propex2, Example 2]]Property Customization: Model Group To General Content Property +
1724 1725 1726

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1727 1728 1729
[source,xml,indent=4]
----
<xs:complexType name="Base">
Lukas Jungmann's avatar
Lukas Jungmann committed
1730 1731 1732 1733 1734 1735 1736 1737
  <xs:choice maxOccurs="unbounded">
    <xs:annotation><xs:appinfo>
      <jaxb:property name="items" />
    </xs:appinfo></xs:annotation>
    <xs:element name="A" type="xs:string"/>
    <xs:element name="B" type="xs:string"/>
    <xs:element name="C" type="xs:int"/>
  </xs:choice>
1738
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1739
----
1740 1741 1742

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1743 1744 1745 1746
[source,java,indent=4]
----
public class Base {
    /**
Lukas Jungmann's avatar
Lukas Jungmann committed
1747 1748 1749
     * A general content list that can contain
     * instances of Base.A, Base.B and Base.C.
     */
Thibault Vallin's avatar
Thibault Vallin committed
1750
    // List getAOrBOrC(); - default
Lukas Jungmann's avatar
Lukas Jungmann committed
1751
    List getItems() {...} // Customized Code
1752
}
Thibault Vallin's avatar
Thibault Vallin committed
1753
----
1754

1755
*_Example 3:_* [[propex3, Example 3]]Property Customization: Model Group To Content Property Set +
1756 1757 1758

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
1759 1760 1761 1762
[source,xml,indent=4]
----
<xs:complexType name="USAddress"/>
<xs:complexType name="PurchaseOrderType">
Lukas Jungmann's avatar
Lukas Jungmann committed
1763 1764 1765 1766 1767 1768 1769 1770 1771 1772
  <xs:sequence>
    <xs:choice>
      <xs:group ref="shipAndBill"/>
      <xs:element name="singleUSAddress" type="USAddress">
        <xs:annotation><xs:appinfo>
          <jaxb:property name="address"/>
        </xs:appinfo></xs:annotation>
      </xs:element>
    </xs:choice>
  </xs:sequence>
1773
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
1774
<xs:group name="shipAndBill">
Lukas Jungmann's avatar
Lukas Jungmann committed
1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786
  <xs:sequence>
    <xs:element name="shipTo" type="USAddress">
      <xs:annotation><xs:appinfo>
        <jaxb:property name="shipAddress"/>
      </appinfo></annotation>
    </xs:element>
    <xs:element name="billTo" type="USAddress">
      <xs:annotation><xs:appinfo>
        <jaxb:property name="billAddress"/>
      </xs:appinfo></xs:annotation>
    </xs:element>
  </xs:sequence>
1787
</xs:group>
Thibault Vallin's avatar
Thibault Vallin committed
1788
----
1789 1790 1791

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
1792 1793 1794 1795 1796 1797
[source,java,indent=4]
----
public interface PurchaseOrderType {
    USAddress getShipAddress(); void setShipAddress(USAddress);
    USAddress getBillAddress(); void setBillAddress(USAddress);
    USAddress getAddress(); void setAddress(USAddress);
1798
}
Thibault Vallin's avatar
Thibault Vallin committed
1799
----
1800

Thibault Vallin's avatar
Thibault Vallin committed
1801
===== Model Group Reference
1802 1803

A model group reference is a reference to a
1804
model group using the `ref` attribute. A property customization is
1805
allowed on the annotation property of the model group reference. Section
1806
<<Annotation Restrictions>> contains more
1807 1808 1809 1810
information regarding the annotation element for a model group
reference.

The customization values must be defined as
1811
specified in <<usage-4>> and have component
1812
scope. A model group reference is bound to a Java property set or a list
1813 1814 1815
property as specified in <<Content Model Default Binding>>
applying customization overrides as specified in
<<Customization Overrides>>.
1816

Thibault Vallin's avatar
Thibault Vallin committed
1817
===== ComplexType
1818

Lukas Jungmann's avatar
Lukas Jungmann committed
1819
A `<property>` customization is allowed on
1820
the annotation element of a complex type. The customization values must
1821
be defined as specified in <<usage-4>> and
1822 1823 1824 1825 1826
have component scope. The result of this customization depends upon the
content type of the complex type.

* If the content type of the content model is
simple content, then the content model must be bound to a property as
1827
specified in <<Simple Content Binding>>.
1828
applying the customization overrides as specified in
1829
<<Customization Overrides>>. If
Lukas Jungmann's avatar
Lukas Jungmann committed
1830 1831
`_javaType_` is defined, then the `_propertyBaseType_` is defined to be Java
datatype specified in the `"name"` attribute of the `_javaType_`.
1832 1833
* For all other content types, the content
model must be bound as specified in step 1. of
1834
<<Content Model Default Binding>>
1835
applying the customization overrides as specified in
1836
<<Customization Overrides>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1837 1838 1839 1840 1841 1842 1843 1844 1845

[NOTE]
.Design Note
====
The <property> declaration is not allowed on an annotation element
of attribute group definition. However, attributes within
the attribute group definition can themselves be customized
as described in the Local Attribute section above.
Section 7.8.4.2, Local Attribute.
1846

Lukas Jungmann's avatar
Lukas Jungmann committed
1847
====
1848

Lukas Jungmann's avatar
Lukas Jungmann committed
1849 1850 1851
=== `<javaType>` Declaration

A `<javaType>` declaration provides a way to
1852
customize the binding of an XML schema atomic datatype to a Java
Lukas Jungmann's avatar
Lukas Jungmann committed
1853
datatype, referred to as the _target Java datatype_. The target Java
1854
datatype can be a Java built-in data type or an application specific
Lukas Jungmann's avatar
Lukas Jungmann committed
1855 1856
Java datatype. This declaration also provides two additional methods:
a _parse method_ and a _print method_.
1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867

The parse method converts a lexical
representation of the XML schema datatype into a value of the target
Java datatype. The parse method is invoked by a JAXB providers
implementation during unmarshalling.

The print method converts a value of the
target Java datatype into its lexical representation of the XML schema
datatype. The print method is invoked by a JAXB providers
implementation during marshalling.

Thibault Vallin's avatar
Thibault Vallin committed
1868
==== Usage
1869

Thibault Vallin's avatar
Thibault Vallin committed
1870 1871
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
1872 1873 1874 1875
<javaType name="javaType"
            [ xmlType = "xmlType" ]
            [ parseMethod = "parseMethod" ]
            [ printMethod = "printMethod" ]>
Thibault Vallin's avatar
Thibault Vallin committed
1876
----
1877 1878 1879 1880

The binding declaration can be used in one of
the following:

Lukas Jungmann's avatar
Lukas Jungmann committed
1881
* a `<globalBindings>` declaration.
1882
* annotation element of one of the XML schema
1883
elements specified in <<Customizable Schema Elements>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
1884
* in a `<property>` declaration. See
1885
<<property-declaration>>. This can be
1886 1887
used for customization at the point of reference to a simple type.

Lukas Jungmann's avatar
Lukas Jungmann committed
1888 1889
When used in a `<globalBindings>`
declaration, `<javaType>` defines customization values with global
1890
scope. When used in an annotation element of one of the schema elements
1891 1892
specified in <<Customizable Schema Elements>>
the customization values have component scope.
1893

Thibault Vallin's avatar
Thibault Vallin committed
1894
===== name
1895

Lukas Jungmann's avatar
Lukas Jungmann committed
1896 1897
The `_javaType_`, if specified, is the Java
datatype to which `_xmlType_` is to be bound. Therefore, `_javaType_` must
1898 1899 1900 1901
be a legal Java type name, which may include a package prefix. If the
package prefix is not present, then the Java type name must be one of
the Java built-in primitive types [JLS - Java Language Specification,
Second Edition, Section 4.2, Primitive Types and Values]. (For
Lukas Jungmann's avatar
Lukas Jungmann committed
1902
example, `"int"`) or a Java class in the unnamed package. If class
1903
javaType declares a public constructor with following signature,
Lukas Jungmann's avatar
Lukas Jungmann committed
1904
`javaType(java.lang.String)`, `parseMethod` attribute does not need to
1905 1906
be specified.

Lukas Jungmann's avatar
Lukas Jungmann committed
1907
===== xmlType
1908

Lukas Jungmann's avatar
Lukas Jungmann committed
1909 1910 1911 1912
The `_xmlType_`, if specified, is the name of
the XML Schema datatype to which `_javaType_` is to bound. If specified,
`_xmlType_` must be a XML atomic datatype derived from restriction. The
use of the `_xmlType_` is further constrained as follows.
1913

Lukas Jungmann's avatar
Lukas Jungmann committed
1914
The purpose of the `_xmlType_` attribute is to
1915
allow the global customization of a XML schema to Java datatype. Hence
Lukas Jungmann's avatar
Lukas Jungmann committed
1916 1917
`_xmlType_` attribute is required when `<javaType>` declarations parent
is `<globalBindings>`. If absent, it must result in an invalid
1918 1919
customization as specified in <<Invalid Customizations>>.
Otherwise, the _xmlType_ attribute must not be present
1920
since the XML datatype is determined from the XML schema element with
Lukas Jungmann's avatar
Lukas Jungmann committed
1921 1922
which the annotation element containing `<javaType>` declaration or the
`<baseType>` (containing the `<javaType>`) is associated. If present,
1923
it must result in an invalid customization as specified in
1924
<<Invalid Customizations>>.
1925

1926
Examples can be found in <<exjtcbt>> and <<exjtcus>>
1927

Lukas Jungmann's avatar
Lukas Jungmann committed
1928
===== parseMethod
1929 1930 1931 1932 1933 1934

The parse method if specified, must be
applied during unmarshalling in order to convert a string from the input
document into a value of the target Java datatype. The parse method must
be invoked as follows:

Lukas Jungmann's avatar
Lukas Jungmann committed
1935 1936 1937
* The parse method defaults to `new` provided
`_javaType_` is not a Java primitive type such as (``"int"``). If
`_javaType_` is a Java primitive type, then this must result in an invalid
1938 1939
customization as specified in <<Invalid Customizations>>.
Otherwise, the binding compiler must assume that the
1940
target type is a class that defines a constructor as follows:
Lukas Jungmann's avatar
Lukas Jungmann committed
1941 1942 1943 1944 1945
+
--
** `String` as the first parameter of the constructor.
--
+
1946 1947 1948 1949 1950
To apply the conversion to a string it must
generate code that invokes this constructor, passing it the input
string.

* The parse method may be specified in the
Lukas Jungmann's avatar
Lukas Jungmann committed
1951
form _ClassName.methodName,_ where the _ClassName_ is a fully qualified
1952 1953 1954
class name that includes the package name. A compiler must assume that
the class _ClassName_ exists and that it defines a static method named
_methodName_ that takes:
Lukas Jungmann's avatar
Lukas Jungmann committed
1955 1956 1957 1958 1959
+
--
** `String` as the first argument.
--
+
1960 1961 1962 1963
To apply the conversion to a string it must
generate code that invokes this method, passing it the input string.

* The parse method may be specified in the
Lukas Jungmann's avatar
Lukas Jungmann committed
1964 1965
form _methodName_ provided `_javaType_` is not a Java primitive type (such
as `"int"`). If `_javaType_` is Java primitive type, then this must
1966
result in an invalid customization as specified in
1967
<<Invalid Customizations>>. Otherwise,
1968
the binding compiler must assume that _methodName_ is a method in the
Lukas Jungmann's avatar
Lukas Jungmann committed
1969 1970
class `_javaType_`. The binding compiler must therefore prefix the
`_javaType_` to the _methodName_ and process `_javaType_`._methodName_ as
1971 1972 1973
specified in above.

The string passed to parse method can be any
Lukas Jungmann's avatar
Lukas Jungmann committed
1974
lexical representation for `xmlType` as specified in [XSD PART2].
1975 1976

If parseMethod attribute is not specified,
Lukas Jungmann's avatar
Lukas Jungmann committed
1977
`xmlType` is not a primitive or wrapper class and `javaType` has an
1978
accessible one argument constructor, where the argument is type
Lukas Jungmann's avatar
Lukas Jungmann committed
1979 1980
`java.lang.String`, input text is parsed by invoking `new` with a
`java.lang.String` parameter.
1981

Lukas Jungmann's avatar
Lukas Jungmann committed
1982
===== printMethod
1983 1984 1985 1986 1987 1988

The print method if specified, must be
applied during marshalling in order to convert a value of the target
type into a lexical representation:

* The print method is specified in the form
Lukas Jungmann's avatar
Lukas Jungmann committed
1989 1990
_methodName_ provided `_javaType_` is not a Java primitive type (such as
`"int"`). If `_javaType_` is Java primitive type, then this must result
1991
in an invalid customization as specified in
1992
<<Invalid Customizations>>. Otherwise,
1993 1994
the compiler must assume that the target type is a class or an interface
that defines a zero-argument instance method named _methodName_ that
Lukas Jungmann's avatar
Lukas Jungmann committed
1995
returns a `String`. To apply the conversion it must generate code to
1996 1997 1998 1999 2000
invoke this method upon an instance of the target Java datatype.
* If the print method is specified in the
form _ClassName.methodName_ then the compiler must assume that the class
_ClassName_ exists and that it defines a static method named
_methodName_ that returns a string that takes the following:
Lukas Jungmann's avatar
Lukas Jungmann committed
2001 2002 2003
+
--
** the first parameter is the target Java
2004
datatype.
Lukas Jungmann's avatar
Lukas Jungmann committed
2005 2006
--
+
2007 2008 2009 2010 2011 2012
To apply the conversion to a string it must
generate code that invokes this method, passing it a value of the target
Java datatype.

The lexical representation to which the value
of the target type is converted can be any lexical representation for
Lukas Jungmann's avatar
Lukas Jungmann committed
2013
`xmlType` as specified in [XSD PART2].
2014

Lukas Jungmann's avatar
Lukas Jungmann committed
2015 2016
If `printMethod` attribute is not specified
and `xmlType` is not a primitive or wrapper class, `javaType.toString()`
2017 2018 2019 2020
is used as the default print method..



Lukas Jungmann's avatar
Lukas Jungmann committed
2021
==== DatatypeConverter
2022 2023 2024 2025

Writing customized parse and print methods
can be difficult for a Java programmer. This requires a programmer to
understand the lexical representations of XML schema datatypes. To make
Lukas Jungmann's avatar
Lukas Jungmann committed
2026 2027
it easier, an interface, `DatatypeConverterInterface`, and a class
`DatatypeConverter` are defined to expose the parse and print methods of
2028 2029 2030 2031
a JAXB implementation. These can be invoked by user defined parse and
print methods. This shifts the burden of dealing with lexical spaces
back to the JAXB implementation.

Lukas Jungmann's avatar
Lukas Jungmann committed
2032
The `DatatypeConverterInterface` defines
2033 2034
parse and print methods for XML schema datatypes. There is one parse and
print method for each of XML schema datatype specified in
2035
<<a725>>. The interface is fully specified by the Javadoc specified in
Lukas Jungmann's avatar
Lukas Jungmann committed
2036
`jakarta.xml.bind.DatatypeConverterInterface`.
2037

Lukas Jungmann's avatar
Lukas Jungmann committed
2038
The `DatatypeConverter` class defines a
2039
static parse and print method corresponding to each parse and print
Lukas Jungmann's avatar
Lukas Jungmann committed
2040 2041
method respectively in the `DatatypeConverterInterface` interface. The
property `jakarta.xml.bind.DatatypeConverter` can be used to select the
2042 2043
name of a class that provides an implementation of the parse and print
methods. The name specified in the property must be a fully qualified
Lukas Jungmann's avatar
Lukas Jungmann committed
2044
class name and must implement the interface `DatatypeConverterInterface`
2045
. The class is fully specified by the Javadoc specified in
Lukas Jungmann's avatar
Lukas Jungmann committed
2046
`jakarta.xml.bind.DatatypeConverter`.
2047

Thibault Vallin's avatar
Thibault Vallin committed
2048
===== Usage
2049 2050

The following example demonstrates the use of
Lukas Jungmann's avatar
Lukas Jungmann committed
2051
the `DatatypeConverter` class for writing a customized parse and print
2052 2053
method.

2054
*_Example:_* [[exjtcus,javaType Customization: User Specified Parse Method]] javaType Customization: User Specified Parse Method +
2055 2056

This example shows the binding of XML schema
Lukas Jungmann's avatar
Lukas Jungmann committed
2057
type `"xs:date"` is bound to a Java datatype `long` using user specified
2058 2059
print and parse methods.

Thibault Vallin's avatar
Thibault Vallin committed
2060 2061 2062 2063 2064 2065 2066 2067 2068
[source,xml,indent=4]
----
<jaxb:globalBindings>
    <jaxb:javaType name="long" xmlType="xs:date"
                parseMethod="pkg.MyDatatypeConverter.myParseDate"
                printMethod="pkg.MyDatatypeConverter.myPrintDate"/>
    </jaxb:javaType>
</jaxb:globalBindings>
----
2069

Thibault Vallin's avatar
Thibault Vallin committed
2070 2071 2072
[source,java,indent=4]
----
package pkg;
2073
import jakarta.xml.bind.DatatypeConverter;
Thibault Vallin's avatar
Thibault Vallin committed
2074 2075 2076 2077 2078 2079 2080 2081 2082 2083
public class MyDatatypeConverter {
public static long myParseDate(String s) {
    java.util.Calendar d = DatatypeConverter.parse(s);
    long result= cvtCalendarToLong(d) ; // userdefined method
    return result;
    }
    public static String myPrintDate(long l) {
        java.util.Calendar d = cvtLongToCalendar(l);//user defined
        return DatatypeConverter.print(d);
    }
2084
}
Thibault Vallin's avatar
Thibault Vallin committed
2085
----
2086 2087

The implementation of the print methods (
Lukas Jungmann's avatar
Lukas Jungmann committed
2088
`_parseDate_` and `_printDate_`) are provided by the user.
2089 2090 2091

The customization is applied during the
processing of XML instance document. During unmarshalling, the JAXB
Lukas Jungmann's avatar
Lukas Jungmann committed
2092 2093 2094
implementation invokes `_myParseDate_`. If `_myParseDate_` method throws a
`_ParseException_`, then the JAXB implementation code catches the
exception, and generate a `_parseConversionEvent_`.
2095

Thibault Vallin's avatar
Thibault Vallin committed
2096
===== Lexical And Value Space
2097 2098 2099 2100 2101 2102 2103 2104

[XSD PART 2] specifies both a value space and
a lexical space for an schema datatypes. There can be more than one
lexical representation for a given value.

Examples of multiple lexical representations
for a single value are:

Lukas Jungmann's avatar
Lukas Jungmann committed
2105 2106 2107 2108
* For boolean, the value `true` has two
lexical representations `"true"` and `"1"`.
* For integer, the value `1` has two lexical
representations `"1.0"` and `"1"`.
2109 2110 2111 2112 2113 2114 2115 2116

XSD PART 2 also specifies a canonical
representation for all XML schema atomic datatypes.

The requirements on the parse and print
methods are as follows:

* A JAXB implementation of a parse method in
Lukas Jungmann's avatar
Lukas Jungmann committed
2117
`DatatypeConverterInterface` must be capable of a processing all lexical
2118 2119 2120 2121
representations for a value as specified by [XSD PART 2]. This ensures
that an instance document containing a value in any lexical
representation specified by [XSD PART 2] can be marshalled.
* A JAXB implementation of a print method in
Lukas Jungmann's avatar
Lukas Jungmann committed
2122
`DatatypeConverterInterface` must convert a value into any lexical
2123 2124 2125
representation of the XML schema datatype to which the parse method
applies, as specified by [XSD PART 2] and which is valid with respect to
the applications schema.
Lukas Jungmann's avatar
Lukas Jungmann committed
2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139

[NOTE]
.Design Note
====
The print methods that are exposed may not be portable. The only
requirement on a print method is that it must output
a lexical representation that is valid with respect to the schema.
So two vendors can choose to output different lexical representations.
However, there is value in exposing them despite being non portable.
Without the print method, a user would have to be knowledgeable about
how to output a lexical representation for a given schema datatype,
which is not desirable.

====
2140

Thibault Vallin's avatar
Thibault Vallin committed
2141
==== Built-in Conversions
2142 2143 2144 2145 2146 2147 2148 2149 2150

As a convenience to the user, this section
specifies some built-in conversions. A built-in conversion is one where
the parse and the print method may be omitted by a user. The built-in
conversions leverage the narrowing and widening conversions defined in
[JLS - Java Language Specification, Second Edition], Section 5.1.2,
Widening Primitive Conversion and Section 5.1.3, Narrowing Primitive
Conversions. For example:

Thibault Vallin's avatar
Thibault Vallin committed
2151 2152
[source,xml,indent=4]
----
2153
<xs:simpleType name="foo" type="xs:long">
Lukas Jungmann's avatar
Lukas Jungmann committed
2154 2155 2156
  <xs:annotation><xs:appinfo>
    <jaxb:javaType name="int"/>
  </xs:appinfo></xs:annotation>
2157
</xs:simpleType>
Thibault Vallin's avatar
Thibault Vallin committed
2158
----
2159 2160 2161 2162

If the parse method is omitted, then a JAXB
implementation must perform the one of the following binding options:

Lukas Jungmann's avatar
Lukas Jungmann committed
2163 2164 2165 2166 2167 2168 2169 2170 2171 2172
.. If `_javaType_` is one of the following
primitive types or its corresponding wrapper class `byte`, `short`, `int`,
`long`, `float`, `double` , bind `_xmlType_` to its default Java datatype using
the parse method for the `_xmlType_` defined in `DatatypeConverter`. If
necessary, convert the default Java datatype for `xmlType` to value of
type `_javaType_` by a type cast.
.. Else if default Java datatype defines a
public one-argument constructor that takes a `java.lang.String`, use
`new` with a `java.lang.String` parameter for parsing.
.. Else javaType(java.lang.String) does not
2173
exist, this must result in an invalid binding customization as specified
2174
in <<Invalid Customizations>>.
2175

2176
*_Example:_* [[exjtcbt,javaType Customization: Java Built-in Type]] javaType Customization: Java Built-in Type +
2177 2178 2179 2180 2181 2182

This example illustrates how to bind a XML
schema type to a Java type different from the default one.

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
2183 2184
[source,xml,indent=4]
----
2185
<xs:element name="partNumber" type="xs:int"/>
Thibault Vallin's avatar
Thibault Vallin committed
2186
----
2187 2188 2189

Customization:

Thibault Vallin's avatar
Thibault Vallin committed
2190 2191
[source,xml,indent=4]
----
2192
<jaxb:globalBindings>
Thibault Vallin's avatar
Thibault Vallin committed
2193 2194 2195
    ....
    <jaxb:javaType name="long"
                xmlType="xs:int"/>
2196
</jaxb:globalBindings>
Thibault Vallin's avatar
Thibault Vallin committed
2197
----
2198 2199 2200

Since a Java built-in is specified, a parse
or a print method need not be specified. A JAXB implementation uses the
Lukas Jungmann's avatar
Lukas Jungmann committed
2201
parse and print methods defined in `DatatypeConverter` class for
2202 2203 2204
converting between lexical representations and values. A JAXB
implementation unmarshals an input value using the following methods:

Lukas Jungmann's avatar
Lukas Jungmann committed
2205
[source,java,indent=8]
Thibault Vallin's avatar
Thibault Vallin committed
2206
----
Lukas Jungmann's avatar
Lukas Jungmann committed
2207
int j = (int) DataTypeConverter.parseLong(string);
Thibault Vallin's avatar
Thibault Vallin committed
2208
----
2209

Thibault Vallin's avatar
Thibault Vallin committed
2210
==== Events
2211

Lukas Jungmann's avatar
Lukas Jungmann committed
2212
The parse method `_parseMethod_` may fail,
2213 2214 2215 2216
since it is only defined on those strings that are valid representations
of target Java datatype values and it can be applied to arbitrary
strings. A parse method must indicate failure by throwing an exception
of whatever type is appropriate, though it should never throw a
Lukas Jungmann's avatar
Lukas Jungmann committed
2217
`TypeConstraintException`. A JAXB unmarshaller process must ensure that
2218
an exception thrown by a parse method is caught and, if appropriate, a
Lukas Jungmann's avatar
Lukas Jungmann committed
2219
`parseConversionEvent` event is generated.
2220

Lukas Jungmann's avatar
Lukas Jungmann committed
2221
The print method `_printMethod_` usually does
2222 2223
not fail. If it does, then the JAXB implementation must ensure that the
exception thrown by a print method is caught and a
Lukas Jungmann's avatar
Lukas Jungmann committed
2224
`printConversionEvent` is generated.
2225

Thibault Vallin's avatar
Thibault Vallin committed
2226
==== Customization Overrides
2227

Lukas Jungmann's avatar
Lukas Jungmann committed
2228
The `<javaType>` overrides the default
2229
binding of `_xmlType_` to the Java datatype specified in <<a725>>.
2230

Thibault Vallin's avatar
Thibault Vallin committed
2231
==== Customizable Schema Elements
2232

Thibault Vallin's avatar
Thibault Vallin committed
2233
==== Simple Type Definition
2234

Lukas Jungmann's avatar
Lukas Jungmann committed
2235
A `<javaType>` binding declaration is allowed
2236
in the annotation element of the of a simple type definition. The
Lukas Jungmann's avatar
Lukas Jungmann committed
2237
`_javaType_` overrides the default binding of `_xmlType_` to the Java
2238
datatype specified in <<a725>>. The customization values defined have
2239 2240 2241 2242
definition scope and thus covers all references to this simple type
definition.

If the simple type definition is mapped to a
Lukas Jungmann's avatar
Lukas Jungmann committed
2243 2244
schema-derived type, an `@XmlJavaTypeAdapter` is generated on that
class. Annotation element `@XmlJavaTypeAdapter.value()` is set to a
Thibault Vallin's avatar
Thibault Vallin committed
2245 2246 2247
generated classfootnote:[There is no need to
standardize the name of the generated class since
_@XmlJavaTypeAdapter.value()_ references the class.] that extends
Lukas Jungmann's avatar
Lukas Jungmann committed
2248 2249
`jakarta.xml.bind.annotation.adapter.XmlAdapter`. The generated class
`unmarshal` method must call the <javaType> customizations parse
2250 2251
method, which is specified in <<javatype-declaration>>.
The generated class `marshal` method must call
2252 2253
the <javaType> customizations print method.

Lukas Jungmann's avatar
Lukas Jungmann committed
2254
===== GlobalBindings
2255

Lukas Jungmann's avatar
Lukas Jungmann committed
2256 2257
A `<javaType>` binding declaration is allowed
as part of `<globalBindings>`. The `_javaType_` overrides the default
2258 2259
binding of `_xmlType_` to the Java datatype specified in <<a725>>.
The customization values defined have global scope.
2260 2261

For each element or attribute declaration
Lukas Jungmann's avatar
Lukas Jungmann committed
2262
that references an `xmlType` that has a globalBindings `<javaType>`
2263
customization specified for it, the corresponding JAXB property is
Lukas Jungmann's avatar
Lukas Jungmann committed
2264
annotated with `@XmlJavaTypeAdapter`.
2265

Lukas Jungmann's avatar
Lukas Jungmann committed
2266
===== `<property><baseType>` declaration
2267

Lukas Jungmann's avatar
Lukas Jungmann committed
2268 2269 2270
A `<javaType>` binding declaration is allowed
as part of `<baseType>` in the `<property>` binding declaration. The
`_javaType_` overrides the default binding of `_xmlType_` to the Java
2271 2272
datatype specified in <<a725>>. Additional semantics are specified in
basetype also apply.
2273 2274

The schema-derived JAXB property is annotated
Lukas Jungmann's avatar
Lukas Jungmann committed
2275
with `@XmlJavaTypeAdapter` as specified in
2276
<<basetype>>.
2277

Lukas Jungmann's avatar
Lukas Jungmann committed
2278
=== `<typesafeEnum>` Declaration
2279 2280 2281 2282 2283 2284 2285

This binding declaration allows the
customization of a binding of an XML schema element to its Java
representation as an enum type, Section 8.9 in [JLS3]. Only simple type
definitions with enumeration facets can be customized using this binding
declaration.

Thibault Vallin's avatar
Thibault Vallin committed
2286 2287 2288 2289 2290
==== Usage
[source,xml,indent=4]
----
<typesafeEnumClass>
    [ name = "enumClassName" ]
Lukas Jungmann's avatar
Lukas Jungmann committed
2291
    [ map = "true" | "false" | "1" | "0" ]
Thibault Vallin's avatar
Thibault Vallin committed
2292 2293 2294 2295 2296 2297 2298 2299
    [ ref = "enumClassName" ]
    [ <typesafeEnumMember> ... </typesafeEnumMember> ]*
    [ <javadoc> enumClassJavadoc </javadoc> ]
</typesafeEnumClass>

<typesafeEnumMember name = "enumMemberName">
                  [ value = "enumMemberValue"]
    [ <javadoc> enumMemberJavadoc </javadoc> ]
2300
</typesafeEnumMember>
Thibault Vallin's avatar
Thibault Vallin committed
2301
----
2302
There are two binding declarations
Lukas Jungmann's avatar
Lukas Jungmann committed
2303
`_<typesafeEnumClass>_` and `_<typesafeEnumMember>_`. The two binding
2304 2305 2306
declarations allow the enumeration members of an enumeration class and
enumeration class itself to be customized independently.

Lukas Jungmann's avatar
Lukas Jungmann committed
2307
The `_<typesafeEnumClass>_` declaration
2308 2309
defines the following customization values:

Lukas Jungmann's avatar
Lukas Jungmann committed
2310 2311 2312
* `name` defines the customization value
`_enumClassName_`, if specified. `_enumClassName_` must be a legal Java
Identifier; it must not have a package prefix.
2313
 +
Lukas Jungmann's avatar
Lukas Jungmann committed
2314
For an anonymous simple type, the `name` attribute must be present. If
2315
absent, it must result in an invalid customization as specified in
2316
<<Invalid Customizations>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2317 2318 2319 2320 2321
* `map` determines if the simple type
definition should be bound to an enum type. When ``map``s value is
`false`, then the simple type definition must not be bound to an enum
type. `map` defaults to `true`.
* `ref` if specified, is the name of the
2322 2323 2324
enum class that is provided outside the schema compiler. This
customization causes a schema compiler to refer to this external enum,
as opposed to generate a definition. It must include the complete
Lukas Jungmann's avatar
Lukas Jungmann committed
2325 2326 2327 2328 2329
package name. This attribute is mutually exclusive with the `className`
attribute and the `map` attribute.
* `<javadoc>` element, if specified
customizes the Javadoc for the enumeration class. _<javadoc>_ defines
the customization value `_enumClassjavadoc_` if specified as described in
2330
<<javadoc-declaration>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2331
* Zero or more `_<typesafeEnumMember>_`
2332
declarations. The customization values are as defined as specified by
Lukas Jungmann's avatar
Lukas Jungmann committed
2333
the `_<typesafeEnumMember>_` declaration.
2334

Lukas Jungmann's avatar
Lukas Jungmann committed
2335
The `_<typesafeEnumMember>_` declaration
2336 2337
defines the following customization values:

Lukas Jungmann's avatar
Lukas Jungmann committed
2338 2339
* `name` must always be specified and
defines a customization value `_enumMemberName_`. `_enumMemberName_` must
2340
be a legal Java identifier.
Lukas Jungmann's avatar
Lukas Jungmann committed
2341 2342 2343
* `value` defines a customization value
`_enumMemberValue_`, if specified. `_enumMemberValue_` must be the
enumeration value specified in the source schema. The usage of `_value_`
2344
is further constrained as specified in <<value-attribute>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2345 2346 2347
* `<javadoc>` if specified, customizes the
Javadoc for the enumeration constant. `<javadoc>` defines a
customization value `_enumMemberjavadoc_` if specified as described in
2348
<<javadoc-declaration>>.
2349 2350

For inline annotation, the
Lukas Jungmann's avatar
Lukas Jungmann committed
2351 2352
`<typesafeEnumClass>` must be specified in the annotation element of the
`<simpleType>` element. The `<typesafeEnumMember>` must be specified
2353 2354 2355 2356
in the annotation element of the enumeration member. This allows the
enumeration member to be customized independently from the enumeration
class.

Lukas Jungmann's avatar
Lukas Jungmann committed
2357
==== `value` Attribute
2358 2359 2360

The purpose of the _value_ attribute is to
support customization of an enumeration value using an external binding
Lukas Jungmann's avatar
Lukas Jungmann committed
2361
syntax. When the `<typesafeEnumMember>` is used in an inline annotation,
2362 2363 2364 2365 2366 2367
the enumeration value being customized can be identified by the
annotation element with which it is associated. However, when an
external binding declaration is used, while possible, it is not
desirable to use XPath to identify an enumeration value.

So when customizing using external binding
Lukas Jungmann's avatar
Lukas Jungmann committed
2368 2369
syntax, the `value` attribute must be provided. This serves as a key to
identify the enumeration value to which the `<typesafeEnumMember>`
2370 2371
applies. Its use is therefore further constrained as follows:

Lukas Jungmann's avatar
Lukas Jungmann committed
2372
* When `<typesafeEnumMember>` is specified in
2373 2374 2375
the annotation element of the enumeration member or when XPath refers
directly to a single enumeration facet, then the value attribute must be
absent. If present, it must result in must result in an invalid
2376
customization as specified in <<Invalid Customizations>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2377 2378
* When `<typesafeEnumMember>` is scoped to
the `typesafeEnumClass` declaration, the value attribute must be
2379
present. If absent, it must result in must result in an invalid
2380 2381
customization as specified in <<Invalid Customizations>>.
The _enumMemberValue_ must be used to identify the
Lukas Jungmann's avatar
Lukas Jungmann committed
2382
enumeration member to which the `<typesafeEnumMember>` applies.
2383 2384

An example of external binding syntax can be
2385
found in <<ex2>>.
2386

Thibault Vallin's avatar
Thibault Vallin committed
2387
==== Inline Annotations
2388 2389 2390 2391 2392 2393 2394 2395 2396

There are two ways to customize an
enumeration class:

* split inline annotation
* combined inline annotation

In split inline annotation, the enumeration
value and the enumeration class are customized separately i.e. the
Lukas Jungmann's avatar
Lukas Jungmann committed
2397
`<typesafeEnumMember>` is used independently not as a child element of
2398
`<typesafeEnumClass>`. An example of this is shown in <<ex1>>.
2399 2400 2401

In combined inline annotation, the
enumeration value and the enumeration class are customized together i.e.
Lukas Jungmann's avatar
Lukas Jungmann committed
2402 2403 2404 2405
the `<typesafeEnumMember>` is used as a child element of
`<typesafeEnumClass>`. This is similar to the customization used in
external binding declaration. In this case the `value` attribute must be
present in the `<typesafeEnumMember>` for reasons noted in
2406 2407
<<value-attribute>>. An example of this
customization is shown in <<ex3>>.
2408

Thibault Vallin's avatar
Thibault Vallin committed
2409
==== Customization Overrides
2410 2411 2412 2413

When binding a schema type definitions Java
representation to an enum type, the following customization values
override the defaults specified in Chapter 5. It is specified in a
2414
common section here and referenced from <<Customizable Schema Elements>>.
2415

Lukas Jungmann's avatar
Lukas Jungmann committed
2416 2417
* *name*: If _enumClassName_ is defined, then the
name obtained by mapping _enumClassName_ as specified in
2418
<<Customized Name Mapping>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2419 2420
* *package name*: The name obtained by
inheriting `_packgeName_` from a scope that covers this schema element and
2421
mapping _packageName_ as specified in <<Customized Name Mapping>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2422 2423
* *enumclass javadoc*: `_enumClassJavaDoc_` if
defined, customizes the `class/interface section`
2424 2425
(<<Javadoc Sections>>) for the enumeration
class, as specified in <<Javadoc Customization>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2426
* *enum constant set*: Each member of the set
2427
is computed as follows:
Lukas Jungmann's avatar
Lukas Jungmann committed
2428 2429
** *name*: If _enumMemberName_ is defined, the
name obtained by mapping _enumMemberName_ as specified in
2430
<<Customized Name Mapping>>.
Lukas Jungmann's avatar
Lukas Jungmann committed
2431
** *javadoc*: `_enumMemberJavaDoc_` if defined,
2432 2433 2434
customizes the `field section` (<<Javadoc Sections>>)
for the enumeration class, as specified in
<<Javadoc Customization>>.
2435

Thibault Vallin's avatar
Thibault Vallin committed
2436
==== Customizable Schema Elements
2437 2438

Any XML Schema simple type which has an
Lukas Jungmann's avatar
Lukas Jungmann committed
2439
enumeration facet can be customized with `<jaxb:typesafeEnumClass>`
2440
declaration with the following exception. If the simple type definition
Lukas Jungmann's avatar
Lukas Jungmann committed
2441 2442 2443
derives from `_xs:QName_`. `_xs:NOTATIION_`, `_xs:base64Binary_`, `_xs:hexBinary_`,
`_xs:date_`, `_xs:time_`, `_xs:dateTime_`, `_xs:duration_`, `_xs:gDay_`, `_xs:gMonth_`,
`_xs:gYear_`, `_xs:gMonthDay_`, `_xs:gYearMonth_`, `_xs:IDREF_`, `_xs:ID_`, it must result
2444
in an invalid customization as specified in
2445
<<Invalid Customizations>>. Since most
2446 2447 2448 2449
of these Xml datatypes bind to a mutable Java type, instances of these
Java types are not sufficient to be an immutable value of an enum
constant.

Lukas Jungmann's avatar
Lukas Jungmann committed
2450 2451 2452 2453 2454 2455 2456
[NOTE]
.Design Note
====
The rationale for not allowing a type definition that derives from `xs:ID`
to bind to an enum type is to avoid complicating the resolution of `xs:IDREF`
values to `xs:ID` values. It is easiest if `xs:ID` values are always mapped to
an instance of `java.lang.String`.
2457

Lukas Jungmann's avatar
Lukas Jungmann committed
2458 2459
====

2460
*_Example 1:_* [[ex1, Example 1]]typesafeEnum Customization: Split Inline Annotation +
2461 2462 2463

XML Schema fragment:

Thibault Vallin's avatar
Thibault Vallin committed
2464 2465 2466
[source,xml,indent=4]
----
<xs:simpleType name="USState">
Lukas Jungmann's avatar
Lukas Jungmann committed
2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481
  <xs:annotation><xs:appinfo>
    <jaxb:typesafeEnumClass name="USStateAbbr"/>
  </xs:appinfo></xs:annotation>
  <xs:restriction base="xs:NCName">
    <xs:enumeration value="AK">
      <xs:annotation><xs:appinfo>
        <jaxb:typesafeEnumMember name="STATE_AK"/>
      </xs:appinfo></xs:annotation>
    </xs:enumeration>
    <xs:enumeration value="AL">
      <xs:annotation><xs:appinfo>
        <jaxb:typesafeEnumMember name="STATE_AL"/>
      </xs:appinfo></xs:annotation>
    </xs:enumeration>
  </xs:restriction>
2482
</xs:simpleType>
Thibault Vallin's avatar
Thibault Vallin committed
2483
----
2484 2485 2486

Customized derived code:

Thibault Vallin's avatar
Thibault Vallin committed
2487 2488 2489 2490 2491 2492
[source,java,indent=4]
----
public enum USStateAbbr {
    STATE_AL, STATE_AK;
    public String value() { return name(); }
    public static USStateAbbr fromValue(String value) {...}
2493
};
Thibault Vallin's avatar
Thibault Vallin committed
2494
----
2495

2496
*_Example 2:_* [[ex2, Example 2]]typesafeEnum Customization: External Binding Declaration +
2497 2498 2499 2500

The following example shows how to customize
the above XML schema fragment using an external binding syntax.

Thibault Vallin's avatar
Thibault Vallin committed
2501 2502 2503 2504 2505
[source,xml,indent=4]
----
<jaxb:typesafeEnumClass name="USStateAbbr">
    <jaxb:typesafeEnumMember name="STATE_AK" value="AK"/>
    <jaxb:typesafeEnumMember name="STATE_AL" value="AL"/>
2506
</jaxb:typesafeEnumClass>
Thibault Vallin's avatar
Thibault Vallin committed
2507
----
2508

Lukas Jungmann's avatar
Lukas Jungmann committed
2509 2510 2511
The attribute `value` must be specified for
`<typesafeEnumMember>`. This identifies the enumeration member to which
`<typesafeEnumMember>` applies.
2512

2513
*_Example 3:_* [[ex3, Example 3]]typesafeEnum Customization: Combined Inline Annotation +
2514 2515 2516 2517 2518

The following example shows how to customize
the above XML schema fragment using inline annotation which does not
split the external binding syntax.

Thibault Vallin's avatar
Thibault Vallin committed
2519 2520 2521
[source,xml,indent=4]
----
<xs:simpleType name="USState">
Lukas Jungmann's avatar
Lukas Jungmann committed
2522 2523 2524 2525 2526 2527 2528 2529 2530 2531
  <xs:annotation><xs:appinfo>
    <jaxb:typesafeEnumClass name="USStateAbbr">
      <jaxb:typesafeEnumMember name="STATE_AK" value="AK"/>
      <jaxb:typesafeEnumMember name="STATE_AL" value="AL"/>
    </jaxb:typesafeEnumClass>
  </xs:appinfo></xs:annotation>
  <xs:restriction base="xs:NCName">
    <xs:enumeration value="AK"/>
    <xs:enumeration value="AL"/>
  </xs:restriction>
2532
</xs:simpleType>
Thibault Vallin's avatar
Thibault Vallin committed
2533
----
2534 2535

The attribute value must be specified for
Lukas Jungmann's avatar
Lukas Jungmann committed
2536
`typesafeEnumMember`. This identifies the enumeration member to which
2537 2538
the binding declaration applies.

Lukas Jungmann's avatar
Lukas Jungmann committed
2539
=== `<javadoc>` Declaration
2540

Lukas Jungmann's avatar
Lukas Jungmann committed
2541
The `<javadoc>` declaration allows the
2542 2543 2544 2545 2546 2547
customization of a javadoc that is generated when an XML schema
component is bound to its Java representation.

This binding declaration is not a global XML
element. Hence it can only be used as a local element within the content
model of another binding declaration. The binding declaration in which
Lukas Jungmann's avatar
Lukas Jungmann committed
2548
it is used determines the _section_ of the Javadoc that is customized.
2549

Thibault Vallin's avatar
Thibault Vallin committed
2550
==== Javadoc Sections
2551 2552 2553

The terminology used for the javadoc sections
is derived from Requirements for Writing Java API Specifications which
Lukas Jungmann's avatar
Lukas Jungmann committed
2554
can be found online at `https://www.oracle.com/java/technologies/javase/api-specifications.html`.
2555 2556 2557 2558

The following sections are defined for the
purposes for customization:

Lukas Jungmann's avatar
Lukas Jungmann committed
2559 2560 2561 2562
* package section (corresponds to package specification)
* class/interface section (corresponds to class/interface specification)
* method section (corresponds to method specification)
* field section (corresponds to field specification)
2563

Thibault Vallin's avatar
Thibault Vallin committed
2564
==== Usage
2565

Lukas Jungmann's avatar
Lukas Jungmann committed
2566 2567
Note that the text content of a `<javadoc>`
element must use `CDATA` or `\&lt;` to escape embedded HTML tags.
2568

Thibault Vallin's avatar
Thibault Vallin committed
2569 2570
[source,xml,indent=4]
----
2571
<javadoc>
Thibault Vallin's avatar
Thibault Vallin committed
2572
    Contents in &lt;b>Javadoc&lt;\b> format.
2573
</javadoc>
Thibault Vallin's avatar
Thibault Vallin committed
2574
----
2575 2576 2577

or

Thibault Vallin's avatar
Thibault Vallin committed
2578 2579
[source,xml,indent=4]
----
2580
<javadoc>
Thibault Vallin's avatar
Thibault Vallin committed
2581 2582 2583
    <<![CDATA[
    Contents in <b>Javadoc<\b> format
    ]]>
2584
</javadoc>
Thibault Vallin's avatar
Thibault Vallin committed
2585
----
2586

Thibault Vallin's avatar
Thibault Vallin committed
2587
==== Javadoc Customization
2588 2589

The Javadoc must be generated from the
Lukas Jungmann's avatar
Lukas Jungmann committed
2590 2591
`<javadoc>` element if specified. The Javadoc section depends upon where
`<javadoc>` element is used. JAXB providers may generate additional
2592
provider specific Javadoc information (for example, contents of the
Lukas Jungmann's avatar
Lukas Jungmann committed
2593
`<xs:documentation>` element).
2594

Lukas Jungmann's avatar
Lukas Jungmann committed
2595
=== `<dom>` Declaration
2596

Lukas Jungmann's avatar
Lukas Jungmann committed
2597
The `<dom>` customization binds an XML Schema
2598 2599 2600 2601 2602
component to DOM rather than to a strongly typed Java representation.
Specifically, JAXB bindings for mixed content and wildcard result in a
hybrid mixture of strongly typed Java instances with DOM nodes or
java.lang.String, representing text info. These mixed bindings might be
more easily processed solely as one form, namely as an XML fragment
Lukas Jungmann's avatar
Lukas Jungmann committed
2603
represented as DOM. This customization also meets a Jakarta XML Web Services
2604
databinding requirement from <<Disabling Databinding>>.
2605

Thibault Vallin's avatar
Thibault Vallin committed
2606
==== Usage
2607

Lukas Jungmann's avatar
Lukas Jungmann committed
2608
The syntax for the customization is the following:
2609

Thibault Vallin's avatar
Thibault Vallin committed
2610 2611
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
2612
    <dom [ [type= "w3c" | otherDomRepresentations ] />
Thibault Vallin's avatar
Thibault Vallin committed
2613
----
2614 2615 2616 2617

You can use the optional type attribute to
specify the type of DOM. By default, it is W3C DOM.

Thibault Vallin's avatar
Thibault Vallin committed
2618
==== Customizable Schema Elements
2619 2620 2621 2622

This customization can be attached to the
following XML Schema components:

Lukas Jungmann's avatar
Lukas Jungmann committed
2623 2624 2625 2626 2627
* Element declaration (`<xs:element>`)
* Type definition (`<xs:complexType>` and `<xs:simpleType>`)
* Wildcard (`<xs:any>`)
* Model groups (`<xs:choice>`, `<xs:all>`, `<xs:sequence>`)
* Model group definition (`<xs:group>`)
2628 2629 2630 2631 2632
* Particle

For all of the above cases, the Java
representation of the DOM element is an instance of the Element class
for the specified DOM representation. For example, W3C DOM element is
Lukas Jungmann's avatar
Lukas Jungmann committed
2633
bound to `org.w3c.dom.Element`.
2634

Lukas Jungmann's avatar
Lukas Jungmann committed
2635
Special Case Handling of DOM customization on a:
2636

Lukas Jungmann's avatar
Lukas Jungmann committed
2637
* _type definition_ - it is semantically
2638 2639
equivalent to placing the dom customization on each element declaration
referencing that type definition.
Lukas Jungmann's avatar
Lukas Jungmann committed
2640
* _global element declaration_ - it is
2641
semantically equivalent to placing the dom customization on each element
Lukas Jungmann's avatar
Lukas Jungmann committed
2642
declaration referencing, via `@ref` , the global element declaration.
2643 2644 2645 2646
The dom customization on the global element declaration does not cause
that element to be unmarshalled as DOM when it is the root element of an
XML document nor when the element is part of a wildcard content JAXB
property.
Lukas Jungmann's avatar
Lukas Jungmann committed
2647 2648
* _mixed content_ - if an XML schema
component is annotated with a `dom` customization and that XML schema
2649 2650
component can contain character data information due to its parent
complex type definition being defined with mixed content, character data
2651
information is handled as specified in <<Bind mixed content>>.
2652 2653 2654 2655 2656

The dom customization allows one to disable
databinding and process a part of a document using other technologies
that require raw XML.

Thibault Vallin's avatar
Thibault Vallin committed
2657
==== Examples
2658

Lukas Jungmann's avatar
Lukas Jungmann committed
2659
*_Wildcard Binding Example_*
2660 2661

A wildcard is mapped to a List of
Lukas Jungmann's avatar
Lukas Jungmann committed
2662
`org.w3c.dom.Element`. Each element that matches to the wildcard will
2663 2664
be turned into a DOM tree.

Thibault Vallin's avatar
Thibault Vallin committed
2665 2666 2667
[source,xml,indent=4]
----
<xs:complexType name=foo>
Lukas Jungmann's avatar
Lukas Jungmann committed
2668 2669 2670 2671 2672 2673 2674
  <xs:sequence>
    <xs:any maxOccurs="unbounded" processContents="lax">
      <xs:annotation><xs:appinfo>
        <jaxb:dom/>
      </xs:appinfo></xs:annotation>
    </xs:any>
  </xs:sequence>
2675
</xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
2676 2677 2678 2679 2680 2681 2682 2683
----

[source,java,indent=4]
----
import org.w3c.dom.Element;
public class Foo {
    @XmlAnyElement(lax=false)
    List<Element> getContent() {...}
2684
}
Thibault Vallin's avatar
Thibault Vallin committed
2685
----
2686

Lukas Jungmann's avatar
Lukas Jungmann committed
2687
*_Wildcard and Mixed Content Binding Example_*
2688 2689

If the complexType definition above is
Lukas Jungmann's avatar
Lukas Jungmann committed
2690 2691
defined to have mixed content, due to element *[complexType]* having
attribute `@mixed="true"`, the JAXB binding is:
2692

Thibault Vallin's avatar
Thibault Vallin committed
2693 2694 2695 2696
[source,java,indent=4]
----
import org.w3c.dom.Element;
public class Foo {
Lukas Jungmann's avatar
Lukas Jungmann committed
2697 2698 2699
    /* Element content is represented org.w3c.dom.Element.
     * Character data information is represented as instances of
     * java.lang.String. */
Thibault Vallin's avatar
Thibault Vallin committed
2700 2701 2702
    @XmlMixed
    @XmlAnyElement(lax=false)
    List<Object> getContent() {...}
2703
}
Thibault Vallin's avatar
Thibault Vallin committed
2704
----
2705

Lukas Jungmann's avatar
Lukas Jungmann committed
2706
=== `<inlineBinaryData>` Declaration
2707

Lukas Jungmann's avatar
Lukas Jungmann committed
2708
The `<inlineBinaryData>` customization
2709
provides declarative control over the optimization for binary data
2710
described in <<Enhanced Binary Data Handling>>.
2711

Thibault Vallin's avatar
Thibault Vallin committed
2712
==== Usage
2713 2714 2715 2716

The syntax for the customization is the
following:

Thibault Vallin's avatar
Thibault Vallin committed
2717 2718
[source,xml,indent=4]
----
Lukas Jungmann's avatar
Lukas Jungmann committed
2719
<inlineBinaryData/>
Thibault Vallin's avatar
Thibault Vallin committed
2720
----
2721 2722 2723 2724 2725 2726 2727

This customization disables considering the
binary data optimization for a schema component containing binary data.

This customization can be attached to the
following XML Schema components:

Lukas Jungmann's avatar
Lukas Jungmann committed
2728 2729 2730
* Element declaration (`<xs:element>`) with binary data or
* Type definition (`<xs:complexType>` and
`<xs:simpleType>`) deriving from binary datatype
2731 2732

When a schema component that binds to a JAXB
Lukas Jungmann's avatar
Lukas Jungmann committed
2733 2734 2735 2736
property is customized with `<inlineBinaryData>`, its schema-derived JAXB
property is annotated with `@XmlInlineBinaryData`. When a type
definition is customized with `<inlineBinaryData>`, its schema-derived
class is annotated with program annotation `@XmlInlineBinaryData`.
2737

Lukas Jungmann's avatar
Lukas Jungmann committed
2738
=== `<factoryMethod>` Declaration
2739

Lukas Jungmann's avatar
Lukas Jungmann committed
2740
The `<factoryMethod>` customization provides
2741
declarative control over an element or type factory method name
Lukas Jungmann's avatar
Lukas Jungmann committed
2742
generated in a packages `ObjectFactory` class introduced in
2743
<<Java Package>>. This customization is
2744
useful to resolve name collisions between factory methods in the
Lukas Jungmann's avatar
Lukas Jungmann committed
2745
schema-derived `ObjectFactory` class.
2746

Thibault Vallin's avatar
Thibault Vallin committed
2747
==== Usage
2748 2749 2750 2751

The syntax for the customization is the
following:

Thibault Vallin's avatar
Thibault Vallin committed
2752 2753 2754 2755
[source,xml,indent=4]
----
<factoryMethod name=BaseForFactoryMethodName/>
----
2756 2757 2758

The customization value defined is:

Lukas Jungmann's avatar
Lukas Jungmann committed
2759
* `_name_` - each character of name must be a
2760
valid part of a Java identifier as determined by
Lukas Jungmann's avatar
Lukas Jungmann committed
2761
`java.lang.Character.isJavaIdentifierPart()`.
2762 2763 2764 2765

The name of the factory method is generated
by concatenating the following components:

Lukas Jungmann's avatar
Lukas Jungmann committed
2766 2767
* The string constant `create`
* ``@name``s value
2768

Thibault Vallin's avatar
Thibault Vallin committed
2769
===== Usage Constraints
2770

Lukas Jungmann's avatar
Lukas Jungmann committed
2771
The usage constraints on `<factoryMethod>`
2772
are specified below. Any constraint violation must result in an invalid
2773 2774
customization as specified in <<Invalid Customizations>>.
The usage constraints are:
2775

Lukas Jungmann's avatar
Lukas Jungmann committed
2776
. `<factoryMethod>` is only allowed to
2777 2778 2779 2780 2781 2782 2783 2784
annotate an element declaration or a type definition.

Note that this customization does not require
a factory method to be generated, it simply provides a factory method
name if a factory method is to be generated for the annotated element
declaration or type definition. Section 6 and 7 specifies when a factory
method is generated for an element declarations or type definitions.

Thibault Vallin's avatar
Thibault Vallin committed
2785
=== Annotation Restrictions
2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805

[XSD PART 1] allows an annotation element to
be specified for most elements but is ambiguous in some cases. The
ambiguity and the way they are addressed are described here.

The source of ambiguity is related to the
specification of an annotation element for a reference to a schema
element using the ref attribute. This arises in three cases:

* A local attribute references a global
attribute declaration using the ref attribute.
* A local element in a particle references a
global element declaration using the ref attribute.
* A model group in a particle references a
model group definition using the ref attribute.

For example in the following schema fragment
(for brevity, the declaration of the global element Name and Address
has been omitted).

Thibault Vallin's avatar
Thibault Vallin committed
2806 2807 2808
[source,xml,indent=4]
----
<xs:element name = "Customer">
Lukas Jungmann's avatar
Lukas Jungmann committed
2809 2810 2811 2812
  <xs:complexType>
    <xs:element ref = "Name"/>
    <xs:element ref = "Address" />
  </xs:complexType>
Thibault Vallin's avatar
Thibault Vallin committed
2813 2814
</xs:element>
----
2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832

XML Schema spec is ambiguous on whether an
annotation element can be specified at the reference to the Name
element.

The restrictions on annotation elements has
been submitted as an issue to the W3C Schema Working Group along with
JAXB technology requirements (which is that annotations should be
allowed anywhere). Pending a resolution, the semantics of annotation
elements where the XML spec is unclear are assumed as specified as
follows.

This specification assumes that an annotation
element can be specified in each of the three cases outlined above.
Furthermore, an annotation element is assumed to be associated with the
abstract schema component as follows:

* The annotation element on an attribute ref
Lukas Jungmann's avatar
Lukas Jungmann committed
2833
is associated with {Attribute Use}
2834
* The annotation element on a model group ref
Lukas Jungmann's avatar
Lukas Jungmann committed
2835
or an element reference is associated with the {particle}.
2836