spec/src/main/asciidoc/ch07-customize_xml_schema.adoc

//
// Copyright (c) 2020 Contributors to the Eclipse Foundation
//

== [[a1498]]Customizing XML Schema to Java Representation Binding

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
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.

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
which defines constructs referred to as binding declarations. A binding
declaration can be used to customize the default binding between an XML
schema component and its Java representation.

http://java.sun.com./xml/ns/jaxb[The schema
for binding declarations is defined in the namespace]
_http://java.sun.com/xml/ns/jaxb_ . This specification uses the
namespace prefix “ _jaxb_ ” to refer to the namespace of binding
declarations. For example,

<jaxb: binding declaration>

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:

* as part of the source schema (inline
annotated schema)
* external to the source schema in an
external binding declaration.

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.

=== Extending the Binding Language

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
global attribute _<jaxb:extensionBindingPrefixes>_ within an instance of
_<xs:schema>_ element. The value of this attribute is a
whitespace-separated list of namespace prefixes. The namespace bound to
each of the prefixes is designated as a customization declaration
namespace. Prefixes are resolved on the _<xs:schema>_ element that
carries this attribute. It is an error if the prefix fails to resolve.
This feature is quite similar to the extension-element-prefixes
attribute in [XSLT 1.0] _http://www.w3.org/TR/xslt10/#extension_ ,
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.

=== Inline Annotated Schema

This method of customization utilizes on the
_<appinfo>_ element specified by the XML Schema [XSD PART 1]. A binding
declaration is embedded within the _<appinfo>_ element as illustrated
below.

<xs:annotation> +
<xs:appinfo> +
_<binding declaration> +
_ </xs:appinfo> +
</xs:annotation>

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

=== External Binding Declaration

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
_<jaxb:bindings>_ element enables the specification of a remote schema
context to associate its binding declaration(s) with. Minimally, an
external binding declaration follows the following format.

<jaxb:bindings [schemaLocation =
"xs:anyURI"]> +
<jaxb:bindings [node = "xs:string"]>* +
<binding declaration> +
<jaxb:bindings> +
</jaxb:bindings>

The schemaLocation attribute is optional for
specifying _<jaxb:globalBindings>_ , and The node attribute is optional
for specifying _<jaxb:schemaBindings>_ . The attributes _schemaLocation_
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 node’s
_<xs:appinfo>_ element. The attribute values are interpreted as follows:

*  _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
be found in link:jaxb.html#a4821[See Example].”

=== Restrictions

* The external binding element
_<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
root is referred to as an external binding declaration file.
* The top-most _<jaxb:binding>_ element
within an _<xs:appinfo>_ element or the root element of an external
binding file must have its _schemaLocation_ attribute set.

=== Version Attribute

The normative binding schema specifies a
global _version_ attribute. It is used to identify the version of the
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
_version should_ be _"2.0"._ It is also valid for @version to be “1.0”.
If any other version is specified, it must result in an invalid
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].”

The _version_ attribute must be specified in
one of the following ways:

* If customizations are specified in inline
annotations, the _version_ attribute must be specified in _<xs:schema>_
element of the source schema. For example,



 <xs:schema jaxb:version="2.0">

* If customizations are specified in an
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
version can be specified either as



 <jaxb:bindings version="2.0" ... />

or

 <jaxb:bindings jaxb:version="2.0" ... />

Specification of both _version_ and
_<jaxb:version>_ must result in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].”

=== [[a1544]]Invalid Customizations

A non conforming binding declaration is a
binding declaration in the _jaxb_ namespace but does not conform to this
specification. A non conforming binding declaration results in a
customization error. The binding compiler must report the customization
error. The exact error is not specified here. For additional
requirements see link:jaxb.html#a3815[See Compatibility].”

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
link:jaxb.html#a4270[See Normative Binding Schema Syntax].” in
addition to the other normative text within this chapter. All examples
are non-normative.

* 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
zero or more.
* The prefix _xs:_ is used to refer to schema
components in W3C XML Schema namespace.
* In examples, the binding declarations as
well as the customized code are shown in bold like this: <appinfo>
<annotation> or getAddress().

=== 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.

=== Scope

When a customization value is defined in a
binding declaration, it is associated with a scope. A scope of a
customization value is the set of schema elements to which it applies.
If a customization value applies to a schema element, then the schema
element is said to be covered by the scope of the customization value.
The scopes are:

* global scope: A customization value defined
in _<globalBindings>_ has global scope. A global scope covers all the
schema elements in the source schema and (recursively) any schemas that
are included or imported by the source schema.
* schema scope: A customization value defined
in <schemaBindings> has schema scope. A schema scope covers all the
schema elements in the target namespace of a schema.
* definition scope: A customization value in
binding declarations of a type definition or global declaration has
definition scope. A definition scope covers all schema elements that
reference the type definition or the global declaration. This is more
precisely specified in the context of binding declarations later on in
this chapter.
* component scope: A customization value in a
binding declaration has component scope if the customization value
applies only to the schema element that was annotated with the binding
declaration.

image:images/xmlb-18.png[image]

=== Scoping Inheritance and Overriding For Binding Declarations

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.

=== XML Schema Parsing

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.
link:jaxb.html#a2217[See Annotation Restrictions]” outlines how
these are addressed.

* 

=== [[a1580]] _<globalBindings>_ Declaration

The customization values in “<
_globalBindings>_ ” binding declaration have global scope. This binding
declaration is therefore useful for customizing at a global level.

=== [[a1582]]Usage

<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" | +
"generateName" | "generateError" ] +
[ 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" ] +
[ localScoping = "nested" | "toplevel" ] > +
[ <javaType> ... </javaType> ]* +
[ <serializable uid=”xxxx”/> ]* +
</globalBindings>

The following customization values are
defined in global scope:

*  _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
specified , defines the customization value
_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"_ .
Consider customizing using the newly introduced _optionalProperty_
before using this JAXB 1.0 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
constraint checking when setting a property is performed as described in
link:jaxb.html#a541[See Properties]". The default value is
_"false"_ .
*  _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
QNames, each of which must resolve to a simple type definition. Only
simple type definitions with an enumeration facet and a restriction base
type listed in _typesafeEnumBase_ or derived from a type listed in
_typesafeEnumBase_ is bound to a _typesafeEnumClass_ by default as
specified in link:jaxb.html#a829[See Enum Type]". The default
value of _typesafeEnumBase_ is _“xs:string”._

The _typesafeEnumBase_ cannot contain the
following simple types and therefore a JAXB implementation is not
required to support the binding of the these types to typesafe
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
invalid customization as specified in link:jaxb.html#a1544[See
Invalid Customizations].” JAXB implementation must be capable of binding
any other simple type listed in _typesafeEnumBase_ to a typesafe
enumeration class.

*  _typesafeEnumMemberName_ if specified,
defines the customization value _typesafeEnumMemberName._ The value must
be one of _skipGeneration_ , _generateError_ or _generateName._ The
default value is _skipGeneration_ . See link:jaxb.html#a1633[See
@typesafeEnumMemberName]” for details.
*  _typesafeEnumMaxMembers_ if specified,
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
attributes type is _xs:int_ and its default value is _256_ .
*  _generateElementClass_ if specified as
true, a schema-derived Element class, as specified in
link:jaxb.html#a657[See Java Element Class]”, is generated for
each element declaration that has an element factory method generated
for it. Its default value is false.
*  _generateElementProperty_ if specified as
true, controls the generation of JAXBElement property. The value must be
one of "true", "false", "1", or "0". The default is absence of the
value.
*  _generateValueClass_
 if specified as true, a
