| // |
| // Copyright (c) 2020 Contributors to the Eclipse Foundation |
| // |
| |
| == Customizing XML Schema to Java Representation Binding |
| |
| The default binding of source schema |
| components to derived Java representation by a binding compiler |
| sometimes may not meet the requirements of a JAXB application. In such |
| cases, the default binding can be customized using a __binding declaration__. |
| Binding declarations are specified by a __binding language__, |
| the syntax and semantics of which are defined in this chapter. |
| |
| All JAXB implementations are required to |
| provide customization support specified here unless explicitly stated as |
| optional. |
| |
| === Binding Language |
| |
| The binding language is an XML based language |
| which defines constructs referred to as __binding declarations__. A binding |
| declaration can be used to customize the default binding between an XML |
| schema component and its Java representation. |
| |
| The schema for binding declarations is defined in the namespace |
| `https://jakarta.ee/xml/ns/jaxb`. This specification uses the |
| namespace prefix `"jaxb"` to refer to the namespace of binding |
| declarations. For example, |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb: binding declaration> |
| ---- |
| |
| A binding compiler interprets the binding |
| declaration relative to the source schema and a set of default bindings |
| for that schema. Therefore a source schema need not contain a binding |
| declarations for every schema component. This makes the job of a JAXB |
| application developer easier. |
| |
| There are two ways to associate a binding |
| declaration with a schema element: |
| |
| * as part of the source schema (_inline |
| annotated schema_) |
| * external to the source schema in an |
| _external binding declaration_. |
| |
| The syntax and semantics of the binding |
| declaration is the same regardless of which of the above two methods is |
| used for customization. |
| |
| A binding declaration itself does not |
| identify the schema component to which it applies. A schema component |
| can be identified in several ways: |
| |
| * explicitly - e.g. QName, XPath expressions |
| etc. |
| * implicitly - based on the context in which |
| the declaration occurs. |
| |
| It is this separation which allows the |
| binding declaration syntax to be shared between inline annotated schema |
| and the external binding. |
| |
| ==== Extending the Binding Language |
| |
| In recognition that there will exist a need |
| for additional binding declarations than those currently specified in |
| this specification, a formal mechanism is introduced so all JAXB |
| processors are able to identify _extension binding declarations_ . An |
| extension binding declaration is not specified in the _jaxb:_ namespace, |
| is implementation specific and its use will impact portability. |
| Therefore, binding customization that must be portable between JAXB |
| implementations should not rely on particular customization extensions |
| being available. |
| |
| The namespaces containing extension binding |
| declarations are specified to a JAXB processor by the occurrence of the |
| global attribute `<jaxb:extensionBindingPrefixes>` within an instance of |
| `<xs:schema>` element. The value of this attribute is a |
| whitespace-separated list of namespace prefixes. The namespace bound to |
| each of the prefixes is designated as a customization declaration |
| namespace. Prefixes are resolved on the `<xs:schema>` element that |
| carries this attribute. It is an error if the prefix fails to resolve. |
| This feature is quite similar to the extension-element-prefixes |
| attribute in [XSLT 1.0] `http://www.w3.org/TR/xslt10/#extension`, |
| introduces extension namespaces for extension instructions and functions |
| for XSLT 1.0. |
| |
| This specification does not define any |
| mechanism for creating or processing extension binding declarations and |
| does not require that implementations support any such mechanism. Such |
| mechanisms, if they exist, are implementation-defined. |
| |
| ==== Inline Annotated Schema |
| |
| This method of customization utilizes on the |
| `<appinfo>` element specified by the XML Schema [XSD PART 1]. A binding |
| declaration is embedded within the `<appinfo>` element as illustrated |
| below. |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:annotation> |
| <xs:appinfo> |
| <binding declaration> |
| </xs:appinfo> |
| </xs:annotation> |
| ---- |
| |
| The inline annotation where the binding |
| declaration is used identifies the schema component. |
| |
| ==== External Binding Declaration |
| |
| The external binding declaration format |
| enables customized binding without requiring modification of the source |
| schema. Unlike inline annotation, the remote schema component to which |
| the binding declaration applies must be identified explicitly. The |
| `<jaxb:bindings>` element enables the specification of a remote schema |
| context to associate its binding declaration(s) with. Minimally, an |
| external binding declaration follows the following format. |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:bindings [schemaLocation = "xs:anyURI"]> |
| <jaxb:bindings [node = "xs:string"]> |
| <binding declaration> |
| <jaxb:bindings> |
| </jaxb:bindings> |
| ---- |
| |
| The schemaLocation attribute is optional for |
| specifying `<jaxb:globalBindings>`, and the _node_ attribute is optional |
| for specifying `<jaxb:schemaBindings>`. The attributes _schemaLocation_ |
| and _node_ are used to construct a reference to a node in a remote |
| schema. The binding declaration is applied to this node by the binding |
| compiler as if the binding declaration was embedded in the node’s |
| `<xs:appinfo>` element. The attribute values are interpreted as follows: |
| |
| * _schemaLocation -_ It is a URI reference |
| to a remote schema. |
| * _node_ - It is an XPath 1.0 expression |
| that identifies the schema node within schemaLocation to associate |
| binding declarations with. |
| |
| An example external binding declaration can |
| be found in link:jaxb.html#a4821[See Example].” |
| |
| ===== Restrictions |
| |
| * The external binding element |
| `<jaxb:bindings>` is only recognized for processing by a JAXB processor |
| when its parent is an `<xs:appinfo>` element, it is an ancestor of |
| another `<jaxb:bindings>` element, or when it is root element of a |
| document. An XML document that has a `<jaxb:bindings>` element as its |
| root is referred to as an external binding declaration file. |
| * The top-most `<jaxb:binding>` element |
| within an `<xs:appinfo>` element or the root element of an external |
| binding file must have its _schemaLocation_ attribute set. |
| |
| ==== Version Attribute |
| |
| The normative binding schema specifies a |
| global `version` attribute. It is used to identify the version of the |
| binding declarations. For example, a future version of this |
| specification may use the version attribute to specify backward |
| compatibility. To indicate this version of the specification, the |
| `version should` be `"2.0"`. It is also valid for @version to be “1.0”. |
| If any other version is specified, it must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” |
| |
| The `version` attribute must be specified in |
| one of the following ways: |
| |
| * If customizations are specified in inline |
| annotations, the `version` attribute must be specified in `<xs:schema>` |
| element of the source schema. For example, |
| + |
| [source,xml,indent=4] |
| ---- |
| <xs:schema jaxb:version="3.0"> |
| ---- |
| |
| * If customizations are specified in an |
| external binding file, then the `jaxb:version` attribute must be |
| specified in the root element `<jaxb:bindings>` in the external binding |
| file. Alternately, a local `version` attribute may be used. Thus the |
| version can be specified either as |
| + |
| [source,xml,indent=4] |
| ---- |
| <jaxb:bindings version="3.0" ... /> |
| ---- |
| or |
| + |
| [source,xml,indent=4] |
| ---- |
| <jaxb:bindings jaxb:version="2.0" ... /> |
| ---- |
| + |
| Specification of both `version` and |
| `<jaxb:version>` must result in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations].” |
| |
| ==== Invalid Customizations |
| |
| A _non conforming_ binding declaration is a |
| binding declaration in the `jaxb` namespace but does not conform to this |
| specification. A non conforming binding declaration results in a |
| _customization error_. The binding compiler must report the customization |
| error. The exact error is not specified here. For additional |
| requirements see link:jaxb.html#a3815[See Compatibility].” |
| |
| The rest of this chapter assumes that non |
| conforming binding declarations are processed as indicated above and |
| their semantics are not explicitly specified in the descriptions of |
| individual binding declarations. |
| |
| === Notation |
| |
| The source and binding-schema fragments shown |
| in this chapter are meant to be illustrative rather than normative. The |
| normative syntax for the binding language is specified in |
| link:jaxb.html#a4270[See Normative Binding Schema Syntax].” in |
| addition to the other normative text within this chapter. All examples |
| are non-normative. |
| |
| * Metavariables are in _italics_. |
| * Optional attributes are enclosed in `[ square="bracket" ]`. |
| * Optional elements are enclosed in `[ <elementA> ... </elementA> ]`. |
| * Other symbols: ‘`,`’ denotes a sequence, |
| ‘`|`’ denotes a choice, ‘`+`’ denotes one or more, ‘`*`’ denotes |
| zero or more. |
| * The prefix `xs:` is used to refer to schema |
| components in W3C XML Schema namespace. |
| * In examples, the binding declarations as |
| well as the customized code are shown in bold like this: |
| *<appinfo> <annotation>* or *getAddress()*. |
| |
| === Naming Conventions |
| |
| The naming convention for XML names in the |
| binding language schema are: |
| |
| * The first letter of the first word in a |
| multi word name is in lower case. |
| * The first letter of every word except the |
| first one is in upper case. |
| |
| For example, the XML name for the Java |
| property basetype is baseType. |
| |
| === Customization Overview |
| |
| A binding declaration customizes the default |
| binding of a schema element to a Java representation. The binding |
| declaration defines one or more customization values each of which |
| customizes a part of Java representation. |
| |
| ==== Scope |
| |
| When a customization value is defined in a |
| binding declaration, it is associated with a _scope_. A scope of a |
| customization value is the set of schema elements to which it applies. |
| If a customization value applies to a schema element, then the schema |
| element is said to be _covered_ by the scope of the customization value. |
| The scopes are: |
| |
| * *global scope*: A customization value defined |
| in `<globalBindings>` has _global scope_. A global scope covers all the |
| schema elements in the source schema and (recursively) any schemas that |
| are included or imported by the source schema. |
| * *schema scope*: A customization value defined |
| in `<schemaBindings>` has _schema scope_. A schema scope covers all the |
| schema elements in the target namespace of a schema. |
| * *definition scope*: A customization value in |
| binding declarations of a type definition or global declaration has |
| _definition scope_. A definition scope covers all schema elements that |
| reference the type definition or the global declaration. This is more |
| precisely specified in the context of binding declarations later on in |
| this chapter. |
| * *component scope*: A customization value in a |
| binding declaration has _component scope_ if the customization value |
| applies only to the schema element that was annotated with the binding |
| declaration. |
| |
| .Scoping Inheritance and Overriding For Binding Declarations |
| image:images/xmlb-18.png[image] |
| |
| The different scopes form a taxonomy. The |
| taxonomy defines both the inheritance and overriding semantics of |
| customization values. A customization value defined in one scope is |
| inherited for use in a binding declaration covered by another scope as |
| shown by the following inheritance hierarchy: |
| |
| * a schema element in schema scope inherits a |
| customization value defined in global scope. |
| * a schema element in definition scope |
| inherits a customization value defined in schema or global scope. |
| * a schema element in component scope |
| inherits a customization value defined in definition, schema or global |
| scope. |
| |
| Likewise, a customization value defined in |
| one scope can override a customization value inherited from another |
| scope as shown below: |
| |
| * value in schema scope overrides a value |
| inherited from global scope. |
| * value in definition scope overrides a value |
| inherited from schema scope or global scope. |
| * value in component scope overrides a value |
| inherited from definition, schema or global scope. |
| |
| ==== XML Schema Parsing |
| |
| Chapter 5 specified the bindings using the |
| abstract schema model. Customization, on the other hand, is specified in |
| terms of XML syntax not abstract schema model. The XML Schema |
| specification [XSD PART 1] specifies the parsing of schema elements into |
| abstract schema components. This parsing is assumed for parsing of |
| annotation elements specified here. In some cases, [XSD PART 1] is |
| ambiguous with respect to the specification of annotation elements. |
| link:jaxb.html#a2217[See Annotation Restrictions]” outlines how |
| these are addressed. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| The reason for specifying using the XML syntax instead of |
| abstract schema model is as follows. For most part, |
| there is a one-to-one mapping between schema elements |
| and the abstract schema components to which they are bound. |
| However, there are certain exceptions: local attributes and particles. |
| A local attribute is mapped to two schema components: |
| {attribute declaration} and {attribute use}. But the XML parsing |
| process associates the annotation with the {attribute declaration} |
| not the {attribute use}. This is tricky and not obvious. |
| Hence for ease of understanding, a choice was made to specify |
| customization at the surface syntax level instead. |
| |
| ==== |
| |
| |
| === `<globalBindings>` Declaration |
| |
| The customization values in `"<globalBindings>"` |
| binding declaration have global scope. This binding |
| declaration is therefore useful for customizing at a global level. |
| |
| ==== Usage |
| |
| [source,xml,indent=4] |
| ---- |
| <globalBindings |
| [ collectionType = "collectionType" ] |
| [ fixedAttributeAsConstantProperty = "true" | "false" | "1" | "0" ] |
| [ generateIsSetMethod = "true" | "false" | "1" | "0" ] |
| [ enableFailFastCheck = "true" | "false" | "1" | "0" ] |
| [ choiceContentProperty = "true" | "false" | "1" | "0" ] |
| [ underscoreBinding = "asWordSeparator" | "asCharInWord" ] |
| [ typesafeEnumBase = "typesafeEnumBase" ] |
| [ typesafeEnumMemberName = "skipGeneration" | |
| "generateName" | "generateError" ] |
| [ typesafeEnumMaxMembers = “xxxx”] |
| [ enableJavaNamingConventions = "true" | "false" | "1" | "0" ] |
| [ generateElementClass = "false" | "true" | "0" | "1" ] |
| [ generateElementProperty = "false" | "true" | "0" | "1" ] |
| [ generateValueClass = "true" | "true" | "0" | "1" ] |
| [ optionalProperty = "wrapper" | "primitive" | "isSet" ] |
| [ mapSimpleTypeDef = "true" | "false" | "1" | "0" ] |
| [ localScoping = "nested" | "toplevel" ] > |
| [ <javaType> ... </javaType> ]* |
| [ <serializable uid=”xxxx”/> ]* |
| </globalBindings> |
| ---- |
| |
| The following customization values are |
| defined in global scope: |
| |
| * `_collectionType_` if specified, must be |
| either `"indexed"` or any fully qualified class name that implements |
| `_java.util.List_`. The default value is to any fully qualified class name |
| that implements `_java.util.List_`. |
| * `_fixedAttributeAsConstantProperty_` if |
| specified , defines the customization value |
| `_fixedAttributeAsConstantProperty_`. The value must be one of `"true"`, |
| `"false"`, `"1"` or `"0"`. The default value is `"false"`. |
| * `_generateIsSetMethod_` if specified, |
| defines the customization value of `_generateIsSetMethod_`. The value must |
| be one of `"true"`, `"false"`, `"1"` or `"0"`. The default value is `"false"`. |
| Consider customizing using the newly introduced _optionalProperty_ |
| before using this JAXB customization. |
| * `_enableFailFastCheck_` if specified, |
| defines the customization value `_enableFailFastCheck`_. The value must be |
| one of `"true"`, `"false"`, `"1"` or `"0"`. If enableFailFastCheck is `"true"` or |
| `"1"` and the JAXB implementation supports this optional checking, type |
| constraint checking when setting a property is performed as described in |
| link:jaxb.html#a541[See Properties]". The default value is `"false"`. |
| * `_choiceContentProperty_` if |
| specified, defines the customization value `_choiceContentProperty_`. The |
| value must be one of `"true"`, `"false"`, `"1"` or `"0"`. |
| The default value is `"false"`. |
| * `_underscoreBinding_` if specified, defines |
| the customization value `_underscoreBinding_`. The value must be one of |
| `"asWordSeparator"` or `"asCharInWord"`. The default value is |
| `"asWordSeparator"`. |
| * `_enableJavaNamingConventions_` if |
| specified, defines the customization value `_enableJavaNamingConventions_`. |
| The value must be one of `"true"`, `"false"`, `"1"` or `"0"`. |
| The default value is `"true"`. |
| * `_typesafeEnumBase_` if specified, defines |
| the customization value `_typesafeEnumBase_`. The value must be a list of |
| QNames, each of which must resolve to a simple type definition. Only |
| simple type definitions with an enumeration facet and a restriction base |
| type listed in `_typesafeEnumBase_` or derived from a type listed in |
| `_typesafeEnumBase_` is bound to a `_typesafeEnumClass_` by default as |
| specified in link:jaxb.html#a829[See Enum Type]". The default |
| value of `_typesafeEnumBase_` is `"xs:string"`. |
| + |
| The `_typesafeEnumBase_` cannot contain the |
| following simple types and therefore a JAXB implementation is not |
| required to support the binding of the these types to typesafe |
| enumeration class: `_"xs:QName"_`, `_"xs:NOTATIION"_`, `_"xs:base64Binary"_`, |
| `_"xs:hexBinary"_`, `_"xs:date"_`, `_"xs:time"_`, `_"xs:dateTime"_`, `_"xs:duration"_`, |
| `_"xs:gDay"_`, `_"xs:gMonth"_`, `_"xs:gYear"_`, `_"xs:gMonthDay"_`, `_"xs:gYearMonth"_`, |
| `_"xs:IDREF"_`, `_"xs:ID"_`. If any of them are specified, it must result in an |
| invalid customization as specified in link:jaxb.html#a1544[See |
| Invalid Customizations].” JAXB implementation must be capable of binding |
| any other simple type listed in `_typesafeEnumBase_` to a typesafe |
| enumeration class. |
| |
| * `_typesafeEnumMemberName_` if specified, |
| defines the customization value `_typesafeEnumMemberName_`. The value must |
| be one of `skipGeneration`, `generateError` or `generateName`. The |
| default value is `skipGeneration`. See link:jaxb.html#a1633[See |
| @typesafeEnumMemberName]” for details. |
| * `_typesafeEnumMaxMembers_` if specified, |
| defines the maximum number of enum facets that a simple type definition |
| can have and be consider to binding to an enum type by default. The |
| attributes type is `xs:int` and its default value is `256`. |
| * `_generateElementClass_` if specified as |
| true, a schema-derived Element class, as specified in |
| link:jaxb.html#a657[See Java Element Class]”, is generated for |
| each element declaration that has an element factory method generated |
| for it. Its default value is `"false"`. |
| * `_generateElementProperty_` if specified as |
| true, controls the generation of JAXBElement property. The value must be |
| one of `"true"`, `"false"`, `"1"` or `"0"`. The default is absence of the |
| value. |
| * `_generateValueClass_` if specified as true, a |
| schema-derived Java value class is generated for each complex type |
| definiton.Value class is specified in link:jaxb.html#a521[See |
| Value Class]. If generateValueClass is specified as false, a |
| schema-derived interface and implementation class is generated for each |
| complex type definition as specified in link:jaxb.html#a536[See |
| Java Content Interface]”. The attribute’s default value is true. See |
| examples of this binding in link:jaxb.html#a1617[See |
| generateElementClass and generateValueClass]”. |
| * zero or more `_javaType_` binding |
| declarations. Each binding declaration must be specified as described in |
| link:jaxb.html#a1981[See <javaType> Declaration].” |
| * zero or one serializable binding declaration. |
| * `_optionalProperty_` controls how a JAXB property with a |
| primitive base type that represents an optional non-nillable |
| element/attribute is bound. If the attribute has the value "wrapper", |
| then the base type of the JAXB property is the wrapper class for the |
| primitive type. A user can indicate that this optional property is not |
| set by calling the setter with “null” value. If the attribute’s value is |
| "primitive", it binds as it did in JAXB 1.0. If the attribute’s value is |
| “isSet”, it binds the optional property using the primitive base type |
| and also the isSet/unset methods are generated for the optional |
| property. The attribute’s default value is “wrapper”. |
| * `_mapSimpleTypeDef_` controls whether a JAXB |
| mapped class should be generated for each simple type definition as |
| specified in link:jaxb.html#a803[See Bind to a JAXB mapped |
| class]”. This attribute’s default value is `"false"`. This customization |
| eases preserving simple type substituting precisely as described in |
| link:jaxb.html#a1158[See Type Substitution of a Simple Type |
| Definition]”. |
| * `_localScoping_` attribute can have the |
| value of either _nested_ or _toplevel_ . This attribute describes the |
| JAXB binding of nested XML schema component to either a _nested_ |
| schema-derived JAXB class or a _toplevel_ schema-derived JAXB class. To |
| avoid naming collisions between nested components, the default value for |
| this attribute is _nested_. A developer can customize _localScoping_ to |
| _toplevel_ when schema components nest too deeply or an application |
| would prefer to not work with nested classes. |
| |
| The semantics of the above customization |
| values, if not specified above, are specified when they are actually |
| used in the binding declarations. |
| |
| For inline annotation, a `<globalBindings>` |
| is valid only in the annotation element of the `<schema>` element. There |
| must only be a single instance of a `<globalBindings>` declaration in |
| the annotation element of the `<schema>` element. |
| |
| ==== Customized Name Mapping |
| |
| A customization value can be used to specify |
| a name for a Java object (e.g. class name, package name etc.). In this |
| case, a customization value is referred to as a _customization name_. |
| |
| A customization name is always a legal Java |
| identifier (this is formally specified in each binding declaration where |
| the name is specified). Since customization deals with customization of |
| a Java representation to which an XML schema element is bound, requiring |
| a customization name to be a legal Java identifier rather than an XML |
| name is considered more meaningful. |
| |
| A customization name may or may not conform |
| to the recommended Java language naming conventions. [JLS - Java |
| Language Specification, Second Edition, Section 6.8, “Naming |
| Conventions”]. The customization value _enableJavaNamingConventions_ |
| determines if a customization name is mapped to a Java identifier that |
| follows Java language naming conventions or not. |
| |
| If _enableJavaNamingConventions_ is defined and |
| the value is `"true"` or `"1"`, then the customization name (except for |
| constant name) specified in the section from where this section is |
| referenced must be mapped to Java identifier which follows the Java |
| language naming conventions as specified in |
| link:jaxb.html#a4816[See Conforming Java Identifier Algorithm]”; |
| otherwise the customized name must be used as is. |
| |
| ==== Underscore Handling |
| |
| The *[jaxb:globalBindings]* attribute |
| customization _underscoreBinding_ allows for the preservation of |
| underscore(s) occurring in an XML name when deriving a a Java identifier |
| from it. |
| |
| The default value for _@underscoreBinding_ is |
| `"asWordSeparator"` and categorizes underscore (‘_’) as a punctuation |
| mark in the XML name to Java identifier algorithm specified in Appendix |
| link:jaxb.html#a4656[See The Name to Identifier Mapping |
| Algorithm]. The resulting algorithm transforms one or more consecutive |
| underscores in an XML name to camel case separated words in the derived |
| Java class and method names. Examples of this mapping are in |
| link:jaxb.html#a4734[See XML Names and derived Java Class, |
| Method, and Constant Names]. |
| |
| When _@underscoreBinding_ is |
| `"asCharInWord"`, underscore (‘_’) is considered a special letter within |
| a word. The result is that all underscore characters from the original |
| XML name are preserved in the derived Java identifier. Example of this |
| mapping are in link:jaxb.html#a4755[See XML Names and derived |
| Java Class, Method, and Constant Names when <jaxb:globalBindings |
| underscoreHandling=”asCharInWord”>]. |
| |
| ==== generateElementClass and generateValueClass |
| |
| The following code examples illustrate |
| default binding to value class and customization to bind to |
| interface/implementation classes. |
| |
| *_Example:_* Default Binding to a value class. + |
| |
| Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="USAddress"> |
| <xs:attribute name="City" type="xs:string"/> |
| </xs:complexType> |
| ---- |
| |
| Default Value Class: |
| |
| [source,java,indent=4] |
| ---- |
| public class USAddress { |
| public USAddress() {...} |
| public String getCity() {...} |
| public void setCity(String value) {...} |
| ... |
| } |
| ---- |
| Customization `<jaxb:globalBinding generateValueClass="false">` |
| generates following interface instead of |
| default value class: |
| |
| *_Example:_* Customized binding to an interface. + |
| |
| [source,java,indent=4] |
| ---- |
| public interface USAddress { |
| String getCity(); |
| void setCity(String value); |
| } |
| ---- |
| |
| *_Example:_* Generation of an Element Class. + |
| |
| Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:element name="Address" type="USAddress"/> |
| ---- |
| [source,java,indent=4] |
| ---- |
| // Default Java binding of global element to element instance factory |
| public ObjectFactory { |
| JAXBElement<USAddress> createAddress(USAddress value); |
| } |
| ---- |
| |
| `<jaxb:globalBinding generateElementClass="true"/>` results in generation |
| of following Element class: |
| |
| [source,java,indent=4] |
| ---- |
| public class Address extends JAXBElement<USAddress> { |
| } |
| ---- |
| |
| ==== @typesafeEnumMemberName |
| |
| If there is a collision among the generated |
| constant fields *name* or if it is not possible to generate a legal Java |
| identifier for one or more of the generated constant field names, then |
| the binding is determined based on the value of @ |
| `_typesafeEnumMemberName_` of element *[jaxb:globalBindings]*. |
| |
| * _skipGeneration_ + |
| An enum type is not generated. This is the default behavior if |
| `_typesafeEnumMemberName_` has not been specified. A binding compiler may |
| report a warning on why the simple type definition was not bound to an |
| enum type. |
| * _generateName_ + |
| The constant fields *name* is `__"VALUE____<N>"_` where `_<N>_` is 1 |
| for the first enumeration value and increments by 1 to represent each |
| value within the XML enumeration. |
| * _generateError_ + |
| An error must be reported. |
| |
| ==== <serializable> Declaration |
| |
| When the serializable customization is |
| specified, all schema-derived classes implement `java.io.Serializable`. |
| Each class is generated with a `serialVersionUID` field set to the value |
| specified by _@uid_. |
| |
| [source,java,indent=4] |
| ---- |
| private static final long serialVersionUID = <value of @uid>; |
| ---- |
| The JAXB user is required to identify when |
| schema-derived classes do not follow |
| _https://docs.oracle.com/javase/8/docs/platform/serialization/spec/version.html#a6519§[Java |
| serialization class evolution rules]_ and change the generated |
| `serialVersionUID` field by changing the *[serializable]* element’s |
| attribute _@uid_ value. |
| |
| ==== @generateElementProperty |
| |
| Some schemas use both minOccurs="0" on |
| element as well as nillable="true", causing the generation of |
| JAXBElement. This customization lets you control this behavior. This |
| attribute may take two values: |
| |
| * _true_: + |
| Always generate properties to use JAXBElement, unless overriden by |
| `<jaxb:property generateElementProperty="false"/>` on individual |
| property. |
| * _false_: + |
| When generating properties from `<element nillable=”true” minOccurs=”0”/>`, |
| generate a property not to use JAXBElement, as if the |
| element declaration were just `<element nillable=”true” />`, unless |
| overriden by `<jaxb:property generateElementProperty="true"/>` on |
| individual property. It is an error to specify this customization, when |
| the property is required to be JAXBElement (such as when a property |
| contains multiple elements with different names but of the same type.) |
| |
| === `<schemaBindings>` Declaration |
| |
| The customization values in |
| `<schemaBindings>` binding declaration have schema scope. This binding |
| declaration is therefore useful for customizing at a schema level. |
| |
| ==== Usage |
| |
| [source,xml,indent=4] |
| ---- |
| <schemaBindings [ map="boolean" ] > |
| [ <package> package </package> ] |
| [ <nameXmlTransform> ... </nameXmlTransform>]* |
| </schemaBindings> |
| |
| <package [ name = "packageName" ] |
| [ <javadoc> ... </javadoc> ] |
| </package> |
| |
| <nameXmlTransform> |
| [ <typeName [ suffix="suffix" ] |
| [ prefix="prefix" ] /> ] |
| [ <elementName [ suffix="suffix" ] |
| [ prefix="prefix" ] /> ] |
| [ <modelGroupName [ suffix="suffix" ] |
| [ prefix="prefix" ] /> ] |
| [ <anonymousTypeName [ suffix="suffix" ] |
| [ prefix="prefix" ] /> ] |
| </nameXmlTransform> |
| ---- |
| |
| For readability, the `<nameXmlTransform>` and |
| `<package>` elements are shown separately. However, they are local |
| elements within the `<schemaBindings>` element. |
| |
| The following customizations are defined in |
| the schema scope: |
| |
| * _map_ if specified, prevents the classes |
| from being generated from this schema. When the value is `"0"` or `"false"`, |
| then no class/interface/enum will be generated from this package. _map_ |
| defaults to `"true"`. |
| |
| The semantics of the customization value, if |
| not specified above, are specified when they are actually used in the |
| binding declarations. |
| |
| For inline annotation, a `<schemaBindings>` |
| is valid only in the annotation element of the `<schema>` element. There |
| must only be a single instance of a `<schemaBindings>` declaration in |
| the annotation element of the `<schema>` element. |
| |
| If one source schema includes (via the |
| include mechanism specified by XSD PART 1) a second source schema, then |
| the `<schemaBindings>` declaration must be declared in the first |
| including source schema. It should be noted that there is no such |
| restriction on `<schemaBindings>` declarations when one source schema |
| imports another schema since the scope of `<schemaBindings>` binding |
| declaration is schema scope. |
| |
| ===== package |
| |
| Usage |
| |
| * `_name_` if specified, defines the |
| customization value `_packageName_`. `_packageName_` must be a valid Java |
| package name. |
| * `_<javadoc>_` if specified, customizes the |
| package level Javadoc. `_<javadoc>_` must be specified as described in |
| link:jaxb.html#a2142[See <javadoc> Declaration].” The Javadoc |
| must be generated as specified in link:jaxb.html#a2163[See |
| Javadoc Customization].” The Javadoc section customized is the `package |
| section`. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| The word “package” has been prefixed to `_name_` used in the binding declaration. |
| This is because the attribute or element tag names “name” is not unique by itself |
| across all scopes. For e.g., “name” attribute can be specified |
| in the <property> declaration. The intent is to disambiguate by reference such as `"packageName"`. |
| |
| ==== |
| |
| The semantics of the `_packageName_` is |
| specified in the context where it is used. If neither `_packageName_` nor |
| the `_<javadoc>_` element is specified, then the binding declaration has |
| no effect. |
| |
| *_Example:_* Customizing Package Name + |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:schemaBindings> |
| <jaxb:package name = "org.example.po" /> |
| </jaxb:schemaBindings> |
| ---- |
| |
| specifies `"org.example.po"` as the package |
| to be associated with the schema. |
| |
| ===== nameXmlTransform |
| |
| The use case for this declaration is the UDDI |
| Version 2.0 schema. The UDDI Version 2.0 schema contains many |
| declarations of the following nature: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:element name="bindingTemplate" type="uddi:bindingTemplate"/> |
| ---- |
| |
| The above declaration results in a name |
| collision since both the element and type names are the same - although |
| in different XML Schema symbol spaces. Normally, collisions are supposed |
| to be resolved using customization. However, since there are many |
| collisions for the UDDI V2.0 schema, this is not a convenient solution. |
| Hence the binding declaration `nameXmlTransform` is being provided to |
| automate name collision resolution. |
| |
| The `nameXmlTransform` allows a `_suffix_` and |
| a `_prefix_` to be specified on a per symbol space basis. The following |
| symbol spaces are supported: |
| |
| * `<typeName>` for the symbol space “type |
| definitions” |
| * `<elementName>` for the symbol space |
| “element definitions” |
| * `<modelGroupName>` for the symbol space |
| “model group definitions.” |
| * `<anonymousTypeName>` for customizing Java |
| value class to which an anonymous type is bound.footnote:[XML schema does not |
| associate anonymous types with a specific symbol space. However, |
| _nameXmlTransform_ is used since it provides a convenient way to |
| customize the value class to which an anonymous type is bound.] |
| |
| If `_suffix_` is specified, it must be appended |
| to all the default XML names in the symbol space. The `_prefix_` if |
| specified, must be prepended to the default XML name. Furthermore, this |
| XML name transformation must be done after the XML name to Java |
| Identifier algorithm is applied to map the XML name to a Java |
| identifier. The XML name transformation must not be performed on |
| customization names. |
| |
| By using a different `_prefix_` and/or `_suffix_` |
| for each symbol space, identical names in different symbol spaces can be |
| transformed into non-colliding XML names. |
| |
| `*anonymousTypeName*` |
| |
| The `<anonymousTypeName>` declaration can be |
| used to customize the suffix and prefix for the Java value class. If |
| `_prefix_` is specified, then it must be prepended to the Java value class |
| name for the anonymous type. If suffix is specified, it must be |
| appended. |
| |
| === `<class>` Declaration |
| |
| This binding declaration can be used to |
| customize the binding of a schema component to an element class, value |
| class or interface/implementation class. The customizations can be used |
| to specify: |
| |
| * a name for the derived Java class. |
| * an alternative implementation of |
| interface/implementation binding. |
| |
| Specification of an alternate implementation |
| for an interface allows implementations generated by a tool (e.g. based |
| on UML) to be used in place of the default implementation generated by a |
| JAXB provider. |
| |
| The implementation class may have a |
| dependency upon the runtime of the binding framework. Since a runtime |
| was not specified for JAXB 1.0 interface/implementation binding, the |
| implementation class may not be portable across JAXB provider |
| implementations. Hence one JAXB provider implementation is not required |
| to support the implementation class from another JAXB provider. |
| |
| ==== Usage |
| |
| [source,xml,indent=4] |
| ---- |
| <class [ name = "className" ] |
| [ implClass = "implClass" ] |
| [ ref = "className" ] > |
| [ <javadoc> ... </javadoc> ] |
| </class> |
| ---- |
| |
| * `_className_` is the name of the derived |
| value class, if specified. It must be a legal Java class name and must |
| not contain a package prefix. The package prefix is inherited from the |
| current value of _package_. |
| * `_implClass_` if specified, is the name of |
| the implementation class for `_className_` and must include the complete |
| package name. Note that this customization only impacts the return value |
| for `className` ’s factory method. This customization is ignored when |
| `new` is used to create instances of a schema-derived Value class. |
| * `_ref_` if specified, is the name of the |
| value class that is provided outside the schema compiler. This |
| customization causes a schema compiler to refer to this external class, |
| as opposed to generate a definition. It must include the complete |
| package name. This attribute is mutually exclusive with the `_className_` |
| attribute and the `_implClass_` attribute. |
| * `_<javadoc>_` element, if specified |
| customizes the Javadoc for the derived value class. `_<javadoc>_` must be |
| specified as described in link:jaxb.html#a2142[See <javadoc> |
| Declaration].” |
| |
| ==== Customization Overrides |
| |
| When binding a schema element’s Java |
| representation to a value class or a Java Element class, the following |
| customization values override the defaults specified in Chapter 5. It is |
| specified in a common section here and referenced from |
| link:jaxb.html#a1718[See Customizable Schema Elements].” |
| |
| * *name*: The name is `_className_` if specified. |
| * *package name:* The name of the package is |
| `_packageName_` inherited from a scope that covers this schema element. |
| + |
| [NOTE] |
| .Note |
| ==== |
| The `_packageName_` is only set in the `<package>` declaration. The |
| scope of `_packageName_` is schema scope and is thus inherited by all |
| schema elements within the schema. |
| |
| ==== |
| |
| * *javadoc:* The Javadoc must be generated as |
| specified in section link:jaxb.html#a2163[See Javadoc |
| Customization].” The Javadoc section customized is the `class/interface |
| section`. |
| |
| ==== Customizable Schema Elements |
| |
| ===== Complex Type Definition |
| |
| When `<class>` customization specified in the |
| annotation element of the complex type definition, the complex type |
| definition must be bound to a Java value class as specified in |
| link:jaxb.html#a933[See Java value class]” applying the |
| customization overrides as specified in link:jaxb.html#a1713[See |
| Customization Overrides].” |
| |
| *_Example:_* Class Customization: Complex Type Definition To Java value class + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="USAddress"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:class name="MyAddress" /> |
| </xs:appinfo></xs:annotation> |
| <xs:sequence>...</xs:sequence> |
| <xs:attribute name="country" type="xs:string"/> |
| </xs:complexType> |
| ---- |
| |
| Customized code: |
| |
| [source,java,indent=4] |
| ---- |
| // public class USAddress { // Default Code |
| public class MyAddress { // Customized Code |
| public String getCountry() {...} |
| public void setCountry(String value) {...} |
| ... |
| } |
| ---- |
| |
| ===== Simple Type Definition |
| |
| When `<class>` customization specified in the |
| annotation element of a simple type definition, the simple type |
| definition must be bound to a Java value class as specified in |
| link:jaxb.html#a803[See Bind to a JAXB mapped class]” applying |
| the customization overrides as specified in |
| link:jaxb.html#a1713[See Customization Overrides].” |
| |
| *_Example:_* Class Customization: Simple Type Definition To Java value class + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:simpleType name="SKU"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:class/> |
| </xs:appinfo></xs:annotation> |
| <xs:restriction base=”xs:int”/> |
| </xs:simpleType> |
| ---- |
| |
| Customized code: |
| |
| [source,java,indent=4] |
| ---- |
| public class SKU { |
| @XmlValue |
| public int getValue() {...} |
| public void setValue(int value) {...} |
| ... |
| } |
| ---- |
| |
| ===== Model Group Definition |
| |
| It is invalid to place a `<jaxb:class>` customization on a model group. |
| |
| ===== Model Group |
| |
| It is invalid to place a `<jaxb:class>` customization on an unnamed model group. |
| |
| ===== Global Element Declaration |
| |
| A `_<class>_` declaration is allowed in the |
| annotation element of the global element declaration. However, the |
| `_implClass_` attribute is not allowed. The global element declaration |
| must be bound as specified in link:jaxb.html#a1068[See Bind to |
| Element Class]” applying the customization overrides specified in |
| link:jaxb.html#a1713[See Customization Overrides].” |
| |
| *_Example:_* Class Customization: Global Element to Class + |
| |
| XML Schema Fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="AComplexType"> |
| <xs:sequence> |
| <xs:element name="A" type="xs:int"/> |
| <xs:element name="B" type="xs:string"/> |
| </xs:sequence> |
| </xs:complexType> |
| |
| <xs:element name="AnElement" type="AComplexType"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:class name="MyElement"/> |
| </xs:appinfo></xs:annotation> |
| </xs:element> |
| ---- |
| |
| Customized code: |
| |
| [source,java,indent=4] |
| ---- |
| // following class is generated because of customization |
| |
| public class AComplexType { |
| void setA(int value) {...} |
| int getA() {...} |
| void setB(String value) {...} |
| String getB() {...} |
| } |
| |
| public class MyElement extends JAXBElement<AComplexType> {...} |
| |
| public class ObjectFactory { |
| |
| // Default code |
| // JAXBElement<AnElement> createAnElement(AnElement)\{...} |
| |
| // Customized code |
| MyElement createMyElement(AnElement) {...} |
| ... other factory methods ... |
| |
| } |
| ---- |
| |
| ===== Local Element |
| |
| A local element is a schema element that |
| occurs within a complex type definition. A local element is one of: |
| |
| * local element reference (using the “ref” |
| attribute) to a global element declaration. |
| * local element declaration (“ref” attribute is not used). |
| |
| A `<class>` declaration is allowed in the |
| annotation element of a local element. link:jaxb.html#a2217[See |
| Annotation Restrictions]” contains more information regarding the |
| annotation element for a local element reference. However, the |
| `_implClass_` attribute is not allowed. |
| |
| A `<class>` customization on local element |
| reference must result in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]” since a local |
| element reference is never bound to a Java Element class. |
| |
| A `<class>` customization on local element |
| declaration applies only when a local element declaration is bound to a |
| Java Element class. Otherwise it must result in an invalid customization |
| as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” If applicable, a local element must be bound as |
| specified in link:jaxb.html#a1040[See Bind to JAXBElement<T> |
| Instance]” applying the customization overrides as specified in |
| link:jaxb.html#a1713[See Customization Overrides].” |
| |
| *_Example:_* Class Customization: Local Element Declaration To Java Element + |
| |
| The following example is from link:jaxb.html#a1359[See Examples]. |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="Base"> |
| <xs:choice maxOccurs="unbounded"> |
| <xs:element name="A" type="xs:string"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:class name="Bar"/> |
| </xs:appinfo></xs:annotation> |
| </xs:element> |
| <xs:element name="B" type="xs:string"/> |
| <xs:element name="C" type="xs:int"/> |
| </xs:choice> |
| </xs:complexType> |
| ---- |
| |
| Customized code: |
| |
| [source,java,indent=4] |
| ---- |
| import jakarta.xml.bind.JAXBElement; |
| public class ObjectFactory { |
| // element instance factories only |
| // JAXBElement<String> createBaseA(String value); // default code |
| JAXBElement<String> createBaseBar(String value); // Customized |
| JAXBElement<String> createBaseB(String value); |
| JAXBElement<Integer> createBaseC(Integer value); |
| } |
| public class Base { |
| static public class Bar extends JAXBElement<String> {...} // Customized code |
| /** |
| * A general content list that can contain element |
| * instances of JAXBElement<String> or JAXBElement<Integer>. |
| */ |
| List<Object> getBarOrBOrC() {...} |
| } |
| ---- |
| |
| === `<property>` Declaration |
| |
| This binding declaration allows the |
| customization of a binding of an XML schema element to its Java |
| representation as a property. This section identifies all XML schema |
| elements that can be bound to a Java property and how to customize that |
| binding. |
| |
| The scope of customization value can either |
| be definition scope or component scope depending upon which XML schema |
| element the `_<property>_` binding declaration is specified. |
| |
| ==== Usage |
| |
| [source,xml,indent=4] |
| ---- |
| <property [ name = "propertyName" ] |
| [ collectionType = "propertyCollectionType" ] |
| [ fixedAttributeAsConstantProperty = "true" | "false" | "1" | "0" ] |
| [ generateIsSetMethod = "true" | "false" | "1" | "0" ] |
| [ enableFailFastCheck = "true" | "false" | "1" | "0" ] |
| [ generateElementProperty = "true" | "false" | "1" | "0" ] |
| [ attachmentRef = "resolve" | "doNotResolve" | "default" ] > |
| [ <baseType name = "fully qualified Java class"> ... </baseType> ] |
| [ <javadoc> ... </javadoc> ] |
| </property> |
| |
| <baseType name=”fully qualified Java class”> |
| <javaType> ... </javaType> |
| </baseType> |
| ---- |
| |
| For readability, the `<baseType>` element is |
| shown separately. However, it can be used only as a local element within |
| the `<property>` element. |
| |
| The use of this declaration is subject to the |
| constraints specified in link:jaxb.html#a1825[See Usage |
| Constraints]. |
| |
| The customization values defined are: |
| |
| * `_name_` if specified, defines the |
| customization value `_propertyName;_` it must be a legal Java identifier. |
| * `_collectionType_` if specified, defines the |
| customization value `_propertyCollectionType_` which is the collection |
| type for the property. `_propertyCollectionType_` if specified, must be |
| either `"indexed"` or any fully qualified class name that implements |
| `_java.util.List_`. |
| * `_fixedAttributeAsConstantProperty_` if |
| specified , defines the customization value |
| `_fixedAttributeAsConstantProperty_`. The value must be one of |
| `"true"`, `"false"`, `"1"` or `"0"`. |
| * `_generateIsSetMethod_` if specified, |
| defines the customization value of `_generateIsSetMethod_`. The value must |
| be one of `"true"`, `"false"`, `"1"` or `"0"`. |
| * `_enableFailFastCheck_` if specified, |
| defines the customization value `_enableFailFastCheck_`. The value must be |
| one of `"true"`, `"false"`, `"1"` or `"0"`. |
| * `@generateElementProperty` if specified, |
| controls the generation of JAXBElement property. The value must be one |
| of `"true"`, `"false"`, `"1"` or `"0"`. The default is absence of the value. |
| It is an error for this attribute to be present if this customization is |
| attached to local or global attribute declarations. This customization |
| affects the binding as follows. It is an error to specify this |
| customization, when the property is required to be `_JAXBElement_` (such |
| as when a property contains multiple elements with different names but |
| of the same type.) |
| ** _true_ : Always generate properties to use `_JAXBElement_`. |
| ** _false_ : When generating properties from |
| `_<element nillable="true" minOccurs="0" />_`, generate a property not to |
| use JAXBElement, as if the element declaration were just `_<element nillable="true"/>_`. |
| * `@attachmentRef` has a default value of |
| “default”. This mode defers to default processing as specified in |
| link:jaxb.html#a5147[See Binding WS-I Attachment Profile |
| ref:swaRef]”. + |
| + |
| When `@attachmentRef` value is _resolve_ and the property’s base type is |
| or derives from `xsd:anyURI`, the schema-derived JAXB property has a |
| base type of `jakarta.activation.DataHandler` and the property is |
| annotated with `@XmlAttachmentRef`. + |
| + |
| Disabling autoresolving an element/attribute of type `ref:swaRef`: + |
| When `@attachmentRef` value is _doNotResolve_ and the property’s base |
| type derives from standard schema type `ref:swaRef`, the schema-derived |
| JAXB property has the base type `String`, derived from `xsd:anyURI`, |
| and `@XmlAttachmentRef` is not generated for the property. |
| * `_<javadoc>_` element, if specified |
| customizes the Javadoc for the property’s getter method. `_<javadoc>_` |
| must be specified as described in link:jaxb.html#a2142[See |
| <javadoc> Declaration].” |
| |
| ==== baseType |
| |
| The `<baseType>` element is intended to allow |
| the customization of a base type for a JAXB property. This element can |
| only be a child of <jaxb:property> element. |
| |
| [source,xml,indent=4] |
| ---- |
| <baseType name="fully qualified Java class>"> |
| <javaType> ... </javaType> |
| </baseType> |
| ---- |
| |
| |
| The `@name` attribute enables either the |
| specialization or generalization of the default base type binding for a |
| JAXB property. Child element `<javaType>` is used to convert the default |
| base type to a Java class. These two mutual exclusive usages of the |
| <baseType> customization are described below. |
| |
| ===== Conversion using Child element <javaType> |
| |
| Optional child element `_<javaType>_`, if |
| specified, defines the customization value `_javaType_` and must be |
| specified as defined in link:jaxb.html#a1981[See <javaType> |
| Declaration]. The customization value defined has component scope. This |
| customization converts the default base type’s value for a simple type |
| definition to the Java class specified by <javaType> name. |
| |
| The schema-derived JAXB property is annotated |
| with `@XmlJavaTypeAdapter` specified in Section 8. |
| `@XmlJavaTypeAdapter.value()` is set to a generated |
| classfootnote:[There is no need to |
| standardize the name of the generated class since |
| _@XmlJavaTypeAdapter.value()_ references the class.] that extends |
| `jakarta.xml.bind.annotation.adapter.XmlAdapter`. The generated class’ |
| `unmarshal` method must call the <javaType> customization’s parse |
| method, which is specified in link:jaxb.html#a1981[See |
| <javaType> Declaration]. The generated class’ `marsha` method must call |
| the <javaType> customization’s print method. |
| |
| ===== Generalize/Specialize baseType with attribute @name |
| |
| The `name` attribute for`<baseType` enables |
| more precise control over the actual base type for a JAXB property. This |
| customization enables specifying an alternative base type than the |
| property’s default base type. The alternative base type must still be in |
| the same class inheritance hierarchy as the default base type. The |
| alternative base type must be either a super interface/class or subclass |
| of the default Java base type for the property. The customization |
| enables one to specialize or generalize the properties binding. |
| |
| The `name` attribute value must be a fully |
| qualified Java class name. When the default base type is a primitive |
| type, consider the default Java base type to be the Java wrapper class |
| of that primitive type. |
| |
| Generalizing the basetype using this |
| customization enables simple type substitution for a JAXB property |
| representing with too restrictive of a default base type. To enable all |
| possible valid type substitutions, the `name` attribute should be |
| `java.lang.Object`. However, if for example, it is known that all type |
| substitutions will share a more specific Java super interface/class than |
| `java.lang.Object`, that Java class name can be used achieve a stronger |
| typed binding. With this customization, the JAXB annotation generated |
| for the property’s `@XmlElement.type()` or `@XmlAttribute.type()` is |
| still the default Java datatype for the element/attribute’s |
| schema-defined type. |
| |
| The schema-derived customized JAXB property |
| is annotated, either explicitly or by default mapping annotations, with |
| the mapping annotation `@XmlElement`, specified in Section 8.10.1. The |
| `@XmlElement` annotation element type is derived in terms of the |
| abstract model properties for a element type definition summarized in |
| link:jaxb.html#a4937[See Element Declaration Schema Component] |
| as follows: |
| |
| .Annotate JAXB property with @XmlElement element-value pairs |
| [cols=",",options="header"] |
| |=== |
| | @XmlElement element | @XmlElement value |
| | type |the java type binding of the element declaration’s _{type definition}_ |
| |=== |
| |
| Note that the Java class for |
| `@XmlElement.type()` can differ from the recommended JAXB property’s |
| base type to enable type substitution of java.lang.Object. This binding |
| enables unmarshalling of the Element’s simple content when it is not |
| qualified with an `xsi:type` as the element’s schema-declared type. |
| `@XmlElement.type()` acts as the default `xsi:type` for a JAXB property |
| where the property’s base type was generalized to allow for type |
| substitution of an element declaration with a simple type definition. |
| |
| Specializing the basetype using this |
| customization generates stronger typing than default JAXB binding. For |
| example, an XML element or attribute of `xs:IDREF` binds to |
| `java.lang.Object` by default as specified in |
| link:jaxb.html#a1290[See Binding an IDREF component to a Java |
| property]”. If the schema only intends the reference to be to an element |
| that binds to a specific type, the baseType @name schema customization |
| can be used to specialize the binding. |
| |
| *_Example:_* Specialize binding of an IDREF via customization + |
| |
| Given XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="Book"> |
| <xs:sequence> |
| <xs:element name="author" type="xs:IDREF"/> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property> |
| <jaxb:baseType name=”AuthorBio.class”/> |
| </jaxb:property> |
| </xs:appinfo></xs:annotation> |
| <!-- ... --> |
| </xs:sequence> |
| </xs:complexType> |
| <xs:complexType name="AuthorBio"> |
| <xs:sequence><!-- ... --> </xs:sequence> |
| <xs:attribute name="name" type="xs:ID"/> |
| </xs:complexType> |
| ---- |
| |
| Schema-derived Java value class: |
| |
| [source,java,indent=4] |
| ---- |
| public class Book { |
| @XmlIDREF |
| AuthorBio getAuthor() {...} |
| void setAuthor(AuthorBio referencedObj) {...} |
| } |
| public class AuthorBio { |
| @XmlID |
| String getName() {...} |
| void setName(String value) {...} |
| } |
| ---- |
| |
| ===== Usage Constraints |
| |
| The usage constraints on `<property>` are |
| specified below. Any constraint violation must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” The usage constraints are: |
| |
| . The `<baseType>` is only allowed with the |
| following XML schema elements from the link:jaxb.html#a1857[See |
| Customizable Schema Elements]”: |
| .. Local Element, link:jaxb.html#a1913[See Local Element]. |
| .. Local Attribute, link:jaxb.html#a1861[See Local Attribute]. |
| .. ComplexType with simpleContent, link:jaxb.html#a1976[See ComplexType]. |
| . `<baseType>` can either have a name attribute |
| or a `<javaType>`, they both can not exist at the same time. |
| . The `_fixedAttributeAsConstantProperty_` is |
| only allowed with a local attribute, link:jaxb.html#a1861[See |
| Local Attribute], that is fixed. |
| . If a `<property>` declaration is associated |
| with the `<complexType>`, then a `<property>` customization cannot be |
| specified on the following schema elements that are scoped to |
| `<complexType>`: |
| + |
| -- |
| .. Local Element |
| .. Model group |
| .. Model Group Reference |
| -- |
| The reason is that a `<property>` declaration |
| associated with a complex type binds the content model of the complex |
| type to a general content property. If a `<property>` declaration is |
| associated with a schema element listed above, it would create a |
| conflicting customization. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| A Local Attribute is excluded from the list above. |
| The reason is that a local attribute is not part of the content model |
| of a complex type. This allows a local attribute to be customized |
| (using a <property> declaration) independently |
| from the customization of a complex type’s content model. |
| |
| ==== |
| |
| *_Example:_* Property Customization: simple type customization + |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="internationalPrice"> |
| .... |
| <xs:attribute name="currency" type="xs:string"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property> |
| <jaxb:baseType> |
| <jaxb:javaType name="java.math.BigDecimal" |
| parseMethod="jakarta.xml.bind.DatatypeConverter.parseInteger" |
| printMethod="jakarta.xml.bind.DatatypeConverter.printInteger"/> |
| </jaxb:baseType> |
| </jaxb:property> |
| </xs:appinfo></xs:annotation> |
| </xs:attribute> |
| </xs:complexType> |
| ---- |
| |
| The code generated is: |
| |
| [source,java,indent=4] |
| ---- |
| public class InternationalPrice { |
| // String getCurrency(); default |
| java.math.BigDecimal getCurrency() {...} //customized |
| public void setCurrency(java.math.BigDecimal val) {...} // customized |
| } |
| ---- |
| |
| ==== Customization Overrides |
| |
| When binding a schema element’s Java |
| representation to a property, the following customization values |
| override the defaults specified in Chapter 6. It is specified in a |
| common section here and referenced from link:jaxb.html#a1857[See |
| Customizable Schema Elements]. |
| |
| * *name*: If _propertyName_ is defined, then it |
| is the name obtained by mapping the name as specified in |
| link:jaxb.html#a1608[See Customized Name Mapping].” |
| * *base type*: The basetype is |
| `_propertyBaseType_` if defined. The _propertyBaseType_ is defined by a XML |
| schema element in link:jaxb.html#a1857[See Customizable Schema |
| Elements]. |
| * *collection type*: The collection type is |
| `_propertyCollectionType_` if specified; otherwise it is the |
| `_propertyCollectionType_` inherited from a scope that covers this schema |
| element. |
| * *javadoc*: The Javadoc must be generated as |
| specified in section link:jaxb.html#a2163[See Javadoc |
| Customization].” The Javadoc section customized is the `method section`. |
| * If `_propertyBaseType_` is a Java primitive |
| type and `_propertyCollectionType_` is a class that implements |
| `java.util.List`, then the primitive type must be mapped to its wrapper |
| class. |
| |
| The following does not apply if local |
| attribute is being bound to a constant property as specified in |
| link:jaxb.html#a1861[See Local Attribute]: |
| |
| * If `_generateIsSetMethod_` is `"true"` or `"1"`, |
| then additional methods as specified in link:jaxb.html#a610[See |
| isSet Property Modifier]” must be generated. |
| * If `_enableFailFastCheck_` is `"true"` or `"1"`, |
| then the type constraint checking when setting a property is enforced by |
| the JAXB implementation. Support for this feature is optional for a JAXB |
| implementation in this version of the specification. |
| |
| ==== Customizable Schema Elements |
| |
| ===== Global Attribute Declaration |
| |
| A `_<property>_` declaration is allowed in |
| the annotation element of the global attribute declaration. |
| |
| The binding declaration does not bind the |
| global attribute declaration to a property. Instead it defines |
| customization values that have definition scope. The definition scope |
| covers all local attributes (link:jaxb.html#a1861[See Local |
| Attribute]”) that can reference this global attribute declaration. This |
| is useful since it allows the customization to be done once when a |
| global attribute is defined instead of at each local attribute that |
| references the global attribute declaration. |
| |
| ===== Local Attribute |
| |
| A local attribute is an attribute that occurs |
| within an attribute group definition, model group definition or a |
| complex type. A local attribute can either be a |
| |
| * local attribute reference (using the “ref” |
| attribute) to a global attribute declaration. |
| * local attribute declaration (“ref” |
| attribute is not used). |
| |
| A `_<property>_` declaration is allowed in |
| the annotation element of a local |
| attribute.link:jaxb.html#a2217[See Annotation Restrictions]” |
| contains more information regarding the annotation element for a local |
| attribute reference. The customization values must be defined as |
| specified in link:jaxb.html#a1786[See Usage]” and have component |
| scope. |
| |
| If `_javaType_` is defined, then the |
| `_propertyBaseType_` is defined to be Java datatype specified in the |
| `"name"` attribute of the `_javaType_`. |
| |
| * If `_fixedAttributeAsConstantProperty_` is |
| `"true"` or `"1"` and the local attribute is a fixed, the local |
| attribute must be bound to a Java Constant property as specified in |
| link:jaxb.html#a1277[See Bind to a Java Constant property] |
| applying customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides]. The |
| `_generateIsSetMethod_`, `_choiceContentProperty_` |
| and `_enableFailFastCheck_` must |
| be considered to have been set to `"false"`. |
| * Otherwise, it is bound to a Java property |
| as specified in link:jaxb.html#a1252[See Attribute use]” |
| applying customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides].” |
| |
| *_Example:_* Customizing Java Constant Property + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="USAddress"> |
| <xs:attribute name="country" type="xs:NMTOKEN" fixed="US"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="MY_COUNTRY" |
| fixedAttributeAsConstantProperty="true"/> |
| </xs:appinfo></xs:annotation> |
| </xs:attribute> |
| </xs:complexType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public class USAddress { |
| public static final String MY_COUNTRY = "US"; // Customized Code |
| } |
| ---- |
| |
| *_Example 2:_* Customizing to other Java Property + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="USAddress"> + |
| <xs:attribute name="country" type="xs:string"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="MyCountry"/> |
| </xs:appinfo></xs:annotation> |
| </xs:attribute> |
| </xs:complexType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public class USAddress { |
| // public getString getCountry(); // DefaultCode |
| // public void setCountry(string value);//Default Code |
| public String getMyCountry() {...} //Customized Code |
| public void setMyCountry(String value) {...}// Customized Code |
| } |
| ---- |
| |
| *_Example 3:_* Generating IsSet Methods + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:attribute name="account" type = "xs:int"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property generateIsSetMethod="true"/> |
| </xs:appinfo></xs:annotation> |
| </xs:attribute> |
| ---- |
| |
| Customized code: |
| |
| [source,java,indent=4] |
| ---- |
| public int getAccount(); |
| public void setAccount(int account); |
| public boolean isSetAccount(); // Customizedcode |
| public void unsetAccount(); // Customizedcode |
| ---- |
| |
| ===== Global Element Declaration |
| |
| A `_<property>_` declaration is allowed in the |
| annotation element of a global element declaration. However, the usage |
| is constrained as follows: |
| |
| The binding declaration does not bind the |
| global element declaration to a property. Instead it defines |
| customization values that have definition scope. The definition scope |
| covers all local elements (link:jaxb.html#a1913[See Local |
| Element]”) that can reference this global element declaration. This is |
| useful since it allows the customization to be done once when a global |
| element is defined instead of at each local element that references the |
| global element declaration. |
| |
| ===== Local Element |
| |
| A local element is a schema element that |
| occurs within a complex type definition. A local element is one of: |
| |
| * local element reference (using the “ref” |
| attribute) to a global element declaration. |
| * local element declaration (“ref” attribute |
| is not used). |
| |
| A `<property>` declaration is allowed in the |
| annotation element of a local element. link:jaxb.html#a2217[See |
| Annotation Restrictions]” contains more information regarding the |
| annotation element for a local element reference. |
| |
| The customization values must be defined as |
| specified in link:jaxb.html#a1786[See Usage]” and have component |
| scope. |
| |
| If `_javaType_` is defined, then the |
| `_propertyBaseType_` is defined to be Java datatype specified in the |
| `"name"` attribute of the `_javaType_`. |
| |
| The local element must be bound as specified |
| in link:jaxb.html#a1414[See Content Model Default Binding] |
| applying customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides]. |
| |
| See example in |
| link:jaxb.html#a1966[See Example 3: Property Customization: |
| Model Group To Content Property Set]” in section |
| link:jaxb.html#a1944[See Model Group]. |
| |
| ===== Wildcard |
| |
| A `<property>` declaration is allowed in the |
| annotation element of the wildcard schema component. The customization |
| values must be defined as specified in link:jaxb.html#a1786[See |
| Usage]” and have component scope. |
| |
| The wildcard schema component must be bound |
| to a property as specified in link:jaxb.html#a1384[See Bind |
| wildcard schema component]” applying customization overrides as |
| specified in link:jaxb.html#a1847[See Customization Overrides].” |
| |
| *_Example:_* The following schema example is from UDDI V2.0 + |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="businessEntityExt"> |
| <xs:sequence> |
| <xs:any namespace="##other" |
| processContents="strict" |
| minOccurs="1" maxOccurs="unbounded"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="Extension"/> |
| </xs:appinfo></xs:annotation> |
| </xs:any> |
| .... |
| </xs:sequence> |
| </xs:complexType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public class BusinessEntityExt { |
| ... |
| // List getAny(); // Default Code |
| List getExtension() {...} // Customized Code |
| } |
| ---- |
| |
| ===== Model Group |
| |
| A `<property>` binding declaration is allowed |
| in the annotation element of the compositor (i.e. `<choice>`, |
| `<sequence>` or `<all>`). The customization values must be defined as |
| specified in link:jaxb.html#a1786[See Usage]” and have component |
| scope. |
| |
| The customized binding of a model group is |
| determined by the following: |
| |
| * `choiceContentProperty` attribute in `<globalBindings>`. |
| . If _propertyBaseType_ is defined and a |
| `<property>` declaration is also present, then the customization |
| overrides specified in link:jaxb.html#a1847[See Customization |
| Overrides] must be applied by the model group’s parent schema element |
| to the property used to aggregate the Java value class. |
| . If _propertySet_ is defined, then the model |
| group’s parent schema element must aggregate the property set as |
| specified in link:jaxb.html#a930[See Aggregation of Property |
| Set]. |
| |
| *_Example 1:_* Property Customization: Model Group To ChoiceContent Property + |
| |
| XML Schema fragment |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:annotation><xs:appinfo> |
| <jaxb:globalBindings choiceContentProperty="true"/> |
| </xs:appinfo></xs:annotation> |
| <xs:complexType name=”AType”> |
| <xs:choice> |
| <xs:element name="foo" type="xs:int"/> |
| <xs:element name="bar" type="xs:string"/> |
| </xs:choice> |
| </xs:complexType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| class ObjectFactory { |
| JAXBElement<Integer> createAtypeFoo(Integer value); |
| JAXBElement<String> createAtypeBar(String value); |
| } |
| public class AType { |
| void setFooOrBar(Object o) {...} //customized code |
| Object getFooOrBar() {...} //customized code |
| } |
| ---- |
| |
| The `choiceContentProperty` is required to |
| bind the choice model group to a choice content property. |
| |
| *_Example 2:_* Property Customization: Model Group To General Content Property + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="Base"> |
| <xs:choice maxOccurs="unbounded"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="items" /> |
| </xs:appinfo></xs:annotation> |
| <xs:element name="A" type="xs:string"/> |
| <xs:element name="B" type="xs:string"/> |
| <xs:element name="C" type="xs:int"/> |
| </xs:choice> |
| </xs:complexType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public class Base { |
| /** |
| * A general content list that can contain |
| * instances of Base.A, Base.B and Base.C. |
| */ |
| // List getAOrBOrC(); - default |
| List getItems() {...} // Customized Code |
| } |
| ---- |
| |
| *_Example 3:_* Property Customization: Model Group To Content Property Set + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name="USAddress"/> |
| <xs:complexType name="PurchaseOrderType"> |
| <xs:sequence> |
| <xs:choice> |
| <xs:group ref="shipAndBill"/> |
| <xs:element name="singleUSAddress" type="USAddress"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="address"/> |
| </xs:appinfo></xs:annotation> |
| </xs:element> |
| </xs:choice> |
| </xs:sequence> |
| </xs:complexType> |
| <xs:group name="shipAndBill"> |
| <xs:sequence> |
| <xs:element name="shipTo" type="USAddress"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="shipAddress"/> |
| </appinfo></annotation> |
| </xs:element> |
| <xs:element name="billTo" type="USAddress"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:property name="billAddress"/> |
| </xs:appinfo></xs:annotation> |
| </xs:element> |
| </xs:sequence> |
| </xs:group> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public interface PurchaseOrderType { |
| USAddress getShipAddress(); void setShipAddress(USAddress); |
| USAddress getBillAddress(); void setBillAddress(USAddress); |
| USAddress getAddress(); void setAddress(USAddress); |
| } |
| ---- |
| |
| ===== Model Group Reference |
| |
| A model group reference is a reference to a |
| model group using the “ref” attribute. A property customization is |
| allowed on the annotation property of the model group reference. Section |
| link:jaxb.html#a2217[See Annotation Restrictions] contains more |
| information regarding the annotation element for a model group |
| reference. |
| |
| The customization values must be defined as |
| specified in link:jaxb.html#a1786[See Usage]” and have component |
| scope. A model group reference is bound to a Java property set or a list |
| property as specified in link:jaxb.html#a1414[See Content Model |
| Default Binding]” applying customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides]. |
| |
| ===== ComplexType |
| |
| A `<property>` customization is allowed on |
| the annotation element of a complex type. The customization values must |
| be defined as specified in link:jaxb.html#a1786[See Usage] and |
| have component scope. The result of this customization depends upon the |
| content type of the complex type. |
| |
| * If the content type of the content model is |
| simple content, then the content model must be bound to a property as |
| specified in link:jaxb.html#a973[See Simple Content Binding].” |
| applying the customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides].” If |
| `_javaType_` is defined, then the `_propertyBaseType_` is defined to be Java |
| datatype specified in the `"name"` attribute of the `_javaType_`. |
| * For all other content types, the content |
| model must be bound as specified in step 1. of |
| link:jaxb.html#a1414[See Content Model Default Binding]” |
| applying the customization overrides as specified in |
| link:jaxb.html#a1847[See Customization Overrides]. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| The <property> declaration is not allowed on an annotation element |
| of attribute group definition. However, attributes within |
| the attribute group definition can themselves be customized |
| as described in the “Local Attribute” section above. |
| Section 7.8.4.2, “Local Attribute.” |
| |
| ==== |
| |
| === `<javaType>` Declaration |
| |
| A `<javaType>` declaration provides a way to |
| customize the binding of an XML schema atomic datatype to a Java |
| datatype, referred to as the _target Java datatype_. The target Java |
| datatype can be a Java built-in data type or an application specific |
| Java datatype. This declaration also provides two additional methods: |
| a _parse method_ and a _print method_. |
| |
| The parse method converts a lexical |
| representation of the XML schema datatype into a value of the target |
| Java datatype. The parse method is invoked by a JAXB provider’s |
| implementation during unmarshalling. |
| |
| The print method converts a value of the |
| target Java datatype into its lexical representation of the XML schema |
| datatype. The print method is invoked by a JAXB provider’s |
| implementation during marshalling. |
| |
| ==== Usage |
| |
| [source,xml,indent=4] |
| ---- |
| <javaType name="javaType" |
| [ xmlType = "xmlType" ] |
| [ parseMethod = "parseMethod" ] |
| [ printMethod = "printMethod" ]> |
| ---- |
| |
| The binding declaration can be used in one of |
| the following: |
| |
| * a `<globalBindings>` declaration. |
| * annotation element of one of the XML schema |
| elements specified in link:jaxb.html#a2079[See Customizable |
| Schema Elements].” |
| * in a `<property>` declaration. See |
| link:jaxb.html#a1783[See <property> Declaration]. This can be |
| used for customization at the point of reference to a simple type. |
| |
| When used in a `<globalBindings>` |
| declaration, `<javaType>` defines customization values with global |
| scope. When used in an annotation element of one of the schema elements |
| specified in link:jaxb.html#a2079[See Customizable Schema |
| Elements].” the customization values have component scope. |
| |
| ===== name |
| |
| The `_javaType_`, if specified, is the Java |
| datatype to which `_xmlType_` is to be bound. Therefore, `_javaType_` must |
| be a legal Java type name, which may include a package prefix. If the |
| package prefix is not present, then the Java type name must be one of |
| the Java built-in primitive types [JLS - Java Language Specification, |
| Second Edition, Section 4.2, “Primitive Types and Values”]. (For |
| example, `"int"`) or a Java class in the unnamed package. If class |
| javaType declares a public constructor with following signature, |
| `javaType(java.lang.String)`, `parseMethod` attribute does not need to |
| be specified. |
| |
| ===== xmlType |
| |
| The `_xmlType_`, if specified, is the name of |
| the XML Schema datatype to which `_javaType_` is to bound. If specified, |
| `_xmlType_` must be a XML atomic datatype derived from restriction. The |
| use of the `_xmlType_` is further constrained as follows. |
| |
| The purpose of the `_xmlType_` attribute is to |
| allow the global customization of a XML schema to Java datatype. Hence |
| `_xmlType_` attribute is required when `<javaType>` declaration’s parent |
| is `<globalBindings>`. If absent, it must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” Otherwise, the _xmlType_ attribute must not be present |
| since the XML datatype is determined from the XML schema element with |
| which the annotation element containing `<javaType>` declaration or the |
| `<baseType>` (containing the `<javaType>`) is associated. If present, |
| it must result in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]. |
| |
| Examples can be found in |
| link:jaxb.html#a2062[See Example: javaType Customization: Java |
| Built-in Type]” and link:jaxb.html#a2027[See Example: javaType |
| Customization: User Specified Parse Method] |
| |
| ===== parseMethod |
| |
| The parse method if specified, must be |
| applied during unmarshalling in order to convert a string from the input |
| document into a value of the target Java datatype. The parse method must |
| be invoked as follows: |
| |
| * The parse method defaults to `new` provided |
| `_javaType_` is not a Java primitive type such as (``"int"``). If |
| `_javaType_` is a Java primitive type, then this must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” Otherwise, the binding compiler must assume that the |
| target type is a class that defines a constructor as follows: |
| + |
| -- |
| ** `String` as the first parameter of the constructor. |
| -- |
| + |
| To apply the conversion to a string it must |
| generate code that invokes this constructor, passing it the input |
| string. |
| |
| * The parse method may be specified in the |
| form _ClassName.methodName,_ where the _ClassName_ is a fully qualified |
| class name that includes the package name. A compiler must assume that |
| the class _ClassName_ exists and that it defines a static method named |
| _methodName_ that takes: |
| + |
| -- |
| ** `String` as the first argument. |
| -- |
| + |
| To apply the conversion to a string it must |
| generate code that invokes this method, passing it the input string. |
| |
| * The parse method may be specified in the |
| form _methodName_ provided `_javaType_` is not a Java primitive type (such |
| as `"int"`). If `_javaType_` is Java primitive type, then this must |
| result in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]. Otherwise, |
| the binding compiler must assume that _methodName_ is a method in the |
| class `_javaType_`. The binding compiler must therefore prefix the |
| `_javaType_` to the _methodName_ and process `_javaType_`._methodName_ as |
| specified in above. |
| |
| The string passed to parse method can be any |
| lexical representation for `xmlType` as specified in [XSD PART2]. |
| |
| If parseMethod attribute is not specified, |
| `xmlType` is not a primitive or wrapper class and `javaType` has an |
| accessible one argument constructor, where the argument is type |
| `java.lang.String`, input text is parsed by invoking `new` with a |
| `java.lang.String` parameter. |
| |
| ===== printMethod |
| |
| The print method if specified, must be |
| applied during marshalling in order to convert a value of the target |
| type into a lexical representation: |
| |
| * The print method is specified in the form |
| _methodName_ provided `_javaType_` is not a Java primitive type (such as |
| `"int"`). If `_javaType_` is Java primitive type, then this must result |
| in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]. Otherwise, |
| the compiler must assume that the target type is a class or an interface |
| that defines a zero-argument instance method named _methodName_ that |
| returns a `String`. To apply the conversion it must generate code to |
| invoke this method upon an instance of the target Java datatype. |
| * If the print method is specified in the |
| form _ClassName.methodName_ then the compiler must assume that the class |
| _ClassName_ exists and that it defines a static method named |
| _methodName_ that returns a string that takes the following: |
| + |
| -- |
| ** the first parameter is the target Java |
| datatype. |
| -- |
| + |
| To apply the conversion to a string it must |
| generate code that invokes this method, passing it a value of the target |
| Java datatype. |
| |
| The lexical representation to which the value |
| of the target type is converted can be any lexical representation for |
| `xmlType` as specified in [XSD PART2]. |
| |
| If `printMethod` attribute is not specified |
| and `xmlType` is not a primitive or wrapper class, `javaType.toString()` |
| is used as the default print method.. |
| |
| |
| |
| ==== DatatypeConverter |
| |
| Writing customized parse and print methods |
| can be difficult for a Java programmer. This requires a programmer to |
| understand the lexical representations of XML schema datatypes. To make |
| it easier, an interface, `DatatypeConverterInterface`, and a class |
| `DatatypeConverter` are defined to expose the parse and print methods of |
| a JAXB implementation. These can be invoked by user defined parse and |
| print methods. This shifts the burden of dealing with lexical spaces |
| back to the JAXB implementation. |
| |
| The `DatatypeConverterInterface` defines |
| parse and print methods for XML schema datatypes. There is one parse and |
| print method for each of XML schema datatype specified in |
| link:jaxb.html#a725[See Java Mapping for XML Schema Built-in |
| Types]. The interface is fully specified by the Javadoc specified in |
| `jakarta.xml.bind.DatatypeConverterInterface`. |
| |
| The `DatatypeConverter` class defines a |
| static parse and print method corresponding to each parse and print |
| method respectively in the `DatatypeConverterInterface` interface. The |
| property `jakarta.xml.bind.DatatypeConverter` can be used to select the |
| name of a class that provides an implementation of the parse and print |
| methods. The name specified in the property must be a fully qualified |
| class name and must implement the interface `DatatypeConverterInterface` |
| . The class is fully specified by the Javadoc specified in |
| `jakarta.xml.bind.DatatypeConverter`. |
| |
| ===== Usage |
| |
| The following example demonstrates the use of |
| the `DatatypeConverter` class for writing a customized parse and print |
| method. |
| |
| *_Example:_* javaType Customization: User Specified Parse Method + |
| |
| This example shows the binding of XML schema |
| type `"xs:date"` is bound to a Java datatype `long` using user specified |
| print and parse methods. |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:globalBindings> |
| <jaxb:javaType name="long" xmlType="xs:date" |
| parseMethod="pkg.MyDatatypeConverter.myParseDate" |
| printMethod="pkg.MyDatatypeConverter.myPrintDate"/> |
| </jaxb:javaType> |
| </jaxb:globalBindings> |
| ---- |
| |
| [source,java,indent=4] |
| ---- |
| package pkg; |
| import jakarta.xml.bind.DatatypeConverter; |
| public class MyDatatypeConverter { |
| public static long myParseDate(String s) { |
| java.util.Calendar d = DatatypeConverter.parse(s); |
| long result= cvtCalendarToLong(d) ; // userdefined method |
| return result; |
| } |
| public static String myPrintDate(long l) { |
| java.util.Calendar d = cvtLongToCalendar(l);//user defined |
| return DatatypeConverter.print(d); |
| } |
| } |
| ---- |
| |
| The implementation of the print methods ( |
| `_parseDate_` and `_printDate_`) are provided by the user. |
| |
| The customization is applied during the |
| processing of XML instance document. During unmarshalling, the JAXB |
| implementation invokes `_myParseDate_`. If `_myParseDate_` method throws a |
| `_ParseException_`, then the JAXB implementation code catches the |
| exception, and generate a `_parseConversionEvent_`. |
| |
| ===== Lexical And Value Space |
| |
| [XSD PART 2] specifies both a value space and |
| a lexical space for an schema datatypes. There can be more than one |
| lexical representation for a given value. |
| |
| Examples of multiple lexical representations |
| for a single value are: |
| |
| * For boolean, the value `true` has two |
| lexical representations `"true"` and `"1"`. |
| * For integer, the value `1` has two lexical |
| representations `"1.0"` and `"1"`. |
| |
| XSD PART 2 also specifies a canonical |
| representation for all XML schema atomic datatypes. |
| |
| The requirements on the parse and print |
| methods are as follows: |
| |
| * A JAXB implementation of a parse method in |
| `DatatypeConverterInterface` must be capable of a processing all lexical |
| representations for a value as specified by [XSD PART 2]. This ensures |
| that an instance document containing a value in any lexical |
| representation specified by [XSD PART 2] can be marshalled. |
| * A JAXB implementation of a print method in |
| `DatatypeConverterInterface` must convert a value into any lexical |
| representation of the XML schema datatype to which the parse method |
| applies, as specified by [XSD PART 2] and which is valid with respect to |
| the application’s schema. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| The print methods that are exposed may not be portable. The only |
| requirement on a print method is that it must output |
| a lexical representation that is valid with respect to the schema. |
| So two vendors can choose to output different lexical representations. |
| However, there is value in exposing them despite being non portable. |
| Without the print method, a user would have to be knowledgeable about |
| how to output a lexical representation for a given schema datatype, |
| which is not desirable. |
| |
| ==== |
| |
| ==== Built-in Conversions |
| |
| As a convenience to the user, this section |
| specifies some built-in conversions. A built-in conversion is one where |
| the parse and the print method may be omitted by a user. The built-in |
| conversions leverage the narrowing and widening conversions defined in |
| [JLS - Java Language Specification, Second Edition], Section 5.1.2, |
| “Widening Primitive Conversion” and Section 5.1.3, “Narrowing Primitive |
| Conversions.” For example: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:simpleType name="foo" type="xs:long"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:javaType name="int"/> |
| </xs:appinfo></xs:annotation> |
| </xs:simpleType> |
| ---- |
| |
| If the parse method is omitted, then a JAXB |
| implementation must perform the one of the following binding options: |
| |
| .. If `_javaType_` is one of the following |
| primitive types or its corresponding wrapper class `byte`, `short`, `int`, |
| `long`, `float`, `double` , bind `_xmlType_` to its default Java datatype using |
| the parse method for the `_xmlType_` defined in `DatatypeConverter`. If |
| necessary, convert the default Java datatype for `xmlType` to value of |
| type `_javaType_` by a type cast. |
| .. Else if default Java datatype defines a |
| public one-argument constructor that takes a `java.lang.String`, use |
| `new` with a `java.lang.String` parameter for parsing. |
| .. Else javaType(java.lang.String) does not |
| exist, this must result in an invalid binding customization as specified |
| in link:jaxb.html#a1544[See Invalid Customizations]. |
| |
| *_Example:_* javaType Customization: Java Built-in Type + |
| |
| This example illustrates how to bind a XML |
| schema type to a Java type different from the default one. |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:element name="partNumber" type="xs:int"/> |
| ---- |
| |
| Customization: |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:globalBindings> |
| .... |
| <jaxb:javaType name="long" |
| xmlType="xs:int"/> |
| </jaxb:globalBindings> |
| ---- |
| |
| Since a Java built-in is specified, a parse |
| or a print method need not be specified. A JAXB implementation uses the |
| parse and print methods defined in `DatatypeConverter` class for |
| converting between lexical representations and values. A JAXB |
| implementation unmarshals an input value using the following methods: |
| |
| [source,java,indent=8] |
| ---- |
| int j = (int) DataTypeConverter.parseLong(string); |
| ---- |
| |
| ==== Events |
| |
| The parse method `_parseMethod_` may fail, |
| since it is only defined on those strings that are valid representations |
| of target Java datatype values and it can be applied to arbitrary |
| strings. A parse method must indicate failure by throwing an exception |
| of whatever type is appropriate, though it should never throw a |
| `TypeConstraintException`. A JAXB unmarshaller process must ensure that |
| an exception thrown by a parse method is caught and, if appropriate, a |
| `parseConversionEvent` event is generated. |
| |
| The print method `_printMethod_` usually does |
| not fail. If it does, then the JAXB implementation must ensure that the |
| exception thrown by a print method is caught and a |
| `printConversionEvent` is generated. |
| |
| ==== Customization Overrides |
| |
| The `<javaType>` overrides the default |
| binding of `_xmlType_` to the Java datatype specified in |
| link:jaxb.html#a725[See Java Mapping for XML Schema Built-in |
| Types]. |
| |
| ==== Customizable Schema Elements |
| |
| ==== Simple Type Definition |
| |
| A `<javaType>` binding declaration is allowed |
| in the annotation element of the of a simple type definition. The |
| `_javaType_` overrides the default binding of `_xmlType_` to the Java |
| datatype specified in link:jaxb.html#a725[See Java Mapping for |
| XML Schema Built-in Types]. The customization values defined have |
| definition scope and thus covers all references to this simple type |
| definition. |
| |
| If the simple type definition is mapped to a |
| schema-derived type, an `@XmlJavaTypeAdapter` is generated on that |
| class. Annotation element `@XmlJavaTypeAdapter.value()` is set to a |
| generated classfootnote:[There is no need to |
| standardize the name of the generated class since |
| _@XmlJavaTypeAdapter.value()_ references the class.] that extends |
| `jakarta.xml.bind.annotation.adapter.XmlAdapter`. The generated class’ |
| `unmarshal` method must call the <javaType> customization’s parse |
| method, which is specified in link:jaxb.html#a1981[See |
| <javaType> Declaration]. The generated class’ `marshal` method must call |
| the <javaType> customization’s print method. |
| |
| ===== GlobalBindings |
| |
| A `<javaType>` binding declaration is allowed |
| as part of `<globalBindings>`. The `_javaType_` overrides the default |
| binding of `_xmlType_` to the Java datatype specified in |
| link:jaxb.html#a725[See Java Mapping for XML Schema Built-in |
| Types]. The customization values defined have global scope. |
| |
| For each element or attribute declaration |
| that references an `xmlType` that has a globalBindings `<javaType>` |
| customization specified for it, the corresponding JAXB property is |
| annotated with `@XmlJavaTypeAdapter`. |
| |
| ===== `<property><baseType>` declaration |
| |
| A `<javaType>` binding declaration is allowed |
| as part of `<baseType>` in the `<property>` binding declaration. The |
| `_javaType_` overrides the default binding of `_xmlType_` to the Java |
| datatype specified in link:jaxb.html#a725[See Java Mapping for |
| XML Schema Built-in Types]. Additional semantics are specified in |
| link:jaxb.html#a1801[See baseType] also |
| apply. |
| |
| The schema-derived JAXB property is annotated |
| with `@XmlJavaTypeAdapter` as specified in |
| link:jaxb.html#a1801[See baseType]. |
| |
| === `<typesafeEnum>` Declaration |
| |
| This binding declaration allows the |
| customization of a binding of an XML schema element to its Java |
| representation as an enum type, Section 8.9 in [JLS3]. Only simple type |
| definitions with enumeration facets can be customized using this binding |
| declaration. |
| |
| ==== Usage |
| [source,xml,indent=4] |
| ---- |
| <typesafeEnumClass> |
| [ name = "enumClassName" ] |
| [ map = "true" | "false" | "1" | "0" ] |
| [ ref = "enumClassName" ] |
| [ <typesafeEnumMember> ... </typesafeEnumMember> ]* |
| [ <javadoc> enumClassJavadoc </javadoc> ] |
| </typesafeEnumClass> |
| |
| <typesafeEnumMember name = "enumMemberName"> |
| [ value = "enumMemberValue"] |
| [ <javadoc> enumMemberJavadoc </javadoc> ] |
| </typesafeEnumMember> |
| ---- |
| There are two binding declarations |
| `_<typesafeEnumClass>_` and `_<typesafeEnumMember>_`. The two binding |
| declarations allow the enumeration members of an enumeration class and |
| enumeration class itself to be customized independently. |
| |
| The `_<typesafeEnumClass>_` declaration |
| defines the following customization values: |
| |
| * `name` defines the customization value |
| `_enumClassName_`, if specified. `_enumClassName_` must be a legal Java |
| Identifier; it must not have a package prefix. |
| + |
| For an anonymous simple type, the `name` attribute must be present. If |
| absent, it must result in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]. |
| * `map` determines if the simple type |
| definition should be bound to an enum type. When ``map``’s value is |
| `false`, then the simple type definition must not be bound to an enum |
| type. `map` defaults to `true`. |
| * `ref` if specified, is the name of the |
| enum class that is provided outside the schema compiler. This |
| customization causes a schema compiler to refer to this external enum, |
| as opposed to generate a definition. It must include the complete |
| package name. This attribute is mutually exclusive with the `className` |
| attribute and the `map` attribute. |
| * `<javadoc>` element, if specified |
| customizes the Javadoc for the enumeration class. _<javadoc>_ defines |
| the customization value `_enumClassjavadoc_` if specified as described in |
| link:jaxb.html#a2142[See <javadoc> Declaration]. |
| * Zero or more `_<typesafeEnumMember>_` |
| declarations. The customization values are as defined as specified by |
| the `_<typesafeEnumMember>_` declaration. |
| |
| The `_<typesafeEnumMember>_` declaration |
| defines the following customization values: |
| |
| * `name` must always be specified and |
| defines a customization value `_enumMemberName_`. `_enumMemberName_` must |
| be a legal Java identifier. |
| * `value` defines a customization value |
| `_enumMemberValue_`, if specified. `_enumMemberValue_` must be the |
| enumeration value specified in the source schema. The usage of `_value_` |
| is further constrained as specified in link:jaxb.html#a2106[See |
| value Attribute].” |
| * `<javadoc>` if specified, customizes the |
| Javadoc for the enumeration constant. `<javadoc>` defines a |
| customization value `_enumMemberjavadoc_` if specified as described in |
| link:jaxb.html#a2142[See <javadoc> Declaration]. |
| |
| For inline annotation, the |
| `<typesafeEnumClass>` must be specified in the annotation element of the |
| `<simpleType>` element. The `<typesafeEnumMember>` must be specified |
| in the annotation element of the enumeration member. This allows the |
| enumeration member to be customized independently from the enumeration |
| class. |
| |
| ==== `value` Attribute |
| |
| The purpose of the _value_ attribute is to |
| support customization of an enumeration value using an external binding |
| syntax. When the `<typesafeEnumMember>` is used in an inline annotation, |
| the enumeration value being customized can be identified by the |
| annotation element with which it is associated. However, when an |
| external binding declaration is used, while possible, it is not |
| desirable to use XPath to identify an enumeration value. |
| |
| So when customizing using external binding |
| syntax, the `value` attribute must be provided. This serves as a key to |
| identify the enumeration value to which the `<typesafeEnumMember>` |
| applies. It’s use is therefore further constrained as follows: |
| |
| * When `<typesafeEnumMember>` is specified in |
| the annotation element of the enumeration member or when XPath refers |
| directly to a single enumeration facet, then the value attribute must be |
| absent. If present, it must result in must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” |
| * When `<typesafeEnumMember>` is scoped to |
| the `typesafeEnumClass` declaration, the value attribute must be |
| present. If absent, it must result in must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations]. The _enumMemberValue_ must be used to identify the |
| enumeration member to which the `<typesafeEnumMember>` applies. |
| |
| An example of external binding syntax can be |
| found in link:jaxb.html#a2134[See Example 2: typesafeEnum |
| Customization: External Binding Declaration].” |
| |
| ==== Inline Annotations |
| |
| There are two ways to customize an |
| enumeration class: |
| |
| * split inline annotation |
| * combined inline annotation |
| |
| In split inline annotation, the enumeration |
| value and the enumeration class are customized separately i.e. the |
| `<typesafeEnumMember>` is used independently not as a child element of |
| `<typesafeEnumClass>`. An example of this is shown in |
| link:jaxb.html#a2129[See Example 1: typesafeEnum Customization: |
| Split Inline Annotation].” |
| |
| In combined inline annotation, the |
| enumeration value and the enumeration class are customized together i.e. |
| the `<typesafeEnumMember>` is used as a child element of |
| `<typesafeEnumClass>`. This is similar to the customization used in |
| external binding declaration. In this case the `value` attribute must be |
| present in the `<typesafeEnumMember>` for reasons noted in |
| link:jaxb.html#a2106[See value Attribute].” An example of this |
| customization is shown in link:jaxb.html#a2138[See Example 3: |
| typesafeEnum Customization: Combined Inline Annotation].” |
| |
| ==== Customization Overrides |
| |
| When binding a schema type definition’s Java |
| representation to an enum type, the following customization values |
| override the defaults specified in Chapter 5. It is specified in a |
| common section here and referenced from link:jaxb.html#a1857[See |
| Customizable Schema Elements].” |
| |
| * *name*: If _enumClassName_ is defined, then the |
| name obtained by mapping _enumClassName_ as specified in |
| link:jaxb.html#a1608[See Customized Name Mapping]. |
| * *package name*: The name obtained by |
| inheriting `_packgeName_` from a scope that covers this schema element and |
| mapping _packageName_ as specified in link:jaxb.html#a1608[See |
| Customized Name Mapping]. |
| * *enumclass javadoc*: `_enumClassJavaDoc_` if |
| defined, customizes the `class/interface section` |
| (link:jaxb.html#a2145[See Javadoc Sections]) for the enumeration |
| class, as specified in link:jaxb.html#a2163[See Javadoc |
| Customization]. |
| * *enum constant set*: Each member of the set |
| is computed as follows: |
| ** *name*: If _enumMemberName_ is defined, the |
| name obtained by mapping _enumMemberName_ as specified in |
| link:jaxb.html#a1608[See Customized Name Mapping]. |
| ** *javadoc*: `_enumMemberJavaDoc_` if defined, |
| customizes the `field section` (link:jaxb.html#a2145[See |
| Javadoc Sections]” ) for the enumeration class, as specified in |
| link:jaxb.html#a2163[See Javadoc Customization]. |
| |
| ==== Customizable Schema Elements |
| |
| Any XML Schema simple type which has an |
| enumeration facet can be customized with `<jaxb:typesafeEnumClass>` |
| declaration with the following exception. If the simple type definition |
| derives from `_xs:QName_`. `_xs:NOTATIION_`, `_xs:base64Binary_`, `_xs:hexBinary_`, |
| `_xs:date_`, `_xs:time_`, `_xs:dateTime_`, `_xs:duration_`, `_xs:gDay_`, `_xs:gMonth_`, |
| `_xs:gYear_`, `_xs:gMonthDay_`, `_xs:gYearMonth_`, `_xs:IDREF_`, `_xs:ID_`, it must result |
| in an invalid customization as specified in |
| link:jaxb.html#a1544[See Invalid Customizations]. Since most |
| of these Xml datatypes bind to a mutable Java type, instances of these |
| Java types are not sufficient to be an immutable value of an enum |
| constant. |
| |
| [NOTE] |
| .Design Note |
| ==== |
| The rationale for not allowing a type definition that derives from `xs:ID` |
| to bind to an enum type is to avoid complicating the resolution of `xs:IDREF` |
| values to `xs:ID` values. It is easiest if `xs:ID` values are always mapped to |
| an instance of `java.lang.String`. |
| |
| ==== |
| |
| *_Example 1:_* typesafeEnum Customization: Split Inline Annotation + |
| |
| XML Schema fragment: |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:simpleType name="USState"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:typesafeEnumClass name="USStateAbbr"/> |
| </xs:appinfo></xs:annotation> |
| <xs:restriction base="xs:NCName"> |
| <xs:enumeration value="AK"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:typesafeEnumMember name="STATE_AK"/> |
| </xs:appinfo></xs:annotation> |
| </xs:enumeration> |
| <xs:enumeration value="AL"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:typesafeEnumMember name="STATE_AL"/> |
| </xs:appinfo></xs:annotation> |
| </xs:enumeration> |
| </xs:restriction> |
| </xs:simpleType> |
| ---- |
| |
| Customized derived code: |
| |
| [source,java,indent=4] |
| ---- |
| public enum USStateAbbr { |
| STATE_AL, STATE_AK; |
| public String value() { return name(); } |
| public static USStateAbbr fromValue(String value) {...} |
| }; |
| ---- |
| |
| *_Example 2:_* typesafeEnum Customization: External Binding Declaration + |
| |
| The following example shows how to customize |
| the above XML schema fragment using an external binding syntax. |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:typesafeEnumClass name="USStateAbbr"> |
| <jaxb:typesafeEnumMember name="STATE_AK" value="AK"/> |
| <jaxb:typesafeEnumMember name="STATE_AL" value="AL"/> |
| </jaxb:typesafeEnumClass> |
| ---- |
| |
| The attribute `value` must be specified for |
| `<typesafeEnumMember>`. This identifies the enumeration member to which |
| `<typesafeEnumMember>` applies. |
| |
| *_Example 3:_* typesafeEnum Customization: Combined Inline Annotation + |
| |
| The following example shows how to customize |
| the above XML schema fragment using inline annotation which does not |
| split the external binding syntax. |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:simpleType name="USState"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:typesafeEnumClass name="USStateAbbr"> |
| <jaxb:typesafeEnumMember name="STATE_AK" value="AK"/> |
| <jaxb:typesafeEnumMember name="STATE_AL" value="AL"/> |
| </jaxb:typesafeEnumClass> |
| </xs:appinfo></xs:annotation> |
| <xs:restriction base="xs:NCName"> |
| <xs:enumeration value="AK"/> |
| <xs:enumeration value="AL"/> |
| </xs:restriction> |
| </xs:simpleType> |
| ---- |
| |
| The attribute value must be specified for |
| `typesafeEnumMember`. This identifies the enumeration member to which |
| the binding declaration applies. |
| |
| === `<javadoc>` Declaration |
| |
| The `<javadoc>` declaration allows the |
| customization of a javadoc that is generated when an XML schema |
| component is bound to its Java representation. |
| |
| This binding declaration is not a global XML |
| element. Hence it can only be used as a local element within the content |
| model of another binding declaration. The binding declaration in which |
| it is used determines the _section_ of the Javadoc that is customized. |
| |
| ==== Javadoc Sections |
| |
| The terminology used for the javadoc sections |
| is derived from “Requirements for Writing Java API Specifications” which |
| can be found online at `https://www.oracle.com/java/technologies/javase/api-specifications.html`. |
| |
| The following sections are defined for the |
| purposes for customization: |
| |
| * package section (corresponds to package specification) |
| * class/interface section (corresponds to class/interface specification) |
| * method section (corresponds to method specification) |
| * field section (corresponds to field specification) |
| |
| ==== Usage |
| |
| Note that the text content of a `<javadoc>` |
| element must use `CDATA` or `\<` to escape embedded HTML tags. |
| |
| [source,xml,indent=4] |
| ---- |
| <javadoc> |
| Contents in <b>Javadoc<\b> format. |
| </javadoc> |
| ---- |
| |
| or |
| |
| [source,xml,indent=4] |
| ---- |
| <javadoc> |
| <<![CDATA[ |
| Contents in <b>Javadoc<\b> format |
| ]]> |
| </javadoc> |
| ---- |
| |
| ==== Javadoc Customization |
| |
| The Javadoc must be generated from the |
| `<javadoc>` element if specified. The Javadoc section depends upon where |
| `<javadoc>` element is used. JAXB providers may generate additional |
| provider specific Javadoc information (for example, contents of the |
| `<xs:documentation>` element). |
| |
| === `<dom>` Declaration |
| |
| The `<dom>` customization binds an XML Schema |
| component to DOM rather than to a strongly typed Java representation. |
| Specifically, JAXB bindings for mixed content and wildcard result in a |
| hybrid mixture of strongly typed Java instances with DOM nodes or |
| java.lang.String, representing text info. These mixed bindings might be |
| more easily processed solely as one form, namely as an XML fragment |
| represented as DOM. This customization also meets a Jakarta XML Web Services |
| databinding requirement from link:jaxb.html#a179[See Disabling |
| Databinding]”. |
| |
| ==== Usage |
| |
| The syntax for the customization is the following: |
| |
| [source,xml,indent=4] |
| ---- |
| <dom [ [type= "w3c" | otherDomRepresentations ] /> |
| ---- |
| |
| You can use the optional type attribute to |
| specify the type of DOM. By default, it is W3C DOM. |
| |
| ==== Customizable Schema Elements |
| |
| This customization can be attached to the |
| following XML Schema components: |
| |
| * Element declaration (`<xs:element>`) |
| * Type definition (`<xs:complexType>` and `<xs:simpleType>`) |
| * Wildcard (`<xs:any>`) |
| * Model groups (`<xs:choice>`, `<xs:all>`, `<xs:sequence>`) |
| * Model group definition (`<xs:group>`) |
| * Particle |
| |
| For all of the above cases, the Java |
| representation of the DOM element is an instance of the Element class |
| for the specified DOM representation. For example, W3C DOM element is |
| bound to `org.w3c.dom.Element`. |
| |
| Special Case Handling of DOM customization on a: |
| |
| * _type definition_ - it is semantically |
| equivalent to placing the dom customization on each element declaration |
| referencing that type definition. |
| * _global element declaration_ - it is |
| semantically equivalent to placing the dom customization on each element |
| declaration referencing, via `@ref` , the global element declaration. |
| The dom customization on the global element declaration does not cause |
| that element to be unmarshalled as DOM when it is the root element of an |
| XML document nor when the element is part of a wildcard content JAXB |
| property. |
| * _mixed content_ - if an XML schema |
| component is annotated with a `dom` customization and that XML schema |
| component can contain character data information due to its parent |
| complex type definition being defined with mixed content, character data |
| information is handled as specified in link:jaxb.html#a1369[See |
| Bind mixed content]. |
| |
| The dom customization allows one to disable |
| databinding and process a part of a document using other technologies |
| that require “raw” XML. |
| |
| ==== Examples |
| |
| *_Wildcard Binding Example_* |
| |
| A wildcard is mapped to a List of |
| `org.w3c.dom.Element`. Each element that matches to the wildcard will |
| be turned into a DOM tree. |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:complexType name=”foo”> |
| <xs:sequence> |
| <xs:any maxOccurs="unbounded" processContents="lax"> |
| <xs:annotation><xs:appinfo> |
| <jaxb:dom/> |
| </xs:appinfo></xs:annotation> |
| </xs:any> |
| </xs:sequence> |
| </xs:complexType> |
| ---- |
| |
| [source,java,indent=4] |
| ---- |
| import org.w3c.dom.Element; |
| public class Foo { |
| @XmlAnyElement(lax=”false”) |
| List<Element> getContent() {...} |
| } |
| ---- |
| |
| *_Wildcard and Mixed Content Binding Example_* |
| |
| If the complexType definition above is |
| defined to have mixed content, due to element *[complexType]* having |
| attribute `@mixed="true"`, the JAXB binding is: |
| |
| [source,java,indent=4] |
| ---- |
| import org.w3c.dom.Element; |
| public class Foo { |
| /* Element content is represented org.w3c.dom.Element. |
| * Character data information is represented as instances of |
| * java.lang.String. */ |
| @XmlMixed |
| @XmlAnyElement(lax=”false”) |
| List<Object> getContent() {...} |
| } |
| ---- |
| |
| === `<inlineBinaryData>` Declaration |
| |
| The `<inlineBinaryData>` customization |
| provides declarative control over the optimization for binary data |
| described in link:jaxb.html#a5109[See Appendix], |
| link:jaxb.html#a5110[See Enhanced Binary Data Handling]. |
| |
| ==== Usage |
| |
| The syntax for the customization is the |
| following: |
| |
| [source,xml,indent=4] |
| ---- |
| <inlineBinaryData/> |
| ---- |
| |
| This customization disables considering the |
| binary data optimization for a schema component containing binary data. |
| |
| This customization can be attached to the |
| following XML Schema components: |
| |
| * Element declaration (`<xs:element>`) with binary data or |
| * Type definition (`<xs:complexType>` and |
| `<xs:simpleType>`) deriving from binary datatype |
| |
| When a schema component that binds to a JAXB |
| property is customized with `<inlineBinaryData>`, its schema-derived JAXB |
| property is annotated with `@XmlInlineBinaryData`. When a type |
| definition is customized with `<inlineBinaryData>`, its schema-derived |
| class is annotated with program annotation `@XmlInlineBinaryData`. |
| |
| === `<factoryMethod>` Declaration |
| |
| The `<factoryMethod>` customization provides |
| declarative control over an element or type factory method name |
| generated in a package’s `ObjectFactory` class introduced in |
| link:jaxb.html#a482[See Java Package]. This customization is |
| useful to resolve name collisions between factory methods in the |
| schema-derived `ObjectFactory` class. |
| |
| ==== Usage |
| |
| The syntax for the customization is the |
| following: |
| |
| [source,xml,indent=4] |
| ---- |
| <factoryMethod name=”BaseForFactoryMethodName”/> |
| ---- |
| |
| The customization value defined is: |
| |
| * `_name_` - each character of name must be a |
| valid part of a Java identifier as determined by |
| `java.lang.Character.isJavaIdentifierPart()`. |
| |
| The name of the factory method is generated |
| by concatenating the following components: |
| |
| * The string constant `create` |
| * ``@name``’s value |
| |
| ===== Usage Constraints |
| |
| The usage constraints on `<factoryMethod>` |
| are specified below. Any constraint violation must result in an invalid |
| customization as specified in link:jaxb.html#a1544[See Invalid |
| Customizations].” The usage constraints are: |
| |
| . `<factoryMethod>` is only allowed to |
| annotate an element declaration or a type definition. |
| |
| Note that this customization does not require |
| a factory method to be generated, it simply provides a factory method |
| name if a factory method is to be generated for the annotated element |
| declaration or type definition. Section 6 and 7 specifies when a factory |
| method is generated for an element declarations or type definitions. |
| |
| === Annotation Restrictions |
| |
| [XSD PART 1] allows an annotation element to |
| be specified for most elements but is ambiguous in some cases. The |
| ambiguity and the way they are addressed are described here. |
| |
| The source of ambiguity is related to the |
| specification of an annotation element for a reference to a schema |
| element using the “ref” attribute. This arises in three cases: |
| |
| * A local attribute references a global |
| attribute declaration using the “ref” attribute. |
| * A local element in a particle references a |
| global element declaration using the “ref” attribute. |
| * A model group in a particle references a |
| model group definition using the “ref” attribute. |
| |
| For example in the following schema fragment |
| (for brevity, the declaration of the global element “Name” and “Address” |
| has been omitted). |
| |
| [source,xml,indent=4] |
| ---- |
| <xs:element name = "Customer"> |
| <xs:complexType> |
| <xs:element ref = "Name"/> |
| <xs:element ref = "Address" /> |
| </xs |