spec/src/main/asciidoc/ch08-java_types.adoc

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

== Java Types To XML

=== Introduction

This chapter specifies the mapping from
program elements to XML Schema. The mapping includes a default as well
as a customized mapping.

=== Overview

This section is non normative and provides a
high level view of Java to XML Schema mapping targeted towards both JAXB
application developers and JAXB implementation vendors.

==== Mapping Scope

The mapping covers program elements commonly
used in the composition of a data model for an application: package,
field, property and types (classes and enum construct). Additionally,
the mapping scope also covers mapping annotations used to annotate
schema derived code.

In so far as possible, a program element is
mapped to an equivalent XML Schema construct in an intuitive manner.
Thus,

* *_Package_* maps to a XML target namespace. A
package provides a naming context for types. A XML target namespace
provides a naming context for schema components such as elements, type
definitions.
* *_Type_* maps to a schema type. A _value type_ is
a data container for values; e.g. a value class contains values
represented by it’s properties and fields. A schema type is a datatype,
an instance of which (e.g. element) acts as a data container for values
represented by schema components within a schema type’s content model
(e.g. element, attributes, etc.). Thus a type maps naturally to a schema
type. For e.g.,
** class typically maps to a complex type definition
** java primitive types and wrapper classes map
to XML Schema simple type definition.
* *_Field or property_* maps to an element or an
attribute contained within the complex type to which a type is mapped.
* *_Enum type_* maps to a simple schema type
constrained by enumeration facets.

The input to the mapping process is one or
more sets of packages or classes. A package or a class is mapped and
recursively, fields, properties and types contained with it. The mapping
is customizable.

==== Mapping Annotations

*_Mapping annotations_* The mapping of program
elements to XML Schema construct can be customized using _mapping annotations_,
program annotations based on JSR 175 program annotation
facility. Mapping annotations are used for:

* customizing the Java to XML schema mapping.
* annotating schema derived code.
* control over optimized binary data encoding.

The mapping annotations are described in the
`jakarta.xml.bind.annotation` and `jakarta.xml.bind.annotation.adapters`
packages.

*_Retention Policy_* The retention policy of all
mapping annotations is RetentionPolicy.RUNTIME. This policy allows
introspection of mapping annotations at runtime. Introspection can be
used by JAXB binding framework to marshal/unmarshal an object graph to
XML representation or to customize the mapping of program elements to
XML Schema constructs. This policy also allows a JAXB vendor
implementation to generate a schema from a program element’s compiled
form rather than its source.

==== XML Name Derivation

Mapped program element is a program element
that has been mapped to an XML Schema construct. It is possible to use
`@XmlTransient` annotation type to prevent the mapping of a program
element.

*_XML Names_* An XML name may be needed for the
schema components for a mapped program element, for e.g. element name.
XML names are usually derived from a program element name, for e.g.
property, field, class name etc.But they can be customized using mapping
annotation. When an XML name is derived from a property name, bean de
capitalization rules are used. If a Java Identifier is not a legal XML
name, then a legal XML name can be assigned using an annotation element
(e.g. `@XmlType(name="foo")`).

==== Fields and Properties

*_XML global element_* Fields and properties
typically map to local elements within a complex type for a class. But a
well formed XML document begins with a root element (a global element in
the corresponding schema). The `@XmlRootElement` annotation can be used
to associate a global element with a class or an enum type.

*_Null Value and Nillable Element_* A null value
for a type mapped to an XML Schema element in two ways: absence of an
element or an nillable element. The mapping annotation for an element
allows either mapping.

==== Type Mapping

Legacy applications One of the primary use
cases for Java language to XML Schema mapping is to allow an existing
application to be exported as a web service. In many cases, the existing
applications are legacy applications consisting of classes that follow
different class designs. The annotations and default mapping are
designed to enable such classes to be mapped to schema with minimal
changes to existing code. See <<Default Mapping>> for default mapping.

*_Class_* A class usually maps to a complex type.
However, using `@XmlValue` annotation, a class can also be mapped to a
simple type (to hold a simple value) or a complexType with simpleContent
(to hold a simple value and attributes). The `@XmlType` annotation can
be used to customize the mapping of a class. For example, it can be used
to map a class to an anonymous type or to control the ordering of
properties and/or fields. Properties and fields are unordered; but they
can be mapped to a content model that is ordered (e.g. xs:sequence) or
unordered content model (xs:all).

*_Class Designs_* A class with a public or
protected no-arg constructor can be mapped. If a class has a
*_static zero-arg factory_* method, then the factory method can be specified using
the annotation element `@XmlType.factoryMethod()` and `@XmlType.factoryClass()`.

*_Ordering of Properties/fields_* The ordering of
properties and fields can be customized in one of two ways: at the
package level using `@XmlAccessorOrder` or using `@XmlType.propOrder()` at
the class level.

*_Class Hierarchy Mapping_* Class hierarchy
typically maps to a type derivation hierarchy. The `@XmlType` and
`@XmlValue` annotations together provide support mapping class hierarchy
to schema type hierarchy where XML Schema complex type derives by
extension from either another complex type or a simple type.

*_Supported Collection Types_* Typed collections
and untyped collections are mapped. Mapped collection types are: arrays,
indexed properties and parametric types. Mapped untyped collection are:
`java.util.List`, `java.util.Set` and `java.util.HashMap`. Of these,
`java.util.HashMap` does not map naturally to a XML Schema construct.
For example, `HashMap` can have different XML serialized forms which
differ in trade-offs made between memory and speed or specificity and
generality. The XML serialization form can be customized using
`@XmlJavaTypeAdapter` (<<adapter>>).

*_Collection serialized forms_* A collection type
can be mapped to a XML Schema complex type and collection item is mapped
to local element within it.

Alternately, a parameterized collection
(e.g. `List<Integer>`) can be mapped to a simple schema type that derives
by list.

When a collection type is mapped to a XML
Schema complex type, the mapping is designed to support two forms of
serialization shown below.

[source,java,indent=4]
----
//Example: code fragment
int[] names;
----
[source,xml,indent=4]
----
<!--XML Serialization Form 1 (Unwrapped collection)
  Element name is derived from property or field name-->
<names> ... </names>
<names> ... </names>
...
----

[source,xml,indent=4]
----
<!--XML Serialization Form 2 (Wrapped collection)
  Element name of wrapper is derived from property or field name
  Element name of each item in collection is also derived from
  property name-->
<names>
  <names> value-of-item </names>
  <names> value-of-item </names>
  ....
</names>
----

The two serialized XML forms allow a null
collection to be represented either by absence or presence of an element
with a nillable attribute. The `@XmlElementWrapper` annotation on the
property or field is used to customize the schema corresponding to the
above XML serialization forms.