schema-derived Java value class is generated for each complex type
definiton.Value class is specified in link:jaxb.html#a521[See
Value Class]. If generateValueClass is specified as false, a
schema-derived interface and implementation class is generated for each
complex type definition as specified in link:jaxb.html#a536[See
Java Content Interface]”. The attribute’s default value is true. See
examples of this binding in link:jaxb.html#a1617[See
generateElementClass and generateValueClass]”.
* zero or more _javaType_ binding
declarations. Each binding declaration must be specified as described in
link:jaxb.html#a1981[See <javaType> Declaration].”
* zero or one serializable binding
declaration.
*  _optionalProperty_
 controls how a JAXB property with a
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 attribute’s value is
"primitive", it binds as it did in JAXB 1.0. If the attribute’s 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 attribute’s default value is “wrapper”.
*  _mapSimpleTypeDef_ controls whether a JAXB
mapped class should be generated for each simple type definition as
specified in link:jaxb.html#a803[See Bind to a JAXB mapped
class]”. This attribute’s default value is _false_ . This customization
eases preserving simple type substituting precisely as described in
link:jaxb.html#a1158[See Type Substitution of a Simple Type
Definition]”.
*  _localScoping_ attribute can have the
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
this attribute is _nested_ . A developer can customize _localScoping_ to
_toplevel_ w hen schema components nest too deeply or an application
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.

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.

=== [[a1608]]Customized Name Mapping

A customization value can be used to specify
a name for a Java object (e.g. class name, package name etc.). In this
case, a customization value is referred to as a customization name.

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
Language Specification, Second Edition, Section 6.8, “Naming
Conventions”]. The customization value enableJavaNamingConventions
determines if a customization name is mapped to a Java identifier that
follows Java language naming conventions or not.

If enableJavaNamingConventions is defined and
the value is _"true"_ or _"1",_ then the customization name (except for
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
link:jaxb.html#a4816[See Conforming Java Identifier Algorithm]”;
otherwise the customized name must be used as is.

=== [[a1613]]Underscore Handling

The _[jaxb:globalBindings]_ attribute
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
_"asWordSeparator"_ and categorizes underscore, ‘_’, as a punctuation
mark in the XML name to Java identifier algorithm specified in Appendix
link:jaxb.html#a4656[See The Name to Identifier Mapping
Algorithm]. The resulting algorithm transforms one or more consecutive
underscores in an XML name to camel case separated words in the derived
Java class and method names. Examples of this mapping are in
link:jaxb.html#a4734[See XML Names and derived Java Class,
Method, and Constant Names].

When @ _underscoreBinding_ is
_"asCharInWord",_ underscore (‘_’) is considered a special letter within
a word. The result is that all underscore characters from the original
XML name are preserved in the derived Java identifier. Example of this
mapping are in link:jaxb.html#a4755[See XML Names and derived
Java Class, Method, and Constant Names when <jaxb:globalBindings
underscoreHandling=”asCharInWord”>].

=== [[a1617]]generateElementClass and generateValueClass

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

=== Default Binding to a value class.

Schema fragment:

<xs:complexType name=”USAddress”> +
<xs:attribute name=”City” type=”xs:string”/>

</xs:complexType>

 Default Value Class:

public class USAddress \{ +
public USAddress() \{... } +
public String getCity() \{....} +
public void setCity(String value) \{...} +
... +
}

Customization _<jaxb:globalBinding
generateValueClass=”false”>_ generates following interface instead of
default value class:

=== Customized binding to an interface.

public interface USAddress \{ +
String getCity(); +
void setCity(String value); +
}

=== Generation of an Element Class

Schema fragment:

<xs:element name=”Address”
type=”USAddress”/> +
 +
// Default Java binding of global element to element instance factory +
public ObjectFactory \{ +
JAXBElement<USAddress> createAddress(USAddress value); +
}

 _<jaxb:globalBinding
generateElementClass=”true”/>_ results in generation of following
Element class:

 +
public class Address extends JAXBElement<USAddress> \{ +
}

=== [[a1633]]@typesafeEnumMemberName

.If there is a collision among the generated
constant fields _name_ or if it is not possible to generate a legal Java
identifier for one or more of the generated constant field names, then
the binding is determined based on the value of @
_typesafeEnumMemberName_ of element _[jaxb:globalBindings]_ .

*  _skipGeneration +
_ An enum type is not generated. This is the default behavior if
_typesafeEnumMemberName_ has not been specified. A binding compiler may
report a warning on why the simple type definition was not bound to an
enum type.
*  _generateName +
_ The constant fields _name_ is “ _VALUE__ _<N>_ _"_ where _<N>_ is 1
for the first enumeration value and increments by 1 to represent each
value within the XML enumeration.
*  _generateError +
_ An error must be reported.

=== <serializable> Declaration

When the serializable customization is
specified, all schema-derived classes implement _java.io.Serializable_ .
Each class is generated with a _serialVersionUID_ field set to the value
specified by _@uid_ .

private static final long serialVersionUID =
_<value of @uid>_ ;

The JAXB user is required to identify when
schema-derived classes do not follow
_http://java.sun.com/j2se/1.4.2/docs/guide/serialization/spec/version.html#wp4602[Java
serialization class evolution rules]_ and change the generated
_serialVersionUID_ field by changing the [serializable] element’s
attribute _@uid_ value.

=== @generateElementProperty

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:

*  _true: +
_ Always generate properties to use JAXBElement, unless overriden by
_<jaxb:property generateElementProperty=”false”/>_ on individual
property.
*  _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
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.)

===  _<schemaBindings>_ Declaration

The customization values in
_<schemaBindings>_ binding declaration have schema scope. This binding
declaration is therefore useful for customizing at a schema level.

=== Usage

<schemaBindings [ map="boolean" ] >

{empty} [ <package> package </package> ]

 [ <nameXmlTransform> ... </nameXmlTransform>
]*

</schemaBindings>



{empty}<package [ name = "packageName" ]

{empty} [ <javadoc> ... </javadoc> ]

</package>



<nameXmlTransform>

{empty} [ <typeName [ suffix="suffix" ]

{empty} [ prefix="prefix" ] /> ]

{empty} [ <elementName [ suffix="suffix" ]

{empty} [ prefix="prefix" ] /> ]

{empty} [ <modelGroupName [ suffix="suffix" ]

{empty} [ prefix="prefix" ] /> ]

{empty} [ <anonymousTypeName [
suffix="suffix" ]

{empty} [ prefix="prefix" ] /> ]

</nameXmlTransform>

For readability, the _<nameXmlTransform>_ and
_<package>_ elements are shown separately. However, they are local
elements within the _<schemaBindings>_ element.

The following customizations are defined in
the schema scope:

*  _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.

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

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.

If one source schema includes (via the
include mechanism specified by XSD PART 1) a second source schema, then
the _<schemaBindings>_ declaration must be declared in the first
including source schema. It should be noted that there is no such
restriction on _<schemaBindings>_ declarations when one source schema
imports another schema since the scope of _<schemaBindings>_ binding
declaration is schema scope.

=== package __ [[a1674]]

Usage

*  _name_ if specified, defines the
customization value _packageName_ . _packageName_ must be a valid Java
package name.
* < _javadoc>_ if specified, customizes the
package level Javadoc. < _javadoc>_ must be specified as described in
link:jaxb.html#a2142[See <javadoc> Declaration].” The Javadoc
must be generated as specified in link:jaxb.html#a2163[See
Javadoc Customization].” The Javadoc section customized is the _package
section._
* 

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
no effect.

=== Example: Customizing Package Name

<jaxb:schemaBindings>

 <jaxb:package name = "org.example.po" />

