| // |
| // 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. |
| |
| http://java.sun.com./xml/ns/jaxb[The schema |
| for binding declarations is defined in the namespace] |
| _http://java.sun.com/xml/ns/jaxb_ . This specification uses the |
| namespace prefix “ _jaxb_ ” to refer to the namespace of binding |
| declarations. For example, |
| |
| [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="2.0"> |
| ---- |
| |
| * If customizations are specified in an |
| external binding file, then the _jaxb:version_ attribute must be |
| specified in the root element _<jaxb:bindings>_ in the external binding |
| file. Alternately, a local _version_ attribute may be used. Thus the |
| version can be specified either as |
| |
| |
| [source,xml,indent=4] |
| ---- |
| <jaxb:bindings version="2.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. |
| |
| image:images/xmlb-18.png[image] |
| |
| ===== Scoping Inheritance and Overriding For Binding Declarations |
| |
| The different scopes form a taxonomy. The |
| taxonomy defines both the inheritance and overriding semantics of |
| customization values. A customization value defined in one scope is |
| inherited for use in a binding declaration covered by another scope as |
| shown by the following inheritance hierarchy: |
| |
| * a schema element in schema scope inherits a |
| customization value defined in global scope. |
| * a schema element in definition scope |
| inherits a customization value defined in schema or global scope. |
| * a schema element in component scope |
| inherits a customization value defined in definition, schema or global |
| scope. |
| |
| Likewise, a customization value defined in |
| one scope can override a customization value inherited from another |
| scope as shown below: |
| |
| * value in schema scope overrides a value |
| inherited from global scope. |
| * value in definition scope overrides a value |
| inherited from schema scope or global scope. |
| * value in component scope overrides a value |
| inherited from definition, schema or global scope. |
| |
| ==== XML Schema Parsing |
| |
| Chapter 5 specified the bindings using the |
| abstract schema model. Customization, on the other hand, is specified in |
| terms of XML syntax not abstract schema model. The XML Schema |
| specification [XSD PART 1] specifies the parsing of schema elements into |
| abstract schema components. This parsing is assumed for parsing of |
| annotation elements specified here. In some cases, [XSD PART 1] is |
| ambiguous with respect to the specification of annotation elements. |
| link:jaxb.html#a2217[See Annotation Restrictions]” outlines how |
| these are addressed. |
| |
| * |
| |
| === _<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 1.0 customization. |
| * _enableFailFastCheck_ if specified, |
| defines the customization value _enableFailFastCheck._ The value must be |
| one of _"true", "false", "1" or"0"._ If enableFailFastCheck is "true" or |
| "1" and the JAXB implementation supports this optional checking, type |
| constraint checking when setting a property is performed as described in |
| link:jaxb.html#a541[See Properties]". The default value is |
| _"false"_ . |
| * _choiceContentProperty_ if |
| specified,defines the customization value _choiceContentProperty_ . The |
| value must be one of _"true", false", "1" or"0"._ The default value is |
| _"false"_ . |
| * _underscoreBinding_ if specified, defines |
| the customization value _underscoreBinding_ . The value must be one of |
| _"asWordSeparator" or "asCharInWord"._ The default value is |
| _"asWordSeparator"_ . |
| * _enableJavaNamingConventions_ if |
| specified, defines the customization value _enableJavaNamingConventions_ |
| . The value must be one of _"true", false", "1" or"0"._ The default |
| value is _"true"_ . |
| * _typesafeEnumBase_ if specified, defines |
| the customization value _typesafeEnumBase._ The value must be a list of |
| QNames, each of which must resolve to a simple type definition. Only |
| simple type definitions with an enumeration facet and a restriction base |
| type listed in _typesafeEnumBase_ or derived from a type listed in |
| _typesafeEnumBase_ is bound to a _typesafeEnumClass_ by default as |
| specified in link:jaxb.html#a829[See Enum Type]". The default |
| value of _typesafeEnumBase_ is _“xs:string”._ |
| |
| The _typesafeEnumBase_ cannot contain the |
| following simple types and therefore a JAXB implementation is not |
| required to support the binding of the these types to typesafe |
| enumeration class: _"xs:QName", "xs:NOTATIION”, xs:base64Binary", |
| "xs:hexBinary", "xs:date", "xs:time", "xs:dateTime", "xs:duration", |
| "xs:gDay", "xs:gMonth", "xs:gYear", "xs:gMonthDay", "xs:gYearMonth", |
| “xs:IDREF”, “xs:ID”._ If any of them are specified, it must result in an |
| invalid customization as specified in link:jaxb.html#a1544[See |
| Invalid Customizations].” JAXB implementation must be capable of binding |
| any other simple type listed in _typesafeEnumBase_ to a typesafe |
| enumeration class. |
| |
| * _typesafeEnumMemberName_ if specified, |
| defines the customization value _typesafeEnumMemberName._ The value must |
| be one of _skipGeneration_ , _generateError_ or _generateName._ The |
| default value is _skipGeneration_ . See link:jaxb.html#a1633[See |
| @typesafeEnumMemberName]” for details. |
| * _typesafeEnumMaxMembers_ if specified, |
| defines the maximum number of enum facets that a simple type definition |
| can have and be consider to binding to an enum type by default. The |
| attributes type is _xs:int_ and its default value is _256_ . |
| * _generateElementClass_ if specified as |
| true, a schema-derived Element class, as specified in |
| link:jaxb.html#a657[See Java Element Class]”, is generated for |
| each element declaration that has an element factory method generated |
| for it. Its default value is false. |
| * _generateElementProperty_ if specified as |
| true, controls the generation of JAXBElement property. The value must be |
| one of "true", "false", "1", or "0". The default is absence of the |
| value. |
| * _generateValueClass_ |
| if specified as true, a |
| schema-derived Java value class is generated for each complex type |
| definiton.Value class is specified in link:jaxb.html#a521[See |
| Value Class]. If generateValueClass is specified as false, a |
| schema-derived interface and implementation class is generated for each |
| complex type definition as specified in link:jaxb.html#a536[See |
| Java Content Interface]”. The attribute’s default value is true. See |
| examples of this binding in link:jaxb.html#a1617[See |
| generateElementClass and generateValueClass]”. |
| * zero or more _javaType_ binding |
| declarations. Each binding declaration must be specified as described in |
| link:jaxb.html#a1981[See <javaType> Declaration].” |
| * zero or one serializable binding |
| declaration. |
| * _optionalProperty_ |
| controls how a JAXB property with a |
| primitive base type that represents an optional non-nillable |
| element/attribute is bound. If the attribute has the value "wrapper", |
| then the base type of the JAXB property is the wrapper class for the |
| primitive type. A user can indicate that this optional property is not |
| set by calling the setter with “null” value. If the attribute’s value is |
| "primitive", it binds as it did in JAXB 1.0. If the attribute’s value is |
| “isSet”, it binds the optional property using the primitive base type |
| and also the isSet/unset methods are generated for the optional |
| property. The attribute’s default value is “wrapper”. |
| * _mapSimpleTypeDef_ controls whether a JAXB |
| mapped class should be generated for each simple type definition as |
| specified in link:jaxb.html#a803[See Bind to a JAXB mapped |
| class]”. This attribute’s default value is _false_ . This customization |
| eases preserving simple type substituting precisely as described in |
| link:jaxb.html#a1158[See Type Substitution of a Simple Type |
| Definition]”. |
| * _localScoping_ attribute can have the |
| value of either _nested_ or _toplevel_ . This attribute describes the |
| JAXB binding of nested XML schema component to either a _nested_ |
| schema-derived JAXB class or a _toplevel_ schema-derived JAXB class. To |
| avoid naming collisions between nested components, the default value for |
| this attribute is _nested_ . A developer can customize _localScoping_ to |
| _toplevel_ w hen schema components nest too deeply or an application |
| would prefer to not work with nested classes. |
| |
| The semantics of the above customization |
| values, if not specified above, are specified when they are actually |
| used in the binding declarations. |
| |
| For inline annotation, a _<globalBindings>_ |
| is valid only in the annotation element of the _<schema>_ element. There |
| must only be a single instance of a _<globalBindings>_ declaration in |
| the annotation element of the _<schema>_ element. |
| |
| ==== 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. |
| |
| ===== 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: |
| |
| ===== Customized binding to an interface. |
| |
| [source,java,indent=4] |
| ---- |
| public interface USAddress { |
| String getCity(); |
| void setCity(String value); |
| } |
| ---- |
| |
| ===== 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 |
| _http://java.sun.com/j2se/1.4.2/docs/guide/serialization/spec/version.html#wp4602[Java |
| serialization class evolution rules]_ and change the generated |
| _serialVersionUID_ field by changing the *[serializable]* element’s |
| attribute _@uid_ value. |
| |
| ==== @generateElementProperty |
| |
| Some schemas use both minOccurs="0" on |
| element as well as nillable="true", causing the generation of |
| JAXBElement. This customization lets you control this behavior. This |
| attribute may take two values: |
| |
| * _true: + |
| _ Always generate properties to use JAXBElement, unless overriden by |
| _<jaxb:property generateElementProperty=”false”/>_ on individual |
| property. |
| * _false: + |
| _ When generating properties from _<element nillable=”true” |
| minOccurs=”0”/>_ , generate a property not to use JAXBElement, as if the |
| element declaration were just _<element nillable=”true” />_ , unless |
| overriden by _<jaxb:property generateElementProperty=”true”/>_ on |
| individual property. It is an error to specify this customization, when |
| the property is required to be JAXBElement (such as when a property |
| contains multiple elements with different names but of the same type.) |
| |
| === _<schemaBindings>_ Declaration |
| |
| The customization values in |
| _<schemaBindings>_ binding declaration have schema scope. This binding |
| declaration is therefore useful for customizing at a schema level. |
| |
| ==== Usage |
| |
| [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._ |
| * xml |
| |
| 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:* 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 _javax.activation.DataHandler_ and the property is |
| annotated with _@XmlAttachmentRef_ . + |
| + |
| Disabling autoresolving an element/attribute of type _ref:swaRef_ : + |
| When _@attachmentRef_ value is _doNotResolve_ and the property’s base |
| type derives from standard schema type _ref:swaRef,_ the schema-derived |
| JAXB property has the base type _String_ , derived from _xsd:anyURI,_ |
| and _@XmlAttachmentRef_ is not generated for the property. |
| * _<javadoc>_ element, if specified |
| customizes the Javadoc for the property’s getter method. _<javadoc>_ |
| must be specified as described in link:jaxb.html#a2142[See |
| <javadoc> Declaration].” |
| |
| ==== _baseType_ |
| |
| 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’ _marshal_ 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 |
| |
| [width="100%",cols="50%,50%",options="header",] |
| |=== |
| |@XmlElement element |
| |@XmlElement value |
| |type |the java |
| type binding of the element declaration’s _\{type definition}_ |
| |=== |
| |
| Note that the Java class for |
| _@XmlElement.type()_ can differ from the recommended JAXB property’s |
| base type to enable type substitution of java.lang.Object. This binding |
| enables unmarshalling of the Element’s simple content when it is not |
| qualified with an _xsi:type_ as the element’s schema-declared type. |
| _@XmlElement.type()_ acts as the default _xsi:type_ for a JAXB property |
| where the property’s base type was generalized to allow for type |
| substitution of an element declaration with a simple type definition. |
| |
| Specializing the basetype using this |
| customization generates stronger typing than default JAXB binding. For |
| example, an XML element or attribute of _xs:IDREF_ binds to |
| _java.lang.Object_ by default as specified in |
| link:jaxb.html#a1290[See Binding an IDREF component to a Java |
| property]”. If the schema only intends the reference to be to an element |
| that binds to a specific type, the baseType @name schema customization |
| can be used to specialize the binding. |
| |
| ====== 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. |
| |
| * |
| |
| *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].” |
| |
| *Example1: 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]". |
| * |
| |
| === _<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. |
| * |
| |
| ==== 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=4] |
| ---- |
| 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. |
| |
| * |
| |
| *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 http: |
| _//java.sun.com/j2se/javadoc/writingapispecs/index.html._ |
| |
| The following sections are defined for the |
| purposes for customization: |
| |
| * package section (corresponds to package |
| specification) |
| * class/interface section (corresponds to |
| class/interface specification) |
| * method section (corresponds to method |
| specification) |
| * field section (corresponds to field |
| specification) |
| |
| ==== Usage |
| |
| Note that the text content of a _<javadoc>_ |
| element must use _CDATA_ or _<_ 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 JAX-WS 2.0 |
| 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:complexType> |
| </xs:element> |
| ---- |
| |
| XML Schema spec is ambiguous on whether an |
| annotation element can be specified at the reference to the “Name” |
| element. |
| |
| The restrictions on annotation elements has |
| been submitted as an issue to the W3C Schema Working Group along with |
| JAXB technology requirements (which is that annotations should be |
| allowed anywhere). Pending a resolution, the semantics of annotation |
| elements where the XML spec is unclear are assumed as specified as |
| follows. |
| |
| This specification assumes that an annotation |
| element can be specified in each of the three cases outlined above. |
| Furthermore, an annotation element is assumed to be associated with the |
| abstract schema component as follows: |
| |
| * The annotation element on an attribute ref |
| is associated with \{Attribute Use} |
| * The annotation element on a model group ref |
| or an element reference is associated with the \{particle}. |
| |