A parameterized collection (e.g.
`List<Integer>)` can also be mapped to simple schema that derives by list
using `@XmlList` annotation. For e.g. the serialized XML form is: "1 2 3".

==== Adapter

A type may not map naturally to a XML
representation (see Supported Collection Types above). As another
example, a single instance of a type may have different on wire XML
serialization forms.

Adapter approach defines a portable
customization mechanism for applications exemplified above. The
mechanism provides a way to adapt a _bound type_, a Java type used to
process XML content, to _value type_, mapped to an XML representation or
vice versa. It is the value type that is used for marshalling and
unmarshalling. Use of this approach involves two steps:

* provide an adapter class that extends the
abstract class `@jakarta.xml.bind.annotation.adapters.XmlAdapter` that
defines two methods `unmarshal()` and `marshal()`. The methods are
invoked by JAXB vendor implementation during unmarshalling and
marshaling respectively to adapt between bound and value types.
* specify the adapter class using the
`@XmlJavaTypeAdapter` annotation.

==== Referential Integrity

Preserving referential integrity of an object
graph across XML serialization followed by a XML de serialization,
requires an object reference to be marshalled by reference or
containment appropriately. Possible strategies include:

* marshal all references to a given object by reference.
* marshal the first reference to an object by
containment and subsequent references to the same object by reference.

Depending on the strategy, the schema to which
program element is mapped also varies accordingly.

Two annotations `@XmlID` and `@XmlIDREF`
provide the mechanism which can be used together to map program element
by reference or containment. This places the burden of preserving
referential integrity on a developer. On the other hand, the ability to
customize the mapping is useful since it can result in mapping of
program elements to a schema that defines a document structure more
meaningfully to an application than a default derived schema.

==== Property/Field Name Collision

A XML name collision can arise when the
property name obtained by bean de capitalization and the name of a field
map to a same schema component. For example

[source,java,indent=4]
----
public int item;
public int getItem();
public void setItem(int val);
----

The name collision occurs because the property
name, bean de capitalization, and the name of the public field are both
the same i.e. `item`. In the case, where the property and the public
field refer to the same field, the `@XmlTransient` can be used to
resolve the name collision by preventing the mapping of either the
public field or the property.

=== Naming Conventions

Any source and schema fragments and examples
shown in this chapter are meant to be illustrative rather than
normative.

* `@XmlAttribute` denotes both a program
annotation type as well a specific use of annotation type.
* The prefix `xs:` is used to refer to schema
components in W3C XML Schema namespace.
* The prefix `ref:` is used to refer to schema
components in the namespace `"http://ws-i.org/profiles/basic/1.1/xsd"`

[NOTE]
.Design Note
====
The mapping of program elements to schema components is specified
using the abstract schema component model in XML Schema Part 1.
The use of abstract schema components allows precise specification of
the mapping and is targeted towards JAXB implementation vendors.
In contrast, jakarta.xml.bind.annotation Javadoc is targeted
towards the JAXB application developer. Hence it is the Javadoc
that contains code and schema fragment samples.

Default mapping is specified in terms of customizations. First
the mapping of program element to a schema component
with the binding annotation is specified. Then the default
mapping for a program element is specified by defining
a default binding annotation. In the absence of any binding
annotation, the default binding annotation is considered to
annotate the program element.

For ease of reading, a synopsis of each program annotation
is included inline in this chapter. Details can be found
in the Javadoc published separately from this document.

====

=== Constraint Violations

For the purpose of mapping and constraint
checking, if a program element is not annotated explicitly, and there is
a default mapping annotation defined for that element, it must be
applied first before performing any constraint checks or mapping. This
is assumed in the normative mapping tables shown below.

The mapping of program elements to XML Schema
constructs is subject to mapping constraints, specified elsewhere in
this chapter. The mapping constraints must be enforced by the
`jakarta.xml.bind.annotation.JAXBContext.newInstance(..)` method. Any
cycles resulting from a combination of annotations or default mapping
must be detected in
`jakarta.xml.bind.annotation.JAXBContext.newInstance(..)` method and also
constitutes a constraint violation. A `jakarta.xml.bind.JAXBException` or
(its subclass, which can be provider specific) must be thrown upon a
constraint violation.

A JAXB Provider must support the schema
generation at runtime. See
`jakarta.xml.bind.JAXBContext.generateSchema(..)` for more information.

=== Type Mapping

This section specifies the mapping of Java
types to XML Schema.

==== Java Primitive types

The default mapping of Java types (and their
wrapper classes) specified in table <<a2310>> must be supported.

.Mapping: Java Primitive types to Schema Types
[[a2310]]
[cols=",",options="header"]
|===
| Java Primitive Type | XML data type
| boolean | xs:boolean
| byte | xs:byte
| short | xs:short
| int | xs:int
| long | xs:long
| float | xs:float
| double | xs:double
|===

==== Java Standard Classes

The default mapping of Java classes specified in <<a2329>> must be supported.

.Mapping of Standard Java classes
[[a2329]]
[cols=",",options="header"]
|===
| Java Class | XML data type
| java.lang.String | xs:string
| java.math.BigInteger | xs:integer
| java.math.BigDecimal | xs:decimal
| java.util.Calendar | xs:dateTim
| java.util.Date | xs:dateTime
| javax.xml.namespace.QName | xs:QName
| java.net.URI | xs:string
| javax.xml.datatype.XMLGregorianCalendar | xs:anySimpleType
| javax.xml.datatype.Duration | xs:duration
| java.lang.Object | xs:anyType
| java.awt.Image | xs:base64Binary
| jakarta.activation.DataHandler | xs:base64Binary
| javax.xml.transform.Source | xs:base64Binary
| java.util.UUID | xs:string
|===

[NOTE]
.Design Note
====
JAXP package javax.xml.datatype introduced the following classes
for supporting XML schema types: Duration and XMLGregorianCalendar.
XMLGregorianCalendar supports for 8 schema calendar types - xs:date,
xs:time, xs:dateTime, 6 g* types, all of which derive from xs:anySimpleType.
The particular schema type is computed based on values of member fields of
XMLGregorianCalendar. Since the actual schema type is not known until runtime,
by default, XMLGregorianCalendar can only be mapped to xs:anySimpleType
and an instance of XMLGregorianCalendar could be marshaled using xsi:type
to specify the appropriate schema calendar type computed at runtime.
However, the mapping can be customized.

====

A byte[] must map to xs:base64Binary by default.

==== Generics

===== Type Variable

The following grammar is from [JLS], Section 4.4, "Type Variables".

[source,subs=+quotes]
----
TypeParameter:
    TypeVariable TypeBound~opt~

TypeBound:
    extends ClassOrInterfaceType AdditionalBoundList~opt~
----

A type variable without a _Typebound_ must be
mapped to xs:anyType.

A type variable with a _TypeBound_ must map to
the schema type to which _ClassOrInterfaceType_ is mapped; the mapping of
_ClassOrInterface_ is subject to the mapping constraints specified in
other sections in this chapter.

[source,java,indent=4]
----
// code fragment
public class Shape <T> {
    public T xshape;
    public Shape() {};
    public Shape(T f) {
        xshape = f;
    }
}
----

[source,xml,indent=2]
----
<!-- XML Schema -->
<xs:complexType name="shape">
  <xs:sequence>
    <xs:element name="xshape" type="xs:anyType" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>
----

===== Type Arguments and Wildcards

The following grammar is from [JLS], Section
4.5.1, "Type Arguments and Wildcards".

----
TypeArguments:
    <ActualTypeArgumentList>

ActualTypeArgumentList:
    ActualTypeArgument
    ActualTypeArgumentList, ActualTypeArgument

ActualTypeArgument:
    ReferenceType
    Wildcard

Wildcard:
?WildcardBounds

WildcardBounds:
    extends ReferenceType
    super ReferenceType
----

A wildcard without a _WildcardBounds_ must map
to schema type xs:anyType.

A wildcard with a _WildcardBounds_ whose super
type is _ReferenceType_ must map to schema type xs:anyType.

A wildcard with a _WildcardBounds_ that extends
a _ReferenceType_ must map to the schema type to which the _ReferenceType_
is mapped; this mapping is subject to the mapping constraints specified
in other sections in this chapter and is determined by the annotations
as specified in the mapping tables in the chapter. For example:

[source,java,indent=4]
----
/**
 * EXAMPLE : WildcarType Mapping
 */
// Code fragment
public class Shape {...}

public class Rectangle extends Shape {...}
public class Circle extends Shape {...}

public class Foo {
    public java.util.List<? extends Shape> shapes;
}
----

[source,xml,indent=2]
----
<!-- XML Schema fragment -->
<xs:complexType name="shape">
  ...
</xs:complexType>

<xs:complexType name="circle">
  <xs:complexContent>
    <xs:extension base="shape">
      ...
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

<xs:complexType name="rectangle">
  <xs:complexContent>
    <xs:extension base="shape">
      ...
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

<xs:complexType name="foo">
  <xs:sequence>
    <xs:element name="shapes" type="shape" nillable="true"
                maxOccurs="unbounded" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>
----

==== Collections

The following collection must be supported:

* `java.util.Map` and its subtypes (e.g. java.util.HashMap)
* `java.util.Collection` and it’s subtypes (e.g. java.util.List)

The mapping of collection depends upon the
annotations on the program elements and is specified in the mapping
tables. This specification uses a _collection type_ to be one of
`java.util.Collection` (or a subtype derived from it), an array or an
JavaBean index property.

=== Java Package

`@XmlSchema` is used in the mapping of package to an XML target namespace.

==== @XmlSchema

===== Synopsis

[source,java,indent=4]
----
public enum XmlNsForm {UNQUALIFIED, QUALIFIED, UNSET}

@Retention(RUNTIME) @Target({})
public @interface XmlNs {...}

@Retention(RUNTIME) @Target({PACKAGE})
public @interface XmlSchema {
    XmlNs[] xmlns() default {};
    String namespace() default "";
    String location() default "";
    XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
    XmlNsForm attributeFormDefault() default XmlNsForm.UNSET;
}
----

===== Mapping

If `location()` is "", a package annotated
with `@XmlSchema` must be mapped as specified in <<a2476>>.
Otherwise a package will not produce any schema document.

[NOTE]
.Design Note
====
XML Schema Part 1 does not contain an abstract component definition for
a schema. Neither is there a mapping of attribute information items
(e.g. elementFormDefault) of the <schema> to properties of an abstract
schema component. So the mapping below maps to attribute information
items on the <schema> element. "absent" in the tables is used to mean
absence of the attribute information item in the schema.

====

[NOTE]
.Design Note
====
When `location()` is present, this specification only guarantees
that no schema is generated for the namespace. Implementations should
generate `<import>` statements accordingly with the `schemaLocation`
attribute pointing to the value of the `@XmlSchema.location()`,
but `<import>` statements do not have corresponding schema components,
and they are anyway just hints, so it's not possible to enforce
such constraints. Implementations are also allowed to use values
other than `@XmlSchema.location()` in `<import schemaLocation="..."/>`
for example so that the reference points to a copy of the resource
that's preferrable for the user.

====

.Table 8-3 Mapping: Package to XML target namespace
[[a2476]]
[cols=","]
|===
| `targetNamespace` | if `@XmlSchema.namespace()` is "", then `absent;` +
 +
otherwise `@XmlSchema.namespace()`

| `elementFormDefault` | if the value of `@XmlSchema.elementFormDefault()
is `@XmlNsForm.UNSET`, then `absent;` +
 +
otherwise, the value of `@XmlSchema.elementFormDefault()`

| `attributeFormDefault` | if the value of `@XmlSchema.attributeFormDefault()`
is `@XmlNsForm.UNSET`, then `absent;` +
 +
otherwise, the value of `@XmlSchema.attributeFormDefault()`

|`Namespace prefixes` | if `@XmlSchema.xmlns()` is {} then implementation defined; +
 +
otherwise `@XmlSchema.xmlns()`
|===

==== @XmlAccessorType

This annotation allows control over default serialization of fields and properties.

===== Synopsis

[source,java,indent=4]
----
@Inherited @Retention(RUNTIME) @Target({PACKAGE, TYPE})
public @interface XmlAccessorType {
    XmlAccessType value() default XmlAccessType.PUBLIC_MEMBER;
}

public enum XmlAccessType { NONE, PROPERTY, FIELD, PUBLIC_MEMBER }
----

===== Mapping

The following mapping constraints must be enforced:

* This annotation can be used only with the
following other annotations: `@XmlType`, `@XmlRootElement`,
`@XmlAccessorOrder`, `@XmlSchema`, `@XmlSchemaType`, `@XmlSchemaTypes`,
`@XmlJavaTypeAdapters`. It can also be used with the following
annotations at the package level: `@XmlJavaTypeAdapter`.

See <<Default Mapping>>.

==== @XmlAccessorOrder

This annotation allows control over the
default ordering of properties and fields that are mapped to XML
elements. Properties and fields mapped to XML attributes are not
impacted by this annotation since XML attributes are unordered.

===== Synopsis

[source,java,indent=4]
----
@Inhertited @Retention(RUNTIME)
@Target({PACKAGE, TYPE})
public @interface XmlAccessorOrder {
    XmlAccessOrder value() default XmlAccessOrder.UNDEFINED;
}

public enum XmlAccessOrder { UNDEFINED, ALPHABETICAL }
----

===== Mapping

The following mapping constraints must be enforced:

* This annotation can be
used only with the following other annotations: `@XmlType`,
`@XmlRootElement`, `@XmlAccessorType`, `@XmlSchema`, `@XmlSchemaType`,
`@XmlSchemaTypes`, `@XmlJavaTypeAdapters`. It can also be used with the
following annotations at the package level: `@XmlJavaTypeAdapter`.

* If the value of `@XmlAccessorOrder.value()` is
`XmlAccessOrder.ALHPHABETICAL`, then the default ordering of
fields/properties is lexicographic order as determined by
`java.lang.String.CompareTo(String anotherString)`.

* If the `@XmlAccessorOrder.value()` is
`XmlAccessOrder.UNDEFINED`, then the default ordering of
fields/properties is unspecified.

==== @XmlSchemaType

This annotation allows a customized mapping to
a XML Schema built in type. This is useful where a Java type can map to
more than one schema built in types. An example is
`XMLGregorianCalendar` which can represent one of the eight schema
built-in types.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME)
@Target({FIELD, METHOD, PACKAGE})
public @interface XmlSchemaType {
    String name();
    String namespace() default "http://www.w3.org/2001/XMLSchema";
    Class type() default DEFAULT.class;
    final class DEFAULT {}
}
----

===== Mapping

The following mapping constraints must be enforced:

* `name()` must be an atomic simple type schema
type (or a type that derives from it) to which the type of the property
or field can be mapped from XML Schema -> Java as specified in Section
6.2.2, "Atomic Datatype".
+
Example
+
[source,java,indent=4]
----
// @XmlSchemaType can specify any one of the eight calendar types
// that map to XMLGregorianCalendar.
@XmlSchemaType(name="date")
XMLGregorianCalendar foo;
----
*  If the annotation is used as a package
level annotation or within `@XmlSchemaTypes`, value of
`@XmlSchemaType.type()` must be specified and must be the Java type that
is being customized.
* If the annotation is used on a field or a
method, then value of `type()` must be `DEFAULT.class`.
* This annotation can only be used with the
following other annotations: `@XmlElement`, `@XmlAttribute`,
`@XmlJavaTypeAdapter`, `@XmlJavaTypeAdapters`.

_package:_

When this annotation is used at the package
level, the mapping applies to references to `@XmlSchemaType.type()` as
specified below. For clarity, the following code example is used along
with normative text.

[source,java,indent=4]
----
// Example: change the default mapping at package level
package foo;
@jakarta.xml.bind.annotation.XmlSchemaType
    (name="date",
     type=javax.xml.datatype.XMLGregorianCalendar.class)
----

A `@XmlSchemaType` that is specified as a
package level annotation must apply at the point of reference as
follows:

. a property/field within a class in package
(e.g `exmple.po`) whose reference type is `@XmlSchemaType.type()`. For
e.g.
+
[source,java,indent=4]
----
// XMLGregorianCalendar will be mapped to XML Schema type "date"
XMLGregorianCalendar cal;
----

. a property/field within a class in package
(e.g `exmple.po`), where `@XmlSchemaType.type()` is used as a
parametric type. For e.g.
+
[source,java,indent=4]
----
 // Example: Following code maps to a repeating element with
 // XML Schema type of "date".
 List<XMLGregorianCalendar> bar;
----

_property/field:_

A `@XmlSchemaType` specified on the
property/field maps references to `@XmlSchemaType.type()` as follows:

. property/field is a single valued.
+
[source,java,indent=4]
----
// Maps XMLGregorianCalendar to XML Schema type "date""
@XmlSchemaType(name="date")
public XMLGregorianCalendar cal;
----

. a property/field where
`@XmlSchemaType.type()` is used as a parametric type. For e.g.
+
[source,java,indent=4]
----
// Example: Following code maps to a repeating element with
// XML Schema type of "date".
@XmlSchemaType(name="date")
List<XMLGregorianCalendar> bar;
----

==== @XmlSchemaTypes

This annotation is a container annotation for
defining multiple `@XmlSchemaType` annotations at the package level.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({PACKAGE})
public @interface XmlSchemaTypes {
    // Collection of @{@link XmlSchemaType} annotations
    XmlSchemaType[] value();
}
----

===== Mapping

Each `@XmlSchemaType` annotation in
`@XmlSchemaTypes.value()` must be mapped as specified in <<xmlschematype>>.

=== Java class

==== @XmlType

`@XmlType` is used to map a Java class to a
schema type. The schema type is computed from its annotation element
values.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({TYPE})
public @interface XmlType {
    String name() default "##default";
    String[] propOrder() default {""};
    String namespace() default "##default";
    Class factoryClass() default DEFAULT.class;
    final class DEFAULT {};
    String factoryMethod() default "";
}
----

===== Mapping

The following mapping constraints must be
enforced:

* a class must be either be a top level class
or a nested static class.
* a class must have a public or protected
no-arg constructor or a factory method identified by {`factoryClass()`,
`factoryMethod()`} unless it is adapted using `@XmlJavaTypeAdapter`.
* If `factoryClass()` is other than
`DEFAULT.class`, then `factoryMethod()` must be specified (i.e. the
default value "" cannot be used.)
* If `factoryClass()` is `DEFAULT.class` and
`factoryMethod()` is not "", then `factoryMethod()` be a method in this
class.
* if `@XmlType.propOrder` is not {} or {""},
then the set must include all of the properties and fields mapped to
particles as specified in:
** <<xmlelement>>
** <<xmlelements>>
** <<xmlelementref>>
** <<xmlelementrefs>>
* `@XmlType.propOrder` must not include a
field or property annotated with `@XmlTransient`.
* if the class, _subClass_, derives from another
XML-bound class, _baseClass_ directly or indirectly (other than
`java.lang.Object`), then the _subClass_ must not contain a mapped property
or field annotated with `@XmlValue` annotation.
* If a class contains a mapped property or
field annotated with `@XmlValue` annotation, then all other mapped
fields or properties in the class must be mapped to an XML attribute.
* This annotation can be used with the
following annotations: `@XmlRootElement`, `@XmlAccessorOrder`,
`@XmlAccessorType`.
* Even though the syntax allows it, `@XmlType`
is disallowed on an interface.

A class annotated with `@XmlType`, must be
mapped as specified below:

* class must be mapped as specified in <<a2678>>
if the class contains only one mapped property or field that
is annotated with `@XmlValue` as specified in <<xmlvalue>>.
* otherwise, the class must be mapped as specified in <<a2611>>.

.Table 8-4 Mapping: Class to Complex Type Definition
[[a2611]]
[cols=","]
|===
| `{name}` | if `@XmlType.name()` is "", then absent +
 +
otherwise if `@XmlType.name()` is `##default`, then
the XML name derived from the class name as
specified in <<Java Identifier To XML Name>>  +
 +
otherwise `@XmlType.name()`

| `{target namespace}` | if `@XmlType.namespace()` is `\\##default`
&& `@XmlType.name()` is "" and class is annotated with
`@XmlRootElement`, then the `{target namespace}` as specified in
<<a2742>> +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is "" and class is not annotated with
`@XmlRootElement`, then the `{target namespace}` of the attribute or
element to which the property or field, from where this class is
referenced, is mapped. +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is not "", then the namespace to
which the package, in which class is defined, is mapped as specified in
<<a2476>> +
 +
otherwise `@XmlType.namespace()`

| `{base type definition}` a| if the class contains a mapped property or
field annotated with `@XmlValue` as specified in <<xmlvalue>>,
then the schema type to which mapped property or field’s type is mapped. +
 +
otherwise schema type to which the nearest
XML-bound ancestor class is mapped +
 +
[NOTE]
.Note
====
In the absence of an extends class, java.lang.Object is the implicit
superclass of a class. java.lang.Object is by default bound to xs:anyType,
the distinguished ur- type definition, the root of schema type definition
hierarchy. In this case, the
{derivation method} is mapped to restriction rather than by extension.
java.lang.Object can be bound to xs:any using

====

| `{derivation method}` | if `{base type definition}` is `xs:anyType`,
then by `restriction` +
 +
otherwise `extension`

| `{final}` | if class modifier `final` is present then the
set `{extension, restriction}`; +
 +
otherwise, the empty set.

| `{abstract}` | `true` if the class modifier `abstract` is
present; +
 +
otherwise `false`.

| `{attribute uses}` | The set of properties or fields mapped to
attributes as specified in <<xmlattribute>>.

| `{attribute wildcard}` | Attribute wildcard as specified in <<xmlanyattribute>>.

| `{content type}` a|
. empty if no mapped property or field is
annotated with `@XmlElement`
. `mixed` if a property or field is annotated
with _@XmlMixed_ as specified in <<xmlmixed>>.
. `simpleContent` if :
.. no property or field is annotated with `@XmlElement`
.. && one or more properties or fields is annotated with `@XmlAttribute`
.. && one property is annotated with `@XmlValue`.
. `element-only content` if one or more
properties is annotated with `@XmlElement`; +
`content model` mapped as specified in <<a2662>>.

| `{prohibited substitutions}` | `empty set`
| `{annotations}` | `absent`
|===

.Table 8-5 Mapping: Class body to Model Group Component
[[a2662]]
[cols=","]
|===
| `{compositor}` | if `@XmlType.propOrder()` is {} then `xs:all`; +
 +
otherwise `xs:sequence`. The ordering of
particles is: if `@XmlType.propOrder()` is not "", then the
order in which properties/fields are listed in `@XmlType.propOrder()`. +
 +
if `@XmlType.propOrder()` is "" && class is annotated with
`@XmlAccessorOrder(XmlAcessOrder.ALPHABETICAL)` or
`@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)` is specified at the
package level and class is not annotated with
`@XmlAccessorOrder(XmlAccessOrder.UNDEFINED)`, then alphabetical order
as specified in <<xmlaccessororder>>. +
 +
otherwise order is unspecified.

| `{particles}` | Set of properties or fields mapped to
particles. See `{compositor}` mapping above for ordering of particles.

| `{annotation}` | `unspecified`
|===

.Table 8-6 Mapping: Class to Simple Type Definition
[[a2678]]
[cols=",,"]
|===
| `{name}` 2.+| if `@XmlType.name()` is "", then absent +
 +
otherwise if `@XmlType.name()` is `##default`, then the XML name derived from the class name
as specified in <<Java Identifier To XML Name>> +
 +
otherwise `@XmlType.name()`

| `{target namespace}` 2.+| if `@XmlType.namespace()` is `\\##default`
&& `@XmlType.name()` is "" and class is annotated with
`@XmlRootElement`, then the `{target namespace}` as specified in
<<a2742>> +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is "" and class is not annotated with
`@XmlRootElement`, then the `{target namespace}` of the attribute or
element to which the property or field, from where this class is
referenced, is mapped. +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is not "", then the namespace to
which the package, in which class is defined, is mapped as specified in
<<a2476>> +
 +
otherwise `@XmlType.namespace()`

| `{base type definition}` 2.+| ur-type definition, `xs:anyType`. +
 +
NOTE: This is subject to the mapping
constraints on XmlType. See <<mapping-6>>.

| `{facets}` 2.+| `empty set`
| `{fundamental facets}` 2.+| derived
| `{final}` 2.+| `empty set`. +
A subset of `{extension, list, restriction, union}`.

| `{variety}` 2.+| Must be mapped as shown below

| | atomic +
`{primitive type definition}` a| if property or field type is one of:

 * primitive type
 * wrapper class
 * reference type mapped to a simple atomic type.

| | list +
`{item type definition}` a| if the property or field type is one of the
following collection types:

* generic list
* indexed property
* single dimensional array <<xmltype-list-simple-type>>

| | union +
`{member type definitions}` | Not mapped.

| `{annotation}` 2.+| `unspecified`
|===

==== @XmlRootElement

`@XmlRooElement` can be used to associate a
global element with the schema type to which a class is mapped.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({TYPE}
public @interface XmlRootElement {
    String name() default "##default";
    String namespace() default "##default";
}
----

===== Mapping

The following mapping constraints must be
enforced:

* The only other annotations allowed with this
annotation are: `@XmlType`, `@XmlEnum`, `@XmlAccessorType`,
`@XmlAcessorOrder`.

A class annotated with `@XmlRootElement`
annotation, must be mapped as specified in <<a2742>>.

.Table 8-7 Mapping: Class to Element Declaration
[[a2742]]
[cols=","]
|===
| `{name}` | if `@XmlRootElement.name()` is `##default`,
then the XML name derived from the class name as specified in
<<Java Identifier To XML Name>>; +
 +
otherwise `@XmlRootElement.name()`

| `{target namespace}` | if `@XmlRootElement.namespace()` is `##default`,
then the value of the `targetNamespace` to which the
package containing the class is mapped as specified in
<<a2476>> +
 +
otherwise `@XmlRootElement.namespace()`

| `{type definition}` | schema type to which the class is mapped as
specified in <<xmltype-2>>.

| `{scope}` | `global`
| `{value constraint}` | `absent`
| `{nillable}` | `false`
| `{identity-constraint definitions}` | `empty set`
| `{substitution group affiliation}` a| `absent`
[NOTE]
.Design Note
====
The value is always absent since there is no mapping to a substitution group.

====

| `{substitution group exclusions}` | `{extension, restriction}`
| `{disallowed substitution}` | `{substitution, extension, restriction}`
| `{abstract}` a| `false`
[NOTE]
.Design Note
====
A value of true indicates that the element is abstract and can occur
in only content models when element has been substituted in a substitution group.
Since there is no mapping to substitution groups, this value
is always mapped to false.

====
| `{annotation}` | `unspecified`
|===

==== @XmlTransient

`@XmlTransient` is used to prevent the mapping of a class.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target(TYPE)
public @interface XmlTransient {}
----

===== Mapping

The class must not be mapped. Any reference to
this class from the other XML-bound classes will treated as if they are
refering to the nearest XML-bound ancestor of this class (which could be
`java.lang.Object`, which guarantees that there always exists such a
class.)

For the effect that this annotation causes on
derived classes, see <<a2611>>.

Note that a class with`@XmlTransient` may
still have properties and fields with JAXB annotations. Those are mapped
to XML when a derived class is mapped to XML. See <<Property And Field>>
for more details.

The following mapping constraints must be enforced:

* `@XmlTransient` is mutually exclusive with
all other mapping annotations.

==== @XmlSeeAlso

`@XmlSeeAlso` is an annotation that can be
optionally placed on a class to instruct the JAXB runtime and the schema
generator to also bind classes listed in `@XmlSeeAlso`, when it binds
the class that `@XmlSeeAlso` is on.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target(TYPE)
public @interface XmlRootElement {
    Class[] value();
}
----

=== Enum Type

==== @XmlEnum

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({TYPE})
public @interface XmlEnum {
    // Java type that is mapped to a XML simple type
    Class <?> value() default String.class;
}
----

===== Mapping

The following mapping constraints must be
enforced:

* `@XmlEnum.value()` must be mapped to a XML schema simple type.

.Table 8-8 Mapping: Enum type to Base Type Definition
[[a3331]]
[cols=",a"]
|===
| `{base type definition}` | schema type to which `@XmlEnum.value()` is mapped.
| `{variety}` | The value depends upon the schema type to which the `@XmlEnum.value()`
is mapped. But syntactically, it is always a restriction of {base type definition}
derived from the {base type definition}.
[NOTE]
.Note
====
The {base type definition} may either be a list simple type or an atomic type.
It will never be a union type because there is no mapping to union type for java->schema

====
|===

==== @XmlEnumValue

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD}
public @interface XmlEnumValue {
    String value();
}
----

===== Mapping

The following mapping constraints must be enforced:

* `@XmlEnumValue.value()` must have a valid lexical representation for `@XmlEnum.value()`.

.Table 8-9 Mapping: Enum constant to Enumeration Schema Component
[[a3230]]
[cols=","]
|===
| `{value}` |  `@XmlEnumValue.value()`
| `{annotation}` | unspecified
|===

==== @XmlType

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({TYPE})
public @interface XmlType {
    String name() default "##default";
    String namespace() default "##default";
    String[] propOrder() default {""};
    Class factoryClass() default DEFAULT.class;
    final class DEFAULT {};
    String factoryMethod() default "";
}
----

===== Mapping

The following mapping constraints must be enforced:

. `factoryMethod()`, `factoryClass()` and `@XmlType.propOrder` must be ignored.
. This annotation can be used only with the
following other annotations: `@XmlRootElement`, `@XmlAccessorOrder`,
`@XmlAccessorType`. However, `@XmlAccessorOrder` and `@XmlAccessorType`
must be ignored; they are not meaningful when used to annotate an enum
type.

.Table 8-10 Mapping: Enum type to Simple Type Definition
[cols=","]
|===
| `{name}` | if `@XmlType.name()` is "", then absent +
 +
otherwise if `@XmlType.name()` is `##default`, then
the XML name derived from the class name as
specified in <<Java Identifier To XML Name>>  +
 +
otherwise `@XmlType.name()`

| `{target namespace}` | if `@XmlType.namespace()` is `\\##default`
&& `@XmlType.name()` is "" and enum type is annotated with
`@XmlRootElement`, then the `{target namespace}` as specified in
<<a2742>> +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is "" and enum type is not annotated with
`@XmlRootElement`, then the `{target namespace}` of the attribute or
element to which the property or field, from where this enum type is
referenced, is mapped. +
 +
otherwise if `@XmlType.namespace()` is `##default` && `@XmlType.name()`
is not "", then the namespace to
which the package, in which enum type is defined, is mapped as specified in
<<a2476>> +
 +
otherwise `@XmlType.namespace()`

| `{base type definition}` a| Mapped as specified in <<a3331>>.

| `{variety}` a| Mapped as specified in <<a3331>>.

| `{final}` | `extension, restriction, list, union`.

| `{facets}` | the set constructed by mapping each enum constant
to an enumeration schema component as specified in <<a3230>>.

| `{fundamental facets}` | `empty set`
| `{annotations}` | `unspecified`
|===

==== @XmlRootElement

`@XmlRootElement` can be used to associate a
global element with the schema type to which the enum type is mapped.

===== Mapping

The following mapping constraints must be enforced:

. The only other annotations allowed with this
annotation are: `@XmlType`, `@XmlEnum`, `@XmlAccessorType`,
`@XmlAcessorOrder`. +
Note that `@XmlAccessorType` and `@XmlAccessorOrder`
while allowed will be ignored by the constraint in <<Mapping>>.

The mapping must be performed as specified in <<a2846>>.

.Table 8-11 Mapping: Enum type to Element Declaration
[[a2846]]
[cols=","]
|===
| `{name}` | if `@XmlRootElement.name()` is `"##default"`,
then the XML name derived from the enum type name as specified in
<<Java Identifier To XML Name>>;

otherwise `@XmlRootElement.name()`

| `{target namespace}` | if `@XmlRootElement.namespace()` is `"##default"`,
then the value of the targetNamespace to which the
package containing the class is mapped as specified in
<<a2476>>

otherwise `@XmlRootElement.namespace()`

| `{type definition}` | schema type to which the class is mapped as
specified in <<xmltype-2>>.

| `{scope}` | `global`
| `{value constraint}` | `absent`
| `{nillable}` | `false`
| `{identity-constraint definitions}` | `empty set`
| `{substitution group affiliation}` a| `absent`
[NOTE]
.Design Note
====
The value is always absent since there is no mapping to a substitution group.
====

| `{substitution group exclusions}` | `{extension, restriction}`
| `{disallowed substitution}` | `{substitution, extension, restriction}`
| `{abstract}` | `false`
| `{annotation}` | `unspecified`
|===

=== Property And Field

The following must be mapped (subject to the mapping constraints listed below):

* read/write property with its nearest XML-bound
superclass as the stopClass.
* non static, non transient field of all the
ancestors up to the stopClass (but excluding the stopClass itself); if
annotated with `@XmlAttribute`, then static final field must be mapped
(informally this maps to a fixed attribute but this is formally
specified in the mapping tables below).

A _mapped property_ is a property found as above
and mapped either by default or using a JAXB annotation.

A _mapped field_ is a field found as above and
mapped either by default or using a JAXB annotation.

A property or field that has been annotated
with `@XmlTransient` is not mapped.

The following mapping constraints must be enforced.

* For a property, a given annotation can be
applied to either read or write property but not both.
* A property name must be different from any
other property name in any of the super classes of the class being
mapped.
* A mapped field name or the de capitalized
name of a mapped property must be unique within a class. For e.g.
+
[source,java,indent=4]
----
 // Example 1:
 // Both the field "x" and property getX/setX are mapped by
 // default. However, the decapitalized name property getX/setX
 // is also "x" which collides with the field name "x".
public class Foo {
    public int x;
    public int getX {...};
    public void setX {...};
 }
----

==== @XmlElement

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD}
public @interface XmlElement {
    String name() default "##default"; // name for XML element
    boolean nillable() default false;
    boolean required() default false;
    String namespace() default "##default";
    Class type() default DEFAULT.class;
    String defaultValue() default "\u0000";
    static final class DEFAULT {}
}
----