</jaxb:schemaBindings>

specifies “ _org.example.po_ ” as the package
to be associated with the schema.

===  _nameXmlTransform_

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:

<xs:element name="bindingTemplate"
type="uddi:bindingTemplate"/>

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.
Hence the binding declaration _nameXmlTransform_ is being provided to
automate name collision resolution.

The _nameXmlTransform_ allows a _suffix_ and
a _prefix_ to be specified on a per symbol space basis. The following
symbol spaces are supported:

*  _<typeName>_ for the symbol space “type
definitions”
*  _<elementName>_ for the symbol space
“element definitions”
*  _<modelGroupName>_ for the symbol space
“model group definitions.”
*  _<anonymousTypeName>_ for customizing Java
value class to which an anonymous type is bound.link:#a5377[26]

If _suffix_ is specified, it must be appended
to all the default XML names in the symbol space. The _prefix_ if
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.

By using a different _prefix_ and/or _suffix_
for each symbol space, identical names in different symbol spaces can be
transformed into non-colliding XML names.

 _anonymousTypeName_

The _<anonymousTypeName>_ declaration can be
used to customize the suffix and prefix for the Java value class. If
_prefix_ is specified, then it must be prepended to the Java value class
name for the anonymous type. If suffix is specified, it must be
appended.

===  _<class>_ [[a1698]] Declaration

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
dependency upon the runtime of the binding framework. Since a runtime
was not specified for JAXB 1.0 interface/implementation binding, the
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.

=== Usage

{empty}<class [ name = " _className_ " ]

{empty} [ implClass = " _implClass_ " ]> +
[ ref = " _className_ " ]

{empty} [ <javadoc> _..._ </javadoc> ]

</class>

*  _className_ is the name of the derived
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
current value of package _._
*  _implClass_ if specified, is the name of
the implementation class for _className_ and must include the complete
package name. Note that this customization only impacts the return value
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
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
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
specified as described in link:jaxb.html#a2142[See <javadoc>
Declaration].”

=== [[a1713]]Customization Overrides

When binding a schema element’s 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
link:jaxb.html#a1718[See Customizable Schema Elements].”

* name: The name is _className_ if specified.
* package name: The name of the package is
_packageName_ inherited from a scope that covers this schema element. +
 +
NOTE: The _packageName_ is only set in the <package> declaration. The
scope of _packageName_ is schema scope and is thus inherited by all
schema elements within the schema.
* javadoc: The Javadoc must be generated as
specified in section link:jaxb.html#a2163[See Javadoc
Customization].” The Javadoc section customized is the _class/interface
section._

=== [[a1718]]Customizable Schema Elements

=== Complex Type Definition

When _<class>_ customization specified in the
annotation element of the complex type definition, the complex type
definition must be bound to a Java value class as specified in
link:jaxb.html#a933[See Java value class]” applying the
customization overrides as specified in link:jaxb.html#a1713[See
Customization Overrides].”

=== Example: Class Customization: Complex Type Definition To Java value class

XML Schema fragment:

<xs:complexType name="USAddress"> +
<xs:annotation> <xs:appinfo> +
<jaxb:class name="MyAddress" /> +
</xs:appinfo></xs:annotation> +
<xs:sequence>...</xs:sequence> +
<xs:attribute name="country" type="xs:string"/> +
</xs:complexType>

Customized code:

// public class USAddress \{ // Default Code

public class MyAddress \{ // Customized Code

 public String getCountry()\{...}

 public void setCountry(String value)\{...}

 ...

}

=== Simple Type Definition

When _<class>_ customization specified in the
annotation element of a simple type definition, the simple type
definition must be bound to a Java value class as specified in
link:jaxb.html#a803[See Bind to a JAXB mapped class]” applying
the customization overrides as specified in
link:jaxb.html#a1713[See Customization Overrides].”

=== Example: Class Customization: Simple Type Definition To Java value class

XML Schema fragment:

<xs:simpleType name="SKU"> +
<xs:annotation> <xs:appinfo> +
<jaxb:class/> +
</xs:appinfo></xs:annotation> +
<xs:restriction base=”xs:int”/> +
</xs:simpleType>

Customized code:

public class SKU \{ +
@XmlValue +
public int getValue()\{...} +
public void setValue(int value)\{...} +
... +
}

=== Model Group Definition

It is invalid to place a _<jaxb:class>_
customization on a model group.

=== Model Group

It is invalid to place a _<jaxb:class>_
customization on an unnamed model group.

=== Global Element Declaration

A < _class_ > declaration is allowed in the
annotation element of the global element declaration. However, the
_implClass_ attribute is not allowed. The global element declaration
must be bound as specified in link:jaxb.html#a1068[See Bind to
Element Class]” applying the customization overrides specified in
link:jaxb.html#a1713[See Customization Overrides].”

=== Example: Class Customization: Global Element to Class

XML Schema Fragment:

<xs:complexType name="AComplexType">

 <xs:sequence>

 <xs:element name="A" type="xs:int"/>

 <xs:element name="B" type="xs:string"/>

 </xs:sequence>

</xs:complexType>

<xs:element name="AnElement"
type="AComplexType">

 <xs:annotation><xs:appinfo>

 <jaxb:class name="MyElement"/>

 </xs:appinfo></xs:annotation>

</xs:element>

Customized code:

// following class is generated because of
customization

public class AComplexType \{ +
void setA(int value) \{...}

 int getA()\{...}

 void setB(String value)\{...}

 String getB()\{...}

}

public class MyElement extends
JAXBElement<AComplexType> \{...}

public class ObjectFactory \{

 // Default code

 // JAXBElement<AnElement>
createAnElement(AnElement)\{...} +
 +
// Customized code

 MyElement createMyElement(AnElement)\{...} +
... other factory methods ...

}

=== Local Element

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).

A _<class>_ declaration is allowed in the
annotation element of a local element. link:jaxb.html#a2217[See
Annotation Restrictions]” contains more information regarding the
annotation element for a local element reference. However, the
_implClass_ attribute is not allowed.

A _<class>_ customization on local element
reference must result in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations]” since a local
element reference is never bound to a Java Element class.

A _<class>_ customization on local element
declaration applies only when a local element declaration is bound to a
Java Element class. Otherwise it must result in an invalid customization
as specified in link:jaxb.html#a1544[See Invalid
Customizations].” If applicable, a local element must be bound as
specified in link:jaxb.html#a1040[See Bind to JAXBElement<T>
Instance]” applying the customization overrides as specified in
link:jaxb.html#a1713[See Customization Overrides].”

=== Example: Class Customization: Local Element Declaration To Java Element

The following example is from
link:jaxb.html#a1359[See Examples].”

XML Schema fragment:

<xs:complexType name="Base"> +
<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> +
</xs:complexType>

Customized code:

import jakarta.xml.bind.JAXBElement; +
public class ObjectFactory \{ +
// element instance factories only +
// JAXBElement<String> createBaseA(String value); //default code +
JAXBElement<String> createBaseBar(String value); //Customized +
JAXBElement<String> createBaseB(String value); +
JAXBElement<Integer> createBaseC(Integer value); +
} +
public class Base \{ +
static public class Bar extends JAXBElement<String> \{...}// Customized
code +
/** +
* A general content list that can contain element +
* instances of JAXBElement<String> or JAXBElement<Integer>. +
*/ +
List<Object> getBarOrBOrC()\{...} +
}

=== [[a1783]] _<property>_ Declaration

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
element the < _property>_ binding declaration is specified.

=== [[a1786]]Usage

