| // |
| // Copyright (c) 2020, 2022 Contributors to the Eclipse Foundation |
| // |
| |
| [appendix] |
| == Change Log |
| |
| === Changes in Version 4 |
| |
| * fixed cross-references in the specification document |
| * removed deprecated `jakarta.xml.bind.Validator` |
| * removed constraints on using `java.beans.Introspector` |
| * removed deprecated steps in implementation lookup algorithm - dropped search |
| through `jaxb.properties` file, `jakarta.xml.bind.context.factory` and |
| `jakarta.xml.bind.JAXBContext` properties and `/META-INF/services/jakarta.xml.bind.JAXBContext` |
| resource file |
| * dropped requirement on compatibility with JAXB 1.0 |
| |
| === Changes in Version 3 |
| |
| * Changed specification version and license. |
| * Package namespace changed to `jakarta.xml.bind.*`. |
| * Customization schema namespace changed to `https://jakarta.ee/xml/ns/jaxb`, |
| minimal supported version set to `3.0`. |
| * Relaxed requirements tight to JAXB 1.0 |
| * Removed inclusion in Java SE from specification goals |
| |
| === Changes since Maintenance Release 2 |
| |
| * Section 4.2 added note related to Java Platform Module System. |
| * Added section 4.9 Implementation discovery. |
| * Added change logs for MR1 and MR2. |
| |
| === Changes since Maintenance Release 1 |
| |
| Details can be found at: |
| _https://jcp.org/aboutJava/communityprocess/maintenance/jsr222/222mr2.zip_ |
| |
| * Section 8.9.1.1 @XmlElement target extended for type PARAMETER |
| * Section 8.9.3.1 added required annotation element to @XmlElementRef |
| |
| === Changes since Final Draft |
| |
| Details can be found at: |
| https://jcp.org/aboutJava/communityprocess/maintenance/jsr222/222changes.txt |
| |
| * Section 7.1.3 External Binding Declaration @schemaLocation and @node are optional. |
| * Section E.2 3 and 3b updated. |
| * Section 3.5.2.1 constraint violation updated JAXB 2.0 implementation |
| delegate to the validation API in JAXP 1.3. |
| |
| === Changes since Proposed Final Draft |
| |
| * Section 7.6.1.2, nameXmlTransform: Apply |
| customization [ _jaxb:nameXmlTransform]_ addition of prefix and/or |
| suffix after XML to Java name transformation is applied. |
| * Section 6.7.1-2 changed to allow generation |
| of element factory method for abstract element. Change was necessary to |
| support element substitution. The abstract element factory method is |
| generated so it can be annotated with JAXB program annotation that |
| enables element substitution, _@XmlElementDecl.substitutionHeadName_ . |
| * Section 7.7.3.5 fixed the example with |
| <class> customization. Made the corresponding change in Section 6.7.2 so |
| Objectfactory method creates an instance of generated class. |
| * Chapter 8 and appendix B: |
| @XmlJavaTypeAdapter on class, interface or enum type is mutually |
| exclusive with any other annotation. |
| * Chapter 8: added @XmlElement.required() for |
| schema generation |
| * Section 8.7.1.2: clarifications for no-arg |
| static factory method in @XmlType annotation. |
| * Section 8.9.13.2: Disallow use of @XmlList |
| on single valued property. |
| * Section 8.9.8.2, Table 8-30 : |
| @XmlAnyAttribute maps to anyAttribute with a namespace constraint with |
| ##other. |
| * Section 8.9.1.2: If @XmlElement.namespace() |
| is different from that of the target namespace of the enclosing class, |
| require a global element to be generated in the namespace specified in |
| @XmlElement.namespace() to make the generated schema complete. |
| * Section 8.9.15: Allow @XmlMimeType on a |
| parameter. |
| * Section 8.9.16: Allow @XmlAttachmentRef on |
| a parameter. |
| * Chapter 8: removed constraint check that |
| namespace() annotation element must be a valid namespace URI from |
| different annotations. |
| * Chapter 8: Java Persistence and JAXB 2.0 |
| alignment related changes. + |
| constructor requirement: public or protected no-arg constructor + |
| @AccessType renamed to @XmlAccessType. + |
| @AccessorOrder renamed to @XmlAccessOrder. + |
| @XmlTransient is mutually exclusive with other annotations. + |
| @A property or field that is transient or marked with @XmlTransient and |
| specified in @XmlType.propOrder is an error. |
| * Chapter 8: Clarifications for generics - |
| type variables with type bound, bounded wildcards and java.util.Map. |
| * Section 8.9: reworked constraints on the |
| properties to handle different use cases permitted by JavaBean design |
| pattern. |
| * Section 8: Take elementFormDefault into |
| account when determining the namespace for @XmlElement and |
| @XmlElementWrapper annotations. |
| * Section 8: Added missing mapping |
| constraints for @XmlElementWrapper. Also disallow use of @XmlIDREF with |
| @XmlElementWrapper. |
| * Chapter 9, “Compatibility”: clarified |
| schema generator and schema compiler requirements. |
| * Section B.2.5: Added marshalling of null |
| value as xsi:nil or empty element based upon @XmlElement.required and |
| @XmlElement.nillable annotation elements. |
| * Section B.5: Added new section and moved |
| runtime requirements on getters/setters to here. |
| |
| === Changes since Public Review |
| |
| * Update <<Compatibility>> for JAXB 2.0 technology. Additional requirements added |
| for Java Types to XML binding and the running of JAXB 1.0 application in |
| a JAXB 2.0 environment. |
| * Added external event callback mechanism, |
| _Unmarshaller.Listener_ and _Marshaller.Listener_ . |
| * Added new unmarshal method overloading, |
| unmarshal by declaredType, to _Unmarshaller_ and _Binder_ . Enables |
| unmarshalling a root element that corresponds with a local element |
| declaration in schema. |
| * Added <<modifying-schema-derived-code>> describing use of annotation |
| _@javax.annotation.Generated_ to distinguish between generated and |
| user-modified code in schema-derived class. |
| * Element declaration with anonymous complex |
| type definition binds to _@XmlRootElement_ annotated class except for |
| cases in Section 6.7.3.1. |
| * Removed <jaxb:globalBindings |
| nullsInCollection>. The customization <jaxb:property |
| generateElementProperty=”true”> can achieve same desired result. |
| * Added clarification that mapping two or |
| more target namespaces to same java package can result in naming |
| collision that should be detected as an error by schema compiler. |
| * Added <jaxb:factoryMethod> customization to |
| enable the resolution of name collisions between factory methods. |
| * First parameter to any of the overloaded |
| Marshaller.marshal() methods must be a JAXB element; otherwise, method |
| must throw MarshalException. See updated Marshaller javadoc and |
| <<Marshalling>> for details. |
| * Prepend “_”, not “Original”, to a Java |
| class name representing an XML Schema type definition that has been |
| redefined in <<Redefine>>. |
| * Format for class name in _jaxb.index_ file |
| clarified in JAXBConext.newInstance(String) method javadoc. |
| * Clarifications on @dom customization in |
| Section 7.12.. |
| * Chapter 8: Added support for |
| @XmlJavaTypeAdapter at the package level. |
| * Chapter 8: Added new annotation |
| @XmlJavaTypeAdapters as a container for defining multiple |
| @XmlJavaTypeAdapters at the package level. |
| * Chapter 8: Added support for @XmlSchemaType |
| at the package level. |
| * Chapter 8: Added @XmlSchemaTypes as a |
| container annotation for defining multiple @XmlSchemaType annotations at |
| the package level. |
| * Chapter 8: added lists of annotations |
| allowed with each annotation. |
| * Chapter 8: Bug fixes and clarifications |
| related to mapping and mapping constraints. |
| * Chapter 8: Expanded collection types mapped |
| to java.util.Map and java.util.Collection. |
| * Appendix B. Incorporate event call backs |
| into unmarshalling process. |
| * Appendix B: Incorporate into unmarshalling |
| process additional unmarshal methods: Binder.unmarshal(..), unmarshal |
| methods that take a declaredType as a parameter - Binder.unmarshal(..., |
| declaredType) and Unmarshaller.unmarshal(...,declaredType). |
| |
| === Changes since Early Draft 2 |
| |
| * Simple type substitution support added in |
| Section 6.7.4.2. |
| * Updates to enum type binding. (Section |
| 7.5.1, 7.5.5, 7.10, Appendix D.3) |
| * Optimized binary data.(Appendix H) and |
| schema customizations. (Section 7.13 and 7.10.5) |
| * Clarification for _<jaxb:globalBindings |
| underscoreHandling=”asCharInWord”>_ (Appendix D.2) |
| * Added Unmarshal and Marshal Callback Events |
| (Section 4.4.1,4.5.1) |
| * Clarification: xs:ID and xs:IDREF can not |
| bind to an enum type. (Section 6.2.3,7.10.5) |
| * Added schema customization: + |
| <jaxb:globalBinding localScoping=”nested”|”toplevel”> (Section 7.5.1) + |
| <jaxb:inlineBinaryData> (Section 7.13) + |
| <jaxb:property @attachmentRef/> (Section 7.8.1) |
| * Updated Section 6 and 7 with mapping |
| annotations that are generated on schema-derived JAXB |
| classes/properties/fields. |
| * Added jakarta.xml.bind.Binder class to |
| Section 4.8.2. |
| * Runtime generation of schema from JAXB |
| mapping annotations: JAXBContext.generateSchema(). |
| * Chapter 8: added @XmlList: bind |
| property/field to simple list type |
| * Chapter 8: added @XmlAnyElement: bind |
| property/field to xs:any |
| * Chapter 8: added @XmlAnyAttribute - bind |
| property/field to xs:anyAttribute |
| * Chapter 8. added @XmlMixed - for mixed |
| content |
| * Chapter 8, added annotations for |
| attachment/MTOM support: @XmlMimeType, @XmlAttachmentRef |
| * Chapter 8: added @XmlAccessorOrder - to |
| specify default ordering. |
| * Chapter 8: added @XmlSchemaType mainly for |
| use in mapping XMLGregorianCalendar. |
| * Chapter 8: map java.lang.Object to |
| xs:anyType |
| * Chapter 8: added mapping of |
| XMLGregorianCalendar |
| * Chapter 8: added mapping of generics - type |
| variables, wildcardType |
| * Chapter 8: added mapping of binary data |
| types. |
| * Chapter 8: default mappings changed for |
| class, enum type. |
| * Chapter 8: default mapping of propOrder |
| specified. |
| * Chapter 8: mapping of classes - zero arg |
| constructor, factory method. |
| * Chapter 8: added Runtime schema generation |
| requirement. |
| * Chapter 8: Clarified mapping constraints |
| and other bug fixes. |
| * Added Appendix B new: Added Runtime |
| Processing Model to specify the marshalling/unmarshalling for dealing |
| with invalid XML content and schema evolution. |
| * Updated Appendix C to JAXB 2.0 binding |
| schema. |
| |
| === Changes since Early Draft |
| |
| * Updated goals in Introduction. |
| * Update to Section 3 “Architecture” |
| introducing Java to Schema binding. |
| * section on portable annotation-driven |
| architecture. |
| * section on handling of invalid XML content |
| * Binding Framework |
| * Replaced _IXmlElement<T>_ interface with |
| _JAXBElement<T>_ class. (JAXBElement is used for schema to java binding) |
| * _JAXBIntrospector_ introduced _._ |
| * Add flexible (by-name) unmarshal and |
| describe JAXB 1.0 structural unmarshalling. |
| * Moved deprecated on-demand validation, |
| accessible via jakarta.xml.bind.Validator, to Appendix H. |
| * XSD to Java Binding |
| * Bind complex type definition to value class |
| by default. |
| * Schema-derived code is annotated with JAXB |
| java annotations. |
| * Bind XSD simpleType with enum facet to J2SE |
| 5.0 enum type. Change default for jaxb:globalBinding @typeEnumBase from |
| xs:NCName to xs:string. |
| * _ObjectFactory_ factory methods no longer |
| throws _JAXBException_ . |
| * Added customizations + |
| [jaxb:globalBindings] @generateValueClass, @generateElementClass, |
| @serializable, @optionalProperty, @nullInCollection + |
| [jaxb:property] @generateElementProperty |
| * Add binding support for redefine |
| * Simplified following bindings: + |
| - union by binding to String rather than Object. + |
| - Attribute Wildcard binds to portable abstraction of a |
| java.util.Map<QName, String>, not jakarta.xml.bind.AttributeMap. + |
| - bind xsd:anyType to java.lang.Object in JAXB property method |
| signatures and element factory method(support element/type substitution) |
| * Changes required for default and customized |
| binding in order to support flexible unmarshalling described in Section |
| 4.4.3. |
| * Java to XSD Binding |
| * Added @XmlAccessorType for controlling |
| whether fields or properties are mapped by default. |
| * Added @XmlEnum and @XmlEnumValue for |
| mapping of enum types. |
| * Collections has been redesigned to allow |
| them to be used in annotation of schema derived code: |
| |
| - removed @XmlCollectionItem and |
| @XmlCollection |
| |
| - Added annotations parameters to @XmlElement |
| |
| - added @XmlElementRef |
| |
| - added @XmlElements and @XmlElementRefs as |
| containers for collections of @XmlElements or @XmlElementRefs. |
| |
| - added @XmlElementWrapper for wrapping of |
| collections. |
| |
| * Added mapping of anonymous types. |
| * Added mapping of nested classes to schema |
| * Added @XmlRootElement for annotating |
| classes. @XmlElement can now only be used to annotate properties/fields. |
| * Added @XmlElementRef for supporting schema |
| derived code as well as mapping of existing object model to XML |
| representation. javadoc for @XmlElementRef contains an example |
| * Added @XmlElementDecl on object factory |
| methods for supporting mapping of substitution groups for schema -> java |
| binding. |
| * Redesigned Adapter support for mapping of |
| non Java Beans. |
| |
| - new package |
| jakarta.xml.bind.annotation.adapters for adapters. |
| |
| - Added XmlAdapter base abstract class for |
| all adapters. |
| |
| - redesigned and moved XmlJavaTypeAdapter to |
| the package. |
| |
| * Moved default mapping from each section to |
| “Default Mapping” section. |
| * Consistent treatment of defaults |
| “##default” |
| * Removed JAX-RPC 1.1 Alignment. JAX-WS 2.0 |
| is deferring its databinding to JAXB 2.0. |
| |
| === Changes for 2.0 + |
| Early Draft v0.4 |
| |
| * Updated <<Introduction>>. |
| * Added <<Requirements>> |
| * Added <<Java Types To XML>> for Java Source to XML Schema mapping. |
| * XML Schema to schema-derived Java Binding |
| changes |
| * Element handling changes to support element |
| and type substitution in <<Java Element Representation Summary>>, |
| <<Element Declaration>> and <<Element Property>>. |
| * Added <<Attribute Wildcard>> binding |
| * Support binding all wildcard content in |
| <<Bind wildcard schema component>>. |
| * Addition/changes in |
| <<Java Mapping for XML Schema Built-in Types>>. |
| * XML Schema to Java Customization |
| * Added ability to doable databinding for an |
| XML Schema fragment in <<dom-declaration>>. |
| |
| === Changes for 1.0 Final |
| |
| * Added method |
| _jakarta.xml.bind.Marshaller.getNode(Object)_ which returns a DOM view of |
| the Java content tree. See method's javadoc for details. |
| |
| === Changes for Proposed Final |
| |
| * Added <<Compatibility>>. |
| * Section 5.9.2, “General Content Property,” |
| removed value content list since it would not be tractable to support |
| when type and group substitution are supported by JAXB technology. |
| * Added the ability to associate |
| implementation specific property/value pairs to the unmarshal, |
| validation and JAXB instance creation. Changes impact Section 3.4 |
| “Unmarshalling,” Section 3.5 “Validator” and the ObjectFactory |
| description in Section 4.2 “Java Package.” |
| * Section 6.12.10.1, “Bind a Top Level Choice |
| Model Group” was updated to handle Collection properties occurring |
| within a Choice value class. |
| * Section 6.12.11, “Model Group binding |
| algorithm” changed step 4(a) to bind to choice value class rather than |
| choice content property. |
| * <<List Property>> and <<isset-property-modifier>> |
| updated so one can discard set value for a List property via calling |
| unset method. |
| * At end of Section 4, added an UML diagram |
| of the JAXB Java representation of XML content. |
| * Updated default binding handling in |
| <<Model Group Definition>>. Specifically, |
| value class, element classes and enum types are derived from the content |
| model of a model group definition are only bound once, not once per time |
| the group is referenced. |
| * Change <<Bind wildcard schema component>>, to bind to a JAXB property with a |
| basetype of _java.lang.Object,_ not _jakarta.xml.bind.Element._ Strict and |
| lax wildcard validation processing allows for contents constrained only |
| by _xsi:type_ attribute. Current APIs should allow for future support of |
| _xsi:type_ . |
| * Simplify anonymous simple type definition |
| binding to typesafe enum class. Replace incomplete approach to derive a |
| name with the requirement that the @name attribute for element |
| typesafeEnumClass is mandatory when associated with an anonymous simple |
| type definition. |
| * Changed <<Deriving Class Names for Named Model Group Descendants>> |
| to state that all classes and interfaces generated for XML Schema component that |
| directly compose the content model for a model group, that these |
| classes/interfaces should be generated once as top-level interface/class |
| in a package, not in every content model that references the model |
| group. |
| * Current <<globalbindings-declaration>>: |
| * Replaced _modelGroupAsClass_ with |
| _bindingStyle_ . |
| * Specified schema types that cannot be |
| listed in _typesafeEnumBase_ . |
| * <<property-declaration>>: |
| * Clarified the customization of model groups |
| with respect to _choiceContentProperty, elementBinding and |
| modelGroupBinding._ Dropped _choiceContentProperty_ from the |
| _<property>_ declaration. |
| * Added _<baseType>_ element and clarified |
| semantics. |
| * Added support for customization of simple |
| content. |
| * Added customization of simple types at |
| point of reference. |
| * Clarified restrictions and relationships |
| between different customizations. |
| * <<javatype-declaration>>: |
| * Added |
| _jakarta.xml.bind.DatatypeConverterInterface_ interface. |
| * Added _jakarta.xml.bind.DatatypeConverter_ |
| class for use by user specified parse and print methods. |
| * Added |
| _javax.xml.namespace.NamespaceContext_ class for processing of QNames. |
| * Clarified print and parse method |
| requirements. |
| * Added narrowing and widening conversion |
| requirements. |
| * Throughout <<Customizing XML Schema to Java Representation Binding>>, |
| clarified the handling of invalid customizations. |
| |
| === Changes for Public Draft 2 |
| |
| Many changes were prompted by inconsistencies |
| detected within the specification by the reference implementation |
| effort. Change bars indicate what has changed since Public Draft. |
| |
| * Section 4.5.4, “isSetProperty Modifier,” |
| describes the customization required to enable its methods to he |
| generated. |
| * Section 5.7.2, “Binding of an anonymous |
| type definition,” clarifies the generation of value class and typesafe |
| enum classes from an anonymous type definition. |
| * Section 5.2.4, “List” Simple Type |
| Definition and the handling of list members within a union were added |
| since public draft. |
| * Clarification on typesafe enum global |
| customization “generateName” in Section 5.2.3.4, “XML Enumvalue |
| To Java Identifier Mapping.” |
| * Clarification of handling binding of |
| wildcard content in Section 5.9.4. |
| * Chapter6, “Customization,” resolved binding |
| declaration naming inconsistencies between specification and normative |
| binding schema. |
| * removed _enableValidation_ attribute (a |
| duplicate of _enableFailFastCheck)_ from < _globalBindings>_ |
| declaration. |
| * Added default values for < |
| _globalBindings>_ declaration attributes. |
| * Changed _typesafeEnumBase_ to a list of |
| QNames. Clarified the binding to typesafe enum class. |
| * Clarified the usage and support for |
| _implClass_ attribute in _<class>_ declaration. |
| * Clarified the usage and support for |
| _enableFailFastCheck_ in the _<property>_ declaration. |
| * Added _<javadoc>_ to typesafe enum class, |
| member and property declarations. |
| * Mention that embedded HTML tags in |
| _<javadoc>_ declaration must be escaped. |
| * Fixed mistakes in derived Java code |
| throughout document. |
| * Added Section 7. Compatibility and updated |
| Appendix E.2 “Non required XML Schema Concepts” accordingly. |
| |
| === Changes for Public Draft |
| |
| * <<Bind single occurrence choice group to a choice content property>>, |
| replaced overloading of choice content property setter method with a single |
| setter method with a value parameter with the common type of all members |
| of the choice. Since the resolution of overloaded method invocation is |
| performed using compile-time typing, not runtime typing, this |
| overloading was problematic. Same change was made to binding of union |
| types. |
| * Added details on how to construct factory |
| method signature for nested content and element classes. |
| * Section 3.3, default validation handler |
| does not fail on first warning, only on first error or fatal error. |
| * Add ID/IDREF handling in section 5. |
| * Updated name mapping in appendix C. |
| * <<Indexed Property>>, added getIDLenth() to indexed property. |
| * Removed ObjectFactory.setImplementation |
| method from <<Java Package>>. The negative |
| impact on implementation provided to be greater than the benefit it |
| provided the user. |
| * Introduced external binding declaration |
| format. |
| * Introduced a method to introduce extension |
| binding declarations. |
| * Added an appendix section describing JAXB |
| custom bindings that align JAXB binding with JAX-RPC binding from XML to |
| Java representation. |
| * Generate isID() accessor for boolean |
| property. |
| * Section 6, Customization has been |
| substantially rewritten. |