===== Mapping

The following mapping constraints must be enforced:

* The only additional mapping annotations
allowed with `@XmlElement` are: `@XmlID`, `@XmlIDREF`, `@XmlList`,
`@XmlSchemaType`, `@XmlValue`, `@XmlAttachmentRef`, `@XmlMimeType`,
`@XmlInlineBinaryData`, `@XmlJavaTypeAdapter` and `@XmElementWrapper`.
`@XmlElement` can also be used within `@XmlElements`.
* If the property or field type is a
parametric collection type, then `@XmlElement.type()` must be
`DEFAULT.class` or `collectionitem.class` (since the type of the
collection is already known).

A field or property annotated must be mapped as follows:

* If `@XmlElement.namespace()` is not `"##default"`
and different from the `{target namespace}` of the
enclosing class, then it must be mapped as specified in <<a2941>>.
* If property is single valued, and it’s type
is annotated with `@XmlRootElement` and `@XmlType.name() = ""`, then the
property must be mapped as specified in <<a2941>>.
+
[NOTE]
.Design Note
====
This mapping is designed to eliminate an infinite recursion. For example:

[source,java,indent=4]
----
// Code fragment
@XmlRootElement
@XmlType(name="")
class Foo {
    Foo foo;
}
----

In the absence of the above mapping, the above code would map to:

[source,xml,indent=2]
----
<schema>
  <element name="foo">
    <complexType>
      <sequence>
        <element name="foo" minOccurs="0">
          <complexType>
            ... infinite recursion ...
----

With the above mapping, the code fragment would instead map to:

[source,xml,indent=2]
----
<schema>
  <element name="foo">
    <complexType>
      <sequence>
        <element ref="foo" minOccurs="0">
----
====
* otherwise, it must be mapped as <<a2959>>.

[NOTE]
.Design Note
====
A local element corresponds to two abstract schema components - a particle
and an element declaration. This is reflected in the mapping shown below.
====

.Table 8-12 Mapping: Property/field to Particle - ref attribute
[[a2941]]
[cols=","]
|===
| `{min occurs}` | if `@XmlElement.required()` is `true`, then `1`

if the property type is a primitive type or a
multi dimensional array with a primitive type then `1`

otherwise `0`

| `{max occurs}` | if the type of the property/field is not a
collection type, then `1`

otherwise `unbounded`.

| `{term}` a| element declaration as specified in <<a2973>>
with the following overrides for the abstract schema component properties: +
`{scope}` is `global` +
`{value constraint}` is `absent` +
`{type definition}` is `xs:anyType` if the
mapping results in two or more element decalarations with the same name.
[NOTE]
.Note
====
The above make the element a global
element declaration rather than a local element declaration.
====
|===