<property [ name = "propertyName" ] +
[ collectionType = " _propertyCollectionType_ " ] +
[ fixedAttributeAsConstantProperty = "true" | "false" | "1" | "0" ] +
[ generateIsSetMethod = "true" | "false" | "1" | "0" ] +
[ enableFailFastCheck="true" | "false" | "1" | "0" ] +
[ generateElementProperty= “true” | “false” | “1” | “0” ] +
[ attachmentRef = “resolve” | “doNotResolve” | “default” ] +
[ <baseType name=”fully qualified Java class”> ... </baseType> ] +
[ <javadoc> ... </javadoc> ] +
</property> +
 +
<baseType name=”fully qualified Java class”> +
<javaType> ... </javaType> +
</baseType>

For readability, the _<baseType>_ element is
shown separately. However, it can be used only as a local element within
the _<property>_ element.

The use of this declaration is subject to the
constraints specified in link:jaxb.html#a1825[See Usage
Constraints].”

The customization values defined are:

*  _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
specified , defines the customization value
_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,
controls the generation of JAXBElement property. The value must be one
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
attached to local or global attribute declarations. This customization
affects the binding as follows. 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.)
*  _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
“default”. This mode defers to default processing as specified in
link:jaxb.html#a5147[See Binding WS-I Attachment Profile
ref:swaRef]”. +
 +
When _@attachmentRef_ value is _resolve_ and the property’s base type is
or derives from _xsd:anyURI_ , the schema-derived JAXB property has a
base type of _javax.activation.DataHandler_ and the property is
annotated with _@XmlAttachmentRef_ . +
 +
Disabling autoresolving an element/attribute of type _ref:swaRef_ : +
When _@attachmentRef_ value is _doNotResolve_ and the property’s 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 property’s getter method. _<javadoc>_
must be specified as described in link:jaxb.html#a2142[See
<javadoc> Declaration].”

===  _baseType_ [[a1801]]

The _<baseType>_ element is intended to allow
the customization of a base type for a JAXB property. This element can
only be a child of <jaxb:property> element.

<baseType name=”fully qualified Java
class”> +
<javaType> ... </javaType> +
</baseType>



The _@name_ attribute enables either the
specialization or generalization of the default base type binding for a
JAXB property. Child element _<javaType>_ is used to convert the default
base type to a Java class. These two mutual exclusive usages of the
<baseType> customization are described below.

=== Conversion using Child element <javaType>

Optional child element < _javaType>_ , if
specified, defines the customization value _javaType_ and must be
specified as defined in link:jaxb.html#a1981[See <javaType>
Declaration].” The customization value defined has component scope. This
customization converts the default base type’s value for a simple type
definition to the Java class specified by <javaType> name.

The schema-derived JAXB property is annotated
with _@XmlJavaTypeAdapter_ specified in Section 8.
_@XmlJavaTypeAdapter.value()_ is set to a generated
classlink:#a5378[27] that extends
_jakarta.xml.bind.annotation.adapter.XmlAdapter_ . The generated class’
_unmarshal_ method must call the <javaType> customization’s parse
method, which is specified in link:jaxb.html#a1981[See
<javaType> Declaration]. The generated class’ _marshal_ method must call
the <javaType> customization’s print method.

=== [[a1809]]Generalize/Specialize baseType with attribute @name

The _name_ attribute for _<baseType>_ enables
more precise control over the actual base type for a JAXB property. This
customization enables specifying an alternative base type than the
property’s 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.

The _name_ attribute value must be a fully
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
possible valid type substitutions, the _name_ attribute should be
_java.lang.Object_ . However, if for example, it is known that all type
substitutions will share a more specific Java super interface/class than
_java.lang.Object_ , that Java class name can be used achieve a stronger
typed binding. With this customization, the JAXB annotation generated
for the property’s _@XmlElement.type()_ or _@XmlAttribute.type()_ is
still the default Java datatype for the element/attribute’s
schema-defined type.

The schema-derived customized JAXB property
is annotated, either explicitly or by default mapping annotations, with
the mapping annotation _@XmlElement_ , specified in Section 8.10.1. The
_@XmlElement_ annotation element type is derived in terms of the
abstract model properties for a element type definition summarized in
link:jaxb.html#a4937[See Element Declaration Schema Component]
as follows:

=== Annotate JAXB property with @XmlElement element-value pairs

[width="100%",cols="50%,50%",options="header",]
|===
|@XmlElement element
|@XmlElement value
|type |the java
type binding of the element declaration’s _\{type definition}_
|===

Note that the Java class for
_@XmlElement.type()_ can differ from the recommended JAXB property’s
base type to enable type substitution of java.lang.Object. This binding
enables unmarshalling of the Element’s simple content when it is not
qualified with an _xsi:type_ as the element’s schema-declared type.
_@XmlElement.type()_ acts as the default _xsi:type_ for a JAXB property
where the property’s 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
example, an XML element or attribute of _xs:IDREF_ binds to
_java.lang.Object_ by default as specified in
link:jaxb.html#a1290[See Binding an IDREF component to a Java
property]”. If the schema only intends the reference to be to an element
that binds to a specific type, the baseType @name schema customization
can be used to specialize the binding.

=== [[a1820]]Specialize binding of an IDREF via customization

Given XML Schema fragment:

<xs:complexType name="Book"> +
<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> +
</xs:complexType> +
<xs:complexType name="AuthorBio"> +
<xs:sequence><!-- ... --> </xs:sequence> +
_<xs:attribute name="name" type="xs:ID"/> +
_ </xs:complexType>

Schema-derived Java value class:

public class Book \{ +
@XmlIDREF +
AuthorBio getAuthor() \{...} +
void setAuthor(AuthorBio referencedObj)\{...} +
} +
public class AuthorBio\{ +
@XmlID +
String getName()\{...} +
void setName(String value)\{...} +
}

=== [[a1825]]Usage Constraints

The usage constraints on _<property>_ are
specified below. Any constraint violation must result in an invalid
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].” The usage constraints are:

. The _<baseType>_ is only allowed with the
following XML schema elements from the link:jaxb.html#a1857[See
Customizable Schema Elements]”:
. Local Element,
link:jaxb.html#a1913[See Local Element].”
. Local Attribute,
link:jaxb.html#a1861[See Local Attribute].”
. ComplexType with simpleContent,
link:jaxb.html#a1976[See ComplexType].”
. <baseType> can either have a name attribute
or a <javaType>, they both can not exist at the same time.
. The _fixedAttributeAsConstantProperty_ is
only allowed with a local attribute, link:jaxb.html#a1861[See
Local Attribute]" , that is fixed.
. If a _<property>_ declaration is associated
with the _<complexType>_ , then a _<property>_ customization cannot be
specified on the following schema elements that are scoped to
_<complexType>_ :
. Local Element
. Model group
. Model Group Reference

The reason is that a _<property>_ declaration
associated with a complex type binds the content model of the complex
type to a general content property. If a _<property>_ declaration is
associated with a schema element listed above, it would create a
conflicting customization.

* 

=== Example: Property Customization: simple type customization

<xs:complexType name="internationalPrice"> +
.... +
<xs:attribute name="currency" type="xs:string"> +
<xs:annotation> <xs:appinfo> +
<jaxb:property> +
<jaxb:baseType> +
<jaxb:javaType name="java.math.BigDecimal" +
parseMethod="jakarta.xml.bind.DatatypeConverter.parseInteger" +
printMethod="jakarta.xml.bind.DatatypeConverter.printInteger"/> +
</jaxb:baseType> +
</jaxb:property> +
</xs:appinfo></xs:annotation> +
</xs:attribute> +
</xs:complexType>

The code generated is:

public class InternationalPrice \{

