| // |
| // 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; |
| static 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; |
| static 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; |
| static 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 as identified by |
| `java.beans.Introspector.getBeanInfo` 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 ""; |
| public 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; |
| static 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 using |
| `java.beans.Introspector.decapitalize(_class name_)`. |
| * _enumtype name_: enumtype name is mapped to an |
| XML name by de capitalization using |
| `java.beans.Introspector.decapitalize(_enumtype name_)`. |
| * A property name (e.g. address) is derived |
| from JavaBean access method (e.g. getAddress) by JavaBean de |
| capitalization of the JavaBean property name |
| `java.beans.Introspector.decapitalize(_JavaBeanAccessMethod_)` |
| |
| ==== 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 |
| `java.beans.Introspector.decapitalize(_JavaBeanAccessMethod_)` |
| |
| 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. |