.Table 8-13 Mapping: Property/field to Particle - no ref attribute
[[a2959]]
[cols=","]
|===
| `{min occurs}` | if `@XmlElement.required()` is `true`, then `1`

otherwise if the property type is a primitive
type or a multi dimensional array with a primitive type then `1`

otherwise `0`

| `{max occurs}` | if the type of the property/field is not a
collection type, then `1`;

otherwise `unbounded`.

| `{term}` | must be mapped as specified in <<a2973>>.
|===

.Table 8-14 Mapping: Property/field to Element declaration
[[a2973]]
[cols=","]
|===
| `{name}` | if `@XmlElement.name()` is `"##default"`, then
the XML name derived from the property or field name as specified in
<<Java Identifier To XML Name>>;

otherwise `@XmlElement.name()`

| `{target namespace}` a| if `@XmlElement.namespace()` is `"##default"`, then
[none]
* if the enclosing package has `@XmlSchema`
annotation and is `@XmlSchema.elementFormDefault` is
`@XmlNsForm.QUALIFIED`, then the namespace of the enclosing class.
* otherwise "" (which produces unqualified element in the default
namespace).

otherwise, `@XmlElement.namespace()`

| `{type definition}` | Note: The order of type inference below is significant.

if `@XmlElement.type()` is not `DEFAULT.class`,
then the schema type to which `@XmlElement.type()` is mapped.

otherwise if annotated with `@XmlList`, schema
type derived by mapping as specified in <<xmllist>>

otherwise if annotated with `@XmlValue`,
schema type derived by mapping as specified in <<xmlvalue>>

otherwise if annotated with `@XmlID`, the
schema type derived by mapping as specified in <<xmlid>>

otherwise if annotated with `@XmlIDREF`, the
schema type derived by mapping as specified in
<<xmlidref>>

otherwise if the property or field is a
collection type, then the schema type derived by mapping the collection
item type.

otherwise the schema type to which the type of
the property is mapped.

| `{scope}` | complex type to which the property’s or the
field’s containing class is mapped as specified in <<xmlschema>>.

| `{value constraint}` | if `@XmlElement.defaultValue()` is `"\u0000"` then `absent`

otherwise default value with the value
`@XmlElement.defaultvalue()`.

| `{nillable}` | `@XmlElement.nillable()`

| `{identity-constraint definitions}` | `absent`

| `{substitution group affiliation}` | `absent`

| `{substitution group exclusions}` | {`extension`, `restriction`}

| `{disallowed substitution}` | {`extension`, `restriction`, `substitution`}

| `{abstract}` | `false`

| `{annotation}` | `unspecified`
|===

==== @XmlElements

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD,METHOD})
public @interface XmlElements {
    XmlElement[] value(); // collection of @XmlElement annotations
}
----

===== Mapping

The following mapping constraints must be enforced:

* If the property or field type is a
parameterized collection type, then the size of the
`@XmlElements.value()` must be `1`.
* This annotation can be used only with the
following annotations: `@XmlIDREF`, `@XmlElementWrapper`,
`@XmlJavaTypeAdapter`.
* If `@XmlIDREF` is specified, then each
`@XmlElement.type()` must contain a JavaBean property/field annotated
with `@XmlID`.

The property or field must be mapped as follows:

* If the size of `@XmlElements.value()` is `1`,
then the property must be mapped as specified in <<xmlelement>>.
* otherwise it must be mapped as specified in <<a3034>>.



.Table 8-15 Mapping: List of types to choice particle
[[a3034]]
[cols=","]
|===
| `{min occurs}` | `0`
| `{max occurs}` | `unbounded`
| `{term}` | If `{particles}` row in <<a3042>> results in a single particle,
then that single particle. Otherwise mapped as specified in <<a3042>>
|===


.Table 8-16 Mapping: List of types to choice model group of elements
[[a3042]]
[cols=","]
|===
| `{compositor}` | `choice`
| `{particles}` | set obtained by mapping each `@XmlElement` in
`@XmlElements.value()` as specified in <<a2973>>.
| `{annotation}` | `unspecified`
|===

==== @XmlElementRef

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD}
public @interface XmlElementRef {
    String name() default "##default"; // name for XML element
    String namespace() default "##default";
    Class type() default DEFAULT.class;
    static final class DEFAULT {}
}
----

===== Mapping

The following mapping constraints must be enforced:

* The only other additional JAXB mapping
annotations allowed with `@XmlElementRef` are: `@XmlElementWrapper` and
`@XmlJavaTypeAdapter`.
* If the collection item type or property type
(for single valued property) is `jakarta.xml.bind.JAXBElement`, then
{`@XmlElementRef.name()`, `@XmlElementRef.namespace()`} must point an
element factory method with an `@XmlElementDecl` annotation in a class
annotated with `@XmlRegistry` (usually `ObjectFactory` class generated
by the schema compiler):
.. `@XmlElementDecl.name()` must equal `@XmlElementRef.name()`
.. `@XmlElementDecl.namespace()` must equal `@XmlElementRef.namespace()`.
* If the collection item type (for collection
property) or property type (for single valued property) is not
`jakarta.xml.bind.JAXBElement`, then the type referenced by the property
or field must be annotated with `@XmlRootElement`.

A field or property annotated with the
`@XmlElementRef` annotation must be mapped as follows:

* if the type of the property or field is
single valued property, then it must be mapped as specified in <<a3078>>
* otherwise (the type of the property or field
is a parametric type), then it must be mapped as specified in <<a3097>>.


.Table 8-17 Mapping: Property/field (property type single valued) to Particle with ref attribute
[[a3078]]
[cols=","]
|===
| `{min occurs}` | if `@XmlElementRef.required()` is `true` ,then `1`;

otherwise `0`
| `{max occurs}` | `1`
| `{term}` | must be mapped as specified in <<a3085>>.
|===

.Table 8-18 Mapping: Property/field to Element declaration with ref attribute
[[a3085]]
[cols=","]
|===

| `{name}` | if `@XmlElementRef.type()` is
`@XmlElementRef.DEFAULT.class` and the property type is not
`jakarta.xml.bind.JAXBElement`, then the XML name
`@XmlRootElement.name()` on the type being referenced.

otherwise if `@XmlElementRef.type()` is
`@XmlElementRef.DEFAULT.class` and the parametric type or the property
type (for single valued property) is a `jakarta.xml.bind.JAXBElement`,
then the `@XmlElementRef.name()`

| `{target namespace}` | if `@XmlElementRef.type()` is
`@XmlElementRef.DEFAULT.class` and the property type is not
`jakarta.xml.bind.JAXBElement`, then the XML namespace of the type being
referenced.

otherwise if `@XmlElementRef.type()` is
`@XmlElementRef.DEFAULT.class` and the property type is single valued
and is `jakarta.xml.bind.JAXBElement`, then the
`@XmlElementRef.namespace()`

| `{annotation}` | `unspecified`
|===

.Table 8-19 Mapping: Property/Field (parametric type) to choice particle
[[a3097]]
[cols=","]
|===

| `{min occurs}` | `0`
| `{max occurs}` | `unbounded`
| `{term}` | If `{particles}` row in <<a3105>> results in single particle,
then that single particle. Otherwise mapped as specified in <<a3105>>
|===

.Table 8-20 Mapping: Property/field (parametric type) to choice model group of element refs
[[a3105]]
[cols=","]
|===
| `{compositor}` | `choice`
| `{particles}` | set obtained by visiting parametric type and
each of its derived types and if annotated with @XmlRootElement, then
mapping the @XmlRootElement as specified in as specified in <<a3085>>.

| `{annotation}` | `unspecified`
|===

==== @XmlElementRefs

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD,METHOD})
public @interface XmlElementRefs {
    XmlElementRef[] value();
}
----

===== Mapping

The following mapping constraints must be enforced:

* The only other additional JAXB mapping
annotations allowed with `@XmlElementRefs` are: `@XmlElementWrapper` and
`@XmlJavaTypeAdapter`.

The property or field must be mapped as
specified in <<a3124>>.


.Table 8-21 Mapping: List of element instances to choice particle
[[a3124]]
[cols=","]
|===
| `{min occurs}` | `0`
| `{max occurs}` | `unbounded`
| `{term}` | If the `{particles}` row in <<a3132>> results in a single particle,
then that single particle. Otherwise mapped as specified in <<a3132>>
|===

.Table 8-22 Mapping: List of element instances to choice model group of element refs
[[a3132]]
[cols=","]
|===
| `{compositor}` | `choice`
| `{particles}` a| set obtained by mapping

* each `@XmlElementRef` in
`@XmlElementRefs.value()` as specified in <<xmlelementref>>.
* if property is annotated with `@XmlAnyElement`,
then the particle obtained by mapping as specified in <<xmlanyelement>>

| `{annotation}` | `unspecified`
|===

==== @XmlElementWrapper

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD}
public @interface XmlElementWrapper {
    String name() default "##default" ; // name for XML element
    String namespace() default "##default";
    boolean nillable() default false;
    boolean required() default false;
}
----

===== Mapping

The following mapping constraints must be enforced:

* The only additional mapping annotations
allowed with `@XmlElementWrapper` are: `@XmlElement`, `@XmlElements`,
`@XmlElementRef`, `@XmlElementRefs`, `@XmlJavaTypeAdapter`.
* The property or the field must be a collection property.

The property or field must be mapped as follows:

* If `@XmlElementWrapper.namespace()` is not `"##default"`
and different from the `{target namespace}` of the enclosing class,
then it must be mapped as specified as specified in <<a3202>>.
* otherwise, it must be mapped as <<a3158>>.

.Table 8-23 Mapping: Property/field to Particle for Element Wrapper
[[a3158]]
[cols=","]
|===
| `{min occurs}` | if `@XmlElementWrapper.nillable()` is `true` or
`@XmlElementWrapper.required()` is `true`, then `1`;

otherwise `0`

| `{max occurs}` | `1`
| `{term}` | must be mapped as specified in <<a3167>>.
|===