 // String getCurrency(); default

 java.math.BigDecimal getCurrency()\{...} //
customized

 public void setCurrency(java.math.BigDecimal
val)\{...} // customized

}

=== [[a1847]]Customization Overrides

When binding a schema element’s Java
representation to a property, the following customization values
override the defaults specified in Chapter 6. It is specified in a
common section here and referenced from link:jaxb.html#a1857[See
Customizable Schema Elements].”

* name: If propertyName is defined, then it
is the name obtained by mapping the name as specified in
link:jaxb.html#a1608[See Customized Name Mapping].”
* base type: The basetype is
_propertyBaseType_ if defined. The propertyBaseType is defined by a XML
schema element in link:jaxb.html#a1857[See Customizable Schema
Elements].”
* collection type: The collection type is
_propertyCollectionType_ if specified; otherwise it is the
_propertyCollectionType_ inherited from a scope that covers this schema
element.
* javadoc: The Javadoc must be generated as
specified in section link:jaxb.html#a2163[See Javadoc
Customization].” The Javadoc section customized is the _method section._
* 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
class.

The following does not apply if local
attribute is being bound to a constant property as specified in
link:jaxb.html#a1861[See Local Attribute]”:

* If generateIsSetMethod is “true” or “1”,
then additional methods as specified in link:jaxb.html#a610[See
isSet Property Modifier]” must be generated.
* If enableFailFastCheck is “true” or “1”
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.

=== [[a1857]]Customizable Schema Elements

=== Global Attribute Declaration

A < _property_ > declaration is allowed in
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
covers all local attributes (link:jaxb.html#a1861[See Local
Attribute]”) that can reference this global attribute declaration. This
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.

=== [[a1861]]Local Attribute

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).

A < _property_ > declaration is allowed in
the annotation element of a local
attribute.link:jaxb.html#a2217[See Annotation Restrictions]”
contains more information regarding the annotation element for a local
attribute reference. The customization values must be defined as
specified in link:jaxb.html#a1786[See Usage]” and have component
scope.

If _javaType_ is defined, then the
_propertyBaseType_ is defined to be Java datatype specified in the
_"name"_ attribute of the _javaType_ .

* If _fixedAttributeAsConstantProperty_ is “
_true"_ or “ _1"_ and the local attribute is a fixed, the local
attribute must be bound to a Java Constant property as specified in
link:jaxb.html#a1277[See Bind to a Java Constant property]”
applying customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides].” The
generateIsSetMethod, choiceContentProperty and enableFailFastCheck must
be considered to have been set to false.
* Otherwise, it is bound to a Java property
as specified in link:jaxb.html#a1252[See Attribute use]”
applying customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides].”

=== Example: Customizing Java Constant Property

XML Schema fragment:

<xs:complexType name="USAddress">

 <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>

</xs:complexType>

Customized derived code:

public class USAddress \{

 public static final String MY_COUNTRY =
"US"; // Customized Code

}

=== Example 2: Customizing to other Java Property

XML Schema fragment:

<xs:complexType name="USAddress"> +
<xs:attribute name="country" type="xs:string">

 <xs:annotation><xs:appinfo>

 <jaxb:property name="MyCountry"/>

 </xs:appinfo></xs:annotation>

 </xs:attribute>

</xs:complexType>

Customized derived code:

public class USAddress \{

 // public getString getCountry(); // Default
Code

 // public void setCountry(string value);//
Default Code

 public String getMyCountry()\{...} //
Customized Code

 public void setMyCountry(String value)\{...}
// Customized Code

}

=== Example 3: Generating IsSet Methods

XML Schema fragment:

<xs:attribute name="account" type = "xs:int">

 <xs:annotation><xs:appinfo>

 <jaxb:property generateIsSetMethod="true"/>

 </xs:appinfo></xs:annotation>

</xs:attribute>

Customized code:

public int getAccount();

public void setAccount(int account);

public boolean isSetAccount(); // Customized
code

public void unsetAccount(); // Customized
code

=== Global Element Declaration

A _<property>_ declaration is allowed in the
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
covers all local elements (link:jaxb.html#a1913[See Local
Element]”) that can reference this global element declaration. This is
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.

=== [[a1913]]Local Element

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).

A <property> declaration is allowed in the
annotation element of a local element. link:jaxb.html#a2217[See
Annotation Restrictions]” contains more information regarding the
annotation element for a local element reference.

The customization values must be defined as
specified in link:jaxb.html#a1786[See Usage]” and have component
scope.

If _javaType_ is defined, then the
_propertyBaseType_ is defined to be Java datatype specified in the
_"name"_ attribute of the _javaType_ .

The local element must be bound as specified
in link:jaxb.html#a1414[See Content Model Default Binding]”
applying customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides].”

See example in
link:jaxb.html#a1966[See Example 3: Property Customization:
Model Group To Content Property Set]” in section
link:jaxb.html#a1944[See Model Group].”

=== Wildcard

A _<property>_ declaration is allowed in the
annotation element of the wildcard schema component. The customization
values must be defined as specified in link:jaxb.html#a1786[See
Usage]” and have component scope.

The wildcard schema component must be bound
to a property as specified in link:jaxb.html#a1384[See Bind
wildcard schema component]” applying customization overrides as
specified in link:jaxb.html#a1847[See Customization Overrides].”

Example: The following schema example is from
UDDI V2.0

<xs:complexType name="businessEntityExt">

 <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>

</xs:complexType>

Customized derived code:

public class BusinessEntityExt \{

 ...

 // List getAny(); // Default Code

 List getExtension()\{...} // Customized Code

}

=== [[a1944]]Model Group

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
specified in link:jaxb.html#a1786[See Usage]” and have component
scope.

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

*  _choiceContentProperty_ attribute in
_<globalBindings>_ .
* If propertyBaseType is defined and a
_<property>_ declaration is also present, then the customization
overrides specified in link:jaxb.html#a1847[See Customization
Overrides]” must be applied by the model group’s parent schema element
to the property used to aggregate the Java value class.
* If propertySet is defined, then the model
group’s parent schema element must aggregate the property set as
specified in link:jaxb.html#a930[See Aggregation of Property
Set].”

=== Example1: Property Customization: Model Group To ChoiceContent Property

XML Schema fragment

<xs:annotation><xs:appinfo> +
<jaxb:globalBindings choiceContentProperty="true"/> +
</xs:appinfo></xs:annotation>

<xs:complexType name=”AType”> +
<xs:choice>

 <xs:element name="foo" type="xs:int"/>

 <xs:element name="bar" type="xs:string"/>

 </xs:choice> +
</xs:complexType>

Customized derived code:

class ObjectFactory \{ +
JAXBElement<Integer> createAtypeFoo(Integer value); +
JAXBElement<String> createAtypeBar(String value);

} +
public class AType \{ +
void setFooOrBar(Object o)\{...} //customized code +
Object getFooOrBar()\{...} //customized code +
}

The _choiceContentProperty_ is required to
bind the choice model group to a choice content property.

=== Example 2: Property Customization: Model Group To General Content Property

XML Schema fragment:

<xs:complexType name="Base"> +
<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> +
</xs:complexType>

Customized derived code:

public class Base \{ +
/** +
* A general content list that can contain +
* instances of Base.A, Base.B and Base.C. +
*/ +
// List getAOrBOrC(); - default +
List getItems()\{...} // Customized Code +
}

=== [[a1966]]Example 3: Property Customization: Model Group To Content Property Set

XML Schema fragment:

<xs:complexType name="USAddress"/> +
<xs:complexType name="PurchaseOrderType"> +
<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> +
</xs:complexType>