.Table 8-24 Mapping: Property/field to Element Declaration for Element Wrapper
[[a3167]]
[cols=","]
|===
| `{name}` | if `@XmlElementWrapper.name()` is `"##default"`,
then the XML name derived from the property or field name
as specified in <<Java Identifier To XML Name>>;

otherwise `@XmlElementWrapper.name()`

| `{target namespace}` a| if `@XmlElementWrapper.namespace()` is `"##default"`,
[none]
* if the enclosing package has `@XmlSchema`
annotation and is `@XmlSchema.elementFormDefault` is
`@XmlNsForm.QUALIFIED`, then the namespace of the enclosing class.
* otherwise "" (which produces unqualified element in the default namespace).

otherwise `@XmlElementWrapper.namespace()`

| `{type definition}` | if property/field is annotated with
`@XmlElementRef` or `@XmlElementRefs` then the schema type as specified in <<a3124>>

otherwise if property/field is annotated with
`@XmlElement` or `@XmlElements` then the schema type as specified <<a3034>>.

| `{scope}` | complex type to which the property’s or the
field’s containing class is mapped.
| `{value constraint}` | `absent`
| `{nillable}` | `@XmlElementWrapper.nillable()`
| `{identity-constraint definitions}` | `absent`
| `{substitution group affiliation}` | `absent`
| `{substitution group exclusions}` | {`extension`, `restriction`}
| `{disallowed substitution}` | {`extension`, `restriction`, `substitution`}
| `{abstract}` | `false`
| `{annotation}` | `unspecified`
|===

.Table 8-25 Mapping: Property/field Element Wrapper with ref attribute
[[a3202]]
[cols=","]
|===
| `{min occurs}` | `1`
| `{max occurs}` | `1`
| `{term}` a| element declaration whose `{name}` is
`@XmlElementWrapper.name()` and `{target namespace}` is
`@XmlElementWrapper.namespace()`.
[NOTE]
.Note
====
The element declaration is assumed to
already exist and is not created.
====
|===

==== @XmlAnyElement

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlAnyElement {
    boolean lax() default false;
    Class<? extends DomHandler> value() default W3CDomHandler.class;
}
----

===== Mapping

The following mapping constraints must be enforced:

* The only other JAXB annotations allowed with
`@XmlAnyElement` are: `@XmlElementRefs`.
* There must be only one property or field
that is annotated with `@XmlAnyElement`.
* If a _baseType_ has a property annotated with
`@XmlAnyElement`, then no other sub type in the inheritance hierarchy
rooted at _baseType_ can contain a property annotated with
`@XmlAnyElement`.

The property or field must be mapped as
specified in <<a3223>>.

.Table 8-26 Mapping: Wildcard schema component for wildcard (xs:any)
[[a3223]]
[cols=","]
|===
| `{namespace constraint}` | `##other`
| `{process contents}` | `"lax"` if `lax()` is `true` otherwise `"skip"`
| `{annotation}` | `unspecified`
|===

==== @XmlAttribute

`@XmlAttribute` is used to map a property or a field to an XML attribute.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlAttribute {
    String name() default "##default";
    boolean required() default false;
    String namespace() default "##default";
}
----

===== Mapping

The following mapping constraints must be enforced:

* If the type of the field or the property is
a collection type, then the collection item type must be mapped to
schema simple type. Examples:
+
[source,java,indent=4]
----
@XmlAttribute List<Integer> foo; // legal
@XmlAttribute List<Bar> foo;     // illegal if Bar does not map to a
                                 // schema simple type
----
* If the type of the field or the property is
a non collection type, then the type of the property or field must map
to a simple schema type. Examples:
+
[source,java,indent=4]
----
@XmlAttribute int foo;  // legal
@XmlAttribute Foo foo;  // illegal if Foo does not map to a schema
                        // simple type
----
* The only additional mapping annotations
allowed with `@XmlAttribute` are: `@XmlID`, `@XmlIDREF`, `@XmlList`,
`@XmlSchemaType`, `@XmlValue`, `@XmlAttachmentRef`, `@XmlMimeType`,
`@XmlInlineBinaryData`, `@XmlJavaTypeAdapter`.

[NOTE]
.Design Note
====
The mapping below supports mapping to either a local attribute or a reference
to a global attribute that already exists. The latter is useful for mapping to
attributes in foreign namespaces for e.g. <xs:attribute ref="xml:lang"/>.
Note that the attribtue is never created in the namespace, `@XmlAttribute.namespace()`;
it is assumed to exist (for e.g. "xml:lang"). The property or field is mapped to
an attribtue reference when `@XmlAttribute.namespace()` is different from
the `{target namespace}` of the type containing the property or field being mapped.
====

The property or field must be mapped as follows:

* If `@XmlAttribute.namespace()` is not
`"##default"` and differs from the `{target namespace}` of the schema
type to which the type containing the property or field is mapped, then
the property or field must be mapped as specified in <<a3255>>.
* otherwise, it must be mapped as specified in <<a3266>>.



.Table 8-27 Mapping: Property/field to Attribute Use (with ref attribute)
[[a3255]]
[cols=","]
|===
| `{required}` | `@XmlAttribute.required()`
| `{attribute declaration}` a| attribute declaration whose `{name}` is
`@XmlAttribute.name()` and `{target namespace}` is
`@XmlAttribute.namespace()`. +
For e.g.
[source,xml,indent="2"]
----
<xs:attribute ref="xml:lang"/>
----
| `{value constraint}` | `absent`
| `{annotation}` | `unspecified`
|===

.Table 8-28 Mapping: Property/field to Attribute Use (no ref attribute)
[[a3266]]
[cols=","]
|===
| `{required}` | `@XmlAttribute.required()`
| `{attribute declaration}` | Mapped as specified in <<a3276>>

| `{value constraint}` | if field has access modifiers public and
static then the `fixed`

otherwise `absent`
|===


.Table 8-29 Mapping: Property/field to Attribute Declaration
[[a3276]]
[cols=","]
|===
| `{name}` | if `@XmlAttribute.name()` is `"##default"`, then
the XML name derived from the property or field name as specified in
<<Java Identifier To XML Name>>;

otherwise `@XmlAttribute.name()`.

| `{target namespace}` | if `@XmlAttribute.namespace()` is `"##default"`,
then value of targetNamespace in <<a2476>>;

otherwise `@XmlAttribute.namespace()`

| `{type definition}` | if annotated with `@XmlList`, schema type
derived by mapping as specified in <<xmllist>>

otherwise if annotated with `@XmlID`, the
schema type derived by mapping as specified in
<<xmlid>>

otherwise if annotated with `@XmlIDREF`, the
schema type derived by mapping as specified in <<xmlidref>>

otherwise if the type of the property is a
collection type, then the schema type derived by mapping the collection
item type.

otherwise the schema type to which the type of
the property is mapped.

| `{scope}` | complex type of the containing class

| `{value constraint}` | if field has access modifiers static and final then `fixed`

otherwise `absent`

| `{annotation}` | `unspecified`
|===

==== XmlAnyAttribute

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlAnyAttribute{}
----

===== Mapping

The following mapping constraints must be enforced:

* There must be only one property or field in
a class that is annotated with `@XmlAnyAttribute`.
* The type of the property or the field must
be `java.util.Map`.
* The only other annotations that can be used
on the property or field with `@XmlAnyAttribute` are:
`@XmlJavaTypeAdapter`.

The property or field must be mapped as
specified in <<a3313>>.

.Table 8-30 Mapping: Wildcard schema component for Attribute Wildcard
[[a3313]]
[cols=","]
|===
| `{namespace constraint}` | `##other`
| `{process contents}` | `skip`
| `{annotation}` | `unspecified`
|===

==== @XmlTransient

`@XmlTransient` is used to prevent the mapping of a property or a field.

===== Synopsis
[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD, TYPE})
public @interface XmlTransient {}
----

===== Mapping

The following mapping constraints must be enforced:

* The field or the property must not be mapped.
* `@XmlTransient` is mutually exclusive with
all other mapping annotations.

==== @XmlValue

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlValue {}
----

===== XmlValue Type Mapping

The following mapping constraints must be enforced:

. At most one field or a property in a class
can be annotated with `@XmlValue`.
. `@XmlValue` can be used with the following annotations:
.. `@XmlList` - however this is redundant
since `@XmlList` maps a type to a schema simple type that derives by
list just as `@XmlValue` would.
.. `@XmlJavaTypeAdapter`
. If the type of the field or property is a
collection type, then the collection item type must map to a simple
schema type.
+
.Examples:
[source,java,indent=4]
----
// Examples (not exhaustive): Legal usage of @XmlValue
@XmlValue List<Integer> foo; // int maps to xs:int
@XmlValue String[] foo;      // String maps to xs:string
@XmlValue List<Bar> foo;     // only if Bar maps to a simple
                             // schema type
----
. If the type of the field or property is not
a collection type, then the type of the property or field must map to a
schema simple type.
. The containing class must not extend another
class (other than `java.lang.Obect`).

===== Mapping

* If the type of the property or field is a
collection type, then the type must be must be mapped as specified in
<<a3353>>.
* Otherwise, the schema type to which the type
of the property or field is mapped.

.Table 8-31 @XmlValue: Mapping to list simple type
[[a3353]]
[cols=","]
|===
| `{name}` | `absent`
| `{target namespace}` | `{target namespace}` of the attribute or
element to which the property or field is mapped and from where this
type is referenced.

| `{base type definition}` | ur-type definition, `xs:anyType`.
| `{facets}` | `empty set`
| `{fundamental facets}` | `derived`
| `{final}` | `#all`
| `{variety}` | list
| `{item type definition}` a| if the field, property or parameter is a
collection type

* if annotated with `@XmlIDREF`, then
`xs:IDREF` as specified in <<xmlidref>>
* otherwise the schema type to which the
collection item type is mapped.

otherwise

* if annotated with `@XmlIDREF`, then
`xs:IDREF` as specified in <<xmlidref>>
* otherwise the schema type to which the type
of the property, field or the parameter is mapped.

| `{annotation}` | `unspecified`
|===

==== @XmlID

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlID {}
----

===== Mapping

The following mapping constraints must be enforced:

* at most one field or property in a class can
be annotated with `@XmlID`.
* The type of the field or property must be
`java.lang.String`.
* The only other program annotations allowed
with `@XmlID` are: `@XmlAttribute` and `@XmlElement`.

The type of the annotated program element must
be mapped to `xs:ID`.

==== @XmlIDREF

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlIDREF {}
----

===== Mapping

The following mapping constraints must be enforced:

* If the type of the field or property is a
collection type, then the collection item type must contain a property
or field annotated with `@XmlID`.
* If the field or property is not a collection
type, then the type of the property or field must contain a property or
field annotated with `@XmlID`.
+
[NOTE]
.Note
====
If the collection item type or the type
of the property (for non collection type) is `java.lang.Object`, then
the instance must contain a property/field annotated with `@XmlID` attribute.