<xs:group name="shipAndBill"> +
<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> +
</xs:group>

Customized derived code:

public interface PurchaseOrderType \{

 USAddress getShipAddress(); void
setShipAddress(USAddress); +
USAddress getBillAddress(); void setBillAddress(USAddress); +
USAddress getAddress(); void setAddress(USAddress); +
}

=== Model Group Reference

A model group reference is a reference to a
model group using the “ref” attribute. A property customization is
allowed on the annotation property of the model group reference. Section
link:jaxb.html#a2217[See Annotation Restrictions]” contains more
information regarding the annotation element for a model group
reference.

The customization values must be defined as
specified in link:jaxb.html#a1786[See Usage]” and have component
scope. A model group reference is bound to a Java property set or a list
property as specified in link:jaxb.html#a1414[See Content Model
Default Binding]” applying customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides].”

=== [[a1976]]ComplexType

A _<property>_ customization is allowed on
the annotation element of a complex type. The customization values must
be defined as specified in link:jaxb.html#a1786[See Usage]” and
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
specified in link:jaxb.html#a973[See Simple Content Binding].”
applying the customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides].” If
_javaType_ is defined, then the _propertyBaseType_ is defined to be Java
datatype specified in the _"name"_ attribute of the _javaType_ .
* For all other content types, the content
model must be bound as specified in step 1. of
link:jaxb.html#a1414[See Content Model Default Binding]”
applying the customization overrides as specified in
link:jaxb.html#a1847[See Customization Overrides]".
* 

=== [[a1981]] _<javaType>_ Declaration

A _<javaType>_ declaration provides a way to
customize the binding of an XML schema atomic datatype to a Java
datatype, referred to as the target Java datatype. The target Java
datatype can be a Java built-in data type or an application specific
Java datatype. This declaration also provides two additional methods: a
parse method and a print method.

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 provider’s
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 provider’s
implementation during marshalling.

=== Usage

<javaType name=" _javaType_ "

{empty} [ xmlType=" _xmlType_ " ]

{empty} [ parseMethod="parseMethod" ]

 [ printMethod="printMethod" ]>

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

* a _<globalBindings>_ declaration.
* annotation element of one of the XML schema
elements specified in link:jaxb.html#a2079[See Customizable
Schema Elements].”
* in a <property> declaration. See
link:jaxb.html#a1783[See <property> Declaration].” This can be
used for customization at the point of reference to a simple type.

When used in a _<globalBindings>_
declaration, _<javaType>_ defines customization values with global
scope. When used in an annotation element of one of the schema elements
specified in link:jaxb.html#a2079[See Customizable Schema
Elements].” the customization values have component scope.

=== name

The _javaType_ , if specified, is the Java
datatype to which _xmlType_ is to be bound. Therefore, _javaType_ must
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
example, “ _int_ ”) or a Java class in the unnamed package. If class
javaType declares a public constructor with following signature,
_javaType(java.lang.String)_ , _parseMethod_ attribute does not need to
be specified.

===  _xmlType_

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.

The purpose of the _xmlType_ attribute is to
allow the global customization of a XML schema to Java datatype. Hence
_xmlType_ attribute is required when _<javaType>_ declaration’s parent
is _<globalBindings>_ . If absent, it must result in an invalid
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].” Otherwise, the _xmlType_ attribute must not be present
since the XML datatype is determined from the XML schema element with
which the annotation element containing _<javaType>_ declaration or the
_<baseType>_ (containing the _<javaType>_ ) is associated. If present,
it must result in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].”

Examples can be found in
link:jaxb.html#a2062[See Example: javaType Customization: Java
Built-in Type]” and link:jaxb.html#a2027[See Example: javaType
Customization: User Specified Parse Method]”

===  _parseMethod_

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:

* 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
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].” Otherwise, the binding compiler must assume that the
target type is a class that defines a constructor as follows:
*  _String_ as the first parameter of the
constructor.

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
form _ClassName.methodName,_ where the ClassName is a fully qualified
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:
*  _String_ as the first argument.

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
form _methodName_ provided _javaType_ is not a Java primitive type (such
as _"int"_ ). If _javaType_ is Java primitive type, then this must
result in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].” Otherwise,
the binding compiler must assume that _methodName_ is a method in the
class _javaType._ The binding compiler must therefore prefix the
_javaType_ to the _methodName_ and process _javaType._ _methodName_ as
specified in above.

The string passed to parse method can be any
lexical representation for _xmlType_ as specified in [XSD PART2].

If parseMethod attribute is not specified,
_xmlType_ is not a primitive or wrapper class and _javaType_ has an
accessible one argument constructor, where the argument is type
_java.lang.String_ , input text is parsed by invoking _new_ with a
_java.lang.String_ parameter.

===  _printMethod_

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
_methodName_ provided _javaType_ is not a Java primitive type (such as
_"int"_ ). If _javaType_ is Java primitive type, then this must result
in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].” Otherwise,
the compiler must assume that the target type is a class or an interface
that defines a zero-argument instance method named _methodName_ that
returns a _String_ . To apply the conversion it must generate code to
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:
* the first parameter is the target Java
datatype.

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
_xmlType_ as specified in [XSD PART2].

If _printMethod_ attribute is not specified
and _xmlType_ is not a primitive or wrapper class, _javaType.toString()_
is used as the default print method..



===  _DatatypeConverter_

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
it easier, an interface, _DatatypeConverterInterface,_ and a class
_DatatypeConverter_ are defined to expose the parse and print methods of
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.

The _DatatypeConverterInterface_ defines
parse and print methods for XML schema datatypes. There is one parse and
print method for each of XML schema datatype specified in
link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
Types]. The interface is fully specified by the Javadoc specified in
_jakarta.xml.bind.DatatypeConverterInterface_ .

The _DatatypeConverter_ class defines a
static parse and print method corresponding to each parse and print
method respectively in the _DatatypeConverterInterface_ interface. The
property _jakarta.xml.bind.DatatypeConverter_ can be used to select the
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
class name and must implement the interface _DatatypeConverterInterface_
. The class is fully specified by the Javadoc specified in
_jakarta.xml.bind.DatatypeConverter_ .

=== Usage

The following example demonstrates the use of
the _DatatypeConverter_ class for writing a customized parse and print
method.

=== [[a2027]]Example: javaType Customization: User Specified Parse Method

This example shows the binding of XML schema
type _"xs:date"_ is bound to a Java datatype _long_ using user specified
print and parse methods.

<jaxb:globalBindings> +
<jaxb:javaType name="long" xmlType="xs:date" +
parseMethod="pkg.MyDatatypeConverter.myParseDate" +
printMethod="pkg.MyDatatypeConverter.myPrintDate"/> +
</jaxb:javaType> +
</jaxb:globalBindings> +

package pkg; +
import jakarta.xml.bind.DatatypeConverter;

public class MyDatatypeConverter \{ +
public static long myParseDate(String s) \{

 java.util.Calendar d =
DatatypeConverter.parse(s);

 long result= cvtCalendarToLong(d) ; // user
defined method

 return result; +
}

 public static String myPrintDate(long l) \{

 java.util.Calendar d = cvtLongToCalendar(l);
//user defined

 return DatatypeConverter.print(d);

 } +
}

The implementation of the print methods (
_parseDate_ and _printDate_ ) are provided by the user.

The customization is applied during the
processing of XML instance document. During unmarshalling, the JAXB
implementation invokes _myParseDate_ . If _myParseDate_ method throws a
_ParseException_ , then the JAXB implementation code catches the
exception, and generate a _parseConversionEvent_ .

=== Lexical And Value Space