====

* The only additional mapping annotations
allowed with `@XmlIDREF` are: `@XmlElement`, `@XmlAttribute`, `@XmlList`,
and `@XmlElements`, `@XmlJavaTypeAdapter`.

If the type of the field or property is a
collection type, then each collection item type must be mapped to
`xs:IDREF`.

If the type of the field or property is single
valued, then the type of the property or field must be mapped to
`xs:IDREF`.

==== @XmlList

This annotation maps a collection type to a list simple type.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER})
public @interface XmlList {}
----

===== Mapping

The following mapping constraints must be enforced:

* The type of the field, property or parameter
must be a collection type.
* The collection item type must map to a
simple schema type that does not derive by list. For example:
+
[source,java,indent=4]
----
// Examples: Legal usage of @XmlList
@XmlList List<Integer> foo; // int maps to xs:int
@XmlList String[] foo; // String maps to xs:string
@XmlList List<Bar> foo; // only if Bar maps to a simple type

// Example: Illegal usage of @XmlList
public class Foo {
    // @XmlValue maps List to a XML Schema listsimple type
    @XmlValue List<Integer> a;
}

class Bar {
    // Use of @XmlList is illegal since Fooitself mapped
    // to a XML Schema list simple type; XMLSchema list simple
    // type can't derive from another XML Schemalist simple type
    @XmlList List<Foo> y;
}
----

* The only additional mapping annotations
allowed with `@XmlList` are: `@XmlElement`, `@XmlAttribute`, `@XmlValue` and
`@XmlIDREF`, `@XmlJavaTypeAdapter`.

The type of the property or field must be
mapped as specified in <<a3428>>.

.Table 8-32 @XmlList: Mapping to list simple type
[[a3428]]
[cols=","]
|===
| `{name}` | `absent`
| `{target namespace}` | `{target namespace}` of the attribute or
element to which the property or field is mapped and from where this
type is referenced.

| `{base type definition}` |  ur-type definition, `xs:anyType`.
| `{facets}` | `empty set`
| `{fundamental facets}` | `derived`
| `{final}` | `#all`
| `{variety}` | list
| `{item type definition}` | if annotated with `@XmlIDREF`, then `xs:IDREF`
as specified in <<xmlidref>>

otherwise the schema type to which the
collection item type is mapped.

| `{annotation}` | `unspecified`
|===

==== @XmlMixed

This annotation is used for dealing with mixed
content in XML instances.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlMixed {}
----

===== Mapping

The following mapping constraints must be enforced:

* The only additional mapping annotations
allowed with`@XmlMixed` are: `@XmlElementRef`, `@XmlAnyElement`,
`@XmlJavaTypeAdapter`.

The `java.lang.String` instances must be
serialized as XML infoset text information items.

==== @XmlMimeType

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME)
@Target({FIELD,METHOD,PARAMETER})
public @interface XmlMimeType {
    // Textual representation of the MIME type,such as "image/jpeg"
    // "image/*", "text/xml; charset=iso-8859-1"and so on.
    String value();
}
----

===== Mapping

.Table 8-33 @XmlMimeType: Mapping to Foreign Namespace attribute
[cols=","]
|===
| `{name}` | `"expectedContentTypes"`
| `{target namespace}` | `"http://www.w3.org/2005/05/xmlmime"`
| `attribute value` | `@XmlMimeType.value()`
|===

==== @XmlAttachmentRef

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD,METHOD,PARAMETER})
public @interface XmlAttachmentRef {}
----

===== Mapping

The type of property or field must map to `ref:swaRef`.

==== XmlInlineBinaryData

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({FIELD,METHOD,TYPE})
public @interface XmlInlineBinaryData {
}
----

===== Mapping

This annotation does not impact the schema
generation. See the javadoc for
`jakarta.xml.bind.annotation.XmlInlineBinaryData` for more details.

=== ObjectFactory Method

The annotations in this section are intended
primarily for use by schema compiler in annotating element factory
methods in the schema derived ObjectFactory class
(<<Java Package>>). They are not expected
to be used when mapping existing classes to schema.

==== @XmlElementDecl

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({METHOD})
public @interface XmlElementDecl {
    Class scope() default GLOBAL.class;

    // XML namespace of element
    String namespace() default "##default";

    String name(); // local name of element

    //XML namespace name of a substitution group's head element.
    String substitutionHeadNamespace() default "##default";

    //XML local name of a substitution group's head element.
    String substitutionHeadName() default "";
    final class GLOBAL {}
}
----

===== Mapping

The following mapping constraints must be enforced:

* annotation can only be used on an _element factory method_ (<<Java Package>>).
The annotation creates a mapping between an XML schema element declaration
and a element factory method that returns a `JAXBElement` instance
representing the element declaration. Typically, the element factory
method is generated (and annotated) from a schema into the
`ObjectFactory` class in a Java package that represents the binding of
the element declaration's target namespace. Thus, while the annotation
syntax allows `@XmlElementDecl` to be used on any method, semantically
its use is restricted to annotation of element factory method
* class containing the element factory method
annotated with `@XmlElementDecl` must be annotated with `@XmlRegistry`.
* element factory method must take one
parameter assignable to `java.lang.Object`.
* two or more element factory methods
annotated with `@XmlElementDecl` must not map to element declarations
with identical `{name}` `{target namespace}` values.
* if type `Foo` has an element factory method
and is also annotated with @XmlRootElement, then they must not map to
element declarations with identical `{name}` and `{target namespace}`
values.
+
One example of where the above scenario occurs
is when a developer attempts to add behavior/data to code generated from
schema. For e.g. schema compiler generates an element instance factory
method (e.g. `createFoo`) annotated with `@XmlElementDec`. But the
developer annotates `Foo` with `@XmlRootElement`.

An element factory method must be mapped as
specified in <<a3518>>.

.Table 8-34 Mapping: Element Factory method to Element Declaration
[[a3518]]
[cols=","]
|===
| `{name}` | `@XmlElementDecl.name()`
| `{target namespace}` | if `@XmlElementDecl.namespace()` is `"##default"`,
then the value of the `targetNamespace` to which the
package of the class containing the factory method is mapped as
specified in <<a2476>>

otherwise `@XmlElementDecl.namespace()`

| `{type definition}` | schema type to which the class is mapped as
specified in <<xmltype-2>>.

| `{scope}` | `global` if `@XmlElementDecl.scope()` is
`@XmlElementDecl.GLOBAL`

otherwise the complex type definition to which
the class containing the object factory method is mapped.

| `{value constraint}` | `absent`
| `{nillable}` | `false`
| `{identity-constraint definitions}` | `empty set`
| `{substitution group affiliation}` | element declaration derived from
`@XmlElementDecl.name()` and `@XmlElementDecl.substitutionHeadName()`

| `{substitution group exclusions}` |  `{}`
| `{disallowed substitution}` | `{}`
| `{abstract}` | `false`
| `{annotation}` | `unspecified`
|===

=== Adapter

==== XmlAdapter

[source,java,indent=4]
----
public abstract class XmlAdapter<ValueType,BoundType> {
    // Do-nothing constructor for the derivedclasses.
    protected XmlAdapter() {}

    // Convert a value type to a bound type.
    public abstract BoundType unmarshal(ValueType v);

    // Convert a bound type to a value type.
    public abstract ValueType marshal(BoundType v);
}
----

For an overview, see the section, <<adapter>>.

For detailed information, see the javadocs for
`jakarta.xml.bind.annotation.adapters.XmlAdapter` and
`jakarta.xml.bind.annotation.adapters.XmlJavaTypeAdapter`.

==== @XmlJavaTypeAdapter

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({PACKAGE,FIELD,METHOD,TYPE,PARAMETER})
public @interface XmlJavaTypeAdapter {
    Class<? extends XmlAdapter> value();
    Class type() default DEFAULT.class;
    final class DEFAULT {}
}
----

For an overview, see <<adapter>>.

===== Scope

The scope of `@XmlJavaTypeAdapter` must cover
the program elements as specified below:

*_package:_*

For clarity, the following code example is used along with normative text.

[source,java,indent=4]
----
// Adapts Foo type to MyFoo type
FooAdapter extends XmlAdapter<MyFoo, Foo>

// FooAdapter is installed at the package level - example.po
@XmlJavaTypeAdapter(value=FooAdapter.class, type=Foo.class)
----
A `@XmlJavaTypeAdapter` that extends
`XmlAdapter<valueType, boundType>` and is specified as a package level
annotation must adapt `boundType` at the point of reference as follows:

. a property/field/parameter within a class in
package (e.g `exmple.po)` whose reference type is `boundType`. For e.g.
+
[source,java,indent=4]
----
 // Foo will be adapted to MyFoo
 Foo foo;
----
. a property/field/parameter within a class in
package (e.g `exmple.po`), where `boundType` is used as a parametric
type. For e.g.
+
[source,java,indent=4]
----
 // List<Foo> will be adapted to List<MyFoo>
 Foo foo;
----

*_class, interface, enum type:_*

For clarity, the following code example is used along with normative text.

[source,java,indent=4]
----
// Adapts Foo type to MyFoo type
FooAdapter extends XmlAdapter<MyFoo, Foo>

// FooAdapter is specified on class, interface or enum type.
@XmlJavaTypeAdapter(FooAdapter.class)
public class Foo {...}
----

A `@XmlJavaTypeAdapter` that extends
`XmlAdapter<valueType, boundType>` and is specified on the class,
interface or Enum type (i.e. on a program element that matches meta
annotation `@Target={type}`) must adapt `boundType` at the point of
reference as follows:

. a property/field whose reference type is `boundType`. For e.g.
+
[source,java,indent=4]
----
// Foo will be adapted to MyFoo
Foo foo;
----
. a property/field where `boundType` is used as a parametric type. For e.g.
+
[source,java,indent=4]
----
// List<Foo> will be adapted to List<MyFoo>
List<Foo> foo;
----

[NOTE]
.Note
====
A `@XmlJavaTypeAdapter` on a class does
not apply to references to it’s sub class.

[source,java,indent=4]
----
//Example:
@XmlJavaTypeAdapter(...) public class Foo {...}
...
public class DerivedFoo extends Foo {...}
...
public class Bar {
    // XmlJavaTypeAdapter applies to foo;
    public Foo foo;
    ...
    // XmlJavaTypeAdaper DOES NOT apply to derivedFoo;
    public DerivedFoo derivedFoo;
}
----
====

*_property/field/parameter_*:

A `@XmlJavaTypeAdapter` that extends
`XmlAdapter<valueType, boundType>` and is specified on the
property/field or parameter must adapt `boundType` as follows:

. property/field is a single valued and its type is `boundType`:
+
[source,java,indent=4]
----
// Foo will be adapted to MyFoo
@XmlJavaTypeAdapter(FooAdapter.class) Foo foo;
----
. a property/field where `boundType` is used as a parametric type. For e.g.
+
[source,java,indent=4]
----
// List<Foo> will be adapted to List<MyFoo>
List<Foo> foo;
----

===== Relationship to other annotations

`@XmlJavaTypeAdapter` must be applied first
before any other mapping annotation is processed. Further annotation
processing is subject to their respective mapping constraints. For
example,

[source,java,indent=4]
----

// PtoQAdapter is applied first and therefore converts type Q to P
// Next foo is mapped with a type of P (not Q) subject to the
// mapping constraints specified in@XmlElements.
@XmlJavaTypeAdapter(PtoQAdapter)
@XmlElements({
    @XmlElement(name="x",type=PX.class),
    @XmlElement(name="y",type=PY.class)
})
Q foo;

@XmlType abstract class P {}
@XmlType class PX extends P {}
@XmlType class PY extends P {}
----

===== Class Inheritance Semantics

When annotated on a class, the use of
`@XmlJavaTypeAdapter` annotation is subject to the class inheritance
semantics described here. The semantics is described in terms of two
classes: a `BaseClas` and a `SubClass` that derives from `BaseClass`.
There are two cases to consider:

* `@XmlJavaTypeAdapter` annotates the `BaseClass`
* `@XmlJavaTypeAdapter` annotates the `SubClass`,
a class that derives from `BaseClass`.

*_BaseClass_*: In this case, `@XmlJavaTypeAdapter`
annotates the `BaseClass`. In this case, the marshalling and
unmarshalling of an instance of property or a field with a static type
of baseClass must follow the schema to which
`XmlJavaTypeAdapter.value()` is mapped.

[source,java,indent=4]
----
//Example: code fragment
@XmlJavaTypeAdapter(...) BaseClass {...}
public SubClass extends BaseClass {...}
public BaseClass foo;
public SubClass subFoo = new SubClass();
foo = subFoo;
----

In the absence of `@XmlJavaTypeAdapter` annotation,
the instance of subFoo is marshalled with an `xsi:type`:

[source,xml,indent=4]
----
<foo xsi:type="subClass"/>
----

With the `@XmlJavaTypeAdapter` annotation,
however, the instance of `subFoo` must be marshalled/unmarshalled
following the XML schema for `@XmlJavaTypeAdapter.value()`.

*_Subclass_*: In this case, `@XmlJavaTypeAdapter`
annotates the `SubClass`. By definition, the annotation does not cover
references to `BaseClass`. Thus, the schema types to which `SubClass` and
`BaseClass` map are not in the same schema type hierarchy. Hence an
object with a static type of `BaseClass` but containing an instance of
`SubClass` can’t be marshalled or unmarshalled. An attempt to do so must
fail. For e.g,

[source,java,indent=4]
----
// Example: Code fragment
BaseClass {...}
...
@XmlJavaTypeAdapter(...) SubClass extends BaseClass {...}

public class Bar {
    public BaseClass foo;
    public SubClass subFoo = new SubClass();

    // marshal, unmarshal of foo will fail
    foo = subFoo;

    // marshal, unmarshal of subFoo will succeed
}
----

==== @XmlJavaTypeAdapters

This annotation is a container annotation for
defining multiple `@XmlJavTypeAdapter` annotations at the package level.

===== Synopsis

[source,java,indent=4]
----
@Retention(RUNTIME) @Target({PACKAGE})
public @interface XmlJavaTypeAdapters {
    // Collection of @{@link XmlJavaTypeAdapter}annotations
    XmlJavaTypeAdapter[] value();
}
----

===== Mapping

Each `@XmlJavaTypeAdapter` annotation in
`@XmlJavaTypeAdapters.value()` must be mapped as specified in
<<xmljavatypeadapter>>.

=== Default Mapping

This section describes the default mapping of
program elements. The default mapping is specified in terms of
_default annotations_ that are considered to apply to a program
element even in their absence.

==== Java Identifier To XML Name

The following is the default mapping for different identifiers:

* _class name_: a class name is mapped to an XML
name by de capitalization of the unqualified class name.
* _enumtype name_: enumtype name is mapped to an
XML name by de capitalization of the unqualified enumtype name.
* A property name (e.g. address) is derived
from access method (e.g. getAddress) by de
capitalization of the property name.

==== Package

A package must be mapped with the following default package level mapping annotations:

* `@XmlAccessorType(jakarta.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER)`
* `@XmlAccessorOrder(jakarta.xml.bind.annotation.XmlAccessOrder.UNDEFINED)`

[NOTE]
.Design Note
====
Ordering of properties/fields based on source code order rather than alphabetical
order is more useful. However, at this time there is no portable way to specify
source code order. Order is undefined by Java reflection. Thus the default order
has been chosen to be `UNDEFINED`. For applications which wish to remain portable
across JAXB Providers, either `XmlAccessOrder.ALPHABETICAL` or `@XmlType.propOrder()`
can be used.
====

* `@XmlSchema`

==== Class

Unless `@XmlTransient` annotation is present,
a class with a public or protected no-arg constructor must be mapped
with the following default mapping annotations: `@XmlType`.

==== Enum type

An enum type must be mapped with the following
default mapping annotations:

* enum type declaration:
[none]
** `@XmlType`
** `@XmlEnum`
** `enum type {...}`
* each enum constant:
[none]
** `@XmlEnumValue (enumConstatEnum.name())`


==== Property / Field

If the value of `@XmlAccessorType.value()` is
`jakarta.xml.bind.annotation.XmlAccessType.NONE`, then

* properties and fields, unless explicitly
annotated, must be considered to be annotated with `@XmlTransient`.

If the value of `@XmlAccessorType.value()` is
`jakarta.xml.bind.annotation.XmlAccessType.PROPERTY`, then

* properties not explicitly annotated must be
mapped; fields, unless explicitly annotated, must be considered to be
annotated with `@XmlTransient`.

If the value of `@XmlAccessorType.value()` is
`jakarta.xml.bind.annotation.XmlAccessType.FIELD`, then

* fields not explicitly annotated must be
mapped; properties, unless explicitly annotated, must be considered to
be annotated with `@XmlTransient`.

If the value of `@XmlAccessorType.value()` is
`jakarta.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER`, then

* all properties and public fields, unless
annotated with `@XmlTransient`, must be mapped.

See javadoc for
`@jakarta.xml.bind.annotation.XmlAccessorType` for further information on
inheritance rules for this annotation.

===== Default Mapping

A property name (e.g. address) must be derived
from JavaBean access method (e.g. getAddress) by JavaBean
decapitalization of the JavaBean property name.

A single valued property or field must be
mapped with the following default mapping annotation:
[none]
** `@XmlElement`
+
[NOTE]
.Note
====
An alternative to mapping property or a field to an element by default is to map
property or field to an attribute if its type maps to a XML Schema simple type.
However, neither alternative is dominant.
The default has been chosen to be `@XmlElement`.
====

A property or field with a collection type
must be mapped by with the following default mapping annotation:

* if the property or field is annotated with
`@XmlList`, then the default mapping annotation is: `@XmlElement`
* otherwise the default mapping annotation is: `@XmlElements( { @XmlElement(nillable=true)})`

==== Map

By default, `java.util.Map<K,V>` must be
mapped to the following anonymous schema type. The parameterized types K
and V must be mapped as specified in <<Type Arguments and Wildcards>>.
The anonymous schema type is at the
point of reference.

[source,xml,indent=2]
----
<!-- Default XML Schema mapping for Map<K,V> -->
<xs:complexType>
  <xs:sequence>
    <xs:element name="entry"
                minOccurs ="0" maxOccurs="unbounded">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="key" type="xs:anyType"
                      minOccurs="0"/>
          <xs:element name="value" type="xs:anyType"
                      minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
  </xs:sequence>
</xs:complexType>

<!-- Default XML Schema mapping for Map<String, Integer> -->
<xs:complexType>
  <xs:sequence>
    <xs:element name="entry"
                minOccurs="0" maxOccurs="unbounded">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="key" type="xs:string"
                      minOccurs="0"/>
          <xs:element name="value" type="xs:int"
                      minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
  </xs:sequence>
</xs:complexType>
----

The mapping of Map can be customized using `@XmlJavaTypeAdapter` annotation.

==== Multidimensional Array

By default, a multidimensional array must be
mapped to a complex type as follows. Note the table specifies a two
dimensional array mapping. If an array is more than two dimensions, then
the mapping is used recursively.



.Table 8-35 Mapping: Two dimensional array to Complex Type Definition
[cols=","]
|===
| `{name}` | If the _basetype_ is a primitive type (e.g.
`int[][]`) or its corresponding wrapper class (e.g. `Integer[][]`), then the
name is _basetype_ concatenated with `"Array"` (e.g. `intArray`).

otherwise if the basetype is a reference type
(e.g. `Foo[][]`), then the XML name to which the reference type is mapped
(e.g. `foo`) concatenated with `"Array"` (e.g. `fooArray`).

| `{target namespace}` | if the _basetype_ is a primitive or its
corresponding wrapper class then `"http://jaxb.dev.java.net/array"`

otherwise the namespace to which the reference
type is mapped (e.g. for `Foo[][]`, the namespace of the XML type to which
`Foo` is mapped).

| `{base type definition}` | `xs:anyType`
| `{derivation method}` | `restriction`
| `{final}` | `#all`
| `{abstract}` | `false`
| `{attribute uses}` | `empty set`
| `{attribute wildcard}` | `absent`
| `{content type}` | element-only content
| `{prohibited substitutions}` | `empty set`
| `{annotations}` | `absent`
|===

.Table 8-36 Mapping: Two dimensional array to sequence model group
[cols=","]
|===
| `{compositor}` | `xs:sequence`
| `{particles}` a| A repeating element defined as follows:

[source,xml,indent=4]
----
<xs:element name="item"
            type=schematype minOccurs="0"
            maxOccurs="unbounded" nillable="true"/>
----

where schematype is the schema to which the
array’s component type is mapped (e.g. `int[][]`, then `"xs:int"`; `Foo[][]`
then `"foo"` assuming `Foo` is mapped to the schema type `foo`.

| `{annotation}` | `unspecified`
|===

=== Notes

This section contains a collection of notes
intended to aid in the review of this version of the specification. They
are collected here in a separate section and referenced from possibly
multiple places elsewhere in the specification to make the specification
more compact.

==== @XmlType: List simple type

It is possible to map a homogenous collection
to a simple type with a variety of {list}. For e.g.

[source,java,indent=4]
----
// Code fragment
public class USStateList {
    @XmlValue List <int> items;
}
----

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

Other types which can be mapped to a list
simple type include: indexed property, single dimensional arrays.