[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:

* 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"._

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
_DatatypeConverterInterface_ must be capable of a processing all lexical
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
_DatatypeConverterInterface_ must convert a value into any lexical
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 application’s schema.
* 

=== Built-in Conversions

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:

<xs:simpleType name="foo" type="xs:long">

 <xs:annotation><xs:appinfo>

 <jaxb:javaType name="int"/>

 </xs:appinfo></xs:annotation>

</xs:simpleType>

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

. 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
exist, this must result in an invalid binding customization as specified
in link:jaxb.html#a1544[See Invalid Customizations].

=== [[a2062]]Example: javaType Customization: Java Built-in Type

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

XML Schema fragment:

<xs:element name="partNumber" type="xs:int"/>

Customization:

<jaxb:globalBindings>

 ....

 <jaxb:javaType name="long"

 xmlType="xs:int"/>

</jaxb:globalBindings>

Since a Java built-in is specified, a parse
or a print method need not be specified. A JAXB implementation uses the
parse and print methods defined in _DatatypeConverter_ class for
converting between lexical representations and values. A JAXB
implementation unmarshals an input value using the following methods:

 int j =
(int)DataTypeConverter.parseLong(string);

=== Events

The parse method _parseMethod_ may fail,
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
_TypeConstraintException_ . A JAXB unmarshaller process must ensure that
an exception thrown by a parse method is caught and, if appropriate, a
_parseConversionEvent_ event is generated.

The print method _printMethod_ usually does
not fail. If it does, then the JAXB implementation must ensure that the
exception thrown by a print method is caught and a
_printConversionEvent_ is generated.

=== Customization Overrides

The _<javaType>_ overrides the default
binding of _xmlType_ to the Java datatype specified in
link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
Types].

=== [[a2079]]Customizable Schema Elements

=== Simple Type Definition

A _<javaType>_ binding declaration is allowed
in the annotation element of the of a simple type definition. The
_javaType_ overrides the default binding of _xmlType_ to the Java
datatype specified in link:jaxb.html#a725[See Java Mapping for
XML Schema Built-in Types]. The customization values defined have
definition scope and thus covers all references to this simple type
definition.

If the simple type definition is mapped to a
schema-derived type, an _@XmlJavaTypeAdapter_ is generated on that
class. Annotation element _@XmlJavaTypeAdapter.value()_ is set to a
generated classlink:#a5379[28] that extends
_jakarta.xml.bind.annotation.adapter.XmlAdapter_ . The generated class’
_unmarshal_ method must call the <javaType> customization’s parse
method, which is specified in link:jaxb.html#a1981[See
<javaType> Declaration]. The generated class’ _marshal_ method must call
the <javaType> customization’s print method.

===  _GlobalBindings_

A _<javaType>_ binding declaration is allowed
as part of _<globalBindings>._ The _javaType_ overrides the default
binding of _xmlType_ to the Java datatype specified in
link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
Types]. The customization values defined have global scope.

For each element or attribute declaration
that references an _xmlType_ that has a globalBindings _<javaType>_
customization specified for it, the corresponding JAXB property is
annotated with _@XmlJavaTypeAdapter_ .

===  _<property><baseType>_ declaration

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
datatype specified in link:jaxb.html#a725[See Java Mapping for
XML Schema Built-in Types]. Additional semantics are specified in
link:jaxb.html#a1801[See baseType]” also
apply.

The schema-derived JAXB property is annotated
with _@XmlJavaTypeAdapter_ as specified in
link:jaxb.html#a1801[See baseType]”.

=== [[a2090]] _<typesafeEnum>_ Declaration

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.

=== [[a2092]]Usage

<typesafeEnumClass> +
[ name = "enumClassName" ] +
[ map = “true” | “false” | “1” | “0” ] +
[ ref = "enumClassName" ] +
[ <typesafeEnumMember> ... </typesafeEnumMember> ]* +
[ <javadoc> enumClassJavadoc </javadoc> ] +
</typesafeEnumClass> +
 +
<typesafeEnumMember name = "enumMemberName"> +
[ value = "enumMemberValue"] +
[ <javadoc> enumMemberJavadoc </javadoc> ] +
</typesafeEnumMember>

There are two binding declarations
_<typesafeEnumClass>_ and _<typesafeEnumMember>_ . The two binding
declarations allow the enumeration members of an enumeration class and
enumeration class itself to be customized independently.

The < _typesafeEnumClass>_ declaration
defines the following customization values:

*  _name_ defines the customization value
_enumClassName_ , if specified. _enumClassName_ must be a legal Java
Identifier; it must not have a package prefix. +
 +
For an anonymous simple type, the _name_ attribute must be present. If
absent, it must result in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].”
*  _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
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
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
link:jaxb.html#a2142[See <javadoc> Declaration].”
* Zero or more _<typesafeEnumMember>_
declarations. The customization values are as defined as specified by
the _<typesafeEnumMember>_ declaration.

The _<typesafeEnumMember>_ declaration
defines the following customization values:

*  _name_ must always be specified and
defines a customization value _enumMemberName_ . _enumMemberName_ must
be a legal Java identifier.
*  _value_ defines a customization value
_enumMemberValue_ , if specified. _enumMemberValue_ must be the
enumeration value specified in the source schema. The usage of _value_
is further constrained as specified in link:jaxb.html#a2106[See
value Attribute].”
*  _<javadoc>_ if specified, customizes the
Javadoc for the enumeration constant. _<javadoc>_ defines a
customization value _enumMemberjavadoc_ if specified as described in
link:jaxb.html#a2142[See <javadoc> Declaration].”

For inline annotation, the
_<typesafeEnumClass>_ must be specified in the annotation element of the
< _simpleType_ > element. The _<typesafeEnumMember>_ must be specified
in the annotation element of the enumeration member. This allows the
enumeration member to be customized independently from the enumeration
class.

===  _value_ [[a2106]] Attribute

The purpose of the _value_ attribute is to
support customization of an enumeration value using an external binding
syntax. When the _<typesafeEnumMember>_ is used in an inline annotation,
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
syntax, the _value_ attribute must be provided. This serves as a key to
identify the enumeration value to which the _<typesafeEnumMember>_
applies. It’s use is therefore further constrained as follows:

* When _<typesafeEnumMember>_ is specified in
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
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].”
* When _<typesafeEnumMember>_ is scoped to
the _typesafeEnumClass_ declaration, the value attribute must be
present. If absent, it must result in must result in an invalid
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].” The enumMemberValue must be used to identify the
enumeration member to which the _<typesafeEnumMember>_ applies.

An example of external binding syntax can be
found in link:jaxb.html#a2134[See Example 2: typesafeEnum
Customization: External Binding Declaration].”

=== Inline Annotations

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
_<typesafeEnumMember>_ is used independently not as a child element of
_<typesafeEnumClass>._ An example of this is shown in
link:jaxb.html#a2129[See Example 1: typesafeEnum Customization:
Split Inline Annotation].”

In combined inline annotation, the
enumeration value and the enumeration class are customized together i.e.
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
link:jaxb.html#a2106[See value Attribute].” An example of this
customization is shown in link:jaxb.html#a2138[See Example 3:
typesafeEnum Customization: Combined Inline Annotation].”

=== Customization Overrides

When binding a schema type definition’s Java
representation to an enum type, the following customization values
override the defaults specified in Chapter 5. It is specified in a
common section here and referenced from link:jaxb.html#a1857[See
Customizable Schema Elements].”

* name: If enumClassName is defined, then the
name obtained by mapping enumClassName as specified in
link:jaxb.html#a1608[See Customized Name Mapping].”
* package name: The name obtained by
inheriting _packgeName_ from a scope that covers this schema element and
mapping packageName as specified in link:jaxb.html#a1608[See
Customized Name Mapping].”
* enumclass javadoc: _enumClassJavaDoc_ if
defined, customizes the _class/interface section (_
link:jaxb.html#a2145[See Javadoc Sections]”) for the enumeration
class, as specified in link:jaxb.html#a2163[See Javadoc
Customization].”
* enum constant set: Each member of the set
is computed as follows:
*  name: If enumMemberName is defined, the
name obtained by mapping enumMemberName as specified in
link:jaxb.html#a1608[See Customized Name Mapping].”
* javadoc: _enumMemberJavaDoc_ if defined,
customizes the _field section (_ link:jaxb.html#a2145[See
Javadoc Sections]” ) for the enumeration class, as specified in
link:jaxb.html#a2163[See Javadoc Customization].”

=== [[a2126]]Customizable Schema Elements

Any XML Schema simple type which has an
enumeration facet can be customized with _<jaxb:typesafeEnumClass>_
declaration with the following exception. If the simple type definition
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
in an invalid customization as specified in
link:jaxb.html#a1544[See Invalid Customizations].”. Since most
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.

* 

=== [[a2129]]Example 1: typesafeEnum Customization: Split Inline Annotation

XML Schema fragment:

<xs:simpleType name="USState"> +
<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> +
</xs:simpleType>

Customized derived code:

public enum USStateAbbr \{ +
STATE_AL, STATE_AK; +
public String value() \{ return name(); } +
public static USStateAbbr fromValue(String value) \{ ... } +
};

=== [[a2134]]Example 2: typesafeEnum Customization: External Binding Declaration

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

<jaxb:typesafeEnumClass name="USStateAbbr"> +
<jaxb:typesafeEnumMember name="STATE_AK" value="AK"> +
<jaxb:typesafeEnumMember name="STATE_AL" value="AL"/> +
</jaxb:typesafeEnumClass>

The attribute _value_ must be specified for
_<typesafeEnumMember>_ . This identifies the enumeration member to which
_<typesafeEnumMember>_ applies.

=== [[a2138]]Example 3: typesafeEnum Customization: Combined Inline Annotation

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

<xs:simpleType name="USState"> +
<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> +
</xs:simpleType>

The attribute value must be specified for
_typesafeEnumMember_ . This identifies the enumeration member to which
the binding declaration applies.

===  _<javadoc>_ [[a2142]] Declaration

The _<javadoc>_ declaration allows the
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
it is used determines the section of the Javadoc that is customized.

=== [[a2145]]Javadoc Sections

The terminology used for the javadoc sections
is derived from “Requirements for Writing Java API Specifications” which
can be found online at http:
_//java.sun.com/j2se/javadoc/writingapispecs/index.html._

The following sections are defined for the
purposes for customization:

* 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)

=== Usage

Note that the text content of a _<javadoc>_
element must use _CDATA_ or _&lt;_ to escape embedded HTML tags.

<javadoc>

 Contents in &lt;b>Javadoc&lt;\b> format.

</javadoc>

or

<javadoc>

 <<![CDATA[

 Contents in <b>Javadoc<\b> format

 ]]>

</javadoc>

=== [[a2163]]Javadoc Customization

The Javadoc must be generated from the
_<javadoc>_ element if specified. The Javadoc section depends upon where
_<javadoc>_ element is used. JAXB providers may generate additional
provider specific Javadoc information (for example, contents of the
_<xs:documentation>_ element).

===  _<dom>_ [[a2165]] Declaration

The _<dom>_ customization binds an XML Schema
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
represented as DOM. This customization also meets a JAX-WS 2.0
databinding requirement from link:jaxb.html#a179[See Disabling
Databinding]”.

=== Usage

The syntax for the customization is the
following:

<dom [ [type= "w3c" |
_otherDomRepresentations_ ] />

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

=== Customizable Schema Elements

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

* 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>_ )
* 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
bound to _org.w3c.dom.Element_ .

Special Case Handling of DOM customization on
a:

*  _type definition_ - it is semantically
equivalent to placing the dom customization on each element declaration
referencing that type definition.
*  _global element declaration_ - it is
semantically equivalent to placing the dom customization on each element
declaration referencing, via _@ref_ , the global element declaration.
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.
*  _mixed content_ - if an XML schema
component is annotated with a _dom_ customization and that XML schema
component can contain character data information due to its parent
complex type definition being defined with mixed content, character data
information is handled as specified in link:jaxb.html#a1369[See
Bind mixed content]”.

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

=== Examples

=== Wildcard Binding Example

A wildcard is mapped to a List of
_org.w3c.dom.Element_ . Each element that matches to the wildcard will
be turned into a DOM tree.

<xs:complexType name=”foo”> +
<xs:sequence> +
<xs:any maxOccurs="unbounded" processContents="lax"> +
_<xs:annotation><xs:appinfo> +
<jaxb:dom/> +
</xs:appinfo></xs:annotation> +
_ </xs:any> +
</xs:sequence> +
</xs:complexType>

 +
import org.w3c.dom.Element; +
public class Foo \{ +
@XmlAnyElement(lax=”false”) +
List<Element> getContent()\{...} +
}

=== Wildcard and Mixed Content Binding Example

If the complexType definition above is
defined to have mixed content, due to element _[complexType]_ __ having
attribute _@mixed=”true”_ , the JAXB binding is:

import org.w3c.dom.Element; +
public class Foo \{ +
/* Element content is represented _org.w3c.dom.Element_ . +
* Character data information is represented as instances of +
* _java.lang.String_ . */ +
@XmlMixed +
@XmlAnyElement(lax=”false”) +
List<Object> getContent()\{...} +
}

===  _<inlineBinaryData>_ [[a2193]] Declaration

The _<inlineBinaryData>_ customization
provides declarative control over the optimization for binary data
described in link:jaxb.html#a5109[See Appendix],
link:jaxb.html#a5110[See Enhanced Binary Data Handling].

=== Usage

The syntax for the customization is the
following:

<inlineBinaryData/>

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:

* Element declaration ( _<xs:element>_ ) with
binary data or
* Type definition ( _<xs:complexType>_ and
_<xs:simpleType>_ ) deriving from binary datatype

When a schema component that binds to a JAXB
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_ .

===  _<factoryMethod>_ Declaration

The _<factoryMethod>_ customization provides
declarative control over an element or type factory method name
generated in a package’s _ObjectFactory_ class introduced in
link:jaxb.html#a482[See Java Package].”. This customization is
useful to resolve name collisions between factory methods in the
schema-derived _ObjectFactory_ class.

=== Usage

The syntax for the customization is the
following:

<factoryMethod
name=”BaseForFactoryMethodName”/>

The customization value defined is:

*  _name -_ each character of name must be a
valid part of a Java identifier as determined by
_java.lang.Character.isJavaIdentifierPart()._

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

* The string constant _create_
*  _@name_ ’s value

=== Usage Constraints

The usage constraints on _<factoryMethod>_
are specified below. Any constraint violation must result in an invalid
customization as specified in link:jaxb.html#a1544[See Invalid
Customizations].” The usage constraints are:

.  _<factoryMethod>_ is only allowed to
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.

=== [[a2217]]Annotation Restrictions

[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).

 _<xs:element name = "Customer">_

 _<xs:complexType>_

 _<xs:element ref = "Name"/>_

 _<xs:element ref = "Address" />_

 _</xs:complexType>_

 _</xs:element>_

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
is associated with \{Attribute Use}
* The annotation element on a model group ref
or an element reference is associated with the \{particle}.