Original specification document
Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>
diff --git a/spec/src/main/asciidoc/XMLBinding.adoc b/spec/src/main/asciidoc/XMLBinding.adoc
new file mode 100644
index 0000000..ba42da3
--- /dev/null
+++ b/spec/src/main/asciidoc/XMLBinding.adoc
@@ -0,0 +1,17523 @@
+//
+// Copyright (c) 2020 Contributors to the Eclipse Foundation
+//
+
+:sectnums:
+= Jakarta XML Binding Specification, Version 2.1
+
+Copyright (c) 2006, 2019 Oracle and/or its affiliates. All rights reserved.
+
+Oracle and Java are registered trademarks of Oracle and/or its
+affiliates. Other names may be trademarks of their respective owners.
+
+== CHAPTER 1 -
+
+[[a2]]Introduction
+
+XML is, essentially, a platform-independent
+means of structuring information. An XML document is a tree of
+_elements_ . An element may have a set of _attributes_ , in the form of
+key-value pairs, and may contain other elements, text, or a mixture
+thereof. An element may refer to other elements via _identifier_
+attributes or other types via _type_ attributes, thereby allowing
+arbitrary graph structures to be represented.
+
+An XML document need not follow any rules
+beyond the well-formedness criteria laid out in the XML 1.0
+specification. To exchange documents in a meaningful way, however,
+requires that their structure and content be described and constrained
+so that the various parties involved will interpret them correctly and
+consistently. This can be accomplished through the use of a _schema_ . A
+schema contains a set of rules that constrains the structure and content
+of a document’s components, _i.e._ , its elements, attributes, and text.
+A schema also describes, at least informally and often implicitly, the
+intended conceptual meaning of a document’s components. A schema is, in
+other words, a specification of the syntax and semantics of a
+(potentially infinite) set of XML documents. A document is said to be
+_valid_ with respect to a schema if, and only if, it satisfies the
+constraints specified in the schema.
+
+In what language is a schema defined? The XML
+specification itself describes a sublanguage for writing _document-type
+definitions_ , or DTDs. As schemas go, however, DTDs are fairly weak.
+They support the definition of simple constraints on structure and
+content, but provide no real facility for expressing datatypes or
+complex structural relationships. They have also prompted the creation
+of more sophisticated schema languages such as XDR, SOX, RELAX, TREX,
+and, most significantly, the XML Schema language defined by the World
+Wide Web Consortium. The XML Schema language has gained widespread
+acceptance. It is the schema language of choice for many of the XML
+related specifications authored by industry standard working groups.
+Therefore, the design center for this specification is W3C XML Schema
+language.
+
+=== Data binding
+
+Any nontrivial application of XML will, then,
+be based upon one or more schemas and will involve one or more programs
+that create, consume, and manipulate documents whose syntax and
+semantics are governed by those schemas. While it is certainly possible
+to write such programs using the low-level SAX parser API or the
+somewhat higher-level DOM parse-tree API, doing so is not easy. The
+resulting code is also difficult to maintain as the schemas evolve.
+While useful to some, many applications access and manipulate XML
+content within a document; its document structure is less relevant.
+
+It would be much easier to write XML-enabled
+programs if we could simply map the components of an XML document to
+in-memory objects that represent, in an obvious and useful way, the
+document’s intended meaning according to its schema. Of what classes
+should these objects be instances? In some cases there will be an
+obvious mapping from schema components to existing classes, especially
+for common types such as _String_ , _Date_ , _Vector_ , and so forth. In
+general, however, classes specific to the schema being used will be
+required.
+
+Classes specific to a schema may be derived or
+may already exist. In some application scenarios e.g. web services, a
+data model composed using user authored classes may already exist. A
+schema is derived from existing classes. In-memory objects are instances
+of existing classes. In other application scenarios, a data model is
+composed by authoring a schema. In such cases, rather than burden
+developers with having to write classes specific to schema, we can
+generate the classes directly from the schema. In all application
+scenarios, we create a Java object-level _binding_ of the schema.
+
+But even applications manipulating documents
+at conceptual object level, may desire to access or manipulate
+structural information in a document, e.g. element names. Therefore, the
+ability for an application to relate between the XML document
+representation and the Java object-level binding enables the use of XML
+operations over the XML document representation, e.g. Xpath.to bind XML
+content to an object model such as DOM is useful.
+
+An _XML data-binding facility_ therefore
+contains a _schema compiler and a schema generator._ A schema compiler
+can consume a schema and generate schema derived classes specific to the
+schema. A schema generator consumes a set of existing classes and
+generates a schema.
+
+A schema compiler binds components of a
+_source schema_ to schema-derived Java value classes. Each value class
+provides access to the content of the corresponding schema component via
+a set of JavaBeans-style access ( _i.e._ , _get_ and _set_ ) methods.
+_Binding_ declarations provides a capability to customize the binding
+from schema components to Java representation.
+
+A schema generator binds existing classes to
+schema components. Each class containing Java Beans-style access (
+_i.e._ , _get_ and _set_ ) methods is bound to a corresponding schema
+component. Program annotations provide a capability to customize the
+binding from existing classes to derived schema components. Access to
+content is through in-memory representation of existing classes.
+
+Such a facility also provides a _binding
+framework_ , a runtime API that, in conjunction with the derived or
+existing classes, supports three primary operations:
+
+* The _unmarshalling_ of an XML document into
+a tree of interrelated instances of both existing and schema-derived
+classes,
+* The _marshalling_ of such _content trees_
+back into XML documents, and
+* The _binding,_ maintained by a _binder,_
+between an XML document representation and _content tree_ .
+
+The unmarshalling process has the capability
+to check incoming XML documents for validity with respect to the
+schema. +
+
+image:xmlb-2.png[image]
+
+=== Binding XML to Java objects
+
+To sum up: Schemas describe the structure and
+meaning of an XML document, in much the same way that a class describes
+an object in a program. To work with an XML document in a program we
+would like to map its components directly to a set of objects that
+reflect the document’s meaning according to its schema. We can achieve
+this by compiling the schema into a set of derived content classes or by
+compiling a set of existing classes into a schema and marshalling,
+unmarshalling and validating XML documents that follow the schema. Data
+binding thus allows XML-enabled programs to be written at the same
+conceptual level as the documents they manipulate, rather than at the
+more primitive level of parser events or parse trees.
+
+Schema evolution in response to changing
+application requirements, is inevitable. A document therefore might not
+always necessarily follow the complete schema, rather a part of a
+versioned schema. Dealing with schema evolution requires both a
+versioning strategy as well as more flexible marshalling, unmarshalling
+and validation operations.
+
+XML applications, such as workflow
+applications, consist of distributed, cooperative components
+interoperating using XML documents for data exchange. Each distributed
+component may need to access and update only a part of the XML document
+relevant to itself, while retaining the fidelity of the rest of the XML
+document. This is also more robust in the face of schema evolution,
+since the changes in schema may not impact the part of the document
+relevant to the application. The _binder_ enables _partial binding_ of
+the relevant parts of the XML document to a content tree and
+_marshalling_ updates __ back to the original XML document.
+
+=== [[a23]]Goals
+
+The JAXB architecture is designed with the
+goals outlined here in mind.
+
+. [[a25]]Full W3C XML Schema
+support
+
+Support for XML Schema features not required
+to be supported in JAXB 1.0 has been added in this version.
+
+. [[a27]]Binding existing Java
+classes to generated XML schema
+
+This addresses application scenarios where
+design begins with Java classes rather than an XML schema. One such
+example is an application that exports itself as a web service that
+communicates using SOAP and XML as a transport mechanism. The
+marshalling of Java object graph is according to program annotations,
+either explicit or defaulted, on the existing Java classes.
+
+. Meet data binding
+requirements for The Java API for XML Web Services(JAX-WS) 2.0
+
+JAX-WS 2.0 will use the XML data binding
+facility defined by JAXB 2.0. Hence, JAXB 2.0 will meet all data binding
+requirements of JAX-WS 2.0.
+
+. Ease of Development: Leverage J2SE 5.0
+Language Extensions
+
+For ease of development, J2SE 5.0 introduces
+additional language language extensions.The language extensions include
+generics (JSR 14), typesafe enums (JSR201), annotations (JSR 175). Use
+of the language extensions in binding of XML schema components to Java
+representation will result in a better and simpler binding, thus making
+the application development easier.
+
+. _Container Managed Environments_
+
+A container managed environment separates
+development from the deployment phases. This enables choice of
+generation of artifacts such as derived classes or derived schema at
+either development or deployment time.
+
+Any requirements related to the deployment of
+components using JAXB in a container managed environment will be
+addressed.
+
+. _Schema evolution_
+
+Schema evolution is a complex and difficult
+area; it is also an important area. It is particularly important in data
+centric applications such as Web services, where distributed
+applications interact using XML as a data interchange format but are
+designed with different versions of the schema. It is also important in
+document centric applications where schemas are designed for
+extensibility. Strategies to address both application scenarios will be
+investigated and support added accordingly.
+
+. Application specific
+behavior
+
+There should be a way to associate application
+specific behavior with schema derived code in a portable manner.
+
+. _Partial mapping of XML document relevant
+to application_
+
+In some application scenarios, only a subset
+of the data within a XML document may be relevant to the application.
+
+. _Integration with other Java technologies_
+
+Integration or relationship with the following
+Java technologies will be clarified.
+
+. Streaming API For XML (JSR 173) (StAX)
+. Relationship to XML related specifications
+
+XML related specifications will be surveyed to
+determine their relationship to JAXB.
+
+. Portability of JAXB mapped classes
+
+An architecture that provides for a fully
+portable JAXB 2.0 applications written to the J2SE platform will be
+defined. JAXB 2.0 is targeted for inclusion in a future version of J2SE.
+Application portability is a key requirement for inclusion in J2SE.
+
+JAXB annotated classes must be source level
+and binary compatible with any other JAXB 2.0 binding framework
+implementation. As in JAXB 1.0, schema-derived interfaces/implementation
+classes are only required to be source code compatible with other JAXB
+implementations of the same version.
+
+. _Preserving equivalence - Round tripping
+(Java to XML to Java)_
+
+Transforming a Java content tree to XML
+content and back to Java content again should result in an equivalent
+Java content tree before and after the transformation.
+
+. _Preserving equivalence - Round tripping
+(XML to Java to XML)_
+
+While JAXB 1.0 specification did not require
+the preservation of the XML information set when round tripping from XML
+document to Java representation and back to XML document again, it did
+not forbid the preservation either. The same applies to this version of
+the specification.
+
+. Unmarshalling invalid XML content
+
+Unmarshalling of invalid content was out of
+scope for JAXB 1.0. Simple binding rules and unmarshalling mechanisms
+that specify the handling of invalid content will be defined.
+
+. _Ease of Use - Manipulation of XML
+documents in Java_
+
+Lower the barrier to entry to manipulating XML
+documents within Java programs. Programmers should be able to access and
+modify XML documents via a Java binding of the data, not via SAX or DOM.
+It should be possible for a developer who knows little about XML to
+compile a simple schema and immediately start making use of the classes
+that are produced. +
+ +
+Rather than not supporting XML Schema extensibility concepts that can
+not be statically bound, such as unconstrained wildcard content, these
+concepts should be exposed directly as DOM or some other XML infoset
+preserving representation since there is no other satisfactory static
+Java binding representation for them.
+
+. Customization
+
+Applications sometimes require customization
+to meet their data binding requirements. Customization support will
+include:
+
+* XML to Java:
+
+A standard way to customize the binding of
+existing XML schema components to Java representation will be provided.
+JAXB 1.0 provided customization mechanisms for the subset of XML Schema
+components supported in JAXB 1.0. Customization support will be extended
+to additional XML Schema features to be supported in this version of the
+specification link:jaxb.html#a25[See Full W3C XML Schema
+support].
+
+* Java to XML:
+
+A standard way to customize the binding of
+existing Java classes to XML schema will be added,
+link:jaxb.html#a27[See Binding existing Java classes to
+generated XML schema].
+
+. Schema derived classes should be natural
+
+Insofar as possible, derived classes should
+observe standard Java API design guidelines and naming conventions. If
+new conventions are required then they should mesh well with existing
+conventions. A developer should not be astonished when trying to use a
+derived class.
+
+. Schema derived classes should match
+conceptual level of source schema
+
+It should be straightforward to examine any
+content-bearing component of the source schema and identify the
+corresponding Java language construct in the derived classes.
+
+=== Non-Goals
+
+* Support for Java versions prior to J2SE 5.0
+
+JAXB 2.0 relies on many of the Java language
+features added in J2SE 5.0. It is not a goal to support JAXB 2.0 on Java
+versions prior to J2SE 5.0.
+
+* _Explicit support for specifying the
+binding of DTD to a Java representation_ .
+
+While it was desired to explicitly support
+binding DTD to a Java representation, it became impractical to describe
+both XML Schema binding and DTD binding. The existence of several
+conversion tools that automate the conversion of a DTD to XML Schema
+allows DTD users to be able to take advantage of JAXB technology by
+converting their existing DTDs to XML Schema.
+
+* XML Schema Extensions
+
+XML Schema specification allows the annotation
+of schemas and schema components with appinfo elements. JAXB 1.0
+specifies the use of appinfo elements to customize the generated code.
+For this version of the specification, use of appinfo elements for
+customization of generated code continues to be in scope. However, use
+of appinfo element to introduce validation constraints beyond those
+already described in XML Schema 1.0 specification is out of scope.
+
+* Support for SOAP Encoding
+
+SOAP Encoding is out of scope. Use of the SOAP
+encoding is essentially deprecated in the web services community, e.g.
+the WS-I Basic Profile[WSIBP] excludes SOAP encoding.
+
+* Support for validation on demand by schema
+derived classes
+
+While working with a content tree
+corresponding to an XML document it is often necessary to validate the
+tree against the constraints in the source schema. JAXB 1.0 made it
+possible to do this at any time, without the user having to first
+marshal the tree into XML. However it is a non goal in JAXB 2.0, which
+leverages the JAXP 1.3 validation API.
+
+* _Object graph traversal_
+
+Portable mechanisms to traverse a graph of
+JavaBean objects will not be addressed in JAXB 2.0.
+
+* _Mapping any existing Java classes to any
+existing XML schema_
+
+The JAXB annotation mechanism is not
+sophisticated enough to enable mapping an arbitrary class to all XML
+schema concepts.
+
+=== Conventions
+
+Within normative prose in this specification,
+the words _should_ and _must_ are defined as follows:
+
+* _should +
+_ Conforming implementations are permitted to but need not behave as
+described.
+* _must +
+_ Conforming implementations are required to behave as described;
+otherwise they are in error.
+
+Throughout the document, the XML namespace
+prefix _xs:_ and _xsd:_ refers to schema components in W3C XML Schema
+namespace as specified in [XSD Part 1] and [XSD Part 2]. The XML
+namespace prefix _xsi:_ refers to the XML instance namespace defined in
+[XSD Part 1]. Additionally, the XML namespace prefix _jaxb_ : refers to
+the JAXB namespace, _http://java.sun.com/xml/ns/jaxb_ . The XML
+namespace prefix _ref:_ refers to the namespace
+_http://ws-i.org/profiles/basic/1.1/xsd_ as defined in [WSIBP] and
+[WSIAP].
+
+All examples in the specification are for
+illustrative purposes to assist in understanding concepts and are
+non-normative. If an example conflicts with the normative prose, the
+normative prose always takes precedence over the example.
+
+=== Expert Group Members
+
+The following people have contributed to this
+specification.
+
+[width="100%",cols="50%,50%",]
+|===
+|Chavdar Baikov |SAP
+AG
+
+|David Bau |
+
+|Arnaud Blandin |
+
+|Stephen Brodsky
+|IBM
+
+|Russell Butek |IBM
+
+|Jongjin Choi |TMAX
+
+|Glen Daniels |Sonic
+Software
+
+|Blaise Doughan
+|Oracle
+
+|Christopher Fry
+|BEA Systems
+
+|Stanley Guan
+|Oracle
+
+|Mette Hedin |
+
+|Kohsuke Kawaguchi
+|Sun Microsystems, Inc.
+
+|Sravan Kumar
+|Pramati Technologies
+
+|Changshin Lee |Tmax
+Soft, Inc.
+
+|Anjana Manian
+|Oracle
+
+|Ed Merks |IBM
+
+|Steve Perry
+|Fidelity Information Services
+
+|Radu Preotiuc-Pietro
+|BEA
+
+|Srividya Rajagopalan
+|Nokia Corporation
+
+|Yann Raoul |
+
+|Bjarne Rasmussen
+|Novell, Inc.
+
+|Adinarayana Sakala
+|IONA Technologies PLC
+
+|Dennis M. Sosnoski
+|
+
+|Keith Visco |
+
+|Stefan Wachter |
+
+|Umit Yalcinalp |
+
+|Scott Ziegler |BEA
+Systems
+
+|Zulfi Umrani
+|Novell, Inc.
+|===
+
+=== Acknowledgements
+
+This document is a derivative work of concepts
+and an initial draft initially led by Mark Reinhold of Sun Microsystems.
+Our thanks to all who were involved in pioneering that initial effort.
+The feedback from the Java User community on the initial JAXB technology
+prototype greatly assisted in identifying requirements and directions.
+
+The data binding experiences of the expert
+group members have been instrumental in identifying the proper blend of
+the countless data binding techniques that we have considered in the
+course of writing this specification. We thank them for their
+contributions and their review feedback.
+
+Kohsuke Kawaguchi and Ryan Shoemaker have
+directly contributed content to the specification and wrote the
+companion javadoc. The following JAXB technology team members have been
+invaluable in keeping the specification effort on the right track: Tom
+Amiro, Leonid Arbouzov, Evgueni Astigueevitch, Jennifer Ball, Carla
+Carlson, Patrick Curran, Scott Fordin, Omar Fung, Peter Kacandes, Dmitry
+Khukhro, Tom Kincaid, K. Ari Krupnikov, Ramesh Mandava, Bhakti Mehta, Ed
+Mooney, Ilya Neverov, Oleg Oleinik, Brian Ogata, Vivek Pandey, Cecilia
+Peltier, Evgueni Rouban and Leslie Schwenk. The following people, all
+from Sun Microsystems, have provided valuable input to this effort:
+Roberto Chinnici, Chris Ferris, Mark Hapner, Eve Maler, Farrukh Najmi,
+Eduardo Pelegri-llopart, Bill Shannon and Rahul Sharma.
+
+The JAXB TCK software team would like to
+acknowledge that the NIST XML Schema test suite [NIST] has greatly
+assisted the conformance testing of this specification.
+
+=== Acknowledgements for JAXB 2.0
+
+Version 2.0 of this specification was created
+under the Java Community Process as JSR-222. This specification is
+shaped by valuable input from expert group members, people with Sun, and
+Java User community feedback based on their experience with JAXB 1.0.
+
+
+
+The data binding experience of the expert
+group has been very instrumental in identifying usage scenarios
+(including those from web services),design and evaluation of different
+databinding techniques. We thank them for their contributions and review
+feedback.
+
+
+
+The following people, all from Sun
+Microsystems, have provided valuable input. The experiences of the
+reference implementation team, led by Kohsuke Kawaguchi, has been
+influential in identifying data binding solutions. Kohsuke Kawaguchi and
+Ryan Shoemaker have directly contributed content to the companion
+javadoc.Addtional feedback was provided by the following JAXB technology
+team members: Bhakti Mehta, Ed Mooney, Ryan Shoemaker, Karthikeyan
+Krishnamurthy, Tom Amiro, Leonid Arbouzov, Leonid Kuskov, Dmitry
+Fazunenko, Dmitry Lepekhin, Alexey Vishentsev, Omar Fung, and Anita
+Jindal. Valuable input was provided by the following people from Sun:
+Eduardo Pelegri-Llopart, Graham Hamilton, Mark Hapner, Bill Shannon.
+
+
+
+The JAXB TCK software team would like to
+acknowledge that the NIST XML Schema test suite [NIST] has greatly
+assisted the conformance testing of this specification.
+
+
+
+== CHAPTER 2 -
+
+[[a151]]Requirements
+
+This chapter specifies the scope and
+requirements for this version of the specification.
+
+=== XML Schema to Java
+
+=== W3C XML Schema support
+
+The mapping of the following XML Schema
+components must be specified.
+
+* type substitution ( _@xsi:type_ )
+* element substitution group ( _<xs:element
+@substitutionGroup_ >)
+* wildcard support( _xs:any_ and
+_xs:anyAttribute_ )
+* identity constraints ( _xs:key_ ,
+_xs:keyref_ and _xs:unique_ )
+* redefinition of declaration ( _xs:redefine_
+)
+* NOTATION
+
+For binding builtin XML Schema datatypes which
+do not map naturally to Java datatypes, Java datatypes specified by JAXP
+1.3 (JSR 206) must be used.
+
+=== Default Bindings
+
+There must be a detailed, unambiguous
+description of the default mapping of schema components to Java
+representations in order to satisfy the portability goal.
+
+=== [[a165]]Customized Binding Schema
+
+A binding schema language and its formats must
+be specified. There must be a means to describe the binding without
+requiring modification to the original schema. Additionally, the same
+XML Schema language must be used for the two different mechanisms for
+expressing a binding declaration.
+
+=== Overriding default binding behavior
+
+Given the diverse styles that can be used to
+design a schema, it is daunting to identify a single ideal default
+binding solution. For situations where several equally good binding
+alternatives exist, the specification will describe the alternatives and
+select one to be the default (see link:jaxb.html#a165[See
+Customized Binding Schema]).
+
+The binding schema must provide a means to
+specify an alternative binding for the scope of an entire schema. This
+mechanism ensures that if the default binding is not sufficient, it can
+easily be overridden in a portable manner.
+
+=== JAX-WS 2.0
+
+=== Backward Compatibility
+
+Mapping of XML Schema to schema derived Java
+classes as specified in versions of JAX-RPC 1.x either by default or by
+customization is out of scope.
+
+=== Binding XML Schema to schema derived classes
+
+A binding of XML Schema constructs to schema
+derived classes must be specified. JAXB 1.0 specified the binding of XML
+Schema constructs to schema derived interfaces. However, JAX-RPC 1.x
+specified the binding of XML Schema constructs to schema derived
+classes, not interfaces. To provide continued support for JAX-RPC 1.x
+programming model, a customization to enable the binding of XML Schema
+constructs to schema derived classes will be added.
+
+=== Accessing MIME content stored as an attachment
+
+The W3C XMLP MTOM/XOP document and WS-I AP
+1.0[WSIAP] both provide mechanisms for embedding references to SOAP
+attachments in SOAP messages. It is desirable to bind these to suitable
+Java types (e.g. Image or DataHandler) rather than just provide URI
+refs.
+
+=== Serializable
+
+A customization must be specified to enable
+schema derived classes to implement the _java.io.Serializable_
+interface. This capability enables the schema derived instance to be
+passed as EJB method parameter and to any other API that requires
+Serializable instances.
+
+=== [[a179]]Disabling Databinding
+
+A customization to disable databinding must be
+specified. When databinding is disabled, an XML Schema component is
+bound to an XML fragment representation rather than a strongly typed
+datatype determined by mapping rules. Binding to XML fragment allows the
+use of alternative binding technologies for example to perform XML
+operations.
+
+=== Java to XML Schema
+
+=== [[a182]]Default Mapping
+
+A default mapping Java constructs to XML
+Schema must be specified. The default mapping may be overridden by
+customizations described in link:jaxb.html#a184[See Customized
+Mapping]”.
+
+=== [[a184]]Customized Mapping
+
+A customization mechanism to override default
+mapping of Java constructs to XML Schema constructs must be specified.
+Since XML Schema provides a much richer feature set than Java language
+for defining data models, the scope of customizations will be restricted
+to enable mapping to commonly used XML Schema constructs.
+
+Support for the following mechanism must be
+specified:
+
+* customization mechanism using the JSR175
+program annotation facility.
+
+=== JAX-WS 2.0
+
+=== WSDL <types>
+
+The WSDL <types> is generated using Java
+constructs to XML Schema mapping. The latter should therefore define
+customizations that enable mapping to XML Schema constructs commonly
+used in web services, subject to the requirements in
+link:jaxb.html#a184[See Customized Mapping]” and
+link:jaxb.html#a182[See Default Mapping]”.
+
+=== Backward Compatibility
+
+Mapping of existing Java constructs to XML
+Schema constructs as specified in JAX-RPC versions 1.x, either by
+default or through customization, is out of scope.
+
+=== Binding Framework
+
+=== Disabling schema validation
+
+The specification will provide an ability _to
+disable schema validation for unmarshal and marshal operations._
+
+There exist a significant number of scenarios
+that do not require validation and/or can not afford the overhead of
+schema validation. An application must be allowed to disable schema
+validation checking during unmarshal and marshal operations. The goal of
+this requirement is to provide the same flexibility and functionality
+that a SAX or DOM parser allows for.
+
+
+
+== CHAPTER 3 -
+
+Architecture
+
+=== Introduction
+
+This chapter describes the architectural
+components, comprising the XML-databinding facility, that realize the
+goals outlined in link:jaxb.html#a23[See Goals]”. The scope of
+this version of specification covers many additional goals beyond those
+in JAXB 1.0. As a result, JAXB 1.0 architecture has been revised
+significantly.
+
+=== Overview
+
+The XML data-binding facility consists of the
+following architectural components:
+
+* schema compiler: A schema compiler binds a
+source schema to a set of schema derived program elements. The binding
+is described by an XML-based language, binding language.
+* schema generator: A schema generator maps a
+set of existing program elements to a derived schema. The mapping is
+described by program annotations.
+* binding runtime framework that provides two
+primary operations for accessing, manipulating and validating XML
+content using either schema derived or existing program elements:
+* _Unmarshalling_ is the process of reading
+an XML document and constructing a tree of content objects. Each content
+object is an instance of either a schema derived or an existing program
+element mapped by the schema generator and corresponds to an instance in
+the XML document. Thus, the content tree reflects the document’s
+content. Validation can optionally be enabled as part of the
+unmarshalling process. _Validation_ is the process of verifying that an
+xml document meets all the constraints expressed in the schema.
+* _Marshalling_ is the inverse of
+unmarshalling, i.e., it is the process of traversing a content tree and
+writing an XML document that reflects the tree’s content. Validation can
+optionally be enabled as part of the marshalling process.
+
+As used in this specification, the term
+_schema_ includes the W3C XML Schema as defined in the XML Schema 1.0
+Recommendation[XSD Part 1][XSD Part 2]. link:jaxb.html#a210[See
+Non-Normative JAXB 2.0 Architecture diagram] illustrates relationships
+between concepts introduced in this section.
+
+image:xmlb-3.png[image]
+
+=== [[a210]]Non-Normative JAXB 2.0 Architecture diagram
+
+JAXB-annotated classes are common to both
+binding schemes. They are either generated by a schema compiler or the
+result of a programmer adding JAXB annotations to existing Java classes.
+The universal unmarshal/marshal process is driven by the JAXB
+annotations on the portable JAXB-annotated classes.
+
+Note that the binding declarations object in
+the above diagram is logical. Binding declarations can either be inlined
+within the schema or they can appear in an external binding file that is
+associated with the source schema.
+
+=== JAXB 1.0 style binding of schema to interface/implementation classes.
+
+image:xmlb-4.png[image]
+
+Note that the application accesses only the
+schema-derived interfaces, factory methods and _javax.xml.bind_ APIs
+directly. This convention is necessary to enable switching between JAXB
+implementations.
+
+=== Java Representation
+
+The content tree contains instances of bound
+types, types that bind and provide access to XML content. Each bound
+type corresponds to one or more schema components. As much as possible,
+for type safety and ease of use, a bound type that constrains the values
+to match the schema constraints of the schema components. The different
+bound types, which may be either schema derived or authored by a user,
+are described below.
+
+Value Class A coarse grained schema
+component, such as a complex type definition, is bound to a Value class.
+The Java class hierarchy is used to preserve XML Schema’s “derived by
+extension” type definition hierarchy. JAXB-annotated classes are
+portable and in comparison to schema derived interfaces/implementation
+classes, result in a smaller number of classes.
+
+Property A fine-grained schema component,
+such as an attribute declaration or an element declaration with a simple
+type, is bound directly to a _property_ or a field within a value class.
+
+A property is _realized_ in a value class by
+a set of JavaBeans-style _access methods_ . These methods include the
+usual _get_ and _set_ methods for retrieving and modifying a property’s
+value; they also provide for the deletion and, if appropriate, the
+re-initialization of a property’s value.
+
+Properties are also used for references from
+one content instance to another. If an instance of a schema component
+_X_ can occur within, or be referenced from, an instance of some other
+component _Y_ then the content class derived from _Y_ will define a
+property that can contain instances of _X_ .
+
+Binding a fine-grained schema component to a
+field is useful when a bound type does not follow the JavaBeans
+patterns. It makes it possible to map such types to a schema without the
+need to refactor them.
+
+Interface JAXB 1.0 bound schema components
+(XML content) to schema derived content interfaces and implementation
+classes. The interface/implementation classes tightly couple the schema
+derived implementation classes to the JAXB implementation runtime
+framework and are thus not portable. The binding of schema components to
+schema derived interfaces continues to be supported in JAXB 2.0.
+
+*
+
+Enum type J2SE 5.0 platform introduced
+linguistic support for type safe enumeration types. Enum type are used
+to represent values of schema types with enumeration values.
+
+Collection type Collections are used to
+represent content models. Where possible, for type safety, parametric
+lists are used for homogeneous collections. For e.g. a repeating element
+in content model is bound to a parametric list.
+
+DOM node In some cases, binding XML content
+to a DOM or DOM like representation rather than a collection of types is
+more natural to a programmer. One example is an open content model that
+allows elements whose types are not statically constrained by the
+schema.
+
+Content tree can be created by unmarshalling
+of an XML document or by programmatic construction. Each bound type in
+the content tree is created as follows:
+
+* schema derived implementation classes that
+implement schema derived interfaces can be created using factory methods
+generated by the schema compiler.
+* schema derived value classes can be created
+using a constructor or a factory method generated by the schema
+compiler.
+* existing types, authored by users, are
+required to provide a no arg constructor. The no arg constructor is used
+by an unmarshaller during unmarshalling to create an instance of the
+type.
+
+=== Binding Declarations
+
+A particular binding of a given source schema
+is defined by a set of _binding declarations_ . Binding declarations are
+written in a _binding language_ , which is itself an application of XML.
+A binding declaration can occur within the annotation _appinfo_ of each
+XML Schema component. Alternatively, binding declarations can occur in
+an auxiliary file. Each binding declaration within the auxiliary file is
+associated to a schema component in the source schema. It was necessary
+to support binding declarations external to the source schema in order
+to allow for customization of an XML Schemas that one prefers not to
+modify. The schema compiler hence actually requires two inputs, a source
+schema and a set of binding declarations.
+
+Binding declarations enable one to override
+default binding rules, thereby allowing for user customization of the
+schema-derived value class. Additionally, binding declarations allow for
+further refinements to be introduced into the binding to Java
+representation that could not be derived from the schema alone.
+
+The binding declarations need not define
+every last detail of a binding. The schema compiler assumes _default
+binding declarations_ for those components of the source schema that are
+not mentioned explicitly by binding declarations. Default declarations
+both reduce the verbosity of the customization and make it more robust
+to the evolution of the source schema. The defaulting rules are
+sufficiently powerful that in many cases a usable binding can be
+produced with no binding declarations at all. By defining a standardized
+format for the binding declarations, it is envisioned that tools will be
+built to greatly aid the process of customizing the binding from schema
+components to a Java representation.
+
+=== Mapping Annotations
+
+A mapping annotation defines the mapping of a
+program element to one or more schema components. A mapping annotation
+typically contains one or more annotation members to allow customized
+binding. An annotation member can be required or optional. A mapping
+annotation can be collocated with the program element in the source. The
+schema generator hence actually requires both inputs: a set of classes
+and a set of mapping annotations.
+
+Defaults make it easy to use the mapping
+annotations. In the absence of a mapping annotation on a program
+element, the schema generator assumes, when required by a mapping rule,
+a default mapping annotation. This, together with an appropriate choice
+of default values for optional annotation members makes it possible to
+produce in many cases a usable mapping with minimal mapping annotations.
+Thus mapping annotations provide a powerful yet easy to use
+customization mechanism
+
+=== Annotations
+
+Many of the architectural components are
+driven by program annotations defined by this specification, mapping
+annotations.
+
+Java to Schema Mapping Mapping annotations
+provide meta data that describe or customize the mapping of existing
+classes to a derived schema.
+
+Portable Value Classes Mapping annotations
+provide information for unmarshalling and marshalling of an XML instance
+into a content tree representing the XML content without the need for a
+schema at run time. Thus schema derived code annotated with mapping
+annotations are portable i.e. they are capable of being marshalled and
+unmarshalled by a universal marshaller and unmarshaller written by a
+JAXB vendor implementation.
+
+Adding application specific behavior and data
+Applications can choose to add either behavior or data to schema derived
+code. link:jaxb.html#a1459[See Modifying Schema-Derived Code]”
+specifies how the mapping annotation, _@javax.annotation.Generated_ ,
+should be used by a developer to denote developer added/modified code
+from schema-derived code. This information can be utilized by tools to
+preserve application specific code across regenerations of schema
+derived code.
+
+=== Binding Framework
+
+The binding framework has been revised
+significantly since JAXB 1.0. Significant changes include:
+
+* support for unmarshalling of invalid XML
+content.
+* deprecation of on-demand validation.
+* unmarshal/marshal time validation deferring
+to JAXP 1.3 validation.
+
+=== Unmarshalling
+
+=== Invalid XML Content
+
+Rationale: Invalid XML content can arise for
+many reasons:
+
+* When the cost of validation needs to be
+avoided.
+* When the schema for the XML has evolved.
+* When the XML is from a non-schema-aware
+processor.
+* When the schema is not authoritative.
+
+Support for invalid XML content required
+changes to JAXB 1.0 schema to java binding rules as well as the
+introduction of a flexible unmarshalling mode. These changes are
+described in link:jaxb.html#a379[See Unmarshalling Modes]”.
+
+=== [[a256]]Validation
+
+The constraints expressed in a schema fall
+into three general categories:
+
+* A _type_ constraint imposes requirements
+upon the values that may be provided by constraint facets in simple type
+definitions.
+* A _local structural_ constraint imposes
+requirements upon every instance of a given element type, e.g., that
+required attributes are given values and that a complex element’s
+content matches its content specification.
+* A _global structural_ constraint imposes
+requirements upon an entire document, e.g., that _ID_ values are unique
+and that for every _IDREF_ attribute value there exists an element with
+the corresponding _ID_ attribute value.
+
+A _document_ is valid if, and only if, all of
+the constraints expressed in its schema are satisfied. The manner in
+which constraints are enforced in a set of derived classes has a
+significant impact upon the usability of those classes. All constraints
+could, in principle, be checked only during unmarshalling. This approach
+would, however, yield classes that violate the _fail-fast_ principle of
+API design: errors should, if feasible, be reported as soon as they are
+detected. In the context of schema-derived classes, this principle
+ensures that violations of schema constraints are signalled when they
+occur rather than later on when they may be more difficult to diagnose.
+
+With this principle in mind we see that schema
+constraints can, in general, be enforced in three ways:
+
+* _Static_ enforcement leverages the type
+system of the Java programming language to ensure that a schema
+constraint is checked at application’s compilation time. Type
+constraints are often good candidates for static enforcement. If an
+attribute is constrained by a schema to have a boolean value, e.g., then
+the access methods for that attribute’s property can simply accept and
+return values of type _boolean_ .
+* _Simple dynamic_ enforcement performs a
+trivial run-time check and throws an appropriate exception upon failure.
+Type constraints that do not easily map directly to Java classes or
+primitive types are best enforced in this way. If an attribute is
+constrained to have an integer value between zero and 100, e.g., then
+the corresponding property’s access methods can accept and return _int_
+values and its mutation method can throw a run-time exception if its
+argument is out of range.
+* _Complex dynamic_ enforcement performs a
+potentially costly run-time check, usually involving more than one
+content object, and throwing an appropriate exception upon failure.
+Local structural constraints are usually enforced in this way: the
+structure of a complex element’s content, e.g., can in general only be
+checked by examining the types of its children and ensuring that they
+match the schema’s content model for that element. Global structural
+constraints must be enforced in this way: the uniqueness of _ID_ values,
+e.g., can only be checked by examining the entire content tree.
+
+It is straightforward to implement both static
+and simple dynamic checks so as to satisfy the fail-fast principle.
+Constraints that require complex dynamic checks could, in theory, also
+be implemented so as to fail as soon as possible. The resulting classes
+would be rather clumsy to use, however, because it is often convenient
+to violate structural constraints on a temporary basis while
+constructing or manipulating a content tree.
+
+Consider, e.g., a complex type definition
+whose content specification is very complex. Suppose that an instance of
+the corresponding value class is to be modified, and that the only way
+to achieve the desired result involves a sequence of changes during
+which the content specification would be violated. If the content
+instance were to check continuously that its content is valid, then the
+only way to modify the content would be to copy it, modify the copy, and
+then install the new copy in place of the old content. It would be much
+more convenient to be able to modify the content in place.
+
+A similar analysis applies to most other sorts
+of structural constraints, and especially to global structural
+constraints. Schema-derived classes have the ability to enable or
+disable a mode that verifies type constraints. JAXB mapped classes can
+optionally be validated at unmarshal and marshal time.
+
+=== Validation Re architecture
+
+The detection of complex schema constraint
+violations has been redesigned to have a JAXB 2.0 implementation to
+delegate to the validation API in JAXP 1.3. JAXP 1.3 defines a standard
+validation API ( _javax.xml.validation_ package) for validating XML
+content against constraints within a schema. Furthermore, JAXP 1.3 has
+been incorporated into J2SE 5.0 platform. Any JAXB 2.0 implementation
+that takes advantage of the validation API will result in a smaller
+footprint.
+
+=== Unmarshal validation
+
+When the unmarshalling process incorporates
+validation and it successfully completes without any validation errors,
+both the input document and the resulting content tree are guaranteed to
+be valid.
+
+However, always requiring validation during
+unmarshalling proves to be too rigid and restrictive a requirement.
+Since existing XML parsers allow schema validation to be disabled, there
+exist a significant number of XML processing uses that disable schema
+validation to improve processing speed and/or to be able to process
+documents containing invalid or incomplete content. To enable the JAXB
+architecture to be used in these processing scenarios, the binding
+framework makes validation optional.
+
+=== Marshal Validation
+
+Validation may also be optionally performed
+at marshal time. This is new for JAXB 2.0. Validation of object graph
+while marshalling is useful in web services where the marshalled output
+must conform to schema constraints specified in a WSDL document. This
+could provide a valuable debugging aid for dealing with any
+interoperability problems
+
+=== Handling Validation Failures
+
+While it would be possible to notify a JAXB
+application that a validation error has occurred by throwing a
+_JAXBException_ when the error is detected, this means of communicating
+a validation error results in only one failure at a time being handled.
+Potentially, the validation operation would have to be called as many
+times as there are validation errors. Both in terms of validation
+processing and for the application’s benefit, it is better to detect as
+many errors and warnings as possible during a single validation pass. To
+allow for multiple validation errors to be processed in one pass, each
+validation error is mapped to a validation error event. A validation
+error event relates the validation error or warning encountered to the
+location of the text or object(s) involved with the error. The stream of
+potential validation error events can be communicated to the application
+either through a registered validation event handler at the time the
+validation error is encountered, or via a collection of validation
+failure events that the application can request after the operation has
+completed.
+
+Unmarshalling and marshalling are the two
+operations that can result in multiple validation failures. The same
+mechanism is used to handle both failure scenarios. See
+link:jaxb.html#a326[See General Validation Processing] for
+further details.
+
+=== An example
+
+Throughout this specification we will refer
+and build upon the familiar schema from [XSD Part 0], which describes a
+purchase order, as a running example to illustrate various binding
+concepts as they are defined. Note that all schema name attributes with
+values in _this font_ are bound by JAXB technology to either a Java
+interface or JavaBean-like property. Please note that the derived Java
+code in the example only approximates the default binding of the
+schema-to-Java representation.
+
+<xsd:schema
+xmlns:xsd="http://www.w3.org/2001/XMLSchema"> +
+<xsd:element name= _"purchaseOrder"_ type= _"PurchaseOrderType"_ /> +
+<xsd:element name= _"comment"_ type=" _xsd:string"_ /> +
+<xsd:complexType name= _"PurchaseOrderType"_ > +
+<xsd:sequence> +
+<xsd:element name= _"shipTo"_ type="USAddress"/> +
+<xsd:element name= _"billTo"_ type="USAddress"/> +
+<xsd:element ref= _"comment"_ minOccurs="0"/> +
+<xsd:element name= _"items"_ type="Items"/> +
+</xsd:sequence> +
+<xsd:attribute name= _"orderDate"_ type="xsd:date"/> +
+</xsd:complexType> +
+ +
+<xsd:complexType name= _"USAddress"_ > +
+<xsd:sequence> +
+<xsd:element name= _"name"_ type="xsd:string"/> +
+<xsd:element name= _"street"_ type="xsd:string"/> +
+<xsd:element name= _"city"_ type="xsd:string"/> +
+<xsd:element name= _"state"_ __ type="xsd:string"/> +
+<xsd:element name= _"zip"_ type="xsd:decimal"/> +
+</xsd:sequence> +
+<xsd:attribute name= _"country"_ type="xsd:NMTOKEN" fixed="US"/> +
+</xsd:complexType> +
+ +
+<xsd:complexType name= _"Items"_ > +
+<xsd:sequence> +
+<xsd:element name= _"item"_ minOccurs="1" maxOccurs="unbounded"> +
+<xsd:complexType>
+
+ <xsd:sequence> +
+<xsd:element name= _"productName"_ type="xsd:string"/> +
+<xsd:element name= _"quantity"_ > +
+<xsd:simpleType> +
+<xsd:restriction base="xsd:positiveInteger"> +
+<xsd:maxExclusive value="100"/> +
+</xsd:restriction> +
+</xsd:simpleType> +
+</xsd:element> +
+<xsd:element name= _"USPrice"_ type="xsd:decimal"/> +
+<xsd:element ref= _"comment"_ minOccurs="0"/> +
+<xsd:element name= _"shipDate"_ type="xsd:date" minOccurs="0"/> +
+</xsd:sequence> +
+<xsd:attribute name= _"partNum"_ type="SKU" use="required"/> +
+</xsd:complexType> +
+</xsd:element> +
+</xsd:sequence> +
+</xsd:complexType>
+
+ +
+<!-- Stock Keeping Unit, a code for identifying products --> +
+<xsd:simpleType name= _"SKU"_ > +
+<xsd:restriction base="xsd:string"> +
+<xsd:pattern value="\d\{3}-[A-Z]\{2}"/> +
+</xsd:restriction> +
+</xsd:simpleType> +
+</xsd:schema>
+
+Binding of purchase order schema to a Java
+representationlink:#a5352[1]:
+
+import
+javax.xml.datatype.XMLGregorianCalendar; import java.util.List; +
+public class _PurchaseOrderType_ _\{ +
+_ USAddress get _ShipTo_ ()\{...} void set _ShipTo_ (USAddress)\{...} +
+USAddress get _BillTo_ ()\{...} void set _BillTo_ (USAddress)\{...} +
+/** Optional to set Comment property. */ +
+String get _Comment_ ()\{...} void set _Comment_ (String)\{...} +
+Items get _Items_ ()\{...} void set _Items_ (Items)\{...} +
+XMLGregorianCalendar get _OrderDate_ () void set _OrderDate_
+(XMLGregorianCalendar) +
+}; +
+public class _USAddress \{ +
+_ String get _Name_ ()\{...} void set _Name_ (String)\{...} +
+String get _Street_ ()\{...} void set _Street_ (String) \{...} +
+String get _City_ ()\{...} void set _City_ (String)\{...} +
+String get _State_ ()\{...} void set _State_ (String)\{...} +
+int get _Zip_ ()\{...} void set _Zip_ (int)\{...} +
+static final String _COUNTRY_ =”USA”;link:#a5353[2] +
+}; +
+public class _Items_ \{ +
+public class _ItemType_ \{ +
+String get _ProductName_ _()\{...}_ void set _ProductName_
+(String)\{...} +
+/** Type constraint on Quantity setter value
+0..99.link:#a5354[3]*/ +
+int get _Quantity_ ()\{...} void set _Quantity_ (int)\{...} +
+float get _USPrice_ ()\{...} void set _USPrice_ (float)\{...} +
+/** Optional to set Comment property. */ +
+String get _Comment_ ()\{...} void set _Comment_ (String)\{...} +
+XMLGregorianCalendar get _ShipDate_ (); void set _ShipDate_
+(XMLGregorianCalendar); +
+/** Type constraint on PartNum setter value "\d\{3}-[A-Z]\{2}".2*/ +
+String get _PartNum_ ()\{...} void set _PartNum_ (String)\{...} +
+}; +
+ +
+/** Local structural constraint 1 or more instances of _Items.ItemType_
+.*/ +
+List<Items.ItemType> get _Item_ ()\{...} +
+} +
+public class ObjectFactory \{ +
+// type factories +
+Object newInstance(Class javaInterface)\{...} +
+PurchaseOrderType create _PurchaseOrderType_ ()\{...} +
+USAddress create _USAddress_ ()\{...} +
+Items create _Items_ ()\{...} +
+Items.ItemType create _ItemsItemType_ ()\{...} +
+// element factories +
+JAXBElement<PurchaseOrderType> create _PurchaseOrder_
+(PurchaseOrderType)\{...} +
+JAXBElement<String> create _Comment_ (String value)\{...} +
+}
+
+The purchase order schema does not describe
+any global structural constraints.
+
+The coming chapters will identify how these
+XML Schema concepts were bound to a Java representation. Just as in [XSD
+Part 0], additions will be made to the schema example to illustrate the
+binding concepts being discussed.
+
+== CHAPTER 4 -
+
+The Binding Framework
+
+ The _binding framework_ defines APIs to
+access unmarshalling, validation and marshalling operations for
+manipulating XML data and JAXB mapped objects. The framework is
+presented here in overview; its full specification is available in the
+javadoc for the package _javax.xml.bind_ .
+
+The binding framework resides in two main
+packages. The _javax.xml.bind_ package defines abstract classes and
+interfaces that are used directly with content classes. The
+_javax.xml.bindlink:#a5355[4]_ package defines the
+_Unmarshaller, Marshaller_ and _Binder_ classes, which are auxiliary
+objects for providing their respective operations.
+
+The _JAXBContext_ class is the entry point
+for a Java application into the JAXB framework. A _JAXBContext_ instance
+manages the binding relationship between XML element names to Java value
+class for a JAXB implementation to be used by the unmarshal, marshal and
+binder operations. The _javax.xml.bind.helper_ package provides partial
+default implementations for some of the _javax.xml.bind_ interfaces.
+Implementations of JAXB technology can extend these classes and
+implement the abstract methods. These APIs are not intended to be used
+directly by applications using the JAXB architecture. A third package,
+_javax.xml.bind.util_ , contains utility classes that may be used
+directly by client applications.
+
+The binding framework defines a hierarchy of
+exception and validation event classes for use when
+marshalling/unmarshalling errors occur, when constraints are violated,
+and when other types of errors are detected.
+
+
+
+=== Annotation-driven Binding Framework
+
+The portability of JAXB annotated classes is
+achieved via an annotation-driven architecture. The program annotations,
+specified in Section 8, describe the mapping from the Java program
+elements to XML Schema components. This information is used by the
+binding framework to unmarshal and marshal to XML content into/from
+JAXB-annotated classes. All JAXB schema binding compilers must be able
+to generate portable schema-derived JAXB-annotated classes following the
+constraints described in Section 6, link:jaxb.html#a694[See
+Binding XML Schema to Java
+Representations]link:jaxb.html#a694[See Binding XML Schema to
+Java Representations]link:jaxb.html#a694[See Binding XML Schema
+to Java Representations]”. All binding runtime frameworks are required
+to be able to marshal and unmarshal portable JAXB-annotated classes
+generated by other JAXB 2.0 schema binding compiler.
+
+It is not possible to require portability of
+the interface/implementation binding from JAXB 1.0. For backwards
+compatibility with existing implementations, that binding remains a
+tight coupling between the schema-derived implementation classes and the
+JAXB implementation’s runtime framework. Users are required to
+regenerate the schema-derived implementation classes when changing JAXB
+implementations.
+
+=== [[a298]]JAXBContext
+
+The _JAXBContext_ class provides the client’s
+entry point to the JAXB API. It provides an abstraction for managing the
+XML/Java binding information necessary to implement the JAXB binding
+framework operations: unmarshal and marshal.
+
+The following summarizes the _JAXBContext_
+class defined in package _javax.xml.bind_ .
+
+public abstract class JAXBContext \{
+
+ static final String JAXB_CONTEXT_FACTORY;
+
+ static JAXBContext newInstance(String
+contextPath);
+
+ static JAXBContext newInstance(String
+contextPath, +
+ClassLoader contextPathCL);
+
+ static JAXBContext newInstance(Class...
+classesToBeBound); +
+abstract Unmarshaller createUnmarshaller();
+
+ abstract Marshaller createMarshaller();
+
+ abstract JAXBIntrospector
+createJAXBIntrospector(); +
+<T> Binder<T> createBinder(Class<T> domType); +
+Binder<org.w3c.dom.Node> createBinder(); +
+void generateSchema(SchemaOutputResolver);
+
+}
+
+To avoid the overhead involved in creating a
+JAXBContext instance, a JAXB application is encouraged to reuse a
+JAXBContext instance. An implementation of abstract class JAXBContext is
+required to be thread-safe, thus, multiple threads in an application can
+share the same JAXBContext instance.
+
+A client application configures a JAXBContext
+using the _JAXBContext.newInstance(String contextPath)_ factory method.
+
+JAXBContext jc =
+
+ JAXBContext.newInstance(
+“com.acme.foo:com.acme.bar” );
+
+The above example initializes a _JAXBContext_
+with the schema-derived Java packages _com.acme.foo_ and _com.acme.bar_
+. A _jaxb.index_ resource file, described in more detail in the javadoc,
+list the non-schema-derived classes, namely the java to schema binding,
+in a package to register with _JAXBContext_ . Additionally, in each
+specified directory, if an optional resource filelink:#a5356[5]
+containing package level mapping annotations exist, it is incorporated
+into the JAXBContext representation.
+
+An alternative mechanism that could be more
+convenient when binding Java classes to Schema is to initialize
+JAXBContext by passing JAXB-annotated class objects.
+
+ JAXBContext jc = +
+JAXBContext.newInstance( POElement.class );
+
+The classes specified as parameters to
+_newInstance_ and all classes that are directly/indirectly referenced
+statically from the specified classes are included into the returned
+_JAXBContext_ instance. For each directory of all the classes imported
+into JAXBContext, if an optional resource file2 containing package level
+mapping annotations exists, it is incorporated into the JAXBContext
+representation.
+
+For example, given the following Java
+classes:
+
+@XmlRootElementlink:#a5357[6] class
+Foo \{ Bar b;} +
+@XmlType class Bar \{ FooBar fb;}
+
+@XmlType class FooBar \{ int x; }
+
+The invocation of
+_JAXBContext.newInstance(Foo.class)_ registers Foo and the statically
+referenced classes, _Bar_ and _FooBar_ .
+
+Note that the jaxb.index resource file is not
+necessary when an application uses
+_JAXBContenxt.newInstances(Class...classesToBeBound)_ .
+
+
+
+For either scenario, the values of these
+parameters initialize the JAXBContext object so that it is capable of
+managing the JAXB mapped classes.
+
+See the javadoc for _JAXBContext_ for more
+details on using this class.
+
+*
+
+=== [[a326]]General Validation Processing
+
+Three identifiable forms of validation exist
+within the JAXB architecture include:
+
+* _Unmarshal-time validation_
+
+This form of validation enables a client
+application to be notified of validation errors and warnings detected
+while unmarshalling XML data into a Java content tree and is completely
+orthogonal to the other types of validation. See
+javax.xml.bind.Unmarshaller javadoc for a description on how to enable
+this feature.
+
+* _On-demand validation_
+
+This mode of validation is deprecated in JAXB
+2.0. See link:jaxb.html#a5094[See On-demand Validation]” for the
+JAXB 1.0 description of this functionality.
+
+* _Fail-fast validation_
+
+This form of validation enables a client
+application to receive immediate feedback about a modification to the
+Java content tree that violates a type constraint of a Java property. An
+unchecked exception is thrown if the value provided to a set method is
+invalid based on the constraint facets specified for the basetype of the
+property. This style of validation is optional in this version of the
+specification. Of the JAXB implementations that do support this type of
+validation, it is customization-time decision to enable or disable
+fail-fast validation when setting a property. __
+
+Unmarshal-time uses an event-driven mechanism
+to enable multiple validation errors and warnings to be processed during
+a single operation invocation. If the validation or unmarshal operation
+terminates with an exception upon encountering the first validation
+warning or error, subsequent validation errors and warnings would not be
+discovered until the first reported error is corrected. Thus, the
+validation event notification mechanism provides the application a more
+powerful means to evaluate validation warnings and errors as they occur
+and gives the application the ability to determine when a validation
+warning or error should abort the current operation (such as a value
+outside of the legal value space). Thus, an application could allow
+locally constrained validation problems to not terminate validation
+processing.
+
+If the client application does not set an
+event handler on a _Unmarshaller_ or _Marshaller_ instance prior to
+invoking the _unmarshal_ or _marshal_ operations, then a default event
+handler will receive notification of any errors or fatal errors
+encountered and stop processing the XML data. In other words, the
+default event handler will fail on the first error that is encountered.
+
+There are three ways to handle validation
+events encountered during the unmarshal and marshal operations:
+
+* _Rely on the default validation event
+handler +
+_ The default handler will fail on the first error or fatal error
+encountered.
+* _Implement and register a custom
+validation event handler +
+_ Client applications that require sophisticated event processing can
+implement the _ValidationEventHandler_ interface and register it with
+the Validator or Unmarshaller instance respectively.
+* _Request an error/warning event list after
+the operation completes +
+_ By registering the _ValidationEventCollector_ helper, a specialized
+event handler, with the _setEventHandler_ method, the _ValidationEvent_
+objects created during the unmarshal and marshal operations are
+collected. The client application can then request the list after the
+operation completes.
+
+Validation events are handled differently
+depending on how the client application is configured to process them as
+described previously. However, there are certain cases where a JAXB
+implementation may need to indicate that it is no longer able to
+reliably detect and report errors. In these cases, the JAXB
+implementation will set the severity of the _ValidationEvent_ to
+_FATAL_ERROR_ to indicate that the _unmarshal_ or _validate_ operation
+should be terminated. The default event handler and
+_ValidationEventCollector_ helper class must terminate processing after
+being notified of a fatal error. Client applications that supply their
+own _ValidationEventHandler_ should also terminate processing after
+being notified of a fatal error. If not, unexpected behavior may occur.
+
+=== Unmarshalling
+
+The _Unmarshaller_ class governs the process
+of deserializing XML data into a Java content tree, capable of
+validating the XML data as it is unmarshalled. It provides the basic
+unmarshalling methods:
+
+public interface Unmarshaller \{
+
+ ValidationEventHandler _getEventHandler_ ()
+
+ void _setEventHandler_
+(ValidationEventHandler)
+
+
+
+ java.lang.Object
+_getProperty_ (java.lang.String name) +
+void _setProperty_ (java.lang.String name,
+java.lang.Object value) +
+ +
+void setSchema(javax.xml.validation.Schema schema)
+
+ javax.xml.validation.Schema getSchema()
+
+
+
+ UnmarshallerHandler _getUnmarshallerHandler_
+() +
+ +
+void setListener(Unmarshaller.Listener); +
+Unmarshaller.Listener getListener();
+
+ +
+java.lang.Object _unmarshal_ (java.io.File)
+
+ java.lang.Object _unmarshal_ (java.net.URL)
+
+ java.lang.Object
+unmarshal(java.io.InputStream) +
+java.lang.Object _unmarshal_ (org.xml.sax.InputSource) +
+java.lang.Object _unmarshal_ (org.w3c.dom.Node) +
+ +
+ java.lang.Object
+_unmarshal_ (javax.xml.transform.Source) +
+java.lang.Object _unmarshal_ (javax.xml.stream.XMLStreamReader) +
+java.lang.Object _unmarshal_ (javax.xml.stream.XMLEventReader) +
+ +
+<T> JAXBElement<T> _unmarshal_ (org.w3c.dom.Node, +
+Class<T> declaredType) +
+<T> JAXBElement<T> _unmarshal_ (javax.xml.transform.Source, +
+Class<T> declaredType) +
+<T> JAXBElement<T> _unmarshal_ (javax.xml.stream.XMLStreamReader, +
+Class<T> declaredType) +
+<T> JAXBElement<T> _unmarshal_ (javax.xml.stream.XMLEventReader, +
+Class<T> declaredType) +
+}
+
+The _JAXBContext_ class contains a factory to
+create an _Unmarshaller_ instance. The _JAXBContext_ instance manages
+the XML/Java binding data that is used by unmarshalling. If the
+_JAXBContext_ object that was used to create an _Unmarshaller_ does not
+know how to unmarshal the XML content from a specified input source,
+then the _unmarshal_ operation will abort immediately by throwing an
+_UnmarshalException_ . There are six convenience methods for
+unmarshalling from various input sources.
+
+An application can enable or disable
+unmarshal-time validation by enabling JAXP 1.3 validation via the
+_setSchema(javax.xml.validation.Schema)_ method. The application has the
+option to customize validation error handling by overriding the default
+event handler using the _setEventHandler(ValidationEventHandler)._ The
+default event handler aborts the unmarshalling process when the first
+validation error event is encountered. Validation processing options are
+presented in more detail in link:jaxb.html#a326[See General
+Validation Processing].”
+
+An application has the ability to specify a
+SAX 2.0 parser to be used by the _unmarshal_ operation using the
+_unmarshal(javax.xml.transform.Source)_ method. Even though the JAXB
+provider’s default parser is not required to be SAX2.0 compliant, all
+providers are required to allow an application to specify their own
+SAX2.0 parser. Some providers may require the application to specify the
+SAX2.0 parser at binding compile time. See the method javadoc
+_unmarshal(Source)_ for more detail on how an application can specify
+its own SAX 2.0 parser.
+
+The _getProperty_ / _setProperty_ methods
+introduce a mechanism to associate implementation specific
+property/value pairs to the unmarshalling process. At this time there
+are no standard JAXB properties specified for the unmarshalling process.
+
+=== Unmarshal event callbacks
+
+The _Unmarshaller_ provides two styles of
+callback mechanisms that allow application specific processing during
+key points in the unmarshalling process. In 'class-defined' event
+callbacks, application specific code placed in JAXB mapped classes is
+triggered during unmarshalling. External listeners allow for centralized
+processing of unmarshal events in one callback method rather than by
+type event callbacks. The 'class defined' and external listener event
+callback methods are independent of each other, both can be called for
+one event. The invocation ordering when both listener callback methods
+exist is defined in _javax.xml.bind.Unmarshaller.Listener_ javadoc.
+
+Event callback methods should be written with
+following considerations. Each event callback invocation contributes to
+the overall unmarshal time. An event callback method throwing an
+exception terminates the current unmarshal process.
+
+=== Class-defined
+
+A JAXB mapped class can optionally implement
+the following unmarshal event callback methods.
+
+ _private void
+beforeUnmarshal(Unmarshaller, +
+Object parent)_
+
+This method is called immediately after the
+object is created and before the unmarshalling of this object begins.The
+callback provides an opportunity to initialize JavaBean properties prior
+to unmarshalling.
+
+ _Parameters:_
+
+ unmarshaller - unmarshal context.
+
+parent - points to the parent object to which
+this object will be set. Parent is null when this object is the root
+object.
+
+ _private void afterUnmarshal(Unmarshaller, +
+Object parent)_
+
+This method is called after all the
+properties (except IDREF) are unmarshalled for this object, but before
+this object is set to the parent object.
+
+ _Parameters:_
+
+ unmarshaller - unmarshal context.
+
+parent - points to the parent object to which
+this object will be set. Parent is null when this object is the root
+object.
+
+These callback methods allow an object to
+perform additional processing at certain key point in the unmarshalling
+operation.
+
+=== External Listener
+
+The external listener callback mechanism
+enables the registration of a _Unmarshaller.Listener_ instance with an
+_Unmarshaller.setListener(Unmarshaller.Listener)_ . The external
+listener receives all callback events, allowing for more centralized
+processing than per class defined callback methods. The external
+listener receives events when unmarshalling to a JAXB element or to JAXB
+mapped class.
+
+=== [[a379]]Unmarshalling Modes
+
+There exist numerous use cases requiring the
+ability to unmarshal invalid XML content. A flexible unmarshalling mode
+is described in this version of the specification to enable predictable
+unmarshalling of invalid content. The previous unmarshalling mode
+implied by JAXB 1.0 specification is named structural unmarshalling.
+This unmarshalling mode was well defined for the unmarshalling of valid
+XML content and allowed an implementation to handle invalid XML content
+in anyway that it choose to.
+
+Both of these modes have benefits and
+drawbacks based on an application’s xml processing needs.
+
+=== Structural Unmarshalling
+
+Some of the XML Schema to Java bindings in
+JAXB 1.0 implied that an unmarshaller had to maintain a state machine,
+implying that the order of elements had to match up exactly as described
+by the schema or unmarshaller would work unpredictably. When this
+unmarshalling process detects a structural inconsistency that it is
+unable to recover from, it should abort the unmarshal process by
+throwing Un _marshalException_ .
+
+For example, it was valid for a JAXB
+implementation to rigidly give up unmarshalling an invalid XML document
+once it came across an unexpected element/attribute or missed a required
+element or attribute. This mode appeals to users who prefer to be
+notified that an xml document is deviating from the schema.
+
+XML Schema to Java binding for interfaces and
+implementation classes, link:jaxb.html#a536[See Java Content
+Interface], can implement either structural unmarshalling or flexible
+unmarshalling.
+
+=== [[a386]]Flexible Unmarshalling
+
+To address the rigidness of structural
+unmarshalling, flexible unmarshalling mode is specified to enable
+greater predictability in unmarshalling invalid XML content. It
+unmarshals xml content by element name, rather than strictly on the
+position of the element within a content model. This allows this mode to
+handle the following cases:
+
+* elements being out of order in a content
+model
+* recovering from required
+elements/attributes missing from an xml document
+* ignoring unexpected elements/attributes in
+an xml document
+
+In order to enable this mode, the following
+JAXB 1.0 customized bindings that required state-driven unmarshalling
+have been removed from this specification.
+
+* Binding a model group or model group
+definition to a Java class. +
+Since there is no XML infoset information denoting these schema
+components, a model group can only be inferred by applying positional
+schema constraints to a valid XML document, tracking position within a
+valid content model.
+* Multiple occurrences of an element name in
+a content model can no longer be mapped to different JAXB properties.
+Instead the entire content model is bound to a general content model.
+
+The removal of these bindings greatly assists
+the error recovery for structural unmarshalling mode.
+
+Flexible unmarshalling appeals to those who
+need to be able to perform best match unmarshalling of invalid xml
+documents.
+
+The flexible unmarshalling process is
+annotation driven. This process is specified in
+link:jaxb.html#a3855[See Appendix],
+link:jaxb.html#a3856[See Runtime Processing]”. Flexible
+unmarshalling is required for JAXB annotated classes.
+
+=== [[a397]]Marshalling
+
+The _Marshaller_ class is responsible for
+governing the process of serializing a Java content tree into XML data.
+It provides the basic marshalling methods:
+
+interface Marshaller \{
+
+ static final string JAXB_ENCODING;
+
+ static final string JAXB_FORMATTED_OUTPUT;
+
+ static final string JAXB_SCHEMA_LOCATION;
+
+ static final string
+JAXB_NO_NAMESPACE_SCHEMA_LOCATION; +
+static final string JAXB_FRAGMENT;
+
+
+
+ <PROTENTIALLY MORE PROPERTIES...> +
+ +
+java.lang.Object
+_getProperty_ (java.lang.String name) +
+void _setProperty_
+(java.lang.String name, java.lang.Object value) +
+
+ void _setEventHandler_
+(ValidationEventHandler handler)
+
+ ValidationEventHandler _getEventHandler_ ()
+
+
+
+ void setSchema(javax.xml.validation.Schema
+schema)
+
+ javax.xml.validation.Schema getSchema()
+
+ +
+void setListener(Unmarshaller.Listener) +
+Unmarshaller.Listener getListener()
+
+ +
+void _marshal_ (java.lang.Object e, java.io.Writer writer) +
+void _marshal_ (java.lang.Object e, java.io.OutputStream os) +
+void _marshal_ (java.lang.Object e, org.xml.sax.ContentHandler)
+
+
+void _marshal_ (java.lang.Object e, javax.xml.transform.Result)
+
+
+void _marshal_ (java.lang.Object e, org.w3c.dom.Node) +
+void _marshal_ (java.lang.Object e, +
+javax.xml.stream.XMLStreamWriter writer)
+
+
+
+ org.w3c.dom.Node _getNode_ (java.lang.Object
+contentTree) +
+}
+
+The _JAXBContext_ class contains a factory to
+create a _Marshaller_ instance. Convenience method overloading of the
+_marshal()_ method allow for marshalling a content tree to common Java
+output targets and to common XML output targets of a stream of SAX2
+events or a DOM parse tree.
+
+Although each of the marshal methods accepts
+a _java.lang.Object_ as its first parameter, JAXB implementations are
+not required to be able to marshal any arbitrary _java.lang.Object_ . If
+the first parameter is not a JAXB element, as determined by
+_JAXBIntrospector.isElement()_ method, the marshal operation must throw
+a _MarshalException_ . There exist two mechanisms to enable marshalling
+an instance that is not a JAXB element. One method is to wrap the
+instance as the value of a _javax.xml.bind.JAXBElement_ instance, and
+pass the wrapper element as the first parameter to a _marshal_ method.
+For java to schema binding, it is also possible to simply annotate the
+instance's class with the appropriate program annotation,
+_@XmlElementRoot_ , specified in Section 8.
+
+The marshalling process can optionally be
+configured to validate the content tree being marshalled. An application
+can enable or disable marshal-time validation by enabling JAXP 1.3
+validation via the _setSchema(javax.xml.validation.Schema)_ method. The
+application has the option to customize validation error handling by
+overriding the default event handler using the
+_setEventHandler(ValidationEventHandler)._ The default event handler
+aborts the marshalling process when the first validation error event is
+encountered. Validation processing options are presented in more detail
+in link:jaxb.html#a326[See General Validation Processing].”
+
+There is no requirement that the Java content
+tree be valid with respect to its original schema in order to marshal it
+back into XML data. If the marshalling process detects a structural
+inconsistency during its process that it is unable to recover from, it
+should abort the marshal process by throwing _MarshalException_ . The
+marshalling process of a JAXB-annotated class is annotation driven. This
+process is specified in link:jaxb.html#a3855[See Appendix],
+link:jaxb.html#a3856[See Runtime Processing]”.
+
+=== Marshal event callbacks
+
+The Marshaller provides two styles of
+callback mechanisms that allow application specific processing during
+key points in the marshalling process. In class-defined event callbacks,
+application specific code placed in JAXB mapped classes is triggered
+during marshalling. External listeners allow for centralized processing
+of marshal events in one callback method rather than by type event
+callbacks. The invocation ordering when both listener callback methods
+exist is defined in _javax.xml.bind.Marshaller.Listener_ javadoc.
+
+Event callback methods should be written with
+following considerations. Each event callback invocation contributes to
+the overall marshal time. An event callback method throwing an exception
+terminates the current marshal process.
+
+=== Class-defined
+
+A JAXB mapped class can optionally implement
+the following marshal event callback methods.
+
+ _private void beforeMarshal(Marshaller)_
+
+This method is called before the marshalling
+of this object starts.
+
+ _Parameters:_
+
+ marshaller - marshal context.
+
+ _private void afterMarshal(Marshaller)_
+
+This method is called after the marshalling
+of this object (and all its descendants) has finished.
+
+ _Parameters:_
+
+ marshaller - marshal context.
+
+These callback methods allow the
+customization of an JAXB mapped class to perform additional processing
+at certain key point in the marshalling operation. The 'class defined'
+and external listener event callback methods are independent of each
+other, both can be called for one event.
+
+An event callback method throwing an
+exception terminates the current marshal process.
+
+=== External Listener
+
+The external listener callback mechanism
+enables the registration of a _Marshaller_ . _Listener_ instance with a
+_Marshaller.setListener(Marshaller.Listener)_ . The external listener
+receives all callback events, allowing for more centralized processing
+than per class-defined callback methods.
+
+=== Marshalling Properties
+
+The following subsection highlights
+properties that can be used to control the marshalling process. These
+properties must be set prior to the start of a marshalling operation:
+the behavior is undefined if these attributes are altered in the middle
+of a marshalling operation. The following standard properties have been
+identified:
+
+* _jaxb.encoding_ _:_ output character
+encoding. If the property is not specified, it defaults to "UTF-8".
+* _jaxb.formatted.output_ : +
+_true_ - human readable indented xml data +
+_false_ - unformatted xml data +
+If the property is not specified, it defaults to _false_ .
+* _jaxb.schemaLocation +
+_ This property allows the client application to specify an
+_xsi:schemaLocation_ attribute in the generated XML data.
+* _jaxb.noNamespaceSchemaLocation +
+_ This property allows the client application to specify an
+_xsi:noNamespaceSchemaLocation_ attribute in the generated XML data.
+* _jaxb.fragment +
+_ Its value must be a java.lang.Boolean. This property determines
+whether or not document level events will be generated by the
+Marshaller. If this property is not defined, it defaults to _false_ .
+
+=== JAXBIntrospector
+
+This class provides access to key XML mapping
+information of a JAXB mapped instance.
+
+public abstract class JAXBIntrospector \{ +
+public boolean isElement(Object jaxbObj); +
+public QName getElementName(Object jaxbElement);
+
+ public static Object getValue(Object
+jaxbElement);
+
+}
+
+The JAXB 2.0 architecture has two uniquely
+different ways to represent an XML element.The XML Schema to Java
+binding for an XML element declaration is described in
+link:jaxb.html#a642[See Java Element Representation]”. The Java
+to XML Schema binding for an XML element declaration is described in
+Section 8.8.2, “@XmlRootElement.“
+
+Use JAXBInstrospector.isElement(Object)
+method to determine if an instance of a JAXB mapped class represents an
+XML element. One can get the xml element tag name associated with a JAXB
+element using _JAXBIntrospector.getElementName_ method.One can an xml
+element’s value using getValue method. The getValue method normalizes
+access of JAXB element, hiding whether the JAXB element is an instance
+of javax.xml.bind.JAXBElement or if it is an JAXB element via an
+@XmlRootElement class annotation.
+
+=== Validation Handling
+
+Methods defined in the binding framework can
+cause validation events to be delivered to the client application’s
+_ValidationEventHandler_ . _Setter_ methods generated in schema-derived
+classes are capable of throwing _TypeConstraintExceptions_ , all of
+which are defined in the binding framework.
+
+The following list describes the primary
+event and constraint-exception classes:
+
+* An instance of a _TypeConstraintException_
+subclass is thrown when a violation of a dynamically-checked type
+constraint is detected. Such exceptions will be thrown by property-set
+methods, for which it would be inconvenient to have to handle checked
+exceptions; type-constraint exceptions are therefore unchecked, _i.e_ ,
+this class extends _java.lang.RuntimeException_ . The constraint check
+is always performed prior to the property-set method updating the value
+of the property, thus if the exception is thrown, the property is
+guaranteed to retain the value it had prior to the invocation of the
+property-set method with an invalid value. This functionality is
+optional to implement in this version of the specification.
+Additionally, a customization mechanism is provided to control enabling
+and disabling this feature.
+* An instance of a _ValidationEvent_ is
+delivered whenever a violation is detected during optionally enabled
+unmarshal/marshal validation. Additionally, _ValidationEvents_ can be
+discovered during marshalling such as ID/IDREF violations and print
+conversion failures. These violations may indicate local and global
+structural constraint violations, type conversion violations, type
+constraint violations, etc.
+* Since the unmarshal operation involves
+reading an input document, lexical well-formedness errors may be
+detected or an I/O error may occur. In these cases, an
+_UnmarshalException_ will be thrown to indicate that the JAXB provider
+is unable to continue the unmarshal operation.
+* During the marshal operation, the JAXB
+provider may encounter errors in the Java content tree that prevent it
+from being able to complete. In these cases, a _MarshalException_ will
+be thrown to indicate that the marshal operation can not be completed.
+
+=== DOM and Java representation Binding
+
+The Binder class is responsible for
+maintaining the relationship between a infoset preserving view of an XML
+document with a possibly partial binding of the XML document to a JAXB
+representation. Modifications can be made to either the infoset
+preserving view or the JAXB representation of the document while the
+other view remains unmodified. The binder is able to synchronize the
+changes made in the modified view back into the read-only view. When
+synchronizing changes to JAXB view back to related xml infoset
+preserving view, every effort is made to preserve XML concepts that are
+not bound to JAXB objects, such as XML infoset comments, processing
+instructions, namespace prefix mappings, etc.
+
+=== Use Cases
+
+* Read-only partial binding. +
+ +
+Application only needs to manipulate a small part of a rather large XML
+document. It suffices to only map the small of the large document to the
+JAXB Java representation. +
+* Updateable partial binding +
+ +
+The application receives an XML document that follows a later version of
+the schema than the application is aware of. The parts of the schema
+that the application needs to read and/or modify have not changed. Thus,
+the document can be read into an infoset preserving representation, such
+as DOM, only bind the part of the document that it does still have the
+correct schema for into the JAXB Java representation of the fragment of
+the document using Binder.unmarshal from the DOM to the JAXB view.
+Modify the partial Java representation of the document and then
+synchronize the modified parts of the Java representation back to the
+DOM view using _Binder.updateXML_ method.
+* XPATH navigation +
+ +
+Given that binder maintains a relationship between XML infoset view of
+document and JAXB representation, one can use JAXP 1.3 XPATH on the XML
+infoset view and use the binder’s associative mapping to get from the
+infoset node to JAXB representation.
+
+=== javax.xml.bind.Binder
+
+The class _javax.xml.bind.Binder_ associates
+an infoset preserving representation of the entire XML document with a
+potentially partial binding to a Java representation. The binder
+provides operations to synchronize between the two views that it is
+binding.
+
+
+
+public abstract class Binder<XmlNode> \{ +
+_// Create two views of XML content, infoset view and JAXB view +
+_ public abstract Object unmarshal(XmlNode) +
+<T> JAXBElement<T> unmarshal(org.w3c.dom.Node, +
+Class<T> declaredType)
+
+ public abstract void marshal(Object
+jaxbObjcet, XmlNode) +
+ +
+_//Navigation between xml infoset view and JAXB view. +
+_ public abstract XmlNode getXMLNode(Object jaxbObject ); +
+public abstract Object getJAXBNode(XmlNode); +
+ +
+_// Synchronization methods_
+
+ public abstract XmlNode updateXML(Object
+jaxbObject ) +
+public abstract XmlNode updateXML(Object jaxbObject, XmlNode)
+
+ throws JAXBException; +
+public abstract Object updateJAXB( XmlNode) +
+throws JAXBException; +
+ +
+_// Enable optional validation +
+_ public abstract void setSchema(Schema); +
+public abstract Schema getSchema(); +
+public abstract void setEventHandler( ValidationEventHandler) +
+throws JAXBException; +
+public abstract ValidationEventHandler getEventHandler() +
+throws JAXBException; +
+ +
+_// Marshal/Unmarshal properties +
+_ public abstract void setProperty(String name, Object value) +
+throws PropertyException; +
+public abstract Object getProperty(String name) +
+throws PropertyException;
+
+}
+
+
+
+== CHAPTER 5 -
+
+Java
+Representation of XML Content
+
+This section defines the basic binding
+representation of package, value class, element classes, properties and
+enum type within the Java programming language. Each section briefly
+states the XML Schema components that could be bound to the Java
+representation. A more rigorous and thorough description of possible
+bindings and default bindings occurs in link:jaxb.html#a694[See
+Binding XML Schema to Java Representations]” and in
+link:jaxb.html#a1498[See Customizing XML Schema to Java
+Representation Binding].”
+
+=== Mapping between XML Names and Java Identifiers
+
+XML schema languages use _XML names_ , _i.e._
+, strings that match the Name production defined in XML 1.0 (Second
+Edition) to label schema components. This set of strings is much larger
+than the set of valid Java class, method, and constant identifiers.
+link:jaxb.html#a4649[See Appendix], “Binding XML Names to Java
+Identifiers,” specifies an algorithm for mapping XML names to Java
+identifiers in a way that adheres to standard Java API design
+guidelines, generates identifiers that retain obvious connections to the
+corresponding schema, and results in as few collisions as possible. It
+is necessary to rigorously define a standard way to perform this mapping
+so all implementations of this specification perform the mapping in the
+same compatible manner.
+
+=== [[a482]]Java Package
+
+Just as the target XML namespace provides a
+naming context for the named type definitions, named model groups,
+global element declarations and global attribute declarations for a
+schema vocabulary, the Java package provides a naming context for Java
+interfaces and classes. Therefore, it is natural to map the target
+namespace of a schema to be the package that contains the Java value
+class representing the structural content model of the document.
+
+A package consists of:
+
+* A _name_ , which is either derived directly
+from the XML namespace URI as specified in
+link:jaxb.html#a4788[See Generating a Java package name]” or
+specified by a binding customization of the XML namespace URI as
+described in link:jaxb.html#a1674[See package].”
+* A set of Java value class representing the
+content models declared within the schema.
+* A set of Java element classes representing
+element declarations occurring within the schema.
+link:jaxb.html#a642[See Java Element Representation]” describes
+this binding in more detail.
+* A public class _ObjectFactory_ contains:
+* An instance factory method signature for
+each Java content within the package. +
+ +
+Given Java value class named Foo, here is the derived factory method:
+
+ +
+public Foo createFoo();
+
+* An element instance factory method
+signature for each bound element declaration.
+
+ +
+public JAXBElement<T> createFoo(T elementValue);
+
+* Dynamic instance factory allocator method
+signature:
+
+ +
+public Object newInstance(Class javaContentInterface); +
+
+* Property setter/getter +
+Provide the ability to associate implementation specific property/value
+pairs with the instance creation process.
+
+ java.lang.Object _getProperty_ (String
+name); +
+void _setProperty_ (String name, Object value);
+
+* A set of enum types.
+* Package javadoc.
+
+=== Example:
+
+Purchase Order Schema fragment with
+_targetNamespace_ :
+
+<xs:schema
+xmlns:xs="http://www.w3.org/2001/XMLSchema" +
+xmlns:po="http://www.example.com/PO1" +
+targetNamespace="http://www.example.com/PO1"> +
+<xs:element name="purchaseOrder" type="po:PurchaseOrderType"/> +
+<xs:element name="comment" type="xs:string"/> +
+<xs:complexType name="PurchaseOrderType"/> +
+... +
+</xs:schema>
+
+Default derived Java code:
+
+import javax.xml.bind.JAXBElement; +
+package com.example.PO1; +
+public class PurchaseOrderType \{ .... }; +
+public Comment \{ String getValue()\{...} void setValue(String)\{...}
+} +
+... +
+public class ObjectFactory \{ +
+PurchaseOrderType createPurchaseOrderType(); +
+JAXBElement<PurchaseOrderType>
+
+createPurchaseOrder(PurchaseOrderType
+elementValue); +
+Comment createComment(String value); +
+... +
+}
+
+=== Enum Type
+
+A simple type definition whose value space is
+constrained by enumeration facets can be bound to a Java enum type. Enum
+type was introduced in J2SE 5.0 and is described in Section 8.9 of
+[JLS]. Enum type is a significant enhancement over the typesafe enum
+design pattern that it was designed to replace. If an application wishes
+to refer to the values of a class by descriptive constants and
+manipulate those constants in a type safe manner, it should consider
+binding the XML component containing enumeration facets to an enum type.
+
+An enum type consists of:
+
+* A _name_ , which is either computed
+directly from an XML name or specified by a binding customization for
+the schema component.
+* A package name, which is either computed
+from the target namespace of the schema component or specified within a
+binding declaration as a customization of the target namespace or a
+specified package name for components that are scoped to no target
+namespace.
+* Outer Class Names is “ _._ ” separated list
+of outer class names.
+
+By default, if the XML component containing a
+typesafe enum class to be generated is scoped within a complex type as
+opposed to a global scope, the typesafe enum class should occur as a
+nested class within the Java value class representing the complex type
+scope. +
+Absolute class name is PackageName.[OuterClassNames.]Name. +
+Note: Outer Class Name is null if class is a top-level class. +
+ +
+The schema customization <jaxb:globalBindings localScoping=”toplevel”/>,
+specified in Section link:jaxb.html#a1582[See Usage], disables
+the generation of schema-derived nested classes and can be used to
+override the default binding of a nested schema component binding to
+nested Java class.
+
+* A set of enum constants.
+* Class javadoc is a combination of a
+documentation annotation from the schema component and/or javadoc
+specified by customization.
+
+An enum constant consists of:
+
+* A name, which is either computed from the
+enumeration facet value or specified by customization.
+* A _value_ for the constant. Optimally, the
+_name_ is the same as the _value_ . This optimization is not possible
+when the enumeration facet value is not a valid Java identifier.
+* A datatype for the constant’s value.
+* Javadoc for the constant field is a
+combination of a documentation annotation for an enumeration value facet
+and/or javadoc specified by customization.
+
+=== Content Representation
+
+A complex type definition is bound to either
+a Java value class or a content interface, depending on the value of the
+global binding customization _[jaxb:globalBinding]_
+_@generateValueClass_ , specified in link:jaxb.html#a1582[See
+Usage]”. Value classes are generated by default. The attributes and
+children element content of a complex type definition are represented as
+properties of the Java content representation. Property representations
+are introduced in link:jaxb.html#a541[See Properties].
+
+=== [[a521]]Value Class
+
+A value class consists of:
+
+* A _name_ , which is either computed
+directly from an XML name or specified by a binding customization for
+the schema component.
+* A package name, which is either computed
+from the target namespace of the schema component or specified by a
+binding customization of the target namespace or a specified package
+name for components that are scoped to no target namespace.
+* The _outer class name_ context, a
+dot-separated list of Java class names.
+
+By default, if the XML schema component for
+which a Java value class is to be generated is scoped within a complex
+type as opposed to globally, the complex class should occur as a nested
+class within the Java value class representing the complex type scope.
+The schema customization <jaxb:globalBindings localScoping=”toplevel”/>,
+specified in Section link:jaxb.html#a1582[See Usage], disables
+the generation of schema-derived nested classes and all classes are
+generated as toplevel classes.
+
+The absolute class name is
+PackageName.[OuterClassNames.]Name. +
+Note: The OuterClassNames is null if the class is a top-level class.
+
+* A base class that this class extends. See
+link:jaxb.html#a917[See Complex Type Definition] for further
+details.
+* A set of Java properties providing access
+and modification to the complex type definition’s attributes and content
+model represented by the value class.
+* Class-level javadoc is a combination of a
+documentation annotation from the schema component and/or javadoc
+specified within customization.
+* Creation
+* A value class supports creation via a
+public constructor, either an explicit one or the default no-arg
+constructor.
+* A factory method in the package’s
+_ObjectFactory_ class (introduced in link:jaxb.html#a482[See
+Java Package]”). The factory method returns the type of the Java value
+class. The name of the factory method is generated by concatenating the
+following components: +
+- The string constant _create_ . +
+- If the Java value class is nested within another value class, +
+then the concatenation of all outer Java class names. +
+- The _name_ of the Java value class.
+
+For example, a Java value class named _Foo_
+that is nested within Java value class _Bar_ would have the following
+factory method signature generated in the containing Java package’s
+_ObjectFactory_ class:
+
+ Bar.Foo createBarFoo() \{...}
+
+=== [[a536]]Java Content Interface
+
+JAXB 1.0 bound a complex type definition to a
+content interface. This binding is similar to the value class binding
+with the following differences.
+
+* A content interface is a public interface
+while a value class is a public class.
+* A content interface can only be created
+with an ObjectFactory method whereas a value class can be created using
+a public constructor. The factory method signature is the same for both
+value class and content interface binding to ease switching between the
+two binding styles.
+* A content interface contains the method
+signatures for the set of properties it contains, while a value class
+contains method implementations.
+
+=== [[a541]]Properties
+
+The schema compiler binds local schema
+components to _properties_ within a Java value class.
+
+A property is defined by:
+
+* A _name_ , which is either computed from
+the XML name or specified by a binding customization for the schema
+component.
+* A _base type_ , which may be a Java
+primitive type ( _e.g._ , _int_ ) or a reference type.
+* An optional _predicate_ , which is a
+mechanism that tests values of the base type for validity and throws a
+_TypeConstraintException_ if a type constraint expressed in the source
+schema is violated. link:#a5358[7]
+* An optional _collection type_ , which is
+used for properties whose values may be composed of more than one value.
+* A _default value_ . Schema component has a
+schema specified default value which is used when property’s value is
+not set and not nil.
+* Is _nillable_ . A property is nillable when
+it represents a nillable element declaration.
+
+A property is _realized_ by a set of _access
+methods_ . Several property models are identified in the following
+subsections; each adds additional functionally to the basic set of
+access methods.
+
+A property’s access methods are named in the
+standard JavaBeans style: the name-mapping algorithm is applied to the
+property name and then each method name is constructed by prefixing the
+appropriate verb ( _get_ , _set_ , etc.).
+
+[[a552]]A property is
+said to have a set value if that value was assigned to it during
+unmarshallinglink:#a5359[8] or by invoking its mutation method.
+The _value_ of a property is its set value, if defined; otherwise, it is
+the property’s schema specified default value, if any; otherwise, it is
+the default initial value for the property’s base type as it would be
+assigned for an uninitialized field within a Java
+classlink:#a5360[9]. link:jaxb.html#50536473_21325[See All other
+property kinds rely on the invocation of their set method with a value
+of null to discard the set value of its property. Since this is not
+possible for primitive types or a List property, the additional method
+is generated for these cases illustrate the method invocations that
+result in transitions between the possible states of a JAXB property
+value.] link:jaxb.html#a623[See States of a Property
+Value]link:jaxb.html#a623[See States of a Property Value]
+illustrates the states of a JAXB property and the invocations that
+result in state changes.
+
+=== Simple Property
+
+A non-collection property _prop_ with a base
+type _Type_ is realized by the two methods
+
+[width="100%",cols="100%",options="header",]
+|===
+|public Type get _Id_ ();
+|public void set _Id_ (Type value);
+|===
+
+where _Id_ is a metavariable that represents
+the Java method identifier computed by applying the name mapping
+algorithm described in link:jaxb.html#a4656[See The Name to
+Identifier Mapping Algorithm]” to prop. There is one exception to this
+general rule in order to support the boolean property described in
+[BEANS]. When _Type_ is boolean, the get _Id_ method specified above is
+replaced by the method signature, _boolean_ is _Id_ ().
+
+* The _get_ or _is_ method returns the
+property’s value as specified in the previous subsection. If null is
+returned, the property is considered to be absent from the XML content
+that it represents.
+* The _set_ method defines the property’s set
+value to be the argument _value_ . If the argument value is _null_ , the
+property’s set value is discarded. Prior to setting the property’s value
+when TypeConstraint validation is enabledlink:#a5361[10], a non-
+_null_ value is validated by applying the property’s predicate _._ If
+_TypeConstraintException_ is thrown, the property retains the value it
+had prior to the _set_ method invocation.
+
+
+
+When the base type for a property is a
+primitive non-reference type and the property’s value is optional, the
+corresponding Java wrapper class can be used as the base type to enable
+discarding the property’s set value by invoking the set method with a
+null parameter. link:jaxb.html#a610[See isSet Property
+Modifier] describes an alternative to using a wrapper class for this
+purpose. The _[jaxb:globalBinding]_ customization _@optionalProperty_
+controls the binding of an optional primitive property as described in
+link:jaxb.html#a1582[See Usage].
+
+=== Example
+
+In the purchase order schema, the _partNum_
+attribute of the _item_ element definition is declared:
+
+<xs:attribute name="partNum" type="SKU"
+use="required"/>
+
+This element declaration is bound to a simple
+property with the base type _java.lang.String_ :
+
+public String getPartNum(); +
+public void setPartNum(String x);
+
+The _setPartNum_ method could apply a
+predicate to its argument to ensure that the new value is legal, _i.e._
+, that it is a string value that complies with the constraints for the
+simple type definition, SKU _,_ and that derives by restriction from
+_xs:string_ and restricts the string value to match the regular
+expression pattern _"\d\{3}-[A-Z]\{2}"_ .
+
+It is legal to pass _null_ to the
+_setPartNum_ method even though the _partNum_ attribute declaration’s
+attribute _use_ is specified as required. The determination if _partNum_
+content actually has a value is a local structural constraint rather
+than a type constraint, so it is checked during validation rather than
+during mutation.
+
+=== Collection Property
+
+A collection property may take the form of an
+_indexed property_ or a _list property_ . The base type of an indexed
+property may be either a primitive type or a reference type, while that
+of a list property must be a reference type.
+
+A collection consists of a group of
+collection items. If one of the collection items can represent a
+nillable element declaration, setting a collection item to _null_ is
+semantically equivalent to inserting a nil element, _xsi:nil=”true”_ ,
+into the collection property. If none of the collection items can ever
+represent a nillable element declaration, setting a collection item to
+_null_ is the semantic equivalent of removing an optional element from
+the collection property.
+
+=== [[a572]]Indexed Property
+
+This property follows the indexed property
+design pattern for a multi-valued property from the JavaBean
+specification. An indexed property _prop_ with base type _Type_ is
+realized by the five methods
+
+[width="100%",cols="100%",options="header",]
+|===
+|public _Type_ [] get _Id_ ();
+|public void set _Id_ __ ( _Type_ [] value);
+
+|public void set _Id_ (int index, _Type_
+value);
+
+|public _Type_ get _Id_ (int index); +
+public int get _Id_ Length();
+|===
+
+regardless of whether _Type_ is a primitive
+type or a reference type. _Id_ is computed from _prop_ as it was defined
+in simple property. An array item is a specialization of the collection
+item abstraction introduced in the collection property overview.
+
+* get _Id_ () +
+The array _getter_ method returns an array containing the property’s
+value. If the property’s value has not set, then _null_ is returned.
+* set _Id_ ( _Type_ [] _) +
+_ The _array setter_ method defines the property’s set value. If the
+argument itself is _null_ then the property’s set value, if any, is
+discarded. If the argument is not _null_ and _TypeConstraint_ validation
+is enabled link:#a5362[11] then the sequence of values in the
+array are first validated by applying the property’s predicate, which
+may throw a _TypeConstraintException_ . If the _TypeConstraintException_
+is thrown, the property retains the value it had prior to the _set_
+method invocation. The property’s value is only modified after the
+_TypeConstraint_ validation step.
+* set _Id_ (int, _Type_ ) +
+The indexed _set_ ter method allows one to set a value within the array.
+The runtime exception _java.lang.ArrayIndexOutOfBoundsException_ may be
+thrown if the index is used outside the current array bounds. If the
+value argument is non-null and TypeConstraint validation is enabled5,
+the value is validated against the property’s predicate, which may throw
+an unchecked _TypeConstraintException_ . If _TypeConstraintException_ is
+thrown, the array index remains set to the same value it had before the
+invocation of the indexed _setter_ method. When the array item
+represents a nillable element declaration and the indexed setter value
+parameter is null, it is semantically equivalent to inserting a nil
+element into the array.
+* get _Id_ (int) +
+The indexed _get_ ter method returns a single element from the array.
+The runtime exception _java.lang.ArrayIndexOutOfBoundsException_ may be
+thrown if the index is used outside the current array bounds. In order
+to change the size of the array, you must use the array set method to
+set a new (or updated) array.
+* get _Id_ Length() +
+The indexed length method returns the length of the array. This method
+enables you to iterate over all the items within the indexed property
+using the indexed mutators exclusively. Exclusive use of indexed
+mutators and this method enable you to avoid the allocation overhead
+associated with array _getter_ and _setter_ methods.
+
+The arrays returned and taken by these
+methods are not part of the content object’s state. When an array
+_getter_ method is invoked, it creates a new array to hold the returned
+values. Similarly, when the corresponding array _setter_ method is
+invoked, it copies the values from the argument array.
+
+To test whether an indexed property has a set
+value, invoke its _array getter_ method and check that the result is not
+_null_ . To discard an indexed property’s set value, invoke its array
+_setter_ method with an argument of _null_ .
+
+See the customization attribute
+_collectionType_ in link:jaxb.html#a1580[See <globalBindings>
+Declaration]” and link:jaxb.html#a1783[See <property>
+Declaration]” on how to enable the generation of indexed property
+methods for a collection property.
+
+=== Example
+
+In the purchase order schema, we have the
+following repeating element occurrence of element _item_ within
+_complexType_ _Items_ .
+
+<xs:complexType name= _"Items"_ >
+
+ <xs:sequence>
+
+ <xs:element name= _"item"_ minOccurs="1"
+maxOccurs="unbounded"> +
+<xs:complexType>...</xs:complexType> +
+</xs:element> +
+</xs:complexType>
+
+The content specification of this element
+type could be bound to an array property realized by these five methods:
+
+public Items.ItemType[] getItem();
+
+public void setItem(Items.ItemType[]
+value); +
+public void setItem(int index, Items.ItemType value); +
+public Items.ItemType getItem(int index); +
+public int getItemLength();
+
+=== [[a595]]List Property
+
+A list property _prop_ with base type _Type_
+is realized by the method where _List_ is the interface _java.util.List_
+, _Id_ is defined as above. If base type is a primitive type, the
+appropriate wrapper class is used in its place.
+
+[width="100%",cols="100%",]
+|===
+|public List<Type> get _Id_ ();
+|===
+
+* The _get_ method returns an object that
+implements the _List<Type>_ interface, is mutable, and contains the
+values of type _Type_ that constitute the property’s value. If the
+property does not have a set value or a schema default value, a zero
+length _java.util.List_ instance is returned.
+
+The _List_ returned by the _get_ method is a
+component of the content object’s state. Modifications made to this list
+will, in effect, be modifications to the content object. If
+_TypeConstraint_ validation is enabled, the list’s mutation methods
+apply the property’s predicate to any non- _null_ value before adding
+that value to the list or replacing an existing element’s value with
+that value; the predicate may throw a _TypeConstraintException_ . The
+collection property overview discussion on setting a collection item to
+null specifies the meaning of inserting a null into a List.
+
+The _unset_ method introduced in
+link:jaxb.html#a610[See isSet Property Modifier] enables one to
+discard the set value for a List property.
+
+*
+
+=== Example
+
+The content specification of the _item_
+element type could alternatively be bound to a list property realized by
+one method:
+
+public List<Item> getItem();
+
+The list returned by the _getItem_ method
+would be guaranteed only to contain instances of the _Item_ class. As
+before, its length would be checked only during validation, since the
+requirement that there be at least one _item_ in an element instance of
+complex type definition _Items_ is a structural constraint rather than a
+type constraint.
+
+=== Constant Property
+
+An attribute use named prop with a schema
+specified fixed value can be bound to a Java constant value. _Id_ is
+computed from _prop_ as it was defined in simple property. The value of
+the fixed attribute of the attribute use provides the _<fixedValue>_
+constant value.
+
+[width="100%",cols="100%",]
+|===
+|static final public _Type_ ID =
+<fixedValue>;
+|===
+
+The binding customization attribute
+_fixedAttributeToConstantProperty_ enables this binding style.
+link:jaxb.html#a1580[See <globalBindings> Declaration]” and
+link:jaxb.html#a1783[See <property> Declaration]” describe how
+to use this attribute.
+
+=== [[a610]] _isSet_ Property Modifier
+
+This optional modifier augments a modifiable
+property to enable the manipulation of the property’s value as a set
+value or a defaulted value. Since this functionality is above and beyond
+the typical JavaBean pattern for a property, the method(s) associated
+with this modifier are not generated by default.
+link:jaxb.html#a1498[See Customizing XML Schema to Java
+Representation Binding]” describes how to enable this customization
+using the _generateIsSetMethod_ attribute.
+
+The method signatures for the _isSet_
+property modifier are the following:
+
+[width="100%",cols="100%",]
+|===
+|public boolean _isSetId_ ();
+|===
+
+where _Id_ is defined as it was for simple
+and collection property.
+
+* The _isSet_ method returns _true_ if the
+property has been set during unmarshalling or by invocation of the
+mutation method _setId_ with a non- _null_ value.
+link:#a5363[12]
+
+To aid the understanding of what _isSet_
+method implies, note that the unmarshalling process only unmarshals set
+values into XML content.
+
+A list property and a simple property with a
+non-reference base type require an additional method to enable you to
+discard the set value for a property:
+
+[width="100%",cols="100%",]
+|===
+|public void _unsetId_ ();
+|===
+
+* The _unset_ method marks the property as
+having no set value. A subsequent call to _getId_ method returns the
+schema-specified default if it existed; otherwise, it returns the Java
+default initial value for _Type_ .
+
+All other property kinds rely on the
+invocation of their set method with a value of null to discard the set
+value of its property. Since this is not possible for primitive types or
+a List property, the additional method is generated for these
+caseslink:jaxb.html#a621[See All other property kinds rely on
+the invocation of their set method with a value of null to discard the
+set value of its property. Since this is not possible for primitive
+types or a List property, the additional method is generated for these
+cases illustrate the method invocations that result in transitions
+between the possible states of a JAXB property value.] illustrate the
+method invocations that result in transitions between the possible
+states of a JAXB property
+value.link:jaxb.html#a552[See A property is said to
+have a set value if that value was assigned to it during unmarshalling
+or by invoking its mutation method. The value of a property is its set
+value, if defined; otherwise, it is the property’s schema specified
+default value, if any; otherwise, it is the default initial value for
+the property’s base type as it would be assigned for an uninitialized
+field within a Java class. Figure 5.1 illustrates the states of a JAXB
+property and the invocations that result in state
+changes.][[a621]]
+
+
+
+image:xmlb-8.png[image]
+
+=== [[a623]]States of a Property Value
+
+=== Example
+
+In the purchase order schema, the _partNum_
+attribute of the element _item_ ’s anonymous complex type is declared:
+
+<xs:attribute name="partNum" type = "SKU"
+use="required"/>
+
+This attribute could be bound to a _isSet_
+simple property realized by these four methods:
+
+public String getPartNum(); +
+public void setPartNum(String skuValue); +
+public boolean isSetPartNum(); +
+public void unsetPartNum();
+
+It is legal to invoke the _unsetPartNum_
+method even though the attribute’s _use_ is _“required”_ in the XML
+Schema. That the attribute actually has a value is a local structural
+constraint rather than a type constraint, so it is checked during
+validation rather than during mutation.
+
+=== [[a630]]Element Property
+
+This property pattern enables the dynamic
+association of an element name for a JAXB property. Typically, the
+element name is statically associated with a JAXB property based on the
+schema’s element name. Element substitution groups and wildcard content
+allow an XML document author to use Element names that were not
+statically specified in the content model of the schema. To support
+these extensibility features, an application uses element property
+setters/getters to dynamically introduce element names at runtime.
+
+The method signatures for the _Element_
+property pattern are the following:
+
+[width="100%",cols="100%",]
+|===
+|public void set _Id_ ( _JAXBElement_ <?
+extends _Type_ > value); +
+public _JAXBElement_ <? extends _Type_ > get _Id_ ();
+|===
+
+where _Id_ and _Type_ are defined as they
+were for simple and collection property. The fully qualified Java name
+for _JAXBElement_ _<T>_ is _javax.xml.bind.JAXBElement<T>_ . The generic
+types in the method signatures are expressed as a bounded wildcard to
+support element substitution group, see details in
+link:jaxb.html#a1023[See Element Declaration]”.
+
+=== Property Summary
+
+The following core properties have been
+defined:
+
+* Simple property - JavaBean design pattern
+for single value property
+* Indexed property - JavaBean design pattern
+for multi-valued property
+* List property - Leverages
+java.util.Collection
+* Constant property
+
+The methods generated for these four core
+property kinds are sufficient for most applications. Configuration-level
+binding schema declarations enable an application to request finer
+control than provided by the core properties. For example, the _isSet_
+property modifier enables an application to determine if a property’s
+value is set or not.
+
+=== [[a642]]Java Element Representation
+
+Based on rationale and criteria described in
+link:jaxb.html#a1023[See Element Declaration], the schema
+compiler binds an element declaration to a Java instance that implements
+_javax.xml.bind.JAXBElement<T>_ . _JAXBElement<T>_ class provides access
+to the basic properties of an XML element: its name, the value of the
+element’s datatype, and whether the element’s content model is set to
+nil, i.e. _xsi:nil=”true”_ . Optional properties for an Xml element that
+corresponds to an element declaration from a known schema include the
+element declaration’s declared type and scope.
+
+The enhanced, default binding for an element
+declaration only generates a element instance factory method and is
+described in link:jaxb.html#a645[See Named Java Element
+instance]”.link:#a5364[13] The customized binding that generates
+a schema-dervied Element class for an element declaration is described
+in link:jaxb.html#a657[See Java Element Class]”.
+
+=== [[a645]]Named Java Element instance
+
+Based on the normative binding details
+described in link:jaxb.html#a1040[See Bind to JAXBElement<T>
+Instance], the schema compiler binds an element declaration to an
+element instance factory method.
+
+The following is a generic element factory
+signature.
+
+package _elementDeclarationTargetNamespace_ ;
+
+class ObjectFactory \{
+
+ javax.xml.bind.JAXBElement< _ElementType_ >
+
+create _ElementName_ ( _ElementType_ __
+value);
+
+}
+
+The element factory method enables an
+application to work with elements without having to directly know the
+precise _javax.xml.namespace.QName_ . The element factory method
+abstraction sets the Xml element name with the Java representation of
+the element, thus shielding the JAXB user from the complexities of
+manipulating namespaces and QNames.
+
+=== Binding of global element declaration to element factory
+
+ +
+<xs:schema targetNamespace=”a” xmlns:a=”a”/> +
+<xs:element name=”Foo” type=”xsd:int”/>
+
+ +
+class ObjectFactory \{ +
+// returns JAXBElement with its name set to QName(“a”, “Foo”). +
+JAXBElement<Integer> createFoo(Integer value); +
+}
+
+=== [[a657]]Java Element Class
+
+Based on criteria to be identified in
+link:jaxb.html#a1068[See Bind to Element Class], the schema
+compiler binds an element declaration to a Java element class. An
+element class is defined in terms of the properties of the
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+* An element class name is generated from the
+element declaration’s name using the XML Name to Java identifier name
+mapping algorithm specified in link:jaxb.html#a4656[See The Name
+to Identifier Mapping Algorithm].
+* Scope of element class
+* Global element declarations are declared in
+package scope.
+* By default, local element declarations
+occur in the scope of the first ancestor complex type definition that
+contains the declaration. The schema customization <jaxb:globalBindings
+localScoping=”toplevel”/>, specified in Section
+link:jaxb.html#a1582[See Usage], disables the generation of
+schema-derived nested classes and all classes are generated as toplevel
+classes.
+* Each generated Element class must extend
+the Java class _javax.xml.bind.JAXBElement<T>_ . The type T of the
+_JAXBElement<T>_ is derived from the element declaration’s type.
+Anonymous type definition binding is a special case that is specified in
+link:jaxb.html#a1084[See Binding of an anonymous complex type
+definition]
+* A factory method is generated in the
+package’s _ObjectFactory_ class introduced in
+link:jaxb.html#a482[See Java Package].” The factory method
+returns JAXBElement _<T>_ . The factory method has one parameter that is
+of type _T_ . The name of the factory method is generated by
+concatenating the following components:
+* The string constant _create_ .
+* If the Java element class is nested within
+a value class, then the concatenation of all outer Java class names.
+* The _name_ of the Java value class.
+
+The returned instance has the Xml Element
+name property set to the QName representing the element declaration’s
+name.
+
+For example, a Java element class named _Foo_
+that is nested within Java value class _Bar_ would have the following
+factory method generated in the containing Java package’s
+_ObjectFactory_ class:
+
+ JAXBElement<Integer> createBarFoo(Integer
+value)
+
+* A public no-arg constructor is generated. +
+The constructor must set the appropriate Xml element name, just as the
+element factory method does.
+* The Java element representation extends
+JAXBElement _<T>_ class, its properties provide the capability to
+manipulate
+* the value of the element’s content +
+Xml Schema’s type substitution capability is enabled by this property.
+* whether the element’s content model is
+_nil_
+
+=== Example:
+
+Given a complex type definition with mixed
+content:
+
+<xs:complexType name="AComplexType"
+mixed=”true”>link:#a5364[14] +
+<xs:sequence> +
+<xs:element name="ASimpleElement"
+type="xs:int"/>link:#a5366[15] +
+</xs:sequence> +
+</xs:complexType>
+
+Its Java representation:
+
+public value class AComplexType \{ +
+public class ASimpleElement extends +
+javax.xml.bind.JAXBElement<Integer> \{ +
+} +
+... +
+}; +
+class ObjectFactory \{ +
+AComplexType createAComplexType(); +
+JAXBElement<Integer> +
+createAComplexTypeASimpleElement(Integer value); +
+... +
+}
+
+=== [[a680]]Java Element Representation Summary
+
+Element declaration binding evolved in JAXB
+v2.0 to support XML Schema type substitution. The following diagrams
+illustrate the binding changes for the following schema fragment:
+
+<xs:element name=”foo” type=”fooType”/>
+
+=== JAXB 1.0 : isA Relationship between generated element interface and its type
+
+image:xmlb-9.png[image]
+
+=== JAXB 2.0: hasA Relationship between element instance and its type as described in link:jaxb.html#a645[See Named Java Element instance]”
+
+image:xmlb-10.png[image]
+
+=== JAXB 2.0: hasA Relationship between generated element class and its type as described in link:jaxb.html#a657[See Java Element Class]”
+
+image:xmlb-11.png[image]
+
+While a JAXB v1.0 Element interface
+implemented its type’s interface, a JAXB v2.0 Element instance has a
+composition relationship to the value of the element declaration’s type,
+accessible via the _javax.xml.bind.JAXBElement<T>_ property _Value_ .
+This change reflects the relationship that type substitution allows an
+element declaration to be associated with many different datatypes, not
+just the datatype that was defined statically within the schema.
+
+An added benefit to the default binding
+change is to reduce the overhead associated with always generating Java
+Element classes for every global element declaration.In JAXB 1.0, an
+interface was generated for every complex type definition and global
+element declaration. In JAXB 2.0, a value class is generated for every
+complex type definition and only a factory method needs to be generated
+for each global element declaration.
+
+=== Summary
+
+The composition and relationships between the
+Java components introduced in this section are reflected in the
+following diagram.
+
+=== UML diagram of Java Representationlink:#a5367[16]
+
+image:xmlb-12.png[image]
+
+=== UML diagram when xs:element is bound to schema-derived Element class
+
+image:xmlb-13.png[image]
+
+See also link:jaxb.html#UNKNOWN[See
+Summarize default XSD to Java binding for Figure 5.1 and Figure 5.2].
+
+== CHAPTER 6 -
+
+[[a694]]Binding
+XML Schema to Java Representations
+
+This chapter describes binding of XML schema
+components to Java representations. The default binding is identified in
+this chapter and the next chapter specifies the customizations that
+override default binding.
+
+=== Overview
+
+The abstract model described in [XSD Part 1]
+is used to discuss the default binding of each schema component type.
+Each schema component is described as a list of properties and their
+semantics. References to properties of a schema component as defined in
+[XSD Part 1] are denoted using the notation \{schema property}
+throughout this section. References to properties of information items
+as defined in [XML-Infoset] are denoted by the notation [property].
+
+All JAXB implementations are required to
+implement the default bindings specified in this chapter. However, users
+and JAXB implementors can use the global configuration capabilities of
+the custom binding mechanism to override the defaults in a portable
+manner.
+
+For each binding of a schema component to its
+Java representation, there is a description of Java mapping
+annotation(s), described in link:jaxb.html#a2236[See Java Types
+To XML]“, to be generated with the Java representation. The
+standardization of these mapping annotations assist in specifying the
+portability of a schema-derived JAXB-annotated classes. All JAXB
+implementations are required to be able to unmarshal/marshal another
+implementation’s schema-derived Java value classes by interpreting the
+specified mapping annotations. Note that each mapping annotation is
+described independent of whether it is the default mapping or a
+customized mapping, JAXB implementations are allowed to optimize away
+redundant mapping annotations that are the default mapping annotation.
+
+*
+
+All examples are non-normative. Note that in
+the examples, the schema-derived code does not list all required mapping
+annotations. In the interest of being terse, only the mapping
+annotations directly connected to the schema component being discussed
+are listed in its example.
+
+=== [[a702]]Simple Type Definition
+
+A schema component using a simple type
+definition typically binds to a Java property. Since there are different
+kinds of such schema components, the following Java property attributes
+(common to the schema components) are specified here and include:
+
+* base type
+* collection type if any
+* predicate
+
+The rest of the Java property attributes are
+specified in the schema component using the simple type definition.
+
+While not necessary to perform by default,
+this section illustrates how a simple type definition is bound to a JAXB
+mapped class. This binding is necessary to preserve a simple type
+definition referred to by _xsi:type_ attribute in an Xml instance
+document. See link:jaxb.html#a1582[See Usage]“for the
+customization that enables this binding.
+
+=== Type Categorization
+
+The simple type definitions can be
+categorized as:
+
+* schema built-in datatypes [XSD PART2]
+* user-derived datatypes
+
+Conceptually, there is no difference between
+the two. A schema built-in datatype can be a primitive datatype. But it
+can also, like a user-derived datatype, be derived from a schema
+built-in datatype. Hence no distinction is made between the schema
+built-in and user-derived datatypes.
+
+The specification of simple type definitions
+is based on the abstract model described in Section 4.1, “Simple Type
+Definition” [XSD PART2]. The abstract model defines three varieties of
+simple type definitions: atomic, list, union. The Java property
+attributes for each of these are described next.
+
+=== [[a715]]Atomic Datatype
+
+If an atomic datatype has been derived by
+restriction using an “enumeration” facet, the Java property attributes
+are defined by link:jaxb.html#a829[See Enum Type].” Otherwise
+they are defined as described here.
+
+The base type is derived upon the XML
+built-in type hierarchy [XSD PART2, Section 3] reproduced below.
+
+
+
+image:xmlb-15.png[image]
+
+=== XML Built-In Type Hierarchy
+
+The above diagram is the same as the one in
+[XSD PART2] except for the following:
+
+* Only schema built-in atomic datatypes
+derived by restriction have been shown.
+* The schema built-in atomic datatypes have
+been annotated with Java data types from the “Java Mapping for XML
+Schema Built-in Types” table below.
+*
+
+The following is a mapping for subset of the
+XML schema built-in data types to Java data types. This table is used to
+specify the base type later.
+
+=== [[a725]]Java Mapping for XML Schema Built-in Types
+
+XML Schema Datatype
+
+Java Datatype
+
+ _xsd:string_
+
+ _java.lang.String_
+
+ _xsd:integer_
+
+ _java.math.BigInteger_
+
+ _xsd:int_
+
+ _int_
+
+ _xsd.long_
+
+ _long_
+
+ _xsd:short_
+
+ _short_
+
+ _xsd:decimal_
+
+ _java.math.BigDecimal_
+
+ _xsd:float_
+
+ _float_
+
+ _xsd:double_
+
+ _double_
+
+ _xsd:boolean_
+
+ _boolean_
+
+ _xsd:byte_
+
+ _byte_
+
+ _xsd:QName_
+
+ _javax.xml.namespace.QName_ 1
+
+ _xsd:dateTime_
+
+javax.xml.datatype.XMLGregorianCalendar 1
+
+ _xsd:base64Binary_
+
+ _byte[]_
+
+ _xsd:hexBinary_
+
+ _byte[]_
+
+xsd:unsignedInt
+
+long
+
+xsd:unsignedShort
+
+int
+
+xsd:unsignedByte
+
+short
+
+xsd:time
+
+javax.xml.datatype.XMLGregorianCalendar 1.
+
+xsd:date
+
+javax.xml.datatype.XMLGregorianCalendar 1.
+
+xsd:g*
+
+javax.xml.datatype.XMLGregorianCalendar 1.
+
+{empty}xsd:anySimpleType +
+(for xsd:element of this type)link:#a5368[17]
+
+java.lang.Object
+
+xsd:anySimpleType +
+(for xsd:attribute of this type)
+
+java.lang.String
+
+xsd:duration
+
+javax.xml.datatype.Duration 1
+
+xsd:NOTATION
+
+javax.xml.namespace.QName 1
+
+1. JAXP 1.3 defines package
+_javax.xml.datatype_ and _javax.xml.namespace_
+
+The base type is determined as follows:
+
+. Map by value space bounding facets +
+If the simple type derives from or is _xsd:integer_ and has either a
+constraining lower and/or upper bounds facet(s) or totalDigits facet,
+check if the following optimized binding is possible:
+. If the simple type derives from or is
+_xsd:short_ , _xsd:byte_ or _xsd:unsignedByte_ , go to step 2.
+. If the value space for the simple type is
+representable in the range of _java.lang.Integer.MIN_VALUE_ and
+_java.lang.Integer.MAX_VALUE_ , map to java primitive type, _int_ .
+. If the value space for the simple type is
+representable in the range of _java.lang.Long.MIN_VALUE_ and
+_java.lang.Long.MAX_VALUE_ , map to java primitive type, _long_ .
+. Else go to step 2.
+. Map by datatype +
+If a mapping is defined for the simple type in Table 6.1, the base type
+defaults to its defined Java datatype.
+. Map by base datatype +
+Otherwise, the base type must be the result obtained by repeating the
+step 1 and 2 using the \{base type definition}. For schema datatypes
+derived by restriction, the \{base type definition} represents the
+simple type definition from which it is derived. Therefore, repeating
+step 1 with \{base type definition} essentially walks up the XML Schema
+built-in type hierarchy until a simple type definition which is mapped
+to a Java datatype is found.
+
+The Java property predicate must be as
+specified in “Simple Type Definition Validation Rules,” Section
+4.1.4[XSD PART2].
+
+=== Example:
+
+The following schema fragment (taken from
+Section 4.3.1, “Length” [XSD PART2]):
+
+<xs:simpleType name="productCode"> +
+<xs:restriction base="xs:string"> +
+<xs:length value="8" fixed="true"/> +
+</xs:restriction> +
+</xs:simpleType>
+
+The facet “length” constrains the length of a
+product code (represented by _productCode_ ) to 8 characters (see
+section 4.3.1 [XSD PART2] for details).
+
+The Java property attributes corresponding to
+the above schema fragment are:
+
+* There is no Java datatype mapping for
+_productCode._ So the Java datatype is determined by walking up the
+built-in type hierarchy.
+* The _\{base type definition}_ of
+_productCode_ is _xs:string. xs:string_ is mapped to _java.lang.String_
+(as indicated in the table, and assuming no customization). Therefore,
+_productCode_ is mapped to the Java datatype _java.lang.String_ .
+* The predicate enforces the constraints on
+the length.
+
+=== Notation
+
+Given that the value space of _xsd:NOTATION_
+is the set of _xsd:QName_ , bind _xsd:NOTATION_ type to
+_javax.xml.namespace.QName_ .
+
+ For example, the following schema:
+
+<xs:schema targetNamespace="http://e.org"
+xmlns:e="http://e.org" +
+xmlns:xs="http://www.w3.org/2001/XMLSchema"> +
+<xs:notation name="jpeg" public="image/jpeg" system="jpeg.exe"/>
+<xs:notation name="png" public="image/png" system="png.exe"/> +
+<xs:simpleType name="pictureType"> +
+<xs:restriction base="xs:NOTATION"> +
+<xs:enumeration value="e:jpeg"/> +
+<xs:enumeration value="e:png"/> +
+</xs:restriction> +
+</xs:simpleType> +
+<xs:complexType name="Picture"> +
+<xs:simpleContent> +
+<xs:extension base="xs:hexBinary"> +
+<xs:attribute name="format" type="e:pictureType"/>
+
+ </xs:extension> +
+</xs:simpleContent> +
+</xs:complexType> +
+</xs:schema>
+
+ is mapped to the following Java code:
+
+package org.e; +
+import javax.xml.namespace.QName; +
+public class Picture \{ +
+void setValue(byte[] value) \{...} +
+byte[] getValue() \{...} +
+void setFormat(QName value)\{...} +
+QName getFormat()\{...} +
+}
+
+With the following usage scenario:
+
+Picture pic = ...; +
+pic.setFormat(new QName("http://e.org","jpeg"));
+
+=== [[a803]]Bind to a JAXB mapped class
+
+By default, a named simple type definition is
+not bound to a Java class. This binding is only necessary to enable the
+precise type of an _xsi:type_ substitution to be preserved as described
+in link:jaxb.html#a1158[See Type Substitution of a Simple Type
+Definition]“. This binding is enabled via the global binding
+customization attribute _@mapSimpleTypeDef_ specified in
+link:jaxb.html#a1582[See Usage]“.
+
+The binding of a named simple type definition
+to a Java value class is based on the abstract model properties in
+link:jaxb.html#a4867[See Simple Type Definition Schema
+Component]. The Java value class must be defined as specified here,
+unless the ref attribute is specified on the _<jaxb:class>_ declaration,
+in which case the schema compiler will simply assume that the nominated
+class is already bound to this simple type.
+
+* _name:_ name is the Java identifier
+obtained by mapping the XML name _\{name}_ using the name mapping
+algorithm, specified in link:jaxb.html#a4656[See The Name to
+Identifier Mapping Algorithm]. Note that anonymous simple type
+definition’s are never bound to a Java value class.
+* _package:_
+* The schema-derived Java value class is
+generated into the Java package that represents the binding of \{target
+namespace}
+* _outer class name:_
+* There is no outer class name for a global
+simple type definition.
+* _base class:_
+* Due to a constraint specified for @XmlValue
+in Section 8, this class can not extend any other class. The derivation
+by restriction hierarchy for simple type definitions can not be captured
+in the schema-derived Java value class.
+* _value property:_
+* Same as the binding of simple content in
+link:jaxb.html#a973[See Simple Content Binding] to an @XmlValue
+annotated JAXB property.
+
+The next two examples illustrate the binding
+of a simple type definition to a Java value class when the appropriate
+JAXB schema customization is enabled.
+
+=== [[a816]]Simple type definition
+
+<xs:simpleType name="productCode"> +
+<xs:restriction base="xs:string"> +
+<xs:length value="8" fixed="true"/> +
+</xs:restriction> +
+</xs:simpleType>
+
+=== Binding of link:jaxb.html#a816[See Simple type definition]“
+
+@XmlType(name="productCode") +
+public class ProductCode \{ +
+@XmlValue +
+String getValue(); +
+void setValue(String value); +
+}
+
+=== [[a820]]Annotations for standard XML datatypes
+
+By default, a schema-derived JAXB property
+bound from one of the following standard XML datatypes is annotated with
+the specified mapping annotation.
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+| _Schema Type_ |
+_JAXB Property Annotation_
+|xsd:ID |@XmlID
+
+|xsd:IDREF
+|@XmlIDREF
+
+|ref:swaRef
+|@XmlAttachmentRef
+|===
+
+Note that JAXB schema customizations could
+override these default binding.
+
+=== [[a829]]Enum Type
+
+The default mapping for a named atomic type
+that is derived by restriction with enumeration facet(s) and whose
+restriction base type (represented by \{base type definition}) is
+_xs:String_ link:#a5369[18] or derived from it is mapped to an
+enum type. The _[typesafeEnumBase]_ attribute customization described in
+link:jaxb.html#a1580[See <globalBindings> Declaration]," enables
+global configuration to alter what Xml built-in datatypes are bound by
+default to an enum type. An anonymous simple type definition is never
+bound to an enum class by default, but it can be customized as described
+in link:jaxb.html#a2090[See <typesafeEnum> Declaration]” to bind
+to an enum type.
+
+=== Example binding
+
+An example is provided first followed by a
+more formal specification.
+
+XML Schema fragment:
+
+<xs:simpleType name="USState"> +
+<xs:restriction base="xs:NCName"> +
+<xs:enumeration value="AK"/> +
+<xs:enumeration value="AL"/> +
+</xs:restriction> +
+</xs:simpleType>
+
+The corresponding enum type binding is:
+
+public enum USState \{ +
+AK, AL; +
+public String value() \{ return name(); } +
+public static USState fromValue(String value) \{ ... } +
+};
+
+=== Enum type binding
+
+The characteristics of an _enum type_ are
+derived in terms of the properties of the
+link:jaxb.html#a4867[See Simple Type Definition Schema
+Component] as follows:
+
+The enum type binding is defined as follows:
+
+* name: The default name of the enum type,
+enumType, is computed by applying the XML Name to Java identifier
+mapping algorithm to the _\{name}_ of the simple type definition. There
+is no mechanism to derive a name for an anonymous simple type
+definition, the customization must provide the _name_ .
+* package name: The package name is
+determined from the _\{targetname space}_ of the schema that directly
+contains the simple type definition.
+* _outer class name:_
+* There is no _outer class name_ for a global
+simple type definition.
+* There is no _outer class name_ when schema
+customization, _[jaxb:globalBindings]_ _@localScoping_ , specified in
+Section link:jaxb.html#a1582[See Usage], has a value of
+_toplevel_ .
+* The _outer class name_ for an anonymous
+simple type definition is computed by traversing up the anonymous simple
+type definition’s ancestor tree until the first ancestor is found that
+is: +
+- an XML component that is mapped to a Java value class, the _outer
+class name_ is composed of the concatenation of this Java value class’s
+_outer class name_ , “.” _,_ and its _name_ . +
+- a global declaration or definition is reached. There is no _outer
+class name_ for this case.
+* _enum constants_ : Specified in next
+section.
+
+Note that since a Java enum type is
+essentially a final class, it is not possible for it to be subclassed.
+Thus, any derivations of a simple type definition bound to an enum type
+can not be captured by an equivalent Java inheritance relationship.
+
+The schema-derived enum is annotated, either
+explicitly or by default mapping annotations, with the mapping
+annotation @XmlEnum, specified in Section 8. The @XmlEnum annotation
+elements are derived in terms of the abstract model properties for a
+simple type definition summarized in link:jaxb.html#a4867[See
+Simple Type Definition Schema Component] as follows:
+
+=== Annotate enum type with @XmlEnum element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlEnum element
+|@XmlEnum value
+|name |simple type
+definition's \{name}
+
+|namespace
+|\{target namespace}
+
+|value |the java
+type binding of the simple type definition’s _\{base type definition}_
+|===
+
+=== Enum Constant
+
+An enum constant is derived for each
+enumeration facet of the atomic type definition. The characteristics of
+an enum constant of the enum type are derived in terms of the properties
+of the link:jaxb.html#a4899[See Enumeration Facet Schema
+Component] as follows:
+
+* name: The name is either specified via
+customization, _jaxb:typesafeEnumMember_ described in
+link:jaxb.html#a2092[See Usage]“, or the name is computed as
+specified in link:jaxb.html#a863[See XML Enumvalue-to-Java
+Identifier Mapping]“.
+* type: The Java type binding of the simple
+type definition’s \{base_type_definition}.
+* _value_ : The conversion of string
+_\{value}_ to _type_ . _Value_ is manipulated via the following
+generated enum type methods:
+
+ _public_ _type_ value(); +
+public static _enumTypeName_ fromValue( _type_ value);
+
+To assist an application in manipulating the
+enum constants that comprise an enum type, all enum types have the
+following two implicitly declared static methods as specified in Section
+8.9 in [JLS3]. The enum type’s static method _values()_ returns an array
+of all enum constants. The static method _valueOf(String name)_ returns
+the enum constant represented by the name parameter.
+
+=== XML Enumvalue-[[a863]]to-Java Identifier Mapping
+
+The default name for the enum constant is
+based on mapping of the XML enumeration value to a Java identifier as
+described below.
+
+The XML enumeration value _\{value}_ is
+mapped to a Java Identifier using the algorithm specified in
+link:jaxb.html#a4773[See Deriving a legal Java identifier from
+an enum facet value]“.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, see
+link:jaxb.html#a1633[See @typesafeEnumMemberName]“for
+customization options to resolve this error case.
+
+=== Enum Constant Name differs from its Value
+
+For all cases where there exist at least one
+enumeration constant name that is not the same as the enumeration
+constant’s value, the generated enum type must have a final value field
+that is set by the enum type’s constructor. The code generation template
+is the following:
+
+=== At least one enum constant name differs from its value.
+
+ public enum _enumType_ \{ +
+_EnumConstantName_ _1_ ( _EnumConstantValue_ _1_ ), +
+... +
+_EnumConstantName_ _X_ ( _EnumConstantValue_ _X)_ _; +
+_ public _EnumConstantValueType_ value() \{ return value;} +
+public static _enumType_ fromValue( _EnumConstantValueType_ val) +
+\{ ... } +
+ +
+final private _EnumConstantValueType_ value; +
+private _enumType_ ( _EnumConstantValueType_ value) \{ +
+this.value = value; +
+} +
+}
+
+=== Code template when enum constant name is same as its enum constant value.
+
+ public enum _enumType_ \{ +
+_EnumConstantName1_ , ..., _EnumConstantNameX_ ; +
+public _Stringlink:#a5370[19]_ value() \{ return name();} +
+public static _enumType_ fromValue( _String_ 1 value) \{ ... } +
+}
+
+The schema-derived enum constant is
+annotated, either explicitly or by default mapping annotations, with the
+mapping annotation specified in Section 8. The _@XmlEnumValue_
+annotation elements are derived in terms of the abstract model
+properties for a enumerated facet summarized in
+link:jaxb.html#a4899[See Enumeration Facet Schema Component] as
+follows:
+
+=== Annotate enum constant with @XmlEnumValue element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlEnumValue element
+|@XmlEnumValue value
+|value
+|Enumeration facet’s \{value}
+|===
+
+=== Schema-derived enum type when enumeration facet’s value does not match enum constant name.
+
+Given following schema fragment:
+
+<xs:simpleType name="Coin"> +
+<!-- Assume jaxb customization that binds Coin to an enumType--> +
+<xs:restriction base="xs:int"> +
+<!--Assume jaxb customization specifying enumConstantName--> +
+<xs:enumeration value="1"/> <!-- name="penny"--> +
+<xs:enumeration value="5"/> <!-- name="nickel"--> +
+<xs:enumeration value="10"/><!-- name="dime"--> +
+<xs:enumeration value="25"/><!-- name="quarter--> +
+</xs:restriction> +
+</xs:simpleType>
+
+Schema-derived enum type:
+
+@XmlEnum(value="java.lang.Integer.class") +
+public enum Coin \{ +
+@XmlEnumValue("1") PENNY(1), +
+@XmlEnumValue("5") NICKEL(5), +
+@XmlEnumValue("10") DIME(10), +
+@XmlEnumValue("25") QUARTER(25); +
+public int value()\{ return value; } +
+public static Coin fromValue(int value) \{ ... } +
+ +
+final private Integer value; +
+Coin(int value) \{ this.value = value; } +
+}
+
+=== [[a883]]List
+
+A list simple type definition can only
+contain list items of atomic or union datatypes. The item type within
+the list is represented by the schema property \{item type definition}.
+
+The Java property attributes for a list
+simple type definition are:
+
+* The _base type_ is derived from the \{item
+type definition} as follows. If the Java datatype for \{item type
+definition} is a Java primitive type, then the base type is the wrapper
+class for the Java primitive type. Otherwise, the Java datatype is
+derived from the XML datatype as specified in
+link:jaxb.html#a715[See Atomic Datatype]” and
+link:jaxb.html#a829[See Enum Type].”
+* The _collection type_ defaults to an
+implementation of _java.util.List_ . Note that this specification does
+not specify the default implementation for the interface
+_java.util.List_ , it is implementation dependent.
+* The _predicate_ is derived from the “Simple
+Type Definition Validation Rules,” in section 4.1.4,[XSD PART2].
+
+=== Example:
+
+For the following schema fragment:
+
+<xs:simpleType name="xs:USStateList">
+
+ <xs:list itemType="xs:string"/>
+
+</xs:simpleType>
+
+The corresponding Java property attributes
+are:
+
+* The _base type_ is derived from \{item type
+definition} which is XML datatype, _“xs:string”_ , thus the Java
+datatype is _java.util.String_ as specified in __
+link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
+Types] _.”_
+* The _collection type_ defaults to an
+implementation of _java.util.List_ .
+* The _predicate_ only allows instances of
+_base type_ to be inserted into the list. When failfast check is being
+performedlink:#a5370[20], the list’s mutation methods apply the
+property’s predicate to any non- _null_ value before adding that value
+to the list or replacing an existing element’s value with that value;
+the predicate may throw a _TypeConstraintException_ .
+
+The schema-derived property is annotated,
+either explicitly or by default mapping annotations, with the mapping
+annotation @XmlList, specified in Section 8.
+
+=== [[a899]]Union Property
+
+A union property _prop_ is used to bind a
+union simple type definition schema component. A union simple type
+definition schema component consists of union members which are schema
+datatypes. A union property, is therefore, realized by:
+
+[width="100%",cols="100%",options="header",]
+|===
+|public Type get _Id_ ();
+|public void set _Id_ (Type value);
+|===
+
+where _Id_ is a metavariable that represents
+the Java method identifier computed by applying the name mapping
+algorithm described in link:jaxb.html#a4656[See The Name to
+Identifier Mapping Algorithm] to _prop_ .
+
+The _base type_ is String. If one of the
+member types is derived by list, then the Union property is represented
+as the appropriate collection property as specified by the customization
+_<jaxb:globalBindings>_ _@collectionType_ value, specified in
+link:jaxb.html#a1582[See Usage].”
+
+* The _getId_ method returns the set value.
+If the property has no set value then the value _null_ is returned. The
+value returned is Type.
+* The _setId_ method sets the set value. +
+If value is _null_ , the property’s set value is discarded. Prior to
+setting the property’s value when TypeConstraint validation is enabled,
+a non- _null_ value is validated by applying the property’s predicate,
+which may throw a _TypeConstraintException._ No setter is generated if
+the union is represented as a collection property.
+
+=== Example: Default Binding: Union
+
+The following schema fragment:
+
+<xs:complexType name="CTType"> +
+<xs:attribute name="state" type="ZipOrName"/> +
+</xs:complexType> +
+<xs:simpleType name="ZipOrName" +
+memberTypes="xs:integer xs:string"/>
+
+ +
+is bound to the following Java representation.
+
+public class CTType \{ +
+String getState() \{...} +
+void setState(String value) \{...} +
+}
+
+=== Union
+
+A simple type definition derived by a union
+is bound using the union property with the following Java property
+attributes:
+
+* the _base type_ as specified in
+link:jaxb.html#a899[See Union Property].”
+* if one of the member types is derived by
+_<xs:list>_ , then the union is bound as a Collection property.
+* The _predicate_ is the schema constraints
+specified in “Simple Type Definition Validation Rules,” Section 4.1.4
+[XSD PART2].
+
+=== [[a917]]Complex Type Definition
+
+=== [[a918]]Aggregation of Java Representation
+
+A Java representation for the entire schema
+is built based on aggregation. A schema component aggregates the Java
+representation of all the schema components that it references. This
+process is done until all the Java representation for the entire schema
+is built. Hence a general model for aggregation is specified here once
+and referred to in different parts of the specification.
+
+The model assumes that there is a schema
+component _SP_ which references another schema component _SC_ . The Java
+representation of _SP_ needs to aggregate the Java representation of
+_SC_ . There are two possibilities:
+
+* _SC_ is bound to a property set.
+* _SC_ is bound to a Java datatype or a Java
+value class.
+
+Each of these is described below.
+
+=== Aggregation of Datatype/Class
+
+If a schema component _SC_ is bound to a Java
+datatype or a Java value class, then _SP_ aggregates _SC’s_ Java
+representation as a simple property defined by:
+
+* _name:_ the name is the class/interface
+name or the Java datatype or a name determined by SP. The name of the
+property is therefore defined by the schema component which is
+performing the aggregation.
+* _base type:_ If SC is bound to a Java
+datatype, the base type is the Java datatype. If SC is bound to a Java
+value class, then the base type is the class name, including a dot
+separated list of class names within which SC is nested.
+* _collection type:_ There is no collection
+type.
+* _predicate:_ There is no predicate.
+
+=== [[a930]]Aggregation of Property Set
+
+If _SC_ is bound to a property set, then _SP_
+aggregates by adding _SC’s_ property set to its own property set.
+
+Aggregation of property sets can result in
+name collisions. A name collision can arise if two property names are
+identical. A binding compiler must generate an error on name collision.
+Name collisions can be resolved by using customization to change a
+property name.
+
+=== [[a933]]Java value class
+
+{empty}The binding of a complex type
+definition to a Java value class is based on the abstract model
+properties in link:jaxb.html#a4907[See Complex Type Definition
+Schema Component]. The Java value class must be defined as specified
+here, unless the ref attribute is specified on the _<jaxb:class>_
+customization, in which case the schema compiler will simply assume that
+the nominated class is already bound to this complex
+type.link:#a5372[21]
+
+* _name:_ name is the Java identifier
+obtained by mapping the XML name _\{name}_ using the name mapping
+algorithm, specified in link:jaxb.html#a4656[See The Name to
+Identifier Mapping Algorithm]. For the handling of an anonymous complex
+type definition, see link:jaxb.html#a1084[See Binding of an
+anonymous complex type definition]” for how a _name_ value is derived
+from its parent element declaration.
+* _package:_
+* For a global complex type definition, the
+derived Java value class is generated into the Java package that
+represents the binding of \{target namespace}
+* For the value of _package_ for an anonymous
+complex type definition, see link:jaxb.html#a1084[See Binding of
+an anonymous complex type definition]".
+* _outer class name:_
+* There is no outer class name for a global
+complex type definition.
+* link:jaxb.html#a1084[See Binding of
+an anonymous complex type definition]" defines how to derive this
+property from the element declaration that contains the anonymous
+complex type definition.
+* _base class:_ A complex type definition
+can derive by restriction or extension (i.e. _\{derivation method}_ is
+either “extension” or “restriction”). However, since there is no concept
+in Java programming similar to restriction, both are handled the same.
+If the _\{base type definition}_ is itself mapped to a Java value class
+(Ci2), then the base class must be Ci2. This must be realized as: +
+
+ public class Ci1 extends Ci2 \{ +
+..... +
+}
+
+See example of derivation by extension at the
+end of this section.
+
+* abstract: The generated Java class is
+abstract when the complex type definition’s _\{abstract}_ property is
+_true_ .
+* _property set:_ The Java representation of
+each of the following must be aggregated into Java value class’s
+property set (link:jaxb.html#a918[See Aggregation of Java
+Representation]”).
+* A subset of _\{attribute uses}_ is
+constructed. The subset must include the schema attributes corresponding
+to the _<xs:attribute>_ children and the _\{attribute uses}_ of the
+schema attribute groups resolved by the <ref> attribute. Every
+attribute’s Java representation (link:jaxb.html#a1252[See
+Attribute use]”) in the set of attributes computed above must be
+aggregated.
+* If the optional _\{attribute wildcard}_ is
+present, either directly or indirectly, a property defined by
+link:jaxb.html#a1306[See Attribute Wildcard]“is generated.
+* The Java representation for _\{content
+type}_ must be aggregated.
+
+For a “Complex Type Definition with complex
+content,” the Java representation for _\{content type}_ is specified in
+link:jaxb.html#a1332[See Content Model - Particle, Model Group,
+Wildcard].” +
+For a complex type definition which is a “Simple Type Definition with
+simple content,” the Java representation for _\{content type}_ is
+specified in link:jaxb.html#a973[See Simple Content Binding].”
+
+* If a complex type derives by restriction,
+there is no requirement that Java properties representing the attributes
+or elements removed by the restriction to be disabled. This is because
+(as noted earlier), derivation by restriction is handled the same as
+derivation by extension.
+* When the complex type definition’s
+_\{abstract}_ property is _false_ , a factory method is generated in the
+package’s _ObjectFactory_ class introduced in
+link:jaxb.html#a482[See Java Package].” The factory method
+returns the type of the Java value class. The name of the factory method
+is generated by concatenating the following components:
+* The string constant _create_ .
+* The _name_ of the Java value class.
+
+The schema-derived Java value class is
+annotated, either explicitly or by default mapping annotations, with the
+mapping annotation @XmlType, specified in Section
+link:jaxb.html#a2578[See @XmlType]. The @XmlType annotation
+elements are derived in terms of the abstract model properties for a
+complex type definition summarized in link:jaxb.html#a4907[See
+Complex Type Definition Schema Component] as follows:
+
+=== [[a956]]Annotate Java value class with @XmlType element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlType element
+|@XmlType value
+|name |complex
+type definition's \{name}
+
+|namespace
+|\{target namespace}
+
+|propOrder a|
+When \{content type} is element-only
+\{content model} and top-level \{compositor} is xs:sequence, ordered
+list of JAXB property names representing order of xs:elements in
+\{content model}.
+
+ +
+All other cases do not need to set propOrder.
+
+|===
+
+=== Example: Complex Type: Derivation by Extension
+
+XML Schema Fragment (from XSD PART 0 primer):
+
+<xs:complexType name="Address"> +
+<xs:sequence> +
+<xs:element name="name" type="xs:string"/> +
+<xs:element name="street" type="xs:string"/> +
+<xs:element name="city" type="xs:string"/> +
+</xs:sequence> +
+</xs:complexType>
+
+<xs:complexType name="USAddress"> +
+<xs:complexContent> +
+<xs:extension base="ipo:Address"> +
+<xs:sequence> +
+<xs:element name="state" type="xs:string"/> +
+<xs:element name="zip" type="xs:integer"/> +
+</xs:sequence> +
+</xs:extension> +
+</xs:complexContent> +
+</xs:complexType>
+
+Default Java binding:
+
+public class Address \{ +
+String getName() \{...} +
+void setName(String) \{...} +
+String getStreet() \{...} +
+void setStreet(String) \{...} +
+void getCity() \{...} +
+void setCity(String) \{...} +
+}
+
+ +
+import java.math.BigInteger;
+
+public class USAdress extends Address \{ +
+String getState() \{...} +
+void setState(String) \{...}\{ +
+BigInteger getZip() \{...} +
+void setZip(BigInteger) \{...} +
+} +
+ +
+class ObjectFactory \{ +
+Address createAddress() \{...} +
+USAddress createUSAddress() \{...} +
+}
+
+=== [[a973]]Simple Content Binding
+
+=== Binding to Property
+
+By default, a complex type definition with
+simple content is bound to a Java property defined by:
+
+* _name:_ The property name must be “
+_value_ ”.
+* _base type, predicate, collection type:_
+As specified in [XSD Part 1], when a complex type has simple content,
+the content type (\{content type}) is always a simple type schema
+component. And a simple type component always maps to a Java datatype
+(link:jaxb.html#a702[See Simple Type Definition]”). Values of
+the following three properties are copied from that Java type:
+* base type
+* predicate
+* collection type
+
+The schema-derived JAXB property representing
+simple content is annotated, either explicitly or by default mapping
+annotations, with the mapping annotation @XmlValue, specified in Section
+link:jaxb.html#a3331[See @XmlValue].
+
+=== Example: Simple Content: Binding To Property
+
+XML Schema fragment:
+
+<xs:complexType name="internationalPrice"> +
+<xs:simpleContent> +
+<xs:extension base="xs:decimal"> +
+<xs:attribute name="currency" type="xs:string"/> +
+</xs:extension> +
+</xs:simpleContent> +
+</xs:complexType>
+
+Default Java binding:
+
+class InternationalPrice \{ +
+/** Java property for simple content */ +
+@XmlValue +
+java.math.BigDecimal getValue() \{...} +
+void setValue(java.math.BigDecimal value) \{...} +
+ +
+/** Java property for attribute*/ +
+String getCurrency() \{...} +
+void setCurrency(String) \{...} +
+}
+
+=== xsd:anyType
+
+ _xsd:anyType_ is the root of the type
+definition hierarchy for a schema. All complex type definitions in a
+schema implicitly derive from _xsd:anyType_ . Given that the JAXB 2.0
+architecture does not define a common base class for all JAXB class
+bindings of complex type definitions, the only possible binding property
+base type binding for _xsd:anyType_ is to _java.lang.Object_ . This
+binding enables all possible type and element substitutions for an
+element of type _xsd:anyType_ .
+
+=== Binding of element with type _xsd:anyType_
+
+ +
+<xs:element name="anyContent/> <!-- _@type_ defaults to _xs:anyType_
+--> +
+<xs:complexType name="base"> +
+<xs:sequence>
+
+ <xs:element ref="anyContent/> +
+<xs:element name="anyContentAgain" type="xs:anyType"/> +
+</xs:sequence> +
+</xs:complexType> +
+ +
+public class Base \{ +
+void setAnyContent(Object obj); +
+Object getAnyContent(); +
+void setAnyContentAgain(Object obj); +
+Object getAnyContentAgain(); +
+}
+
+A schema author defines an element to be of
+type _xs:anyType_ to defer constraining an element to a particular type
+to the xml document author. Through the use of _xsi:type_ attribute or
+element substitution, an xml document author provides constraints for an
+element defined as _xs:anyType_ . The JAXB unmarshaller is able to
+unmarshal a schema defined _xsd:anyType_ element that has been
+constrained within the xml document to an easy to access JAXB mapped
+class. However, when the xml document does not constrain the
+_xs:anyType_ element, JAXB unmarshals the unconstrained content to an
+element node instance of a supported DOM API.
+
+Type substitution is covered in more detail
+in Section link:jaxb.html#a1148[See Type Substitution of a
+Complex Type Definition] and link:jaxb.html#a1158[See Type
+Substitution of a Simple Type Definition]. Element substitution is
+covered in more detail in Section link:jaxb.html#a1223[See Bind
+to a Simple Element property].
+
+=== Attribute Group Definition
+
+There is no default mapping for an attribute
+group definition. When an attribute group is referenced, each attribute
+in the attribute group definition becomes a part of the [attribute uses]
+property of the referencing complex type definition. Each attribute is
+mapped to a Java property as described in
+link:jaxb.html#a1252[See Attribute use]“. If the attribute group
+definition contains an attribute wildcard, denoted by the
+_xs:anyAttribute_ element, then the referencing complex type definition
+will contain a property providing access to wildcard attributes as
+described in link:jaxb.html#a1306[See Attribute Wildcard]“.
+
+=== [[a996]]Model Group Definition
+
+When a named model group definition is
+referenced, the JAXB property set representing its content model is
+aggregated into the Java value class representing the complex type
+definition that referenced the named model group definition as
+illustrated in link:jaxb.html#a999[See Binding for a reference
+to a model group definition.]”
+
+
+
+image:xmlb-16.png[image]
+
+=== [[a999]]Binding for a reference to a model group definition.
+
+This binding style results in the same
+properties occurring within both Java value class’s A and C to represent
+the referenced Model Group B’s content model.
+
+When a model group definition’s content model
+contains an XML Schema component that is to be bound to a Java value
+class, element class or enum type, it is desirable to only create a
+single Java representation, not one for each complex content that
+references the named model group definition. This default binding from a
+model group definition’s content model is defined in
+link:jaxb.html#a1012[See Deriving Class Names for Named Model
+Group Descendants]."
+
+To meet the JAXB 2.0 goal of predictable
+unmarshalling of invalid XML content, the JAXB 1.0 customization for
+binding a model group to a JAXB mapped class is no longer supported.
+link:jaxb.html#a386[See Flexible Unmarshalling]“details the
+rationale behind this change.
+
+=== Bind to a set of properties
+
+A non-repeating reference to a model group
+definition, when the particle referencing the group has _\{max occurs}_
+equal to one, results in a set of content properties being generated to
+represent the content model. link:jaxb.html#a1332[See Content
+Model - Particle, Model Group, Wildcard]” describes how a content model
+is bound to a set of properties and has examples of the binding.
+
+=== Bind to a list property
+
+A reference to a model group definition from
+a particle with a repeating occurrence is bound by default as specified
+in link:jaxb.html#a1402[See Bind a repeating occurrence model
+group]“.
+
+=== Example:
+
+Schema fragment contains a particle that
+references the model group definition has a _\{maxOccurs}_ value greater
+than one.
+
+<xs:group name="AModelGroup"> +
+<xs:choice> +
+<xs:element name="A" type="xs:int"/> +
+<xs:element name="B" type="xs:float"/> +
+</xs:choice> +
+</xs:group> +
+ +
+<xs:complexType name="foo"> +
+<xs:sequence> +
+<xs:group ref="AModelGroup" maxOccurs="unbounded"/> +
+<xs:element name="C" type="xs:float"/> +
+</xs:sequence> +
+</xs:complexType>
+
+Derived Java representation:
+
+ public class Foo \{ +
+/** A valid general content property of AModelGroup content +
+model.*/ +
+@XmlElements(\{@XmlElement(type=Integer.class, name="A"), +
+@XmlElement(type=Float.class, name="B")}) +
+java.util.List<Object> getAModelGroup() \{...} +
+ +
+float getC() \{...} +
+void setC(float value) \{...} +
+};
+
+=== [[a1012]]Deriving Class Names for Named Model Group Descendants
+
+When a model group definition’s content model
+contains XML Schema components that need to be bound to a Java class or
+interface, this section describes how to derive the package and name for
+the Java value class, enum type or element class derived from the
+content model of the model group definition. The binding of XML Schema
+components to Java classes/interfaces is only performed once when the
+model group definition is processed, not each time the model group
+definition is referenced as is done for the property set of the model
+group definition.
+
+XML Schema components occurring within a
+model group definition’s content model that are specified by this
+chapter and the customization chapter to be bound to a Java value class,
+interface or typesafe enum class are bound as specified with the
+following naming exceptions:
+
+* _package_ : The element class, Java value
+class or typesafe enum class is bound in the Java package that
+represents the target namespace containing the model group definition.
+* _name_ : The name of the interface or
+class is generated as previously specified with one additional step to
+promote uniqueness between interfaces/classes promoted from a model
+group definition to be bound to a top-level class within a Java package.
+By default, a prefix for the interface/class name is computed from the
+model group definition’s _\{name}_ using the XML name to Java identifier
+algorithm.If the schema customization _[jaxb:globalBindings]_ @
+_localScoping_ has a value of _toplevel_ , then a prefix is not
+generated from the model group definition’s _\{name}_ .
+
+For example, given a model group definition
+named _Foo_ containing an element declaration named _bar_ with an
+anonymous complex type definition, the anonymous complex type definition
+is bound to a Java value class with the name _FooBar_ . The following
+figure illustrates this example.
+
+
+
+image:xmlb-17.png[image]
+
+=== Default binding for anonymous type def within a model group definition.
+
+Note that even customization specified Java
+value class, interface or typesafe enum class names are prepended with
+the model group definition’s name. Thus, if a model group definition
+named _Foo_ contains an anonymous simple type definition with a typesafe
+enum class customization name of _Colors,_ the enum type name is
+_FooColors_ .
+
+=== Attribute Declaration
+
+An attribute declaration is bound to a Java
+property when it is referenced or declared, as described in
+link:jaxb.html#a1252[See Attribute use],” from a complex type
+definition.
+
+=== [[a1023]]Element Declaration
+
+This section describes the binding of an XML
+element declaration to a Java representation. For a description of how
+this binding has changed since the previous version, see
+link:jaxb.html#a680[See Java Element Representation Summary]“.
+This section introduces why a JAXB technology user has to use instances
+of JAXB element as opposed to instances of Java datatypes or Java value
+class when manipulating XML content.
+
+An XML element declaration is composed of the
+following key components:
+
+* its qualified name is \{target namespace}
+and \{name}
+* its value is an instance of the Java class
+binding of its \{type definition}
+* whether the element’s content is
+_\{nillable}_
+
+Typically, an instance of
+_javax.xml.bind.JAXBElement<T>_ , returned by an element factory method,
+__ represents an element declaration’s key components. An instance of a
+Java value class or content interface represents only the value of an
+element. Commonly in JAXB binding, the Java representation of XML
+content enables one to manipulate just the value of an XML element, not
+an actual element instance. The binding compiler statically associates
+the XML element qualified name to a content property and this
+information is used at unmarshal/marshal time. For cases where the
+element name can be dynamically altered at runtime, the JAXB user needs
+to manipulate elements, not element values. The following schema/derived
+Java code example illustrates this point.
+
+=== Example:
+
+Given the XML Schema fragment:
+
+<xs:complexType name="chair_kind"> +
+<xs:sequence> +
+<xs:element name="has_arm_rest" type="xs:boolean"/> +
+</xs:sequence> +
+</xs:complexType> +
+
+Schema-derived Java value class:
+
+public class ChairKind \{ +
+boolean isHasArmRest() \{...} +
+void setHasArmRest(boolean value) \{...} +
+}
+
+A user of the Java value class _ChairKind_
+never has to create a Java instance that both has the value of local
+element _has_arm_rest_ and knows that its XML element name is
+_has_arm_rest_ . The user only provides the value of the element to the
+content-property _hasArmRest_ . A JAXB implementation associates the
+content-property _hasArmRest_ with XML element name _has_arm_rest_ when
+marshalling an instance of _ChairKind_ .
+
+The next schema/derived Java code example
+illustrates when XML element information can not be inferred by the
+derived Java representation of the XML content. Note that this example
+relies on binding described in link:jaxb.html#a1384[See Bind
+wildcard schema component].”
+
+=== Example:
+
+<xs:complexType name="chair_kind"> +
+<xs:sequence> +
+<xs:any/> +
+</xs:sequence> +
+</xs:complexType> +
+ +
+public class ChairKind \{ +
+@XmlAnyElement(lax="true") +
+java.lang.Object getAny() \{...} +
+void setAny(java.lang.Object elementOrValue) \{...} +
+}
+
+For this example, the user can provide an
+Element instance to the _any_ content-property that contains both the
+value of an XML element and the XML element name since the XML element
+name could not be statically associated with the content-property _any_
+when the Java representation was derived from its XML Schema
+representation. The XML element information is dynamically provided by
+the application for this case. link:jaxb.html#a1332[See Content
+Model - Particle, Model Group, Wildcard] cover additional circumstances
+when one can use JAXB elements.
+
+=== [[a1040]]Bind to _JAXBElement<T>_ Instance
+
+The characteristics of the generated
+ObjectFactory element factory method that returns an _JAXBElement<T>_
+instance are derived in terms of the properties of the
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+* The element factory method is generated
+into the _ObjectFactory_ class in the Java package that represents the
+binding of the element declaration’s \{target namespace}.
+* The element factory method returns an
+instance of _javax.xml.bind.JAXBElement<T>_ , where _T_ is the Java
+value class representing the _\{type definition}_ of the element
+declaration. The factory method sets the element name of the returned
+instance to the element declaration’s fully qualified name.
+* The element factory method has a single
+parameter that is an instance of type _T_ , where T is the Java value
+class representing the _\{type definition}_ of the element declaration.
+* The name of the factory method is generated
+by concatenating the following components:
+* The string constant _create_ .
+* By default, if the element declaration is
+nested within another XML Schema component, then the concatenation of
+all outer Java class names representing those XML Schema components. If
+the schema customization _[jaxb:globalBindings]_ @ _localScoping_ has a
+value of toplevel, skip this step.
+* A name that is generated from the element
+declaration’s _\{name}_ using the XML Name to Java identifier name
+mapping algorithm specified in link:jaxb.html#a4656[See The Name
+to Identifier Mapping Algorithm].
+* The _JAXBElement<T>_ property for nil __
+test whether an element’s content model is _xsi:nil="true"_ .
+
+For example, an element declaration named
+_Foo_ __ with a type of __ _xs:int_ __ that is nested within the content
+model of complex type definition _Bar_ would have the following factory
+method generated in the containing Java package’s _ObjectFactory_ class:
+
+JAXBElement<Integer> createBarFoo(Integer
+value) \{...}
+
+Default binding rules require an element
+declaration to be bound to element factory method under the following
+conditions:
+
+* All non-abstract, named element
+declarations with global \{scope} are bound to an element factory method
+that returns an _JAXBElement<T>_ instance. The rationale is that any
+global element declaration can occur within a wildcard context and one
+might want to provide element instances, not instances of the element’s
+type, the element’s value, for this case.
+* All local element declarations, having a
+\{scope} of a complex type definition, occurring within content that is
+mapped to a general content property of JAXB elements must have an
+element factory method generated. General content property is specified
+in link:jaxb.html#a1344[See General content property]” An
+example of when a content model is mapped to a general content property,
+forcing the generation of element declarations is at
+link:jaxb.html#a1359[See Examples].”
+
+The schema-derived element factory method is
+annotated, either explicitly or by default mapping annotations, with the
+mapping annotation _@XmlElementDecl_ , specified in Section 8. The
+_@XmlElementDecl_ annotation elements are derived in terms of the
+abstract model properties for an element declaration summarized in
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+=== Annotate element instance factory with @XmlElementDecl element-value pairs.
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlElementDecl element
+|@XmlElementDecl value
+|name |element
+declaration’s _\{name}_
+
+|namespace |
+_\{target namespace}_
+
+|scope |If
+_\{scope}_ is _global_ , _JAXBElement.GlobalScope.class_ . else the JAXB
+Java value class representing the _\{scope}_ ing complex type
+definition.
+
+|substitutionHeadName
+|If optional _\{substitution group
+affiliation}_ exists, its local name.
+
+|substitutionHeadNamespace
+|If optional _\{substitution group
+affiliation}_ exists, its namespace.
+|===
+
+The element declaration’s _\{type}_ can
+result in additional JAXB annotations being generated on the element
+instance factory. For more details, see link:jaxb.html#a820[See
+Annotations for standard XML datatypes]“and @XmlList in
+link:jaxb.html#a883[See List]“.
+
+The schema-derived ObjectFactory class
+containing the @XmlElementDecl annotations is annotated with
+@XmlRegistry annotation.
+
+=== [[a1068]]Bind to Element Class
+
+link:jaxb.html#a1698[See <class>
+Declaration]“customization enables the binding of an element declaration
+with a named type definition to a schema-derived Element class. The
+characteristics of the schema-derived Element class are derived in terms
+of the properties of the link:jaxb.html#a4937[See Element
+Declaration Schema Component] as follows:
+
+* The name of the generated Java Element
+class is derived from the element declaration \{name} using the XML Name
+to Java identifier mapping algorithm for class names.
+* Each generated Element class must extend
+the Java value class _javax.xml.bind.JAXBElement_ <T>. The next bullet
+specifies the schema-derived Java class name to use for generic
+parameter _T_ .
+* If the element declaration’s \{type
+definition} is
+* Anonymous
+
+Generic parameter _T_ from the second bullet
+is set to the schema-derived class represented the anonymous type
+definition generated as specified in Section 6.7.3.
+
+* Named
+
+Generic parameter T from the second bullet is
+set to the Java class representing the element declaration’s \{type
+definition}.
+
+The _ObjectFactory_ method to create an
+instance of name has a single parameter that is an instance of type _T_
+. By default, the name of the ObjectFactory method is derived by
+concatenating outerClassNames and name. When schema customization,
+_[jaxb:globalBindings]_ _@localScoping,_ specified in Section
+_link:jaxb.html#a1582[See Usage],_ has a value of _toplevel_ ,
+then the outer Classnames are ommitted from the factory method name.
+
+* If \{scope} is
+* _Global:_ The derived Element class is
+generated into the Java package that represents the binding of \{target
+namespace}.
+* _A Complex Type Definition:_ By default,
+the derived Element class is generated within the Java value class
+represented by the complex type definition value of \{scope}. When
+_@localScoping_ is _toplevel_ , the derived element class is generated
+as a toplevel class.
+* The property for nil __ test whether
+element’s content model is _xsi:nil="true"_ .
+* Optional \{value constraint} property with
+pair of _default_ or _fixed_ and a value. +
+If a default or fixed value is specified, the data binding system must
+substitute the default or fixed value if an empty tag for the element
+declaration occurs in the XML content.
+
+A global binding customization,
+_@generateElementClass,_ specified in link:jaxb.html#a1580[See
+<globalBindings> Declaration]“enables this binding over the default
+binding specified in the previous subsection.
+
+=== [[a1084]]Binding of an anonymous complex type definition
+
+An anonymous complex type definition is bound
+to a generated schema-derived Java value class by default.
+
+The naming characteristics of the generated
+Java value class is derived in terms of the properties of the
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+* The name of the generated Java value class
+is derived from the element declaration \{name} using the XML Name to
+Java identifier
+* The _package_ of the generated Java value
+class is the same as the package derived from the element declaration’s
+_\{target namespace}_ .
+* The _outer class names_ of the generated
+Java value class is determined by the element declaration’s _\{scope}._
+If _\{scope}_ is:
+* Global +
+There is no outer class name.
+* A Complex Type Definition +
+By default, the derived Java value class is generated nested within the
+Java value class represented by the complex type definition value of
+\{scope}. The derived Java value is not generated nested when schema
+customization _[globalBindings]_ has attribute _@localScoping_ with a
+value of _toplevel_ _._
+* _base class:_ Same as defined in
+link:jaxb.html#a933[See Java value class]“.
+* _property set:_ As defined in
+link:jaxb.html#a933[See Java value class]“.
+* A type factory method is generated in the
+package’s _ObjectFactory_ class introduced in
+link:jaxb.html#a482[See Java Package].” The factory method
+returns the type of the Java value class. The name of the factory method
+is generated by concatenating the following components:
+* The string constant _create_ .
+* If the element declaration containing the
+anonymous complex type definition is nested within another complex type
+definition representing a value class and [globalBindings] @localScoping
+has a value of _nested_ , then the concatenation of all outer Java class
+names. This step is skipped when @localScoping has a value of _toplevel_
+.
+* The _name_ of the Java value class.
+
+The schema-derived value class is annotated
+with the mapping annotation _@XmlType_ , specified in Section
+link:jaxb.html#a2578[See @XmlType]. The _@XmlType_ annotation
+elements are set as described in link:jaxb.html#a956[See
+Annotate Java value class with @XmlType element-value pairs] with one
+exception: _@XmlType.name()_ is set to the empty string.
+
+As long as the element declaration is not one
+of the exception cases specified in link:jaxb.html#a1113[See
+Bind Element Declaration to JAXBElement]", the schema-derived value
+class is annotated with the mapping annotation _@XmlRootElement_
+specified in Section 8. The _@XmlRootElement_ annotation elements are
+derived in terms of the abstract model properties for the referenced
+global element declaration summarized in
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+=== Annotate JAXB Mapped Class with @XmlRootElement element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlRootElement element
+|@XmlRootElement value
+|namespace a|
+When element declaration _\{target
+namespace}_ is absent, +
+(i.e. unqualified local element declaration), @XmlElement.namespace() is
+not set. +
+
+Otherwise, set @XmlElement.namespace() to
+value of _\{target namespace}_ . (either a qualified local element
+declaration or a reference to a global element)
+
+Note: same result could be achieved with
+package level annotation of @XmlSchema and not setting
+@XmlElement.namespace.
+
+|name |element
+declaration _\{name}_
+|===
+
+=== Example:
+
+Given XML Schema fragment:
+
+<xs:element name="foo"> +
+<xs:complexType> +
+<xs:sequence> +
+<xs:element name="bar" type="xs:int"/> +
+</xs:sequence> +
+</xs:complexType> +
+</xs:element>
+
+Derived Java code:
+
+/*Value class representing element
+declaration with an anonymous complex type definition.*/ +
+@XmlType(name="") +
+@XmlRootElement(namespace="", name="foo") +
+public class Foo \{ +
+int getBar() \{...} +
+void setBar(int value) \{...} +
+}; +
+
+=== [[a1113]]Bind Element Declaration to JAXBElement
+
+An element declaration with an anonymous
+complex type definition is not bound to a _@XmlRootElement_ ,annotated
+schema-derived class when the element declaration is:
+
+* nillable
+* the head element or a member of a
+substitution group
+* non-global (i.e. declared within a complex
+type definition)
+
+When one or more of the above conditions are
+met, the schema-derived class representing the anonymous complex type
+definition must not be annotated with _@XmlRootElement_ . Instead, an
+element factory that returns _JAXBElement<_ _anonymousTypeValueClass_
+_>_ may be generated as specified in link:jaxb.html#a1040[See
+Bind to JAXBElement<T> Instance]“.
+
+=== Example:
+
+Given XML Schema fragment:
+
+ +
+<xs:element name="foo" nillable="true"> +
+<xs:complexType> +
+<xs:sequence> +
+<xs:element name="bar" type="xs:int"/> +
+</xs:sequence> +
+</xs:complexType> +
+</xs:element> +
+
+Derived Java code:
+
+/*Value class representing anonymous complex
+type definition.*/ +
+@XmlType(name="") +
+public class Foo \{ +
+int getBar() \{...} +
+void setBar(int value) \{...} +
+}; +
+@XmlRegistry +
+class ObjectFactory \{ +
+// type factory method +
+Foo createFoo() \{...} +
+// element factory method +
+@XmlElementDecl(name="foo", namespace="", nillable="true") +
+JAXBElement<Foo> createFoo(Foo value) \{...} +
+}
+
+=== Bind to a Property
+
+A local element declaration is bound by
+default to a Java property as described in
+link:jaxb.html#a541[See Properties]. The characteristics of the
+Java property are derived in terms of the properties of the
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+and link:jaxb.html#a5022[See Particle Schema Component] as
+follows:
+
+* The name of the Java property is derived
+from the \{element declaration} property’s \{name} property using the
+XML Name to Java Identifier mapping algorithm described in
+link:jaxb.html#a4656[See The Name to Identifier Mapping
+Algorithm].
+* A _base type_ for the Java property is
+derived from the _\{element declaration}_ property’s _\{type
+definition}_ property as described in binding of Simple Type Definition
+in _link:jaxb.html#a702[See Simple Type Definition]_ .” or
+link:jaxb.html#a917[See Complex Type Definition]". If the base
+type is initially a primitive type and this JAXB property is _optional_
+, the _[jaxb:globalBinding]_ customization _@optionalProperty_ controls
+the binding of an optional primitive property as described in
+link:jaxb.html#a1582[See Usage]“.
+* An optional _predicate_ for the Java
+property is constructed from the _\{element declaration}_ property’s
+_\{type definition}_ property as described in the binding of simple type
+definition to a Java representation.
+* An optional _collection type_ for the Java
+property is derived from:
+* _\{element declaration}_ property’s
+_\{type definition}_ property as described in the binding of simple type
+definition to a Java representation
+* the \{particle} property’s \{max occurs}
+value being greater than one.
+* Element defaulting +
+The default value is derived from the element declaration’s \{value
+constraint} property’s value. Unlike attribute defaulting, an element
+only defaults when there is an empty element tag in an xml document. The
+element’s default value is captured by mapping annotation
+_@XmlElement.defaultValue()_ . The unmarshaller sets the property to
+this default value when it encounters an empty element tag. The
+marshaller can output an empty element tag whenever the element’s
+_@XmlValue_ property value is the same as its defaulted value..
+* A local element declaration that binds to a
+JAXB property with a primitive base type is bound as an _optional_ JAXB
+property if the element declaration is a member of a choice model group
+or the element declaration’s particle has optional occurrence, \{ _min
+occurs} value is "0",_ or belongs to a model group that has optional
+occurrence. By default, the optional JAXB property binds the property’s
+base type to the Java wrapper class for the primitive type. One can test
+and set the absence of an optional property using null. The
+_[jaxb:globalBinding]_ customization _@optionalProperty_ controls
+alternative bindings of an optional primitive property as described in
+link:jaxb.html#a1582[See Usage]“.
+* If the element declaration’s \{nillable}
+property is _“true”_ , the base type for the Java property is mapped to
+the corresponding Java wrapper class for the Java primitive type.
+Setting the property to the _null_ value indicates that the property has
+been set to the XML Schema concept of @xs: _nil=’true_ ’.
+
+This Java property is a member of the Java
+value class that represents the binding of the complex type definition
+containing the local element declaration or reference to global element.
+
+The schema-derived JAXB property getter
+method is annotated, either explicitly or by default mapping
+annotations, with the mapping annotation _@XmlElement_ , specified in
+Section 8, “@XmlElement”. The _@XmlElement_ annotation elements are
+derived in terms of the abstract model properties for the referenced
+global element declaration 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
+|namespace a|
+When element declaration _\{target
+namespace}_ is absent, +
+(i.e. unqualified local element declaration), @XmlElement.namespace() is
+not set. +
+
+Otherwise, set @XmlElement.namespace() to
+value of _\{target namespace}_ . (either a qualified local element
+declaration or a reference to a global element)
+
+Note: same result could be achieved with
+package level annotation of @XmlSchema and not setting
+@XmlElement.namespace.
+
+|name |element
+declaration _\{name}_
+
+|nillable |element
+declaration _\{nillable}_
+
+|defaultValue |if
+element declaration _\{value constraint}_ is not absent, set
+defaultValue() to _\{value constraint}_ ’s value.
+|===
+
+link:jaxb.html#a1240[See Xml Schema
+example containing an element substitution group]illustrates how to
+define an element substitution group and to reference the head element
+of the substitution group within an Xml Schema.
+link:jaxb.html#a1242[See avo binding of Xml Schema from CODE
+EXAMPLE 6-5] illustrates the Java bindings of the element substation
+enabled schema. link:jaxb.html#a1244[See Element substitution
+using Java bindings from CODE EXAMPLE 6-6] demonstrates element
+substitution using the JAXB API.link:jaxb.html#a1246[See Invalid
+element substitution using Java bindings from CODE EXAMPLE 6-6]
+illustrates invalid element substitution handling.
+
+=== [[a1148]]Type Substitution of a Complex Type Definition
+
+link:jaxb.html#a917[See Complex Type
+Definition]“describes that when a complex type definition is mapped to
+Java value class that the type definition derivation hierarchy is
+preserved in the Java class hierarchy. This preservation makes it quite
+natural for Java to support the Xml Schema mechanism type substitution
+across all complex type definitions.
+
+Performing an invalid type substitution is
+not detected as a fail-fast check when setting the JAXB property or
+checked as part of marshalling the element declaration. Invalid type
+substitution can be checked by optional validation that can be enabled
+as part of unmarshalling or marshalling process.
+
+The following three code examples illustrate
+how type substitution is supported in JAXB 2.0 for a complex type
+definition hierarchy.
+
+=== [[a1152]]Xml Schema example containing type derivation hierarchy
+
+ +
+<xs:schema targetNamespace="travel:acme" xmlns:a="travel:acme"> +
+ +
+<!-- Define type definition derivation hierarchy --> +
+<xs:complexType name=" _TransportType_ ">...<\xs:complexType> +
+<xs:complexType name=" _PlaneType_ "> +
+<xs:extension base="a:TransportType">...<\xs:complexType> +
+<xs:complexType name=" _AutoType_ "> +
+<xs:extension base="a:TransportType">...<\xs:complexType> +
+<<xs:complexType name=" _SUV_ "> +
+<xs:extension base="a:AutoType">...<\xs:complexType> +
+ +
+<xs:complexType name=" _itinerary_ "> +
+<xs:sequence> +
+<!-- Type substitution possible for " _transport"._ -->. +
+<xs:element name=" _transport_ " type=" _TransportType_ "/> +
+</xs:sequence> +
+</xs:complexType> +
+</xs:schema> +
+
+=== [[a1154]]Java binding of Xml Schema from link:jaxb.html#a1240[See Xml Schema example containing an element substitution group]
+
+package travel.acme; +
+ +
+// Type derivation hierarchy from schema is preserved in Java binding. +
+public class _TransportType_ \{ ... } +
+public class _PlaneType_ extends TransportType \{ ... } +
+public class _AutoType_ extends TransportType \{ ... } +
+public class _SUV_ extends AutoType \{ ... } +
+ +
+public class ObjectFactory \{ +
+// Type Factories +
+TransportType createTransportType()\{...} +
+AutoType createAutoType()\{...} +
+PlaneType createPlaneType()\{...} +
+TrainType createSUV()\{...} +
+} +
+ +
+public class Itinerary \{ +
+// Simple property supports type substitution. +
+_TransportType_ getTransport()\{...} +
+void setTransport( _TransportType_ value) +
+}
+
+=== Type substitution using Java bindings from link:jaxb.html#a1242[See avo binding of Xml Schema from CODE EXAMPLE 6-5]
+
+ +
+ObjectFactory of = ...; +
+Itinerary itinerary = of.createItinerary(); +
+itinerary.setTransport(of.createTransportType); // Typical Use +
+ +
+// Type Substitution +
+// transport marshalled as <e:transport xsi:type="e:AutoType">> +
+itinerary.setTransport(of.createAutoType()); +
+ +
+// transport marshalled as <e:transport xsi:type="e:PlaneType">> +
+itinerary.setTransport(of.createPlaneType());
+
+=== [[a1158]]Type Substitution of a Simple Type Definition
+
+An XML element declaration having a simple
+type definition is bound most naturally to a JAXB property with a base
+type that is a primitive Java datatype. Unfortunately, this strongly
+typed binding conflicts with fully supporting type substitution of a
+simple type definition. Unlike the JAXB binding of complex type
+definitions, the simple type derivation hierarchy is not preserved when
+binding builtin XML Schema simple type definitions to corresponding Java
+datatypes as specified in link:jaxb.html#a715[See Atomic
+Datatype]“. Since there is not a natural Java inheritance hierarchy to
+support simple type substitution, a JAXB property customization is
+required to enable optimal support of simple type substitution.
+
+For example, the most natural binding of an
+XML Schema built-in datatype _xs:int_ is to the Java primitive datatype,
+_int_ . However, simple type substitution implies that an _xs:short_ or
+a complex type definition that derives by extension from _xs:int_ can be
+type substituted for an _xs:int_ within an XML document using the
+_xsi:type_ attribute. The strongly typed JAXB property with Java type
+_int_ would never allow for a Java value class for the complex type to
+be assigned to a JAXB property of type _int_ .
+
+By default, unmarshalling handles simple type
+substitution by assigning the relevant part of the type substituted
+content to the JAXB property. When the value of the xsi:type attribute
+resolves to:
+
+* a type that derives by restriction from the
+element’s schema type. +
+The substituted value is always parsable into a legal value of the base
+type of the JAXB property being type substituted.
+* a complex type that derives by extension
+from element’s schema type. +
+The JAXB binding of the substituted complex type definition must have
+one JAXB property annotated with an _@XmlValue_ that is assignable to
+the type substituted JAXB property’s base type. Attribute(s) associated
+with the complex type definition can not be preserved by the default
+binding.
+
+The rationale behind the default binding is
+that substitution of a simple type definition occurs rarely. The default
+JAXB binding is more convenient and precise for programmer to use. Its
+one drawback is that it does not faithfully preserve _xsi:type_
+occurring in an XML document.
+
+To enable more comprehensive support of
+simple type substituting of an XML element with a simple type
+definition, the JAXB property customization specified in
+link:jaxb.html#a1809[See Generalize/Specialize baseType with
+attribute @name]“enables setting the property’s base type to the more
+general type of _java.lang.Object._ This binding allows for retention of
+the XML document _xsi:type_ and attributes associated with complex type
+definition substituted for an XML element with a simple type definition.
+When an _xsi:type_ value refers to a type definition not registered with
+_JAXBContext_ instance, the content is unmarshalled as the element’s
+schema type.
+
+To preserve an application-defined simple
+type definition involved in simple type substitution, it must be mapped
+to a JAXB mapped class as described in link:jaxb.html#a803[See
+Bind to a JAXB mapped class]“. This can be achieved for all simple type
+definitions in a schema using the customization _<jaxb:globalBinding
+mapSimpleTypeDefs="true"/>_ or it can be achieved per simple type
+definition using <jaxb:class> customization. An invalid simple type
+substitution can be detected by JAXP 1.3 validation enabled at unmarshal
+or marshal time
+
+Below are examples of the type substitution
+of an XML element’s simple type definition for the default and
+customized binding.
+
+=== [[a1168]]Schema fragment to illustrate simple type substitution
+
+<xsd:element name="Price"> +
+<xsd:complexType> +
+<xsd:sequence> +
+<xsd:element name="name" type="xsd:string"/> +
+_<!-- element price subject to type substitution-> +
+_ <xsd:element name="price" type="xsd:int"/> +
+</xsd:sequence> +
+</xsd:complexType> +
+</xsd:element> +
+<xsd:complexType name="AmountType"> +
+<xsd:simpleContent> _<!-- type substitutable for xs:int --> +
+_ <xsd:extension base="xsd:int"> +
+<xsd:attribute name="currency" type="xsd:string"/> +
+</xsd:extension> +
+</xsd:simpleContent> +
+</xsd:complexType> +
+<xsd:simpleType name="AppInt"> +
+<xsd:restriction base="xsd:int"/> +
+</xsd:simpleType>
+
+=== [[a1170]]XML documents with simple type substitution
+
+<product> +
+<name>hotdog</name><price>3</price> +
+</product>
+
+<product> +
+<name>peanuts</name> +
+<price _xsi:type="short_ ">4</price> +
+</product>
+
+<product> +
+<name>popcorn</name> +
+<price _xsi:type="AppInt_ ">5</price> +
+</product>
+
+<product> +
+<name>sushi</name> +
+<price _xsi:type="AmountType"_ currency="yen">500</price> +
+</product>
+
+=== Default Handling of Simple Type Substitution
+
+=== [[a1176]]Default JAXB binding of link:jaxb.html#a1168[See Schema fragment to illustrate simple type substitution]
+
+public class AmountType \{ +
+@XmlValue +
+int getValue()\{...} void setValue(int value) \{...} +
+String getCurrency() \{...} void setCurrency(String value) \{...} +
+} +
+@XmlRootElement(namespace="", name="product") +
+public class Product \{ +
+int getPrice()\{...} void setPrice(int value) \{ ...} +
+int getName() \{...} void setName(String value) \{...} +
+}
+
+Unmarshalling XML document fragments from
+link:jaxb.html#a1170[See XML documents with simple type
+substitution] into link:jaxb.html#a1176[See Default JAXB binding
+of CODE EXAMPLE 6-1] JAXB binding of element _product_ results in the
+_xsi:type_ and attributes associated with JAXB mapped class _Price_
+being lost as part of the unmarshal process. This loss is illustrated by
+comparing link:jaxb.html#a1179[See Product instances from
+unmarshalling XML docs from CODE EXAMPLE 6-2] with
+link:jaxb.html#a1204[See Product instances from unmarshalling
+XML docs from CODE EXAMPLE 6-2].
+
+=== [[a1179]]Product instances from unmarshalling XML docs from link:jaxb.html#a1170[See XML documents with simple type substitution]
+
+[width="100%",cols="20%,20%,20%,20%,20%",options="header",]
+|===
+|document xsi:type
+| _Product.name +
+value_ | _Product.price +
+value_ | _Product.price +
+type_ | _marshal Product.price xsi:type_
+| |hotdog
+|3 |int
+|
+
+|xs:short |peanuts
+|4 |int
+|
+
+|AppInt |popcorn
+|5 |int
+|
+
+|AmountType |sushi
+|500 |int
+|
+|===
+
+=== Simple Type Substitution enabled by JAXB customizations.
+
+The simple type definition _AppInt_ is mapped
+to a JAXB class either by _<jaxb:class>_ customization or by
+_<jaxb:globalBindings mapSimpleTypeDef="true"/>_ . The JAXB property
+_Product.Price_ is mapped to a JAXB property with a general base type of
+_java.lang.Object_ with following external JAXB schema customization:
+
+<jaxb:bindings
+schemaLocation="link:jaxb.html#a1168[See Schema fragment to
+illustrate simple type substitution]" +
+node="//xsd:element[@name=’price’]"> +
+<jaxb:property> +
+<jaxb:baseType name="java.lang.Object"/> +
+</jaxb:property> +
+</jaxb:bindings>
+
+specified in link:jaxb.html#a1809[See
+Generalize/Specialize baseType with attribute @name]“.
+
+=== [[a1201]]Customized JAXB binding of link:jaxb.html#a1168[See Schema fragment to illustrate simple type substitution]
+
+public class AmountType \{ +
+@XmlValue +
+int getValue()\{...} void setValue(int value) \{...} +
+String getCurrency() \{...} void setCurrency(String value) \{...} +
+} +
+public class AppInt \{ +
+@XmlValue +
+int getValue() \{...} void setValue(int value) \{...} +
+} +
+public class Product \{ +
+// enable simple type substitution with base type of Object +
+@XmlElement(type=java.lang.Integer.class) +
+Object getPrice()\{...} void setPrice(Object value) \{ ...} +
+int getName() \{...} void setName(String value) \{...} +
+}
+
+Unmarshalling XML document fragments from
+link:jaxb.html#a1170[See XML documents with simple type
+substitution] into link:jaxb.html#a1201[See Customized JAXB
+binding of CODE EXAMPLE 6-1] JAXB binding of element _product_ preserves
+the _xsi:type_ and attributes associated with JAXB mapped class
+_AmountType_ is illustrated in link:jaxb.html#a1204[See Product
+instances from unmarshalling XML docs from CODE EXAMPLE 6-2].
+
+=== [[a1204]]Product instances from unmarshalling XML docs from link:jaxb.html#a1170[See XML documents with simple type substitution]
+
+[width="100%",cols="20%,20%,20%,20%,20%",options="header",]
+|===
+|document xsi:type
+| _Product.name +
+value_ | _Product. +
+price +
+value_ | _Product. +
+price +
+Java type_ | _Marshal +
+Product. +
+price +
+_ _xsi:type_
+| |hotdog
+|3 |Integer
+|
+
+|xs:short |peanuts
+|4 |Short
+|xs:short
+
+|AppInt |popcorn
+|5 |AppInt
+|AppInt
+
+|AmountType |sushi
+|\{value=500, +
+currency=”yen”} |AmountType
+|AmountType
+|===
+
+=== [[a1223]]Bind to a Simple Element property
+
+Element substitution group is an Xml Schema
+mechanism that enables the substitution of one named element for
+another. This section uses terms and concepts described in Section 4.6
+of [XSD Part 0] and normatively defined in Section 2.2.2.2 of [XSD Part
+1].
+
+The following constraints assist in defining
+the Java binding that enables element substitution group:
+
+. Element substitution is only possible for a
+reference to a global element.
+. Assuming the absence of the Xml Schema
+constraints on substitution, any global element can be made the head
+element of a substitution group.
+. All elements in a substitution group must
+derive from or have the same type definition as the head element.
+
+{empty}To support element substitution, for
+each global element reference to a head element of a substitution group
+or to an abstract element, it is necessary to generate the Element
+property bindings defined in link:jaxb.html#a630[See Element
+Property].link:#a5373[22] This property enables the overriding
+of the schema-specified element name bound to a JAXB property by setting
+and getting the JAXB element representation,
+_javax.xml.bind.JAXBElement<T>_ . The name property of the JAXBElement
+_<T>_ instance overrides the schema specified element declaration name.
+To enable the passing of any element that could be part of the element
+substitution group, it is necessary to accept any JAXBElement derivation
+that extends Java binding of the head element’s type definition. Using
+the upper bounded wildcard notation for a generic JAXBElement container,
+_JAXBElement<? extends T>_ , the element property is able to get and set
+any element that has an element value that is a subtype of T. Compile
+time checking will not allow invalid JAXBElement derivations to be
+passed to the Element property setter. When the element type is correct
+but the element name is not part of the substitution group, this invalid
+scenario can only be caught at runtime by validation or optional
+fail-fast checking by the element property
+setter.link:#a5374[23]
+
+The schema-derived Element property getter
+method is annotated, either explicitly or by default mapping
+annotations, with the mapping annotation _@XmlElementRef_ , specified in
+Section 8.10.3, “@XmlElementRef”. The _@XmlElementRef_ annotation
+elements are derived in terms of the abstract model properties for the
+referenced global element declaration summarized in
+link:jaxb.html#a4937[See Element Declaration Schema Component]
+as follows:
+
+=== Annotate Element Property with @XmlElementRef element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlElementRef element
+|@XmlElementRef value
+|value
+|javax.xml.bind.JAXBElement.class
+
+|namespace
+|referenced element declaration _\{target
+namespace}_
+
+|name |referenced
+element declaration _\{name}_
+|===
+
+link:jaxb.html#a1240[See Xml Schema
+example containing an element substitution group]illustrates how to
+define an element substitution group and to reference the head element
+of the substitution group within an Xml Schema.
+link:jaxb.html#a1242[See avo binding of Xml Schema from CODE
+EXAMPLE 6-5] illustrates the Java bindings of the element substation
+enabled schema. link:jaxb.html#a1244[See Element substitution
+using Java bindings from CODE EXAMPLE 6-6] demonstrates element
+substitution using the JAXB API.link:jaxb.html#a1246[See Invalid
+element substitution using Java bindings from CODE EXAMPLE 6-6]
+illustrates invalid element substitution handling.
+
+=== [[a1240]]Xml Schema example containing an element substitution group
+
+<xs:schema targetNamespace="travel:acme"
+xmlns:a="travel:acme"> +
+ +
+<!-- See type definition derivation hierarchy defined in
+link:jaxb.html#a1152[See Xml Schema example containing type
+derivation hierarchy]for +
+complexType definitions TransportType, PlaneType, AutoType and SUV.--> +
+< +
+<!-- Define element substitution group. a:transport is head
+element.--> +
+<xs:element name="transport" type="a:TransportType"/> +
+<xs:element name="plane" type="a:PlaneType"
+substitutionGroup="a:transport"/> +
+<xs:element name="auto" type="a:AutoType"
+substitutionGroup="a:transport"/><!- +
+ +
+<xs:complexType name="itinerary"> +
+<xs:sequence> +
+<!-- Global element reference. +
+References head element of element substitution group. --> +
+<xs:element ref="a:transport"/> +
+</xs:sequence> +
+</xs:complexType> +
+<\xs:schema>
+
+=== [[a1242]]avo binding of Xml Schema from link:jaxb.html#a1240[See Xml Schema example containing an element substitution group]
+
+ppackage travel.acme; +
+public class ObjectFactory \{ +
+// Type Factories +
+TransportType createTransportType(); +
+AutoType createAutoType(); +
+PlaneType createPlaneType(); +
+TrainType createSUVType(); +
+ +
+// Element Instance Factories +
+JAXBElement<AutoType> createAuto(AutoType value); +
+JAXBElement<PlaneType> createPlane(PlaneType value); +
+JAXBElement<TransportType> createTrain(TransportType value); +
+} +
+ +
+// See Java binding of type derivation hierarchy in
+link:jaxb.html#a1154[See Java binding of Xml Schema from CODE
+EXAMPLE 6-5] +
+ +
+public class Itinerary \{ +
+// Element substitution supported by link:jaxb.html#a630[See
+Element Property]" +
+JAXBElement<? extends TransportType> getTransport(); +
+void setTransport(JAXBElement<? extends TransportType> value); +
+}
+
+=== [[a1244]]Element substitution using Java bindings from link:jaxb.html#a1242[See avo binding of Xml Schema from CODE EXAMPLE 6-5]
+
+ +
+ObjectFactory of = ...; +
+Itinerary itinerary = of.createItinerary(); +
+itinerary.setTransport(of.createTransportType()); // Typical use. +
+ +
+// Element substitution: +
+// Substitute <e:auto> for schema specified <e:transport>. +
+itinerary.setTransport(of.createAuto(of.createAutoType())); +
+ +
+// Substitute <e:plane> for schema specified <e:transport>> +
+itinerary.setTransport(of.createPlane(of.createPlaneType())); +
+ +
+// Combination of element and type substitution: +
+_// Substitutes <e:auto xsi:type="e:SUV"> for <e:transport>> +
+_ itinerary.setTransport(of.createAuto(of.createSUV()));
+
+=== [[a1246]]Invalid element substitution using Java bindings from link:jaxb.html#a1242[See avo binding of Xml Schema from CODE EXAMPLE 6-5]
+
+ +
+<!-- Add elements not part of element substitution group. --> +
+<xs:element name="apple" type="xsd:string"/> +
+<xs:complexType name="spaceShuttle"> +
+<xs:extension base="a:TransportType">...<\xs:complexType> +
+<xs:element name="spaceShuttle" type="a:spaceShuttleType"> +
+ +
+ObjectFactory of = ...; +
+Itinerary itinerary = of.createItinerary(); +
+// Invalid element substitution +
+// compile time error: method not found +
+//Element apple of type JAXBElement<String> does not match +
+//bounded wildcard JAXBElement<? extends TransportType>. +
+itinerary.setTransport(of.createApple("granny smith")); +
+ +
+//Invalid element substitution detected by validation. +
+// Element spaceShuttle not part of substitution group. +
+// Adding _substitutionGroup="transport"_ to line 4 fixes this. +
+itinerary.setTranport( +
+of.createSpaceShuttle(of.createSpaceShuttleType()));
+
+=== Bind to an Element Collection property
+
+A repeating occurrence element declaration
+that is element substitutable binds solely to a JAXB Collection property
+of JAXBElement.
+
+=== Bind repeating occurrence element substitution variant of link:jaxb.html#a1240[See Xml Schema example containing an element substitution group]
+
+<!--deleted schema that remains same --> +
+<xs:complexType name="itinerary"> +
+<xs:sequence> +
+<!-- Repeating occurance to substitutable global element reference.
+--> +
+<xs:element ref="a:transport" _maxOccurs="unbounded"_ /> +
+</xs:sequence> +
+</xs:complexType> +
+<\xs:schema> +
+ +
+Java Binding: +
+public class Itinerary \{ +
+List<JAXBElement<? extends TransportType>> getTransport(); +
+}
+
+=== [[a1252]]Attribute use
+
+A ‘required’ or ‘optional’ attribute use is
+bound by default to a Java property as described in
+link:jaxb.html#a541[See Properties]. The characteristics of the
+Java property are derived in terms of the properties of the
+link:jaxb.html#a5012[See Attribute Use Schema Component] and
+link:jaxb.html#a4965[See Attribute Declaration Schema Component]
+as follows:
+
+* The name of the Java property is derived
+from the \{attribute declaration} property’s \{name} property using the
+XML Name to Java Identifier mapping algorithm described in
+link:jaxb.html#a4656[See The Name to Identifier Mapping
+Algorithm].
+* A _base type_ for the Java property is
+derived from the _\{attribute declaration}_ property’s _\{type
+definition}_ property as described in binding of Simple Type Definition
+in _link:jaxb.html#a702[See Simple Type Definition]_ .”. If the
+base type is initially a primitive type and this JAXB property is
+_optional_ , the _[jaxb:globalBinding]_ customization
+_@optionalProperty_ controls the binding of an optional primitive
+property as described in link:jaxb.html#a1582[See Usage]“.
+* An optional _predicate_ for the Java
+property is constructed from the _\{attribute declaration}_ property’s
+_\{type definition}_ property as described in the binding of simple type
+definition to a Java representation.
+* An optional _collection type_ for the Java
+property is derived from the _\{attribute declaration}_ property’s
+_\{type definition}_ property as described in the binding of simple type
+definition to a Java representation.
+* The _default value_ for the Java property
+is the value from the attribute use’s \{value constraint} property. If
+the optional \{value constraint} is absent, the default value for the
+Java property is the Java default value for the base type.
+* The JAXB property is _optional_ when the
+attribute use’s _\{required}_ property is _false_ .
+
+This Java property is a member of the Java
+value class that represents the binding of the complex type definition
+containing the attribute use
+
+The JAXB property getter for this attribute
+is annotated, either explicitly or via default mapping, with the mapping
+annotation @XmlAttribute, specified in Section
+link:jaxb.html#a3230[See @XmlAttribute]. The @XmlAttribute
+element values are derived in terms of the properties of the
+link:jaxb.html#a5012[See Attribute Use Schema Component] and
+link:jaxb.html#a4965[See Attribute Declaration Schema Component]
+as follows:
+
+=== [[a1262]]Annotate Attribute property getter method with @XmlAttribute annotation
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlAttribute element
+|@XmlAttribute value
+|name |attribute
+declaration's \{name}
+
+|namespace a|
+if attribute declaration’s \{target
+namespace} absent, set to “”
+
+otherwise, set to \{target namespace}
+
+|required
+|attribute use's \{required}
+|===
+
+*
+
+=== Example:
+
+Given XML Schema fragment:
+
+<xs:complexType name="USAddress"> +
+<xs:attribute name="country" type="xs:string"/> +
+</xs:complexType>
+
+Default derived Java code:
+
+public class USAddress \{ +
+@XmlAttribute(name="country", targetNamespace="", +
+required="false"); +
+public String getCountry() \{...} +
+public void setCountry(String value) \{...} +
+}
+
+=== [[a1277]]Bind to a Java Constant property
+
+Rather than binding to a read/write JAXB
+property, an attribute use with a _fixed_ \{value constraint} property
+can be bound to a Java Constant property. This mapping is not performed
+by default since _fixed_ is only a validation constraint. The user must
+set the binding declaration attribute _fixedAttributeToConstantProperty_
+on _<jaxb:globalBinding>_ element as specified in
+link:jaxb.html#a1582[See Usage] or on _<jaxb:property>_ element
+as specified in link:jaxb.html#a1786[See Usage] to enable this
+mapping.
+
+=== Example:
+
+Given XML Schema fragment:
+
+<xs:annotation><xs:appinfo>
+
+ <jaxb:globalBindings
+fixedAttributeAsConstantProperty="true"/>
+
+</xs:appinfo></xs:annotation> +
+<xs:complexType name="USAddress"> +
+<xs:attribute name="country" type="xs:NMTOKEN" fixed="US"/> +
+</xs:complexType>
+
+If the appropriate binding schema
+customization enables mapping a fixed XML value to Java constant
+property, the following Java code fragment is generated.
+
+public class USAddress \{ +
+@XmlAttribute +
+public static final String COUNTRY="US"; +
+... +
+}
+
+The schema-derived constant for this fixed
+attribute is annotated, either explicitly or via default mapping, with
+the mapping annotation _@XmlAttribute._ The elements of _@XmlAttribute_
+are set as described in _link:jaxb.html#a1262[See Annotate
+Attribute property getter method with @XmlAttribute annotation]_
+
+Note that if derivation by restriction
+constrains an existing attribute declaration to be fixed, this
+refinement must not be bound to a constant property. The initial binding
+of the attribute to a JAXB property remains the only binding of the
+attribute in the Java class hierarchy.
+
+=== Contributions to Local Structural Constraint
+
+If the attribute use’s \{required} property
+is true, the local structural constraint for an instance of the Java
+value class requires that the corresponding Java property to be set when
+the Java value class instance is validated.
+
+=== [[a1290]]Binding an IDREF component to a Java property
+
+An element or attribute with a type of
+_xs:IDREF_ refers to the element in the instance document that has an
+attribute with a type of _xs:ID_ or derived from type _xs:ID_ with the
+same value as the _xs:IDREF_ value. Rather than expose the Java
+programmer to this XML Schema concept, the default binding of an
+_xs:IDREF_ component maps it to a Java property with a base type of
+_java.lang.Object_ . The caller of the property setter method must be
+sure that its parameter is identifiable. An object is considered
+identifiable if one of its properties is derived from an element or
+attribute that is or derives from type _xs:ID_ . The JAXB mapped class
+must have one property annotated with an @XmlID program annotation as it
+is specified in Section 8. There is an expectation that all instances
+provided as values for properties’ representing an _xs:IDREF_ should
+have the Java property representing the _xs:ID_ of the instances set
+before the content tree containing both the _xs:ID_ and _xs:IDREF_ is
+marshalled. If a property representing an _xs:IDREF_ is set with an
+object that does not have its _xs:ID_ set, the _NotIdentifiableEvent_ is
+reported by marshalling.
+
+* The name of the Java property is derived
+from the \{name} property of the attribute or element using the XML Name
+to Java Identifier mapping algorithm described in
+link:jaxb.html#a4656[See The Name to Identifier Mapping
+Algorithm].
+* A _base type_ for the Java property is
+java.lang.Object.
+* There is no _predicate_ for a property
+representing an _xs:IDREF_ .
+* An optional _collection type_
+* Default and fixed values can not be
+supported for an attribute with type _xs:IDREF_ .
+
+The schema-derived JAXB property representing
+xs:IDREF(s) is annotated, either explicitly or by default mapping
+annotations, with the mapping annotation @XmlIDREF, specified in Section
+8.
+
+=== Example:
+
+Given XML Schema fragment:
+
+<xs:complexType name="Book"> +
+<xs:sequence> +
+_<xs:element name="author" type="xs:IDREF"/> +
+_ <!-- ... --> +
+</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:
+
+public class Book \{ +
+@XmlIDREF +
+java.lang.Object getAuthor() \{...} +
+ +
+/** Parameter referencedObj should have an attribute or +
+* child element with base type of xs:ID by validation +
+* or marshal time. +
+*/ +
+void setAuthor(java.lang.Object referencedObj)\{...} +
+} +
+public class AuthorBio\{ +
+@XmlID +
+String getName()\{...} +
+void setName(String value)\{...} +
+}
+
+Demonstration of a Java content instance
+referencing another instance:
+
+Book book = ...; +
+AuthorBio authorBio = ...; +
+book.setAuthor(authorBio); +
+authorBio.setName("<some author’s name>"); +
+// The content instance root used to validate or marshal book must +
+// also include "authorBio" as a child element somewhere. +
+// A Java content instance is not included
+
+Note that _ID_ and _IDREF_ mechanisms do not
+incorporate type definitions that can be referenced. To generate
+stronger typing for a JAXB property representing an IDREF, the schema
+customization described in link:jaxb.html#a1809[See
+Generalize/Specialize baseType with attribute @name]" can be used to
+specialize the binding.. link:jaxb.html#a1820[See Specialize
+binding of an IDREF via customization] illustrates the generation of
+stronger typing for the above example.
+
+=== [[a1306]]Attribute Wildcard
+
+Attribute wildcard is an extensibility
+feature in XML Schema. It enables an XML document author to introduce
+attribute(s) to an element that were not statically associated with the
+element’s complex type definition. Obviously, it is not possible to bind
+such an attribute to a strongly typed JAXB property as the previous
+section describes for attribute use schema component. The JAXB binding
+of a complex type definition that contains an attribute wildcard,
+directly or indirectly, provides dynamic access to the wildcard
+attributes via the following property:
+
+// Return, by reference, a mapping of
+attribute QName and String. +
+Map<QName, String> getOtherAttributes();
+
+The returned attribute map provides dynamic
+access to wildcard attributes associated with a complex type definition.
+The key to the map is the attribute’s QName and the key’s value is the
+String value of the attribute.
+
+The schema-derived property getter method is
+annotated, either explicitly or by default mapping annotations, with the
+mapping annotation _@XmlAnyAttribute_ , specified in Section 8.
+
+The following code examples show the JAXB
+binding for xs:anyAttribute and how to manipulate wildcard attributes
+using this binding.
+
+=== Bind anyAttribute to a JAXB property
+
+ +
+<xs:schema targetNamespace="http://a.org"> +
+<xs:complexType name=" _widget_ "> +
+<xs:anyAttribute/> +
+<xs:attribute name="color" type="xs:string"/> +
+</xs:complexType> +
+</xs:schema> +
+ +
+package org.a; +
+importjavax.xml.namespace.QName; +
+import java.util.Map; +
+public class _Widget_ \{ +
+String getColor()\{...} +
+void setColor(String value)\{...} +
+@XmlAnyAttribute Map<QName, String> _getOtherAttributes_ ()\{...} +
+}
+
+=== Dynamic access to wildcard attribute and attribute use
+
+ +
+import javax.xml.bind.DatatypeConverter; +
+Widget w = ...; +
+Map attrs = w.getOtherAttributes(); +
+ +
+// access schema-defined global attribute associated with +
+// complexType defintion widget via attribute wildcard. +
+QName IS_OPEN=new QName("http://example.org", "isOpen"); +
+boolean isOpen = DatatypeConverter.parseBoolean(attrs.get(IS_OPEN)); +
+ +
+// set wildcard attribute value +
+attrs.put(IS_OPEN, DatatypeConverter.printBoolean(false)); +
+ +
+// semantically the same results setting attribute use via +
+// dynamic or static setter for attribute use. +
+attrs.put(new QName("color"), "red"); +
+ +
+// iterate over wildcard attributes +
+for (Map.Entry<QName,String> e: attrs.entrySet()) \{ +
+System.out.println("Attribute: " + e.getKey() + +
+" Value:" + e.getValue()); +
+}
+
+=== [[a1316]]Redefine
+
+Redefinition allows an existing XML Schema
+component to be “renamed” and its new definition takes the place of the
+old one. The binding of the redefined schema components, simple and
+complex type definitions and model and attribute group declarations, are
+described in the following subsections.
+
+=== Bind Redefined Simple Type Definition
+
+As introduced in
+link:jaxb.html#a702[See Simple Type Definition]“, a schema
+component using a simple type definition typically binds to a JAXB
+property. The base type, collection type and predicate of the JAXB
+property are derived from the simple type definition. Thus, the redefine
+of a simple type definition results in the redefinition of the simple
+type definition being used to derive the base type, collection type and
+predicate of the JAXB property.
+
+The one exception to this binding is that a
+simple type definition with enum facets is sometimes bound to an enum
+type. A redefined simple type definition that binds to an enum type, as
+described in link:jaxb.html#a829[See Enum Type]“, is not bound
+to a Java representation, only the redefinition is bound to an enum
+type.
+
+=== Bind Redefined Complex Type Definition
+
+A redefinition of a type definition must use
+the original type definition as its base type definition. The redefined
+complex type definition is bound to a Java value class or interface name
+that prepends “_” to the class name. The redefinition complex type
+definition is bound to a class that extends the JAXB class that
+represents the redefined complex type definition.
+
+=== Binding of a redefined complex type definition
+
+File: v1.xsd: +
+<!-- Extracted from Section 4.2.2 of [XSD1] --> +
+<xs:complexType name="personName"> +
+<xs:sequence> +
+<xs:element name="title" type="xs:string" minOccurs="0"/> +
+<xs:element name="forename" type="xs:string" +
+minOccurs="0" maxOccurs="unbounded"/> +
+</xs:sequence> +
+</xs:complexType>
+
+File: v2.xsd: +
+<xs:redefine schemaLocation="v1.xsd"> +
+<xs:complexType name="personName"> +
+<xs:complexContent> +
+<xs:extension base="personName"> +
+<xs:sequence> +
+<xs:element name="generation" minOccurs="0"/> +
+</xs:sequence> +
+</xs:extension> +
+</xs:complexContent> +
+</xs:complexType> +
+</xs:redefine>
+
+Java binding: +
+// binding of file v1.xsd complex type definition for personName +
+@XmlType(name="_PersonName") +
+public class _PersonName \{ +
+void setTitle(String value); String getTitle(); +
+List<String> getForename(); +
+} +
+// binding of v2.xsd redefinition for complex type personName +
+@XmlType(name="PersonName") +
+public class PersonName extends _PersonName \{ +
+void setGeneration(Object value); Object getGeneration(); +
+
+=== Bind Redefined Group Definition
+
+The attribute or model group redefinition is
+used instead of the initial group definition to construct the property
+set of the content model(s) that reference the redefined attribute or
+model group definition. The construction of a property set is described
+in link:jaxb.html#a933[See Java value class]“.
+
+Since there is no binding of an attribute or
+model group definition to a Java representation, no other special case
+handling is required for this binding.
+
+=== Identity Constraint
+
+An identity constraint does not represent any
+data, it represents a constraint that is enforced by validation. These
+constraints can be checked by optional validation that can be enabled at
+either unmarshal and/or marshal time.
+
+=== [[a1332]]Content Model - Particle, Model Group, Wildcard
+
+This section describes the possible Java
+bindings for the content model of a complex type definition schema
+component with a \{content type} property of _mixed_ or _element-only_ .
+The possible element content(s) and the valid ordering between those
+contents are constrained by the \{particles} describing the complex type
+definition’s content model. The Java binding of a content model is
+realized by the derivation of one or more content-properties to
+represent the element content constrained by the model group. Section
+6.12.1 through 6.12.7 describes the _element binding_ of a content
+model.
+
+=== Element binding style
+
+The ideal Java binding would be to map each
+uniquely named element declaration occurring within a content model to a
+single JAXB property. The model group schema component constraint,
+element declarations consistent, specified in [XSD-Part 1] ensures that
+all element declarations/references having the same \{target namespace}
+and \{name} must have the same top-level type definition. This model
+allows the JAXB technology user to specify only the content and the JAXB
+implementation infers the valid ordering between the element content
+based on the \{particles} constraints in the source schema. However,
+there do exist numerous scenarios that this ideal binding is not
+possible for parts of the content model or potentially the entire
+content model. For these cases, default binding has a fallback position
+of representing the element content and the ordering between the content
+using a _general content model_ . The scenarios where one must fallback
+to the general content model will be identified later in this
+subsection.
+
+=== Bind each element declaration name to a JAXB property
+
+This approach relies on the fact that a model
+group merely provide constraints on the ordering between children
+elements and the user merely wishes to provide the content. It is
+easiest to introduce this concept without allowing for repeating
+occurrences of model groups within a content model. Conceptually, this
+approach presents all element declarations within a content model as a
+set of element declaration \{name}’s. Each one of the \{name}’s is
+mapped to a content-property. Based on the element content that is set
+by the JAXB application via setting content-properties, the JAXB
+implementation can compute the order between the element content using
+the following methods.
+
+Computing the ordering between element
+content within [children] of an element information item
+
+* Schema constrained fixed ordering or
+semantically insignificant ordering
+
+The sequence in the schema represents an
+ordering between children elements that is completely fixed by the
+schema. Schema-constrained ordering is not exposed to the Java
+programmer when mapping each element in the sequence to a Java property.
+However, it is necessary for the marshal/unmarshal process to know the
+ordering. No new ordering constraints between children elements can be
+introduced by an XML document or Java application for this case.
+Additionally, the Java application does not need to know the ordering
+between children elements. When the compositor is _all_ , the ordering
+between element content is not specified semantically and any ordering
+is okay. So this additional case can be handled the same way.
+
+* Schema only constrains content and does not
+significantly constrain ordering
+
+If the ordering between the children elements
+is significant and must be accessible to the Java application, then the
+ordering is naturally preserved in Java representation via a collection.
+Below are examples where schema provides very little help in
+constraining order based on content.
+
+ <xs:choice maxOccurs="unbounded"> ...
+</xs:choice> +
+<xs:sequence maxOccurs="unbounded"> ... </xs:sequence>
+
+=== [[a1344]]General content property
+
+A general content property is, as its name
+implies, the most general of all content properties. Such a property can
+be used with any content specification, no matter how complex. A general
+content property is represented as a List property as introduced in
+link:jaxb.html#a595[See List Property]. Unlike the prior
+approach where the JAXB implementation must infer ordering between the
+element content, this approach always requires the JAXB technology user
+to specify a valid ordering of element and text content. This approach
+has the benefit of providing the application with more control over
+setting and knowing the order between element content.
+
+A general content property is capable of
+representing both element information items and character data items
+occurring within [children] of an element information item. Character
+data is inserted into the list as java.lang.String values. Element data
+is added to the list as instances of JAXB element. To support wildcard
+content occurring as part of a general content property, xml data
+content with no static Java binding is added and accessed from the list
+as instances of _org.w3c.org.dom.Node_ .
+
+The schema-derived Collection property getter
+method is annotated, either explicitly or by default mapping
+annotations, with the mapping annotations reflecting what content is
+within the Collection.
+
+* If the content model is mixed, the property
+is annotated as _@XmlMixed_ . See link:jaxb.html#a1369[See Bind
+mixed content]“for details.
+* link:jaxb.html#a1351[See Collection
+of Element types]“describes an optimized binding of a collection of
+element values, instead of a collection of JAXB elements annotated with
+_@XmlElementRefs(@XmlElementRef, ...)_ .
+* If optimized binding can not be used, each
+element in the content model is represented by an _@XmlElementRef_ ,
+described in link:jaxb.html#a1223[See Bind to a Simple Element
+property]“. If there is more than one element annotations needed, they
+must occur as elements in the map annotation _@XmlElementRefs_ specified
+in Section 8.10.3, “@XmlElementRef”.
+
+=== [[a1351]]Collection of Element types
+
+If the content model for a general content
+property meets all of the following constraints, the collection can be
+optimized to be a list of value classes instead of a list of JAXB
+elements.
+
+* If the content model is not mixed and does
+not contain a wildcard.
+* If none of the element declarations in the
+content model are abstract or the head of an element substitution group.
+* If none of the element declarations in the
+content model have a xml datatype that is or derives from xs:list or
+xs:IDREF.
+* For all element declarations in the content
+model, there does not exist two distinct element declarations whose
+types bind to the same Java datatype.
+* If not more than one element declaration in
+the content model is nillable.
+
+Such a collection is annotated with @
+_XmlElements_ annotation, specified in Section 8, that contains a
+_@XmlElement_ annotation for each unique Java datatype within the
+collection. The _@XmlElement_ annotation associates an element name with
+each unique Java datatype in the collection
+
+=== [[a1359]]Examples
+
+=== Example 1: Complex content model of Elements with primitive types
+
+<xs:complexType name="Base"> +
+<xs:choice maxOccurs="unbounded"> +
+<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> +
+public class ObjectFactory \{ +
+// Element instance factories. +
+JAXBElement<String> createBaseA(String value)\{...} +
+JAXBElement<String> createBaseB(String value)\{...} +
+JAXBElement<Integer> createBaseC(Integer value)\{...} +
+// Type factories +
+Base createBase()\{...} +
+} +
+public class Base \{ +
+ +
+/** +
+* A general content list that can contain +
+* element instances representing A, B and/or C. +
+*/ +
+@XmlElementRefs(\{ @XmlElementRef(name="A", value=JAXBElement.class), +
+@XmlElementRef(name="B", value=JAXBElement.class), +
+@XmlElementRef(name="C", value=JAXBElement.class)}) +
+List<JAXBElement> getAOrBOrC()\{...} +
+}
+
+=== Example 2: Optimized Binding to a Collection of Element Types
+
+XML Schema fragment:
+
+<xs:complexType name="AType"/> +
+<xs:complexType name="BType"/> +
+<xs:complexType name="FooBar"> +
+<xs:choice maxOccurs="unbounded"> +
+<xs:element name="foo" type="AType"/> +
+<xs:element name="bar" type="BType"/> +
+</xs:choice> +
+</xs:complexType>
+
+ Default derived Java code:
+
+public class AType \{ ... } +
+public class BType \{ ... } +
+ +
+class ObjectFactory \{
+
+ // element instance factories only +
+JAXBElement<AType> createFooBarFoo(AType value); +
+JAXBElement<BType> createFooBarBar(BType value); +
+} +
+ +
+public class FooBar \{
+
+ /** +
+‘* Collection of element types: AType and BType. */ +
+@XmlElements(\{@XmlElement(value=AType.class, name="Foo"), +
+@XmlElement(value=BType.class, name="Bar")}) +
+List<Object> getFooOrBar() \{...} +
+};
+
+=== [[a1369]]Bind mixed content
+
+When a complex type definition’s _\{content
+type}_ is “mixed,” its character and element information content is
+bound to general content list as described in
+link:jaxb.html#a1344[See General content property].” Character
+information data is inserted as instances of _java.lang.String_ into a
+JAXB collection property.
+
+The schema-derived Collection property getter
+method is annotated, either explicitly or by default mapping
+annotations, with the mapping annotation _@XmlMixed_ , specified in
+Section 8.
+
+=== Example:
+
+Schema fragment loosely derived from mixed
+content example from +
+[XSD Part 0].
+
+<xs:element name="letterBody"> +
+<xs:complexType mixed="true"> +
+<xs:sequence> +
+<xs:element name="name" type="xs:string"/> +
+<xs:element name="quantity" type="xs:positiveInteger"/> +
+<xs:element name="productName" type="xs:string"/> +
+<!-- etc. --> +
+</xs:sequence> +
+</xs:complexType> +
+</xs:element>
+
+Derived Java code:
+
+import java.math.BigInteger; +
+class ObjectFactory \{
+
+ // element instance factories only +
+JAXBElement<LetterBody> createLetterBody(LetterBody value); +
+JAXBElement<String> createLetterBodyName(String value); +
+JAXBElement<BigInteger> +
+createLetterBodyQuantity(BigInteger value); +
+JAXBElement<String> +
+createLetterBodyProductName(String value); +
+} +
+public class LetterBody implements JAXBElement<LetterBody> \{ +
+ +
+/** Mixed content can contain instances of Element classes +
+Name, Quantity and ProductName. Text data is represented as +
+java.util.String for text. +
+*/ +
+@XmlMixed +
+@XmlElementRefs(\{ +
+@XmlElementRef(name="productName", type=JAXBElement.class), +
+@XmlElementRef(name="quantity", type=JAXBElement.class), +
+@XmlElementRef(name="name", type=JAXBElement.class)}) +
+List getContent()\{...} +
+}
+
+The following instance document
+
+<letterBody> +
+Dear Mr.<name>Robert Smith</name> +
+Your order of <quantity>1</quantity> <productName>Baby +
+Monitor</productName> shipped from our warehouse. .... +
+</letterBody>
+
+could be constructed using JAXB API.
+
+LetterBody lb =
+ObjectFactory.createLetterBody(null); +
+List gcl = lb.getContent(); +
+gcl.add("Dear Mr."); +
+gcl.add(ObjectFactory.createLetterBodyName("Robert Smith")); +
+gcl.add("Your order of "); +
+gcl.add(ObjectFactory.
+
+ createLetterBodyQuantity(new
+BigInteger("1"))); +
+gcl.add(ObjectFactory.createLetterBodyProductName("Baby Monitor")); +
+gcl.add("shipped from our warehouse");
+
+Note that if any element instance is placed
+into the general content list, _gcl_ , that is not an instance of
+_LetterBody.Name_ , _LetterBody.Quantity_ or _LetterBody.ProductName_ ,
+validation would detect the invalid content model. With the fail fast
+customization enabled, element instances of the wrong type are detected
+when being added to the general content list, _gcl_ .
+
+=== Bind wildcard schema component[[a1384]]
+
+A wildcard is mapped to a simple
+content-property with:
+
+* Content-property name set to the constant “
+_any_ ”. A binding schema customization could provide a more
+semantically meaningful content-property name.
+* Content-property base type set to
+_java.lang.Object_ by default.
+
+Wildcard content is represented as one of the
+following:
+
+. JAXB element +
+Either an instance of _javax.xml.bind.JAXBElement<T>_ or a JAXB class
+annotated with _@XmlRootElement. +
+_ Corresponds to a recognized global element tag name registered with
+the instance _javax.xml.bind.JAXBContext_ , meaning the schema(s)
+describing the element content is registered with the _JAXBContext_
+instance, see link:jaxb.html#a298[See JAXBContext] on how
+bindings are registered with a _JAXBContext_ instance.,
+. instance of _javax.xml.bind.JAXBElement. +
+_ Corresponds to an unknown element name but a recognized type
+definition specified by _@xsi:type_ on the element. JAXBElement
+_declaredType_ is set to _java.lang.Object_ since the unknown element
+declaration’s default type is _xs:anyType_ .
+. element node instance of a supported xml
+infoset API +
+Necessary to represent Xml data content that does not have a schema
+defined element or type definition. Such content is allowed by element
+_xs:any_ with attribute _@processContents=”lax”_ or _"skip"_ .
+. See content-property predicate for a
+wildcard.
+. If the _maxOccurs_ is greater than one, the
+content property is mapped to a collection property. The default
+collection property is a List property of base type java.lang.Object.
+. These is no default value.
+
+Since the schema does not contain any
+information about the element content of a wildcard content, even the
+content-property, by default, can not infer an XML element tag for
+wildcard element content.
+
+The schema-derived property getter method for
+representing wildcard content is annotated, either explicitly or by
+default mapping annotations, with the mapping annotation
+_@XmlAnyElement_ , specified in Section 8. The @XmlAnyElement annotation
+element values are derived in terms of the abstract model properties for
+wildcard summarized in link:jaxb.html#a5032[See Wildcard Schema
+Component] as follows:
+
+=== Annotate JAXB property with @XmlAnyElement element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@XmlAnyElement element
+|@XmlAnyElement element value
+|lax |If wildcard
+schema component’s _\{process contents}_ is _lax_ or _strict_ , +
+set _@XmlAnyElement.lax()_ to _true_ . +
+ +
+else if _\{process contents}_ is _skip_ , set _@XmlAnyElement.lax()_ to
+_false_ .
+
+|value |
+_javax.xml.bind.annotation. +
+W3CDomHandler.class_
+|===
+
+=== [[a1402]]Bind a repeating occurrence model group
+
+A choice or sequence model group, containing
+more than one member, with a repeating occurrence, _maxOccurs_ attribute
+greater than one, is bound to a general content property in the
+following manner:
+
+* Content-property name is derived in
+following ways:
+* If a named model group definition is being
+referenced, the value of its \{name} property is mapped to a Java
+identifier for a method using the algorithm specified in
+link:jaxb.html#a4656[See The Name to Identifier Mapping
+Algorithm].
+* To derive a content property name for
+unnamed model group, see link:jaxb.html#a4780[See Deriving an
+identifier for a model group].
+* Content-property base type set to
+_java.lang.Object_ . A binding schema customization could provide a more
+specialized java class.
+* Content-property predicate validates the
+order between element instances in the list and whether the occurrence
+constraints for each element instance type is valid according to the
+schema.
+* Since the _maxOccurs_ is always greater
+than one, the content property is mapped to a collection property. The
+default collection property is a List property.
+* These is no default value.
+
+The schema-derived collection property is
+annotated as specified in link:jaxb.html#a1344[See General
+content property]“and link:jaxb.html#a1351[See Collection of
+Element types]“.
+
+=== Local structural Constraints
+
+The list content property’s value must
+satisfy the content specification of the model group. The ordering and
+element contents must satisfy the constraints specified by the model
+group.
+
+=== [[a1414]]Content Model Default Binding
+
+The following rules define _element_ binding
+style for a complex type definition’s content model.
+
+. If \{content type} is mixed, bind the
+entire content model to a general content property with the
+content-property name “ _content_ ”. See
+link:jaxb.html#a1369[See Bind mixed content]” for more details.
+. If (1) a particle has \{max occurs} >1 and
+(2) its \{term} is a model group and (3) all the particles in the model
+group have \{terms} that bind to different Java datatypes, bind to a
+collection of element types. See complete list of constraints required
+to perform this optimized binding in link:jaxb.html#a1351[See
+Collection of Element types]“.
+. If (1) a particle has \{max occurs} >1 and
+(2) its \{term} is a model group, then that particle and its descendants
+are mapped to one general content property that represents them. See
+link:jaxb.html#a1402[See Bind a repeating occurrence model
+group]” for details.
+. Process all the remaining particles (1)
+whose \{term} are wildcard particles and (2) that did not belong to a
+repeating occurrence model group bound in step. 2. If there is only one
+wildcard, bind it as specified in link:jaxb.html#a1384[See Bind
+wildcard schema component].” If there is more than one, then fallback to
+representing the entire content model as a single general content
+property. See link:jaxb.html#a1344[See General content
+property]).
+. Process all particles (1) whose \{term} are
+element declarations and (2) that do not belong to a repeating
+occurrence model group bound in step.2.
+
+First, we say a particle has a label L if it
+refers to an element declaration whose \{name} is L. Then, for all the
+possible pair of particles P and P’ in this set, if the following
+constraints are not met:
+
+. If P and P’ have the same label, then they
+must refer to the same element declaration.
+. If P and P’ refer to the same element
+reference, then its closest common ancestor particle may not have
+sequence as its \{term}.
+
+If either of the above constraints are
+violated, it is not possible to map each element declaration to a unique
+content property. Fallback to representing the entire content model as a
+single general content property.
+
+Otherwise, create a content property for each
+label L as follows:
+
+* The content property name is derived from
+label name L.
+* The base type will be the Java type to
+which the referenced element declaration maps.
+* The content property predicate reflects the
+occurrence constraint.
+* The content property collection type
+defaults to ‘ _list_ ’ if there exist a particle with label L that has
+\{maxOccurs} > 1.
+* For the default value, if all particles
+with label L has a \{term} with the same \{value constraint} default or
+fixed value, then this value. Otherwise none.
+
+Below is an example demonstrating of not
+meeting the uniqueness constraints of 5(a) and 5(b) specified above.
+
+ +
+<xs:sequence> +
+<xs:choice> +
+<xs:element ref="ns1:bar"/> (A) +
+<xs:element ref="ns2:bar"/> (B) +
+</xs:choice> +
+<xs:element ref="ns1:bar"/> (C) +
+</xs:sequence>
+
+The pair (A,B) violates the first clause
+because they both have the label “bar” but they refer to different
+element declarations. The pair (A,C) violates the second clause because
+their nearest common ancestor particle is the outermost _<sequence>_ .
+This model group fragment is bound to a general content property.
+
+=== Default binding of content model “derived by extension”
+
+If a content-property naming collision occurs
+between a content-property that exists in an base complex type
+definition and a content-property introduced by a “derive by extension”
+derived complex type definition, the content-properties from the
+colliding property on are represented by a general content property with
+the default property name _rest_ .
+
+=== Example: +
+derivation by extension content model with a content-property collision.
+
+Given XML Schema fragment:
+
+<xs:complexType name="Base"> +
+<xs:sequence> +
+<xs:element name="A" type="xs:int"/> +
+<xs:element name="B" type="xs:int"/> +
+</xs:sequence> +
+</xs:complexType> +
+ +
+<xs:complexType name="Derived"> +
+<xs:complexContent> +
+<xs:extension base="Base"> +
+<xs:sequence> +
+<xs:element name="A" type="xs:int"/> +
+</xs:sequence> +
+</xs:extension>
+
+ </xs:complexContent> +
+</xs:complexType>
+
+Default binding derived Java code:
+
+public class Base \{ +
+int getA()\{...} void setA(int)\{...} +
+int getB()\{...} void setB(int)\{...} +
+} +
+ +
+public class Derived extends Base \{ +
+/** +
+* Instances of Derived.A must be placed in this general +
+* content propert that represents the rest of the content +
+* model. link:#a5375[24] */ +
+List getRest()\{...} +
+} +
+class ObjectFactory \{ +
+// element instance factories only +
+JAXBElement<Integer> createDerivedA(Integer value)\{...} +
+}
+
+=== [[a1442]]Bind single occurrence choice group to a choice content property
+
+Setting the _choiceContentProperty_ attribute
+of _<jaxb:globalBindings>_ as specified in
+link:jaxb.html#a1582[See Usage] enables this customized binding
+option.
+
+A non-repeating choice model group is bound
+to a simple property. The simple choice content property is derived from
+a choice model group as follows:
+
+* The choice content property name is either
+the referenced model group definition _\{name}_ or obtained using the
+algorithm specified in link:jaxb.html#a4780[See Deriving an
+identifier for a model group].
+* The choice content property _base type_ is
+the first common supertype of all items within the choice model group,
+with _java.lang.Object_ always being a common root for all Java
+objects.link:#a5376[25]
+* The predicate
+* The collection type defaults to List if one
+or more items in the choice model group bind to List.
+* No default value.
+
+A choice property consists of the following
+methods:
+
+* The _getChoiceID_ method returns the set
+value. If the property has no set value then the value _null_ is
+returned. Note that a set value of a primitive Java type is returned as
+an instance of the corresponding Java wrapper class.
+* The _setChoiceID_ method has a single
+parameter that is the type of the choice content property _base type_ .
+
+The _globalBindings_ and property
+customization attribute, _choiceContentProperty,_ enables this
+customized binding _._ The customization is specified in
+link:jaxb.html#a1580[See <globalBindings> Declaration].”
+
+=== Example:
+
+XML Schema representation of a choice model
+group.
+
+<xs:choice> +
+<xs:element name="foo" type="xs:int"/> +
+<xs:element name="bar" type="xs:string"/> +
+</xs:choice>
+
+Derived choice content property method
+signatures:
+
+ void setFooOrBar(Object)\{...} +
+Object getFooOrBar()\{...}
+
+=== [[a1459]]Modifying Schema-Derived Code
+
+There exist a number of use cases on why a
+developer would find it beneficial to modify schema-derived classes.
+Here are some of those use cases.
+
+* Add functionality to schema-derived
+classes. +
+Since schema-derived classes are derived from a data description
+language, the derived classes only represent data and have no
+object-level functionality.
+* Add polymorphic methods to Java class
+hierarchy generated from XML Schema type definition derivation
+hierarchy.
+* Initialize a JAXB property or field
+representing an XML element with a default value. Regretfully, XML
+Schema element defaulting is insufficient to accomplish this. Note that
+XML Schema attribute defaulting is sufficient and does not require this
+approach.
+
+The JAXB 2.0 schema-derived class was
+designed to be easily understandable and modifiable by a developer. For
+many development environments, it is not sufficient to only run the
+schema compiler once due to modification of the schema-derived classes.
+Since schemas evolve over time, it is desirable to have the ability to
+regenerate schema-derived classes from an updated schema while
+preserving modification made by a developer. Given the complexities of
+supporting this capability, a JAXB implementation is not required to
+support regeneration from a schema into previously modified
+schema-derived classes. External tools, such as an IDE, could assist in
+supporting the sophisticated task of regeneration of a modified
+schema-derived class in the future. To enable tools to support
+regeneration, a JAXB implementation is required to have an option for
+generating an annotation that enables a portable means for
+distinguishing between developer code and generated code in a
+schema-derived class.The next section describes the portable format for
+distinguishing between generated and developer added/modified methods
+and /or fields in a schema-derived class.
+
+=== Distinguish between generated and user added code
+
+A schema compiler must have an option to
+generate the Common Annotation, _@javax.annotation.Generated_
+annotation, specified in [CA], on every generated class, method and
+field. If a developer does modify an _@Generated_ annotated method or
+field, they must denote this modification by deleting the _@Generated_
+annotation. If a developer adds a new method or field, it will not have
+an _@Generated_ annotation on it. Based on these conventions, a JAXB
+implementation in conjunction with an IDE or other external tool, would
+be able to support regeneration of schema-derived code while preserving
+developer additions/modifications to methods and fields in a
+schema-derived class.
+
+When schema compiler option to generate
+_@Generated_ annotation is selected, the table describes the annotation
+to be generated.
+
+=== Annotate generated class, field and property with @Generated element-value pairs
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|@Generated element
+|@Generated element value
+|value |fully
+qualified class name of schema compiler
+
+|date |date of
+generation of schema-derived class. Value must follow the ISO 8601
+standard.
+
+|comment
+|optional. Is implementation specific.
+|===
+
+=== Default Binding Rule Summary
+
+Note that this summary is non-normative and
+all default binding rules specified previously in the chapter take
+precedence over this summary.
+
+* Bind the following to Java package:
+* XML Namespace URI
+* Bind the following XML Schema components to
+Java value class:
+* Named complex type
+* Bind to typesafe enum class:
+* A named simple type definition with a
+basetype that derives from “ _xs:NCName_ ” and has enumeration facets.
+* Bind the following XML Schema components to
+an element instance factory that returns _javax.xml.bind.JAXBElement<T>_
+* A global element declaration with a named
+type definition.
+* Local element declaration with a named type
+definition that can be inserted into a general content list.
+* Bind the following XML Schema components to
+a Java Element class
+* A global element declaration with anonymous
+type definition to a Java value class.
+* Local element declaration with anonymous
+type definition that can be inserted into a general content list.
+* Bind to Java property
+* Attribute use
+* Particle with a term that is an element
+reference or local element declaration.
+
+Additionally, generate an element property
+for an element reference to the head element of a substitution group.
+
+* Bind to JAXB property: +
+_getOtherAttributes(): java.util.Map<QName, String>_
+* Attribute Wildcard occurring directly or
+indirectly via an attribute group reference in a complex type
+definition.
+* Bind model group and wildcard content with
+a repeating occurrence and complex type definitions with _mixed_
+\{content type} to:
+* A general content property - a List
+content-property that holds Java instances representing element
+information items and character data items. To support dynamic Xml
+content that validates against xs:any processContents=”lax” or “skip”,
+allow instances of org.w3c.dom.Node into the list.
+
+== CHAPTER 7 -
+
+[[a1498]]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,
+
+<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.
+
+<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.
+
+<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,
+
+
+
+ <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
+
+
+
+ <jaxb:bindings version="2.0" ... />
+
+or
+
+ <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].”
+
+=== [[a1544]]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: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.
+
+*
+
+=== [[a1580]] _<globalBindings>_ Declaration
+
+The customization values in “<
+_globalBindings>_ ” binding declaration have global scope. This binding
+declaration is therefore useful for customizing at a global level.
+
+=== [[a1582]]Usage
+
+<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.
+
+=== [[a1608]]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.
+
+=== [[a1613]]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”>].
+
+=== [[a1617]]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:
+
+<xs:complexType name=”USAddress”> +
+<xs:attribute name=”City” type=”xs:string”/>
+
+</xs:complexType>
+
+ Default Value Class:
+
+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.
+
+public interface USAddress \{ +
+String getCity(); +
+void setCity(String value); +
+}
+
+=== Generation of an Element Class
+
+Schema fragment:
+
+<xs:element name=”Address”
+type=”USAddress”/> +
+ +
+// 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:
+
+ +
+public class Address extends JAXBElement<USAddress> \{ +
+}
+
+=== [[a1633]]@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_ .
+
+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
+
+<schemaBindings [ map="boolean" ] >
+
+{empty} [ <package> package </package> ]
+
+ [ <nameXmlTransform> ... </nameXmlTransform>
+]*
+
+</schemaBindings>
+
+
+
+{empty}<package [ name = "packageName" ]
+
+{empty} [ <javadoc> ... </javadoc> ]
+
+</package>
+
+
+
+<nameXmlTransform>
+
+{empty} [ <typeName [ suffix="suffix" ]
+
+{empty} [ prefix="prefix" ] /> ]
+
+{empty} [ <elementName [ suffix="suffix" ]
+
+{empty} [ prefix="prefix" ] /> ]
+
+{empty} [ <modelGroupName [ suffix="suffix" ]
+
+{empty} [ prefix="prefix" ] /> ]
+
+{empty} [ <anonymousTypeName [
+suffix="suffix" ]
+
+{empty} [ 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 __ [[a1674]]
+
+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._
+*
+
+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
+
+<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:
+
+<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.link:#a5377[26]
+
+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>_ [[a1698]] 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
+
+{empty}<class [ name = " _className_ " ]
+
+{empty} [ implClass = " _implClass_ " ]> +
+[ ref = " _className_ " ]
+
+{empty} [ <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].”
+
+=== [[a1713]]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._
+
+=== [[a1718]]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:
+
+<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:
+
+// 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:
+
+<xs:simpleType name="SKU"> +
+<xs:annotation> <xs:appinfo> +
+<jaxb:class/> +
+</xs:appinfo></xs:annotation> +
+<xs:restriction base=”xs:int”/> +
+</xs:simpleType>
+
+Customized code:
+
+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:
+
+<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:
+
+// 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:
+
+<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:
+
+import javax.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()\{...} +
+}
+
+=== [[a1783]] _<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.
+
+=== [[a1786]]Usage
+
+<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_ [[a1801]]
+
+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.
+
+<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
+classlink:#a5378[27] that extends
+_javax.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.
+
+=== [[a1809]]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.
+
+=== [[a1820]]Specialize binding of an IDREF via customization
+
+Given XML Schema fragment:
+
+<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:
+
+public class Book \{ +
+@XmlIDREF +
+AuthorBio getAuthor() \{...} +
+void setAuthor(AuthorBio referencedObj)\{...} +
+} +
+public class AuthorBio\{ +
+@XmlID +
+String getName()\{...} +
+void setName(String value)\{...} +
+}
+
+=== [[a1825]]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
+
+<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="javax.xml.bind.DatatypeConverter.parseInteger" +
+printMethod="javax.xml.bind.DatatypeConverter.printInteger"/> +
+</jaxb:baseType> +
+</jaxb:property> +
+</xs:appinfo></xs:annotation> +
+</xs:attribute> +
+</xs:complexType>
+
+The code generated is:
+
+public class InternationalPrice \{
+
+ // String getCurrency(); default
+
+ java.math.BigDecimal getCurrency()\{...} //
+customized
+
+ public void setCurrency(java.math.BigDecimal
+val)\{...} // customized
+
+}
+
+=== [[a1847]]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.
+
+=== [[a1857]]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.
+
+=== [[a1861]]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:
+
+<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:
+
+public class USAddress \{
+
+ public static final String MY_COUNTRY =
+"US"; // Customized Code
+
+}
+
+=== Example 2: Customizing to other Java Property
+
+XML Schema fragment:
+
+<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:
+
+public class USAddress \{
+
+ // public getString getCountry(); // Default
+Code
+
+ // 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:
+
+<xs:attribute name="account" type = "xs:int">
+
+ <xs:annotation><xs:appinfo>
+
+ <jaxb:property generateIsSetMethod="true"/>
+
+ </xs:appinfo></xs:annotation>
+
+</xs:attribute>
+
+Customized code:
+
+public int getAccount();
+
+public void setAccount(int account);
+
+public boolean isSetAccount(); // Customized
+code
+
+public void unsetAccount(); // Customized
+code
+
+=== 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.
+
+=== [[a1913]]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
+
+<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:
+
+public class BusinessEntityExt \{
+
+ ...
+
+ // List getAny(); // Default Code
+
+ List getExtension()\{...} // Customized Code
+
+}
+
+=== [[a1944]]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
+
+<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:
+
+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:
+
+<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:
+
+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 +
+}
+
+=== [[a1966]]Example 3: Property Customization: Model Group To Content Property Set
+
+XML Schema fragment:
+
+<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:
+
+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].”
+
+=== [[a1976]]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]".
+*
+
+=== [[a1981]] _<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
+
+<javaType name=" _javaType_ "
+
+{empty} [ xmlType=" _xmlType_ " ]
+
+{empty} [ 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
+_javax.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 _javax.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
+_javax.xml.bind.DatatypeConverter_ .
+
+=== Usage
+
+The following example demonstrates the use of
+the _DatatypeConverter_ class for writing a customized parse and print
+method.
+
+=== [[a2027]]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.
+
+<jaxb:globalBindings> +
+<jaxb:javaType name="long" xmlType="xs:date" +
+parseMethod="pkg.MyDatatypeConverter.myParseDate" +
+printMethod="pkg.MyDatatypeConverter.myPrintDate"/> +
+</jaxb:javaType> +
+</jaxb:globalBindings> +
+
+package pkg; +
+import javax.xml.bind.DatatypeConverter;
+
+public class MyDatatypeConverter \{ +
+public static long myParseDate(String s) \{
+
+ java.util.Calendar d =
+DatatypeConverter.parse(s);
+
+ long result= cvtCalendarToLong(d) ; // user
+defined 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:
+
+<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].
+
+=== [[a2062]]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:
+
+<xs:element name="partNumber" type="xs:int"/>
+
+Customization:
+
+<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:
+
+ 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].
+
+=== [[a2079]]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 classlink:#a5379[28] that extends
+_javax.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]”.
+
+=== [[a2090]] _<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.
+
+=== [[a2092]]Usage
+
+<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_ [[a2106]] 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].”
+
+=== [[a2126]]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.
+
+*
+
+=== [[a2129]]Example 1: typesafeEnum Customization: Split Inline Annotation
+
+XML Schema fragment:
+
+<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:
+
+public enum USStateAbbr \{ +
+STATE_AL, STATE_AK; +
+public String value() \{ return name(); } +
+public static USStateAbbr fromValue(String value) \{ ... } +
+};
+
+=== [[a2134]]Example 2: typesafeEnum Customization: External Binding Declaration
+
+The following example shows how to customize
+the above XML schema fragment using an external binding syntax.
+
+<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.
+
+=== [[a2138]]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.
+
+<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>_ [[a2142]] 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.
+
+=== [[a2145]]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.
+
+<javadoc>
+
+ Contents in <b>Javadoc<\b> format.
+
+</javadoc>
+
+or
+
+<javadoc>
+
+ <<![CDATA[
+
+ Contents in <b>Javadoc<\b> format
+
+ ]]>
+
+</javadoc>
+
+=== [[a2163]]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>_ [[a2165]] 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:
+
+<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.
+
+<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>
+
+ +
+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:
+
+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>_ [[a2193]] 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:
+
+<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:
+
+<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.
+
+=== [[a2217]]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).
+
+ _<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}.
+
+== CHAPTER 8 -
+
+[[a2236]]Java Types To XML
+
+=== Introduction
+
+This chapter specifies the mapping from
+program elements to XML Schema. The mapping includes a default as well
+as a customized mapping.
+
+=== Overview
+
+This section is non normative and provides a
+high level view of Java to XML Schema mapping targeted towards both JAXB
+application developers and JAXB implementation vendors.
+
+=== Mapping Scope
+
+The mapping covers program elements commonly
+used in the composition of a data model for an application: package,
+field, property and types (classes and enum construct). Additionally,
+the mapping scope also covers mapping annotations used to annotate
+schema derived code.
+
+In so far as possible, a program element is
+mapped to an equivalent XML Schema construct in an intuitive manner.
+Thus,
+
+* Package maps to a XML target namespace. A
+package provides a naming context for types. A XML target namespace
+provides a naming context for schema components such as elements, type
+definitions.
+* Type maps to a schema type. A value type is
+a data container for values; e.g. a value class contains values
+represented by it’s properties and fields. A schema type is a datatype,
+an instance of which (e.g. element) acts as a data container for values
+represented by schema components within a schema type’s content model
+(e.g. element, attributes, etc.). Thus a type maps naturally to a schema
+type. For e.g.,
+* class typically maps to a complex type
+definition
+* java primitive types and wrapper classes map
+to XML Schema simple type definition.
+* Field or property maps to an element or an
+attribute contained within the complex type to which a type is mapped.
+* Enum type maps to a simple schema type
+constrained by enumeration facets.
+
+The input to the mapping process is one or
+more sets of packages or classes. A package or a class is mapped and
+recursively, fields, properties and types contained with it. The mapping
+is customizable.
+
+=== Mapping Annotations
+
+Mapping annotationsThe mapping of program
+elements to XML Schema construct can be customized using mapping
+annotations, program annotations based on JSR 175 program annotation
+facility. Mapping annotations are used for:
+
+* customizing the Java to XML schema mapping.
+* annotating schema derived code.
+* control over optimized binary data encoding.
+
+The mapping annotations are described in the
+_javax.xml.bind.annotation_ and _javax.xml.bind.annotation.adapters_
+packages.
+
+Retention Policy The retention policy of all
+mapping annotations is RetentionPolicy.RUNTIME. This policy allows
+introspection of mapping annotations at runtime. Introspection can be
+used by JAXB binding framework to marshal/unmarshal an object graph to
+XML representation or to customize the mapping of program elements to
+XML Schema constructs. This policy also allows a JAXB vendor
+implementation to generate a schema from a program element’s compiled
+form rather than its source.
+
+=== XML Name Derivation
+
+Mapped program element is a program element
+that has been mapped to an XML Schema construct. It is possible to use
+_@XmlTransient_ annotation type to prevent the mapping of a program
+element.
+
+XML Names An XML name may be needed for the
+schema components for a mapped program element, for e.g. element name.
+XML names are usually derived from a program element name, for e.g.
+property, field, class name etc.But they can be customized using mapping
+annotation. When an XML name is derived from a property name, bean de
+capitalization rules are used. If a Java Identifier is not a legal XML
+name, then a legal XML name can be assigned using an annotation element
+(e.g. _@XmlType(name=”foo”)_ ).
+
+=== Fields and Properties
+
+XML global element Fields and properties
+typically map to local elements within a complex type for a class. But a
+well formed XML document begins with a root element (a global element in
+the corresponding schema). The _@XmlRootElement_ annotation can be used
+to associate a global element with a class or an enum type.
+
+Null Value and Nillable Element A null value
+for a type mapped to an XML Schema element in two ways: absence of an
+element or an nillable element. The mapping annotation for an element
+allows either mapping.
+
+
+
+=== Type Mapping
+
+Legacy applications One of the primary use
+cases for Java language to XML Schema mapping is to allow an existing
+application to be exported as a web service. In many cases, the existing
+applications are legacy applications consisting of classes that follow
+different class designs. The annotations and default mapping are
+designed to enable such classes to be mapped to schema with minimal
+changes to existing code. See link:jaxb.html#a3676[See Default
+Mapping] for default mapping.
+
+Class A class usually maps to a complex type.
+However, using _@XmlValue_ annotation, a class can also be mapped to a
+simple type (to hold a simple value) or a complexType with simpleContent
+(to hold a simple value and attributes). The _@XmlType_ annotation can
+be used to customize the mapping of a class. For example, it can be used
+to map a class to an anonymous type or to control the ordering of
+properties and/or fields. Properties and fields are unordered; but they
+can be mapped to a content model that is ordered (e.g. xs:sequence) or
+unordered content model (xs:all).
+
+Class Designs A class with a public or
+protected no-arg constructor can be mapped. If a class has a static
+zero-arg factory method, then the factory method can be specified using
+the annotation element _@XmlType.factoryMethod()_ and
+_@XmlType.factoryClass()_ .
+
+Ordering of Properties/fields: The ordering of
+properties and fields can be customized in one of two ways: at the
+package level using @XmlAccessorOrder or using _@XmlType.propOrder()_ at
+the class level.
+
+Class Hierarchy Mapping Class hierarchy
+typically maps to a type derivation hierarchy. The _@XmlType_ and
+_@XmlValue_ annotations together provide support mapping class hierarchy
+to schema type hierarchy where XML Schema complex type derives by
+extension from either another complex type or a simple type.
+
+Supported Collection Types Typed collections
+and untyped collections are mapped. Mapped collection types are: arrays,
+indexed properties and parametric types. Mapped untyped collection are:
+_java.util.List_ , _java.util.Set_ and _java.util.HashMap_ . Of these,
+_java.util.HashMap_ does not map naturally to a XML Schema construct.
+For example, _HashMap_ can have different XML serialized forms which
+differ in trade-offs made between memory and speed or specificity and
+generality. The XML serialization form can be customized using
+_@XmlJavaTypeAdapter_ (link:jaxb.html#a2278[See Adapter]”).
+
+Collection serialized forms A collection type
+can be mapped to a XML Schema complex type and collection item is mapped
+to local element within it. Alternately, a parameterized collection
+(e.g. List<Integer>) can be mapped to a simple schema type that derives
+by list.
+
+When a collection type is mapped to a XML
+Schema complex type, the mapping is designed to support two forms of
+serialization shown below.
+
+//Example: code fragment +
+int[] names; +
+ +
+// XML Serialization Form 1 (Unwrapped collection) +
+// Element name is derived from property or field name +
+<names> ... </names> +
+<names> ... </names> +
+... +
+ +
+// XML Serialization Form 2 ( Wrapped collection ) +
+// Element name of wrapper is derived from property or field name +
+// Element name of each item in collection is also derived from
+
+// property name +
+<names> +
+<names> value-of-item </names> +
+<names> value-of-item </names> +
+.... +
+</names>
+
+The two serialized XML forms allow a null
+collection to be represented either by absence or presence of an element
+with a nillable attribute. The _@XmlElementWrapper_ annotation on the
+property or field is used to customize the schema corresponding to the
+above XML serialization forms.
+
+A parameterized collection (e.g.
+List<Integer>) can also be mapped to simple schema that derives by list
+using _@XmlList_ annotation. For e.g. the serialized XML form is: “1 2 3
+“.
+
+=== [[a2278]]Adapter
+
+A type may not map naturally to a XML
+representation (see Supported Collection Types above). As another
+example, a single instance of a type may have different on wire XML
+serialization forms.
+
+Adapter approach defines a portable
+customization mechanism for applications exemplified above. The
+mechanism provides a way to adapt a bound type, a Java type used to
+process XML content, to value type, mapped to an XML representation or
+vice versa. It is the value type that is used for marshalling and
+unmarshalling. Use of this approach involves two steps:
+
+* provide an adapter class that extends the
+abstract class _@javax.xml.bind.annotation.adapters.XmlAdapter_ that
+defines two methods _unmarshal()_ and _marshal()_ . The methods are
+invoked by JAXB vendor implementation during unmarshalling and
+marshaling respectively to adapt between bound and value types.
+* specify the adapter class using the
+_@XmlJavaTypeAdapter_ annotation.
+
+=== Referential Integrity
+
+Preserving referential integrity of an object
+graph across XML serialization followed by a XML de serialization,
+requires an object reference to be marshalled by reference or
+containment appropriately. Possible strategies include:
+
+* marshal all references to a given object by
+reference.
+* marshal the first reference to an object by
+containment and subsequent references to the same object by reference.
+
+Depending on the strategy, the schema to which
+program element is mapped also varies accordingly.
+
+Two annotations _@XmlID_ and _@XmlIDREF_
+provide the mechanism which can be used together to map program element
+by reference or containment. This places the burden of preserving
+referential integrity on a developer. On the other hand, the ability to
+customize the mapping is useful since it can result in mapping of
+program elements to a schema that defines a document structure more
+meaningfully to an application than a default derived schema.
+
+=== Property/Field Name Collision
+
+A XML name collision can arise when the
+property name obtained by bean de capitalization and the name of a field
+map to a same schema component. For example
+
+public int item;
+
+pubilc int getItem();
+
+public void setItem(int val);
+
+The name collision occurs because the property
+name, bean de capitalization, and the name of the public field are both
+the same i.e. _item._ In the case, where the property and the public
+field refer to the same field, the _@XmlTransient_ can be used to
+resolve the name collision by preventing the mapping of either the
+public field or the property.
+
+=== Naming Conventions
+
+Any source and schema fragments and examples
+shown in this chapter are meant to be illustrative rather than
+normative.
+
+* _@XmlAttribute_ denotes both a program
+annotation type as well a specific use of annotation type.
+* The prefix _xs:_ is used to refer to schema
+components in W3C XML Schema namespace.
+* The prefix _ref:_ is used to refer to schema
+components in the namespace _“http://ws-i.org/profiles/basic/1.1/xsd”_
+*
+
+=== Constraint Violations
+
+For the purpose of mapping and constraint
+checking, if a program element is not annotated explicitly, and there is
+a default mapping annotation defined for that element, it must be
+applied first before performing any constraint checks or mapping. This
+is assumed in the normative mapping tables shown below.
+
+The mapping of program elements to XML Schema
+constructs is subject to mapping constraints, specified elsewhere in
+this chapter. The mapping constraints must be enforced by the
+_javax.xml.bind.annotation.JAXBContext.newInstance(..)_ method. Any
+cycles resulting from a combination of annotations or default mapping
+must be detected in
+_javax.xml.bind.annotation.JAXBContext.newInstance(..)_ method and also
+constitutes a constraint violation. A _javax.xml.bind.JAXBException_ or
+(its subclass, which can be provider specific) must be thrown upon a
+constraint violation.
+
+A JAXB Provider must support the schema
+generation at runtime. See
+_javax.xml.bind.JAXBContext.generateSchema(..)_ for more information.
+
+=== Type Mapping
+
+This section specifies the mapping of Java
+types to XML Schema.
+
+=== Java Primitive types
+
+The default mapping of Java types (and their
+wrapper classes) specified in table link:jaxb.html#a2310[See
+Mapping: Java Primitive types to Schema Types] must be supported.
+
+=== [[a2310]]Mapping: Java Primitive types to Schema Types
+
+Java Primitive Type
+
+XML data type
+
+boolean
+
+xs:boolean
+
+byte
+
+xs:byte
+
+short
+
+xs:short
+
+int
+
+xs:int
+
+long
+
+xs:long
+
+float
+
+xs:float
+
+double
+
+xs:double
+
+=== Java Standard Classes
+
+The default mapping of Java classes specified
+in link:jaxb.html#a2329[See Mapping of Standard Java classes]
+must be supported.
+
+=== [[a2329]]Mapping of Standard Java classes
+
+Java Class
+
+XML data type
+
+java.lang.String
+
+xs:string
+
+java.math.BigInteger
+
+xs:integer
+
+java.math.BigDecimal
+
+xs:decimal
+
+java.util.Calendar
+
+xs:dateTime
+
+java.util.Date
+
+xs:dateTime
+
+javax.xml.namespace.QName
+
+xs:QName
+
+java.net.URI
+
+xs:string
+
+javax.xml.datatype.XMLGregorianCalendar
+
+xs:anySimpleType
+
+javax.xml.datatype.Duration
+
+xs:duration
+
+java.lang.Object
+
+xs:anyType
+
+java.awt.Image
+
+xs:base64Binary
+
+javax.activation.DataHandler
+
+xs:base64Binary
+
+javax.xml.transform.Source
+
+xs:base64Binary
+
+java.util.UUID
+
+xs:string
+
+
+
+*
+
+A byte[] must map to xs:base64Binary by
+default.
+
+=== Generics
+
+=== Type Variable
+
+The following grammar is from [JLS], Section
+4.4, “Type Variables”.
+
+ _TypeParameter: +
+TypeVariable TypeBoundopt_
+
+
+
+ _TypeBound: +
+extends ClassOrInterfaceType AdditionalBoundListopt_
+
+A type variable without a Typebound must be
+mapped to xs:anyType.
+
+A type variable with a TypeBound must map to
+the schema type to which ClassOrInterfaceType is mapped; the mapping of
+ClassOrInterface is subject to the mapping constraints specified in
+other sections in this chapter.
+
+<!-- code fragment
+
+public class Shape <T> \{
+
+ public T xshape;
+
+ public Shape() \{};
+
+ public Shape(T f) \{
+
+ xshape = f;
+
+ }
+
+}
+
+
+
+<!-- XML Schema
+
+<xs:complexType name="shape">
+
+ <xs:sequence>
+
+ <xs:element name="xshape" type="xs:anyType"
+minOccurs="0"/>
+
+ </xs:sequence>
+
+ </xs:complexType>
+
+=== [[a2386]]Type Arguments and Wildcards
+
+The following grammar is from [JLS], Section
+4.5.1, “Type Arguments and Wildcards”.
+
+TypeArguments:
+
+ <ActualTypeArgumentList>
+
+
+
+ActualTypeArgumentList:
+
+ ActualTypeArgument
+
+ ActualTypeArgumentList, ActualTypeArgument
+
+
+
+ActualTypeArgument:
+
+ ReferenceType
+
+ Wildcard
+
+
+
+Wildcard:
+
+?WildcardBounds
+
+
+
+WildcardBounds:
+
+ extends ReferenceType
+
+ super ReferenceType
+
+A wildcard without a WildcardBounds must map
+to schema type xs:anyType.
+
+A wildcard with a WildcardBounds whose super
+type is ReferenceType must map to schema type xs:anyType.
+
+A wildcard with a WildcardBounds that extends
+a ReferenceType must map to the schema type to which the ReferenceType
+is mapped; this mapping is subject to the mapping constraints specified
+in other sections in this chapter and is determined by the annotations
+as specified in the mapping tables in the chapter. For example:
+
+
+
+
+
+/** EXAMPLE : WildcarType Mapping
+
+// Code fragment
+
+public class Shape \{...}
+
+
+
+public class Rectangle extends Shape \{...}
+
+public class Circle extends Shape \{...}
+
+
+
+public class Foo \{
+
+ public java.util.List<? extends Shape>
+shapes;
+
+}
+
+
+
+<-- XML Schema fragment
+
+<xs:complexType name="shape">
+
+ ...
+
+</xs:complexType>
+
+
+
+<xs:complexType name="circle">
+
+ <xs:complexContent>
+
+ <xs:extension base="shape">
+
+ ...
+
+ </xs:extension>
+
+ </xs:complexContent>
+
+ </xs:complexType>
+
+
+
+<xs:complexType name="rectangle">
+
+ <xs:complexContent>
+
+ <xs:extension base="shape">
+
+ ...
+
+ </xs:extension>
+
+ </xs:complexContent>
+
+</xs:complexType>
+
+
+
+<xs:complexType name="foo">
+
+ <xs:sequence>
+
+ <xs:element name="shapes" type="shape"
+nillable="true"
+
+ maxOccurs="unbounded" minOccurs="0"/>
+
+ </xs:sequence>
+
+</xs:complexType>
+
+
+
+=== Collections
+
+The following collection must be supported:
+
+* _java.util.Map_ and its subtypes (e.g.
+java.util.HashMap)
+* _java.util.Collection_ and it’s subtypes
+(e.g. java.util.List)
+
+The mapping of collection depends upon the
+annotations on the program elements and is specified in the mapping
+tables. This specification uses a collection type to be one of
+_java.util.Collection_ (or a subtype derived from it) , an array or an
+JavaBean index property.
+
+=== Java Package
+
+ _@XmlSchema_ is used in the mapping of
+package to an XML target namespace.
+
+=== [[a2456]]@XmlSchema
+
+=== Synopsis
+
+public enum XmlNsForm \{UNQUALIFIED,
+QUALIFIED, UNSET}
+
+
+
+@Retention(RUNTIME) @Target(\{})
+
+public @interface XmlNs \{
+
+
+
+@Retention(RUNTIME) @Target(\{PACKAGE})
+
+public @interface XmlSchema \{
+
+ XmlNs[] xmlns() default \{};
+
+ String namespace() default "";
+
+ String location() default "";
+
+ XmlNsForm elementFormDefault() default
+XmlNsForm.UNSET;
+
+ XmlNsForm attributeFormDefault() default
+XmlNsForm.UNSET;
+
+}
+
+=== Mapping
+
+If _location()_ is “”, a package annotated
+with _@XmlSchema_ must be mapped as specified in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace]. Otherwise a package will not produce any schema document.
+
+*
+
+*
+
+
+
+=== Mapping: Package to [[a2476]]XML target namespace
+
+ _targetNamespace_
+
+if _@XmlSchema.namespace()_ is __ "" _,_ then
+_absent;_
+
+
+
+otherwise @XmlSchema.namespace()
+
+ _elementFormDefault_
+
+ if the value of
+_@XmlSchema.elementFormDefault()_ is _@XmlNsForm.UNSET,_ then _absent;_
+
+
+
+otherwise, the value of
+_@XmlSchema.elementFormDefault()_
+
+ _attributeFormDefault_
+
+ if the value of
+_@XmlSchema.attributeFormDefault()_ is _@XmlNsForm.UNSET,_ then
+_absent;_
+
+
+
+otherwise, the value of
+_@XmlSchema.attributeFormDefault()_
+
+ _Namespace prefixes_
+
+if _@XmlSchema.xmlns()_ is \{} then
+implementation defined;
+
+
+
+otherwise _@XmlSchema.xmlns()_
+
+=== @XmlAccessorType
+
+This annotation allows control over default
+serialization of fields and properties.
+
+=== Synopsis
+
+@Inherited @Retention(RUNTIME)
+@Target(\{PACKAGE, TYPE})
+
+public @interface XmlAccessorType \{
+
+ XmlAccessType value() default
+XmlAccessType.PUBLIC_MEMBER;
+
+}
+
+
+
+public enum XmlAccessType \{ NONE, PROPERTY,
+FIELD, PUBLIC_MEMBER}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+This annotation can be used only with the
+following other annotations: _@XmlType, @XmlRootElement_ ,
+_@XmlAccessorOrder, @XmlSchema, @XmlSchemaType, @XmlSchemaTypes,
+@XmlJavaTypeAdapters._ It can also be used with the following
+annotations at the package level: _@ XmlJavaTypeAdapter_ .
+
+See link:jaxb.html#a3676[See Default
+Mapping]”.
+
+=== [[a2506]]@XmlAccessorOrder
+
+This annotation allows control over the
+default ordering of properties and fields that are mapped to XML
+elements. Properties and fields mapped to XML attributes are not
+impacted by this annotation since XML attributes are unordered.
+
+=== Synopsis
+
+@Inhertited @Retention(RUNTIME)
+@Target(\{PACKAGE, TYPE})
+
+public @interface XmlAccessorOrder \{
+
+ XmlAccessOrder value() default
+XmlAccessOrder.UNDEFINED;
+
+}
+
+
+
+public enum XmlAccessOrder \{ UNDEFINED,
+ALPHABETICAL}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+. This annotation can be
+used only with the following other annotations: _@XmlType,
+@XmlRootElement_ , _@XmlAccessorType, @XmlSchema, @XmlSchemaType,
+@XmlSchemaTypes, @XmlJavaTypeAdapters._ It can also be used with the
+following annotations at the package level: _@ XmlJavaTypeAdapter_ .
+
+If the value of _@XmlAccessorOrder.value()_ is
+_XmlAccessOrder.ALHPHABETICAL_ , then the default ordering of
+fields/properties is lexicographic order as determined by
+_java.lang.String.CompareTo((String anotherString)_ .
+
+If the _@XmlAccessorOrder.value()_ is
+_XmlAccessOrder.UNDEFINED_ , then the default ordering of
+fields/properties is unspecified.
+
+=== [[a2520]]@XmlSchemaType
+
+This annotation allows a customized mapping to
+a XML Schema built in type. This is useful where a Java type can map to
+more than one schema built in types. An example is
+_XMLGregorianCalendar_ which can represent one of the eight schema
+built-in types.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD,
+PACKAGE})
+
+public @interface XmlSchemaType \{
+
+ String name();
+
+ String namespace() default
+"http://www.w3.org/2001/XMLSchema";
+
+ Class type() default DEFAULT.class;
+
+ static final class DEFAULT \{}
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* name() must be an atomic simple type schema
+type (or a type that derives from it) to which the type of the property
+or field can be mapped from XML Schema -> Java as specified in Section
+6.2.2, “Atomic Datatype”. Example
+
+
+
+ // @XmlSchemaType can specify any one of the
+eight calendar types
+
+ // that map to XMLGregorianCalendar.
+
+ @XmlSchemaType(name=”date”)
+
+ XMLGregorianCalendar foo;
+
+* If the annotation is used as a package
+level annotation or within _@XmlSchemaTypes_ , value of
+_@XmlSchemaType.type()_ must be specified and must be the Java type that
+is being customized.
+* If the annotation is used on a field or a
+method, then value of type() must be DEFAULT.class.
+* This annotation can only be used with the
+following other annotations: _@XmlElement, @XmlAttribute,
+@XmlJavaTypeAdapter, @XmlJavaTypeAdapters._
+
+package:
+
+When this annotation is used at the package
+level, the mapping applies to references to _@XmlSchemaType.type()_ as
+specified below. For clarity, the following code example is used along
+with normative text.
+
+// Example: change the default mapping at
+package level
+
+package foo;
+
+@javax.xml.bind.annotation.XmlSchemaType
+
+ (name="date",
+
+
+type=javax.xml.datatype.XMLGregorianCalendar.class)
+
+A _@XmlSchemaType_ that is specified as a
+package level annotation must apply at the point of reference as
+follows:
+
+. a property/field within a class in package
+(e.g _exmple.po)_ whose reference type is _@XmlSchemaType.type()_ . For
+e.g.
+
+ // XMLGregorianCalendar will be mapped to XML
+Schema type "date"
+
+ XMLGregorianCalendar cal;
+
+. a property/field within a class in package
+(e.g _exmple.po)_ , where _@XmlSchemaType.type()_ is used as a
+parametric type. For e.g.
+
+ // Example: Following code maps to a
+repeating element with
+
+ // XML Schema type of "date".
+
+ List<XMLGregorianCalendar> bar;
+
+property/field:
+
+A _@XmlSchemaType_ specified on the
+property/field maps references to _@XmlSchemaType.type()_ as follows:
+
+. property/field is a single valued.
+
+ // Maps XMLGregorianCalendar to XML Schema
+type "date"”
+
+ @XmlSchemaType(name=”date”)
+
+ public XMLGregorianCalendar cal;
+
+. a property/field where
+_@XmlSchemaType.type()_ is used as a parametric type. For e.g.
+
+ // Example: Following code maps to a
+repeating element with
+
+ // XML Schema type of "date".
+
+ @XmlSchemaType(name="date")
+
+ List<XMLGregorianCalendar> bar;
+
+=== @XmlSchemaTypes
+
+This annotation is a container annotation for
+defining multiple _@XmlSchemaType_ annotations at the package level.
+
+=== Synopsis
+
+ @Retention(RUNTIME) @Target(\{PACKAGE})
+
+ public @interface XmlSchemaTypes \{
+
+ // Collection of @\{@link XmlSchemaType}
+annotations
+
+ XmlSchemaType[] value();
+
+ }
+
+=== Mapping
+
+Each _@XmlSchemaType_ annotation in
+_@XmlSchemaTypes.value()_ must be mapped as specified in
+link:jaxb.html#a2520[See @XmlSchemaType]”.
+
+=== Java class
+
+=== [[a2578]]@XmlType
+
+ _@XmlType_ is used to map a Java class to a
+schema type. The schema type is computed from its annotation element
+values.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{TYPE})
+
+public @interface XmlType \{
+
+ String name() default "##default";
+
+ String[] propOrder() default \{""};
+
+ String namespace() default "##default" ;
+
+ Class factoryClass() default DEFAULT.class;
+
+ static final class DEFAULT \{};
+
+ String factoryMethod() default "";
+
+}
+
+
+
+=== [[a2591]]Mapping
+
+The following mapping constraints must be
+enforced:
+
+* a class must be either be a top level class
+or a nested static class.
+* a class must have a public or protected
+no-arg constructor or a factory method identified by \{ _factoryClass(),
+factoryMethod()_ } unless it is adapted using _@XmlJavaTypeAdapter_ .
+* If _factoryClass()_ is other than
+DEFAULT.class, then _factoryMethod()_ must be specified (i.e. the
+default value ““ cannot be used.)
+* If _factoryClass()_ is _DEFAULT.class_ and
+_factoryMethod()_ is not ““, then _factoryMethod()_ be a method in this
+class.
+* if _@XmlType.propOrder_ is not \{} or \{““},
+then the set must include all of the properties and fields mapped to
+particles as specified in:
+* link:jaxb.html#a2898[See
+@XmlElement]”
+* link:jaxb.html#a3019[See
+@XmlElements]”
+* link:jaxb.html#a3049[See
+@XmlElementRef]”
+* link:jaxb.html#a3112[See
+@XmlElementRefs]”
+* _@XmlType.propOrder_ must not include a
+field or property annotated with _@XmlTransient._
+* if the class, subClass, derives from another
+XML-bound class, baseClass directly or indirectly (other than
+java.lang.Object), then the subClass must not contain a mapped property
+or field annotated with _@XmlValue_ annotation.
+* If a class contains a mapped property or
+field annotated with _@XmlValue_ annotation, then all other mapped
+fields or properties in the class must be mapped to an XML attribute.
+* This annotation can be used with the
+following annotations: _@XmlRootElement, @XmlAccessorOrder,
+@XmlAccessorType._
+* Even though the syntax allows it, @XmlType
+is disallowed on an interface.
+
+A class annotated with @ _XmlType_ , must be
+mapped as specified below:
+
+class must be mapped as specified in
+link:jaxb.html#a2678[See Mapping: Class to Simple Type
+Definition] if the class contains only one mapped property or field that
+is annotated with @ _XmlValue_ as specified in
+link:jaxb.html#a3331[See @XmlValue]”.
+
+otherwise, the class must be mapped as
+specified in link:jaxb.html#a2611[See Mapping: Class to Complex
+Type
+Definition].
+
+=== [[a2611]]Mapping: Class to Complex Type Definition
+
+\{name}
+
+if _@XmlType.name()_ is ““, then absent
+
+
+
+otherwise if _@XmlType.name()_ is “
+_##default_ “, then the XML name derived from the class name as
+specified in link:jaxb.html#a3678[See Java Identifier To XML
+Name]”
+
+
+
+otherwise _@XmlType.name()_
+
+\{target namespace}
+
+{empty}if _@XmlType.namespace()_ is “
+_##default_ “ && _@XmlType.name()_ is ““ and class is annotated with
+_@XmlRootElement_ , then the \{target namespace} as specified in
+link:jaxb.html#a2742[See Mapping: Class to Element Declaration]
+
+
+
+otherwise if _@XmlType.namespace()_ is “
+_##default_ “ && _@XmlType.name()_ is ““ and class is not annotated with
+_@XmlRootElement_ , then the \{target namespace} of the attribute or
+element to which the property or field, from where this class is
+referenced, is mapped.
+
+
+
+{empty}otherwise if _@XmlType.namespace()_ is
+“ _##default_ “ && _@XmlType.name()_ is not ““, then the namespace to
+which the package, in which class is defined, is mapped as specified in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace]
+
+
+
+otherwise _@XmlType.namespace()_
+
+\{base type definition}
+
+if the class contains a mapped property or
+field annotated with _@XmlValue_ as specified in
+link:jaxb.html#a3331[See @XmlValue]”, then the schema type to
+which mapped property or field’s type is mapped.
+
+
+
+otherwise schema type to which the nearest
+XML-bound ancestor class is mapped
+
+*
+
+*
+
+\{derivation method}
+
+if _\{base type definition}_ is _xs:anyType_ ,
+then by _restriction_
+
+
+
+otherwise _extension_
+
+\{final}
+
+if class modifier final is present. then the
+set \{extension, restriction};
+
+
+
+otherwise, the empty set.
+
+\{abstract}
+
+true if the class modifier abstract is
+present;
+
+
+
+otherwise false.
+
+\{attribute uses}
+
+The set of properties or fields mapped to
+attributes as specified in link:jaxb.html#a3230[See
+@XmlAttribute]”.
+
+\{attribute wildcard}
+
+Attribute wildcard as specified in
+link:jaxb.html#a3303[See XmlAnyAttribute]”.
+
+\{content type}
+
+. empty if no mapped property or field is
+annotated with _@XmlElement_
+. _mixed_ if a property or field is annotated
+with _@XmlMixed_ as specified in link:jaxb.html#a3449[See
+@XmlMixed]”.
+. _simpleContent_ if :
+. no property or field is annotated with
+_@XmlElement_
+. && one or more properties or fields is
+annotated with _@XmlAttribute_
+. && one property is annotated with
+_@XmlValue_ .
+. _element-only content_ if one or more
+properties is annotated with _@XmlElement; +
+content model_ mapped as specified in link:jaxb.html#a2662[See
+Mapping: Class body to Model Group Component]”.
+
+\{prohibited substitutions}
+
+Empty set
+
+
+
+*
+
+\{annotations}
+
+ _absent_
+
+=== [[a2662]]Mapping: Class body to Model Group Component
+
+\{compositor}
+
+if _@XmlType.propOrder()_ is \{} then _xs:all_
+;
+
+
+
+otherwise _xs:sequence_ . The ordering of
+particles is:
+
+if _@XmlType.propOrder()_ is not ““, then the
+order in which properties/fields are listed in _@XmlType.propOrder()_ .
+
+
+
+if _@XmlType.propOrder()_ is ““ &&
+
+class is annotated with
+_@XmlAccessorOrder(XmlAcessOrder.ALPHABETICAL) )_ or
+_@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)_ is specified at the
+package level and class is not annotated with
+_@XmlAccessorOrder(XmlAccessOrder.UNDEFINED)_ , then alphabetical order
+as specified in link:jaxb.html#a2506[See @XmlAccessorOrder]”.
+
+
+
+otherwise order is unspecified.
+
+\{particles}
+
+Set of properties or fields mapped to
+particles. See _\{compositor}_ mapping above for ordering of particles.
+
+\{annotation}
+
+ _unspecified_
+
+
+
+=== [[a2678]]Mapping: Class to Simple Type Definition
+
+\{name}
+
+if _@XmlType.name()_ is ““, then absent
+
+
+
+otherwise if _@XmlType.name()_ is “
+_##default_ “,
+
+then the XML name derived from the class name
+as specified in link:jaxb.html#a3678[See Java Identifier To XML
+Name]”
+
+
+
+otherwise _@XmlType.name()_
+
+\{target namespace}
+
+{empty}if _@XmlType.namespace()_ is “
+_##default_ “ && _@XmlType.name()_ is ““ and class is annotated with
+_@XmlRootElement_ , then the \{target namespace} as specified in
+link:jaxb.html#a2742[See Mapping: Class to Element Declaration]
+
+
+
+otherwise if _@XmlType.namespace()_ is “
+_##default_ “ && _@XmlType.name()_ is ““ and class is not annotated with
+_@XmlRootElement_ , then the \{target namespace} of the attribute or
+element to which the property or field, from where this class is
+referenced, is mapped.
+
+
+
+{empty}otherwise if _@XmlType.namespace()_ is
+“ _##default_ “ && _@XmlType.name()_ is not ““, then the namespace to
+which the package, in which class is defined, is mapped as specified in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace]
+
+
+
+otherwise _@XmlType.namespace()_
+
+\{base type definition}
+
+ur-type definition, _xs:anyType_ .
+
+
+
+NOTE: This is subject to the mapping
+constraints on XmlType. See link:jaxb.html#a2591[See Mapping]”.
+
+\{facets}
+
+ _empty set_
+
+\{fundamental facets}
+
+derived
+
+\{final}
+
+empty set.
+
+A subset of \{extension, list, restriction,
+union}.
+
+\{variety}
+
+Must be mapped as shown below
+
+
+
+atomic
+
+ _\{primitive type definition}_
+
+if property or field type is one of:
+
+- primitive type
+
+- wrapper class
+
+- reference type mapped to a simple atomic
+type.
+
+
+
+
+
+list
+
+ _\{item type definition}_
+
+if the property or field type is one of the
+following collection types:
+
+- generic list
+
+- indexed property
+
+- single dimensional array
+
+{empty}link:jaxb.html#a3800[See
+@XmlType: List simple type]
+
+
+
+union
+
+ _\{member type definitions}_
+
+Not mapped.
+
+\{annotation}
+
+ _unspecified_
+
+
+
+=== @XmlRootElement
+
+ _@XmlRooElement_ can be used to associate a
+global element with the schema type to which a class is mapped.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{TYPE}
+
+public @interface XmlRootElement \{
+
+ String name() default "##default" ;
+
+ String namespace() default "##default" ;
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+. The only other annotations allowed with this
+annotation are: _@XmlType, @XmlEnum, @XmlAccessorType,
+@XmlAcessorOrder._
+
+A class annotated with _@XmlRootElement_
+annotation, must be mapped as specified in
+link:jaxb.html#a2742[See Mapping: Class to Element Declaration].
+
+=== Mapping: Class [[a2742]]to Element Declaration
+
+\{name}
+
+if _@XmlRootElement.name()_ is “##default“,
+then the XML name derived from the class name as specified in
+link:jaxb.html#a3678[See Java Identifier To XML Name]”;
+
+
+
+otherwise _@XmlRootElement.name()_
+
+\{target namespace}
+
+{empty}if _@XmlRootElement.namespace()_ is “
+_##default_ “ _,_ then the value of the targetNamespace to which the
+package containing the class is mapped as specified in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace]
+
+
+
+otherwise _@XmlRootElement.namespace()_
+
+\{type definition}
+
+schema type to which the class is mapped as
+specified in link:jaxb.html#a2578[See @XmlType]”.
+
+\{scope}
+
+ _global_
+
+\{value constraint}
+
+ _absent_
+
+\{nillable}
+
+ _false_
+
+\{identity-constraint definitions}
+
+empty set
+
+\{substitution group affiliation}
+
+ _absent_
+
+*
+
+\{substitution group exclusions}
+
+ _\{extension, restriction}_
+
+\{disallowed substitution}
+
+ _\{substitution,extension,restriction}_
+
+\{abstract}
+
+ _false_
+
+*
+
+\{annotation}
+
+ _unspecified_
+
+=== @XmlTransient
+
+ _@XmlTransient_ is used to prevent the
+mapping of a class.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(TYPE)
+
+public @interface XmlTransient \{}
+
+=== Mapping
+
+The class must not be mapped. Any reference to
+this class from the other XML-bound classes will treated as if they are
+refering to the nearest XML-bound ancestor of this class (which could be
+_java.lang.Object_ , which guarantees that there always exists such a
+class.)
+
+For the effect that this annotation causes on
+derived classes, see link:jaxb.html#a2611[See Mapping: Class to
+Complex Type Definition].
+
+Note that a class with _@XmlTransient_ may
+still have properties and fields with JAXB annotations. Those are mapped
+to XML when a derived class is mapped to XML. See section
+link:jaxb.html#a2876[See Property And Field] for more details.
+
+The following mapping constraints must be
+enforced:
+
+* _@XmlTransient_ is mutually exclusive with
+all other mapping annotations.
+
+=== @XmlSeeAlso
+
+ _@XmlSeeAlso_ is an annotation that can be
+optionally placed on a class to instruct the JAXB runtime and the schema
+generator to also bind classes listed in _@XmlSeeAlso_ , when it binds
+the class that _@XmlSeeAlso_ is on.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(TYPE)
+
+public @interface XmlRootElement \{
+
+ Class[] value();
+
+}
+
+=== Enum Type
+
+=== @XmlEnum
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{TYPE}
+
+public @interface XmlEnum \{
+
+ // Java type that is mapped to a XML simple
+type
+
+ Class <?> value() default String.class;
+
+}
+
+
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+ _@XmlEnum.value()_ must be mapped to a XML
+schema simple type.
+
+=== Mapping: Enum type to Base Type Definition
+
+\{base type definition}
+
+schema type to which _@XmlEnum.value()_ is
+mapped.
+
+\{variety}
+
+The value depends upon the schema type to
+which the _@XmlEnum.value()_ is mapped. But syntactically, it is always
+a restriction of \{base type definition}.
+
+derived from the \{base type definition}
+
+*
+
+
+
+=== @XmlEnumValue
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD}
+
+public @interface XmlEnumValue \{
+
+ String value();
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* _@XmlEnumValue.value()_ must have a valid
+lexical representation for _@XmlEnum.value()_ .
+
+
+
+=== Mapping: Enum constant to Enumeration Schema Component
+
+\{value}
+
+ _@XmlEnumValue.value()_
+
+\{annotation}
+
+unspecified
+
+=== @XmlType
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{TYPE})
+
+public @interface XmlType \{
+
+ String name() default "##default";
+
+ String namespace() default "##default" ;
+
+ String[] propOrder() default \{""};
+
+ Class factoryClass() default DEFAULT.class;
+
+ static final class DEFAULT \{};
+
+ String factoryMethod() default ““;
+
+}
+
+=== [[a2837]]Mapping
+
+The following mapping constraints must be
+enforced:
+
+. _factoryMethod(),factoryClass()_ and
+_@XmlType.propOrder_ must be ignored.
+. This annotation can be used only with the
+following other annotations: _@XmlRootElement, @XmlAccessorOrder,
+@XmlAccessorType._ However, _@XmlAccessorOrder_ and _@XmlAccessorType_
+must be ignored; they are not meaningful when used to annotate an enum
+type.
+
+=== @XmlRootElement
+
+ _@XmlRootElement_ can be used to associate a
+global element with the schema type to which the enum type is mapped.
+
+The following mapping constraints must be
+enforced:
+
+. The only other annotations allowed with this
+annotation are: _@XmlType, @XmlEnum, @XmlAccessorType,
+@XmlAcessorOrder._ Note that _@XmlAccessorType_ and _@XmlAccessorOrder_
+while allowed will be ignored by the constraint in
+link:jaxb.html#a2837[See Mapping].
+
+The mapping must be performed as specified in
+link:jaxb.html#a2846[See Mapping: Enum type to Element
+Declaration].
+
+=== [[a2846]]Mapping: Enum type to Element Declaration
+
+\{name}
+
+if _@XmlRootElement.name()_ is “##default“,
+then the XML name derived from the enum type name as specified in
+link:jaxb.html#a3678[See Java Identifier To XML Name]”;
+
+
+
+otherwise _@XmlRootElement.name()_
+
+\{target namespace}
+
+{empty}if _@XmlRootElement.namespace()_ is “
+_##default_ “ _,_ then the value of the targetNamespace to which the
+package containing the class is mapped as specified in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace]
+
+
+
+otherwise _@XmlRootElement.namespace()_
+
+\{type definition}
+
+schema type to which the class is mapped as
+specified in link:jaxb.html#a2578[See @XmlType]”.
+
+\{scope}
+
+ _global_
+
+\{value constraint}
+
+ _absent_
+
+\{nillable}
+
+ _false_
+
+\{identity-constraint definitions}
+
+empty set
+
+\{substitution group affiliation}
+
+ _absent_
+
+*
+
+\{substitution group exclusions}
+
+ _\{extension, restriction}_
+
+\{disallowed substitution}
+
+ _\{substitution,extension,restriction}_
+
+\{abstract}
+
+ _false_
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a2876]]Property And Field
+
+The following must be mapped (subject to the
+mapping constraints listed below):
+
+* read/write property as identified by
+java.beans.Introspector.getBeanInfo with its nearest XML-bound
+superclass as the stopClass.
+* non static, non transient field of all the
+ancestors up to the stopClass (but excluding the stopClass itself); if
+annotated with _@XmlAttribute_ , then static final field must be mapped
+(informally this maps to a fixed attribute but this is formally
+specified in the mapping tables below).
+
+A mapped property is a property found as above
+and mapped either by default or using a JAXB annotation.
+
+A mapped field is a field found as above and
+mapped either by default or using a JAXB annotation.
+
+A property or field that has been annotated
+with _@XmlTransient_ is not mapped.
+
+The following mapping constraints must be
+enforced.
+
+* For a property, a given annotation can be
+applied to either read or write property but not both.
+* A property name must be different from any
+other property name in any of the super classes of the class being
+mapped. +
+* A mapped field name or the de capitalized
+name of a mapped property must be unique within a class. For e.g.
+
+
+
+ // Example 1:
+
+ // Both the field “x” and property getX/setX
+are mapped by
+
+ // default. However, the decapitalized name
+property getX/setX
+
+ // is also “x” which collides with the field
+name “x”.
+
+ public class Foo \{
+
+ public int x;
+
+
+
+ public int getX \{..};
+
+ public void setX \{..};
+
+ }
+
+=== [[a2898]]@XmlElement
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD}
+
+public @interface XmlElement \{
+
+ String name() default "##default" ; // name
+for XML element
+
+ boolean nillable() default false;
+
+ boolean required() default false;
+
+ String namespace() default "##default" ;
+
+ Class type() default DEFAULT.class;
+
+ String defaultValue() default "\u0000";
+
+ static final class DEFAULT \{}
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only additional mapping annotations
+allowed with _@XmlElement_ are: _@XmlID, @XmlIDREF, @XmlList,
+@XmlSchemaType, @XmlValue, @XmlAttachmentRef, @XmlMimeType,
+@XmlInlineBinaryData, @XmlJavaTypeAdapter_ and _@XmElementWrapper.
+@XmlElement_ can also be used within _@XmlElements_ .
+* If the property or field type is a
+parametric collection type, then _@XmlElement.type()_ must be
+_DEFAULT.class_ or _collectionitem.class_ (since the type of the
+collection is already known).
+
+A field or property annotated must be mapped
+as follows:
+
+* If _@XmlElement.namespace()_ is not “
+_##default_ ” and different from the _\{target namespace}_ of the
+enclosing class, then it must be mapped as specified in
+link:jaxb.html#a2941[See Mapping: Property/field to Particle -
+ref attribute].
+* If property is single valued, and it’s type
+is annotated with _@XmlRootElement_ and _@XmlType.name()= ““_ , then the
+property must be mapped as specified in link:jaxb.html#a2941[See
+Mapping: Property/field to Particle - ref attribute].
+
+Design Note: This mapping is designed to
+eliminate an infinite recursion. For example:
+
+ // Code fragment
+
+ @XmlRootElement
+
+ @XmlType(name="")
+
+ class Foo \{
+
+ Foo foo;
+
+ }
+
+In the absence of the above mapping, the above
+code would map to:
+
+ <schema>
+
+ <element name="foo">
+
+ <complexType>
+
+ <sequence>
+
+ <element name=”foo” minOccurs=”0”>
+
+ <complexType>
+
+ ... infinite recursion ...
+
+With the above mapping, the code fragment
+would instead map to:
+
+ <schema>
+
+ <element name="foo">
+
+ <complexType>
+
+ <sequence>
+
+ <element ref=”foo” minOccurs=”0”>
+
+
+
+* otherwise, it must be mapped as
+link:jaxb.html#a2959[See Mapping: Property/field to Particle -
+no ref attribute].
+*
+
+=== Mapping: Property/field to [[a2941]]Particle - ref attribute
+
+\{min occurs}
+
+if _@XmlElement.required()_ is true, then 1
+
+
+
+if the property type is a primitive type or a
+multi dimensional array with a primitive type then 1
+
+
+
+otherwise 0
+
+\{max occurs}
+
+if the type of the property/field is not a
+collection type, then 1
+
+
+
+otherwise _unbounded_ .
+
+\{term}
+
+element declaration as specified in
+link:jaxb.html#a2973[See Mapping: Property/field to Element
+declaration] with the following overrides for the abstract schema
+component properties:
+
+\{scope} is _global_
+
+ _\{value constraint}_ is _absent_
+
+ _\{type definition}_ is _xs:anyType_ if the
+mapping results in two or more element decalarations with the same name.
+
+Note: The above make the element a global
+element declaration rather than a local element declaration.
+
+
+
+=== [[a2959]]Mapping: Property/field to Particle - no ref attribute
+
+\{min occurs}
+
+if _@XmlElement.required()_ is true, then 1
+
+
+
+otherwise if the property type is a primitive
+type or a multi dimensional array with a primitive type then 1
+
+
+
+otherwise 0
+
+\{max occurs}
+
+if the type of the property/field is not a
+collection type, then 1;
+
+
+
+otherwise _unbounded_ .
+
+\{term}
+
+must be mapped as specified in
+link:jaxb.html#a2973[See Mapping: Property/field to Element
+declaration].
+
+
+
+=== Mapping: [[a2973]]Property/field to Element declaration
+
+\{name}
+
+if _@XmlElement.name()_ is _“##default”,_ then
+the XML name derived from the property or field name as specified in
+link:jaxb.html#a3678[See Java Identifier To XML Name]”;
+
+
+
+otherwise _@XmlElement.name()_
+
+\{target namespace}
+
+if _@XmlElement.namespace()_ is “ _##default_
+“, then
+
+if the enclosing package has @ _XmlSchema_
+annotation and is _@XmlSchema.elementFormDefault_ is
+_@XmlNsForm.QUALIFIED_ , then the namespace of the enclosing class. +
+ +
+otherwise ““ (which produces unqualified element in the default
+namespace).
+
+otherwise, _@XmlElement.namespace()_
+
+\{type definition}
+
+Note: The order of type inference below is
+significant.
+
+
+
+if _@XmlElement.type()_ is not _DEFAULT.class_
+, then the schema type to which _@XmlElement.type()_ is mapped.
+
+
+
+otherwise if annotated with _@XmlList,_ schema
+type derived by mapping as specified in link:jaxb.html#a3399[See
+@XmlList]”
+
+
+
+otherwise if annotated with _@XmlValue_ ,
+schema type derived by mapping as specified in
+link:jaxb.html#a3331[See @XmlValue]”
+
+
+
+otherwise if annotated with _@XmlID_ , the
+schema type derived by mapping as specified in
+link:jaxb.html#a3377[See @XmlID]”
+
+
+
+otherwise if annotated with _@XmlIDREF_ , the
+schema type derived by mapping as specified in
+link:jaxb.html#a3387[See @XmlIDREF]”
+
+
+
+otherwise if the property or field is a
+collection type, then the schema type derived by mapping the collection
+item type.
+
+
+
+otherwise the schema type to which the type of
+the property is mapped.
+
+\{scope}
+
+complex type to which the property’s or the
+field’s containing class is mapped as specified in
+link:jaxb.html#a2456[See @XmlSchema]”.
+
+\{value constraint}
+
+if @XmlElement.defaultValue() is "\u0000" then
+_absent_
+
+
+
+otherwise default value with the value
+_@XmlElement.defaultvalue()_ .
+
+\{nillable}
+
+ _@XmlElement.nillable()_
+
+\{identity-constraint definitions}
+
+ _absent_
+
+\{substitution group affiliation}
+
+ _absent_
+
+\{substitution group exclusions}
+
+\{ _extension, restriction_ }
+
+\{disallowed substitution}
+
+\{ _extension, restriction,substitution_ }
+
+\{abstract}
+
+ _false_
+
+\{annotation}
+
+ _unspecified_
+
+.
+
+=== [[a3019]]@XmlElements
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD,METHOD})
+
+public @interface XmlElements \{
+
+ XmlElement[] value(); // collection of
+@XmlElement annotations
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* If the property or field type is a
+parameterized collection type, then the size of the
+_@XmlElements.value()_ must be 1.
+* This annotation can be used only with the
+following annotations: _@XmlIDREF, @XmlElementWrapper,
+@XmlJavaTypeAdapter._
+* If _@XmlIDREF_ is specified, then each
+_@XmlElement.type()_ must contain a JavaBean property/field annotated
+with _@XmlID_ .
+
+The property or field must be mapped as
+follows:
+
+* If the size of _@XmlElements.value()_ is 1,
+then the property must be mapped as specified in
+link:jaxb.html#a2898[See @XmlElement]”.
+* otherwise it must be mapped as specified in
+link:jaxb.html#a3034[See Mapping: List of types to choice
+particle].
+
+
+
+=== [[a3034]]Mapping: List of types to choice particle
+
+\{min occurs}
+
+0
+
+\{max occurs}
+
+ _unbounded_
+
+\{term}
+
+{empty}If \{particples} row in
+link:jaxb.html#a3042[See Mapping: List of types to choice model
+group of elements] results in a single particle, then that single
+particle. Otherwise mapped as specified in
+link:jaxb.html#a3042[See Mapping: List of types to choice model
+group of elements]
+
+
+
+=== [[a3042]]Mapping: List of types to choice model group of elements
+
+\{compositor}
+
+ _choice_
+
+\{particles}
+
+set obtained by mapping each _@XmlElement_ in
+_@XmlElements.value()_ as specified in link:jaxb.html#a2973[See
+Mapping: Property/field to Element declaration].
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3049]]@XmlElementRef
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD}
+
+public @interface XmlElementRef \{
+
+ String name() default "##default" ; // name
+for XML element
+
+ String namespace() default "##default" ;
+
+ Class type() default DEFAULT.class;
+
+ static final class DEFAULT \{}
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only other additional JAXB mapping
+annotations allowed with _@XmlElementRef_ are: _@XmlElementWrapper_ and
+_@XmlJavaTypeAdapter._
+* If the collection item type or property type
+(for single valued property) is _javax.xml.bind.JAXBElement_ , then \{
+_@XmlElementRef.name()_ , _@XmlElementRef.namespace()}_ must point an
+element factory method with an _@XmlElementDecl_ annotation in a class
+annotated with _@XmlRegistry_ (usually _ObjectFactory_ class generated
+by the schema compiler) :
+* _@XmlElementDecl.name()_ must equal
+_@XmlElementRef.name()_
+* _@XmlElementDecl.namespace()_ must equal
+_@XmlElementRef.namespace()_ .
+* If the collection item type (for collection
+property) or property type (for single valued property) is not
+_javax.xml.bind.JAXBElement_ , then the type referenced by the property
+or field must be annotated with _@XmlRootElement_ .
+
+A field or property annotated with the
+_@XmlElementRef_ annotation must be mapped as follows:
+
+* if the type of the property or field is
+single valued property, then it must be mapped as specified in
+link:jaxb.html#a3078[See Mapping: Property/field (property type
+single valued) to Particle with ref attribute]
+* otherwise (the type of the property or field
+is a parametric type), then it must be mapped as specified in
+link:jaxb.html#a3097[See Mapping: Property/Field (parametric
+type) to choice particle].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+=== [[a3078]]Mapping: Property/field (property type single valued) to Particle with ref attribute
+
+\{min occurs}
+
+1
+
+\{max occurs}
+
+1
+
+\{term}
+
+must be mapped as specified in
+link:jaxb.html#a3085[See Mapping: Property/field to Element
+declaration with ref attribute].
+
+=== [[a3085]]Mapping: Property/field to Element declaration with ref attribute
+
+\{name}
+
+if _@XmlElementRef.type()_ is
+_@XmlElementRef.DEFAULT.class_ and the property type is not
+_javax.xml.bind.JAXBElement_ , then the XML name
+_@XmlRootElement.name()_ on the type being referenced.
+
+
+
+otherwise if _@XmlElementRef.type()_ is
+_@XmlElementRef.DEFAULT.class_ and the parametric type or the property
+type (for single valued property) is a _javax.xml.bind.JAXBElement_ ,
+then the _@XmlElementRef.name()_
+
+\{target namespace}
+
+if _@XmlElementRef.type()_ is
+_@XmlElementRef.DEFAULT.class_ and the property type is not
+_javax.xml.bind.JAXBElement_ , then the XML namespace of the type being
+referenced.
+
+ __
+
+otherwise if _@XmlElementRef.type()_ is
+_@XmlElementRef.DEFAULT.class_ and the property type is single valued
+and is _javax.xml.bind.JAXBElement_ , then the
+_@XmlElementRef.namespace()_
+
+\{annotation}
+
+ _unspecified_
+
+
+
+=== [[a3097]]Mapping: Property/Field (parametric type) to choice particle
+
+\{min occurs}
+
+ _0_
+
+\{max occurs}
+
+ _unbounded_
+
+\{term}
+
+{empty}If \{particles} row in
+link:jaxb.html#a3105[See Mapping: Property/field (parametric
+type) to choice model group of element refs] results in single particle,
+then that single particle. Otherwise mapped as specified in
+link:jaxb.html#a3105[See Mapping: Property/field (parametric
+type) to choice model group of element refs]
+
+
+
+=== [[a3105]]Mapping: Property/field (parametric type) to choice model group of element refs
+
+\{compositor}
+
+ _choice_
+
+\{particles}
+
+set obtained by visiting parametric type and
+each of its derived types and if annotated with @XmlRootElement, then
+mapping the @XmlRootElement as specified in as specified in
+link:jaxb.html#a3085[See Mapping: Property/field to Element
+declaration with ref attribute].
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3112]]@XmlElementRefs
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD,METHOD})
+
+public @interface XmlElementRefs \{
+
+ XmlElementRef[] value();
+
+}
+
+
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only other additional JAXB mapping
+annotations allowed with @XmlElementRefs are: _@XmlElementWrapper_ and @
+_XmlJavaTypeAdapter_ .
+
+The property or field must be mapped as
+specified in link:jaxb.html#a3124[See Mapping: List of element
+instances to choice particle].
+
+
+
+=== [[a3124]]Mapping: List of element instances to choice particle
+
+\{min occurs}
+
+ _0_
+
+\{max occurs}
+
+ _unbounded_
+
+\{term}
+
+{empty}If the \{particles} row in
+link:jaxb.html#a3132[See Mapping: List of element instances to
+choice model group of element refs] results in a single particle, then
+that single particle. Otherwise mapped as specified in
+link:jaxb.html#a3132[See Mapping: List of element instances to
+choice model group of element refs]
+
+
+
+=== [[a3132]]Mapping: List of element instances to choice model group of element refs
+
+\{compositor}
+
+ _choice_
+
+\{particles}
+
+set obtained by mapping
+
+* each _@XmlElementRef_ in
+_@XmlElementRefs.value()_ as specified in
+link:jaxb.html#a3049[See @XmlElementRef]”.
+* if property is annotated with
+_@XmlAnyElement,_ then the particle obtained by mapping as specified in
+link:jaxb.html#a3210[See @XmlAnyElement]”
+
+\{annotation}
+
+ _unspecified_
+
+=== @XmlElementWrapper
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD}
+
+public @interface XmlElementWrapper \{
+
+ String name() default "##default" ; // name
+for XML element
+
+ String namespace() default "##default" ;
+
+ boolean nillable() default false;
+
+ boolean required() default false;
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only additional mapping annotations
+allowed with _@XmlElementWrapper_ are: _@XmlElement, @XmlElements,
+@XmlElementRef, @XmlElementRefs, @XmlJavaTypeAdapter._
+* The property or the field must be a
+collection property.
+
+The property or field must be mapped as
+follows:
+
+* If _@XmlElementWrapper.namespace()_ is not “
+_##default_ ” and different from the _\{target namespace}_ of the
+enclosing class, then it must be mapped as specified as specified in
+link:jaxb.html#a3202[See Mapping: Property/field Element Wrapper
+with ref attribute].
+* otherwise, it must be mapped as
+link:jaxb.html#a3158[See Mapping: Property/field to Particle for
+Element Wrapper].
+
+
+
+=== [[a3158]]Mapping: Property/field to Particle for Element Wrapper
+
+\{min occurs}
+
+if _@XmlElementWrapper.nillable()_ is true or
+_@XmlElementWrapper.required()_ is true, then 1;
+
+
+
+otherwise 0
+
+\{max occurs}
+
+1
+
+\{term}
+
+must be mapped as specified in
+link:jaxb.html#a3167[See Mapping: Property/field to Element
+Declaration for Element Wrapper].
+
+=== Mapping: Property/field to Element Declaration for Element Wrapper [[a3167]]
+
+\{name}
+
+if _@XmlElementWrapper.name()_ is “
+_##default_ “, then the XML name derived from the property or field name
+as specified in link:jaxb.html#a3678[See Java Identifier To XML
+Name]”;
+
+
+
+otherwise _@XmlElementWrapper.name()_
+
+\{target namespace}
+
+if _@XmlElementWrapper.namespace()_ is “
+_##default_ “,
+
+if the enclosing package has @ _XmlSchema_
+annotation and is _@XmlSchema.elementFormDefault_ is
+_@XmlNsForm.QUALIFIED_ , then the namespace of the enclosing class. +
+ +
+otherwise ““ (which produces unqualified element in the default
+namespace).
+
+otherwise _@XmlElementWrapper.namespace()_
+
+\{type definition}
+
+{empty}if property/field is annotated with
+_@XmlElementRef_ or _@XmlElementRefs_ then the schema type as specified
+in link:jaxb.html#a3124[See Mapping: List of element instances
+to choice particle]
+
+
+
+otherwise if property/field is annotated with
+_@XmlElement_ or _@XmlElements_ then the schema type as specified
+inlink:jaxb.html#a3034[See Mapping: List of types to choice
+particle].
+
+\{scope}
+
+complex type to which the property’s or the
+field’s containing class is mapped.
+
+\{value constraint}
+
+ _absent_
+
+\{nillable}
+
+ _@XmlElementWrapper.nillable()_
+
+\{identity-constraint definitions}
+
+ _absent_
+
+
+
+\{substitution group affiliation}
+
+ _absent_
+
+
+
+\{substitution group exclusions}
+
+\{ _extension, restriction_ }
+
+
+
+\{disallowed substitution}
+
+\{ _extension, restriction,substitution_ }
+
+
+
+\{abstract}
+
+ _false_
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3202]]Mapping: Property/field Element Wrapper with ref attribute
+
+\{min occurs}
+
+1
+
+\{max occurs}
+
+1
+
+\{term}
+
+element declaration whose \{name} is
+_@XmlElementWrapper.name()_ and \{target namespace} is
+_@XmlElementWrapper.namespace()._
+
+Note: The element declaration is assumed to
+already exist and is not created.
+
+=== [[a3210]]@XmlAnyElement
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlAnyElement \{
+
+ boolean lax() default false;
+
+ Class<? extends DomHandler> value() default
+W3CDomHandler.class;
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only other JAXB annotations allowed with
+_@XmlAnyElement_ are: _@XmlElementRefs._
+* There must be only one property or field
+that is annotated with _@XmlAnyElement_ .
+* If a baseType has a property annotated with
+_@XmlAnyElement_ , then no other sub type in the inheritance hierarchy
+rooted at baseType can contain a property annotated with
+_@XmlAnyElement_ .
+
+The property or field must be mapped as
+specified in link:jaxb.html#a3223[See Mapping: Wildcard schema
+component for wildcard (xs:any)]”.
+
+=== [[a3223]]Mapping: Wildcard schema component for wildcard (xs:any)
+
+\{namespace constraint}
+
+ _##other_
+
+\{process contents}
+
+ _”lax”_ if _lax()_ is _true_ otherwise
+_“skip”_
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3230]]@XmlAttribute
+
+ _@XmlAttribute_ is used to map a property or
+a field to an XML attribute.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlAttribute \{
+
+ String name() default ##default”;
+
+ boolean required() default false;
+
+ String namespace() default "##default" ;
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* If the type of the field or the property is
+a collection type, then the collection item type must be mapped to
+schema simple type. Examples:
+
+ @XmlAttribute List<Integer> foo; // legal
+
+ @XmlAttribute List<Bar> foo; // illegal if
+Bar does not map to a
+
+ // schema simple type
+
+* If the type of the field or the property is
+a non collection type, then the type of the property or field must map
+to a simple schema type. Examples:
+
+ @XmlAttribute int foo; // legal
+
+ @XmlAttribute Foo foo; // illegal if Foo does
+not map to a schema
+
+ // simple type
+
+* The only additional mapping annotations
+allowed with _@XmlAttribute_ are: _@XmlID, @XmlIDREF, @XmlList,
+@XmlSchemaType, @XmlValue, @XmlAttachmentRef, @XmlMimeType,
+@XmlInlineBinaryData, @XmlJavaTypeAdapter._
+*
+
+The property or field must be mapped as
+follows:
+
+* If _@XmlAttribute.namespace()_ is not
+“##default” and differs from the _\{target namespace}_ of the schema
+type to which the type containing the property or field is mapped, then
+the property or field must be mapped as specified in
+link:jaxb.html#a3255[See Mapping: Property/field to Attribute
+Use (with ref attribute)].
+* otherwise, it must be mapped as specified in
+link:jaxb.html#a3266[See Mapping: Property/field to Attribute
+Use (no ref attribute)].
+
+
+
+=== [[a3255]]Mapping: Property/field to Attribute Use (with ref attribute)
+
+\{required}
+
+ _@XmlAttribute.required()_
+
+\{attribute declaration}
+
+attribute declaration whose \{name} is
+_@XmlAttribute.name()_ and \{target namespace} is
+_@XmlAttribute.namespace()._
+
+For e.g.
+
+ _<xs:attribute ref=”xml:lang”/>_
+
+\{value constraint}
+
+ _absent_
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3266]]Mapping: Property/field to Attribute Use (no ref attribute)
+
+\{required}
+
+ _@XmlAttribute.required()_
+
+\{attribute declaration}
+
+Mapped as specified in
+link:jaxb.html#a3276[See Mapping: Property/field to Attribute
+Declaration]”
+
+\{value constraint}
+
+
+
+if field has access modifiers public and
+static then the _fixed_
+
+otherwise _absent_
+
+
+
+=== [[a3276]]Mapping: Property/field to Attribute Declaration
+
+\{name}
+
+if _@XmlAttribute.name()_ is “##default“, then
+the XML name derived from the property or field name as specified in
+link:jaxb.html#a3678[See Java Identifier To XML Name]”;
+
+
+
+otherwise _@XmlAttribute.name()_ .
+
+\{target namespace}
+
+if _@XmlAttribute.namespace()_ is
+_“##default”,_ then value of targetNamespace in
+link:jaxb.html#a2476[See Mapping: Package to XML target
+namespace];
+
+
+
+otherwise _@XmlType.namespace()_
+
+\{type definition}
+
+if annotated with _@XmlList,_ schema type
+derived by mapping as specified in link:jaxb.html#a3399[See
+@XmlList]”
+
+
+
+otherwise if annotated with _@XmlID_ , the
+schema type derived by mapping as specified in
+link:jaxb.html#a3377[See @XmlID]”
+
+
+
+otherwise if annotated with _@XmlIDREF_ , the
+schema type derived by mapping as specified in
+link:jaxb.html#a3387[See @XmlIDREF]”
+
+
+
+otherwise if the type of the property is a
+collection type, then the schema type derived by mapping the collection
+item type.
+
+
+
+otherwise the schema type to which the type of
+the property is mapped.
+
+\{scope}
+
+complex type of the containing class
+
+\{value constraint}
+
+if field has access modifiers static and final
+then _fixed_
+
+otherwise _absent_
+
+\{annotation}
+
+ _unspecified_
+
+
+
+=== [[a3303]]XmlAnyAttribute
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlAnyAttribute\{}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* There must be only one property or field in
+a class that is annotated with _@XmlAnyAttribute._
+* The type of the property or the field must
+be _java.util.Map._
+* The only other annotations that can be used
+on the property or field with _@XmlAnyAttribute_ are:
+_@XmlJavaTypeAdapter._
+
+The property or field must be mapped as
+specified in link:jaxb.html#a3313[See Mapping: Wildcard schema
+component for Attribute Wildcard].”
+
+=== [[a3313]]Mapping: Wildcard schema component for Attribute Wildcard
+
+\{namespace constraint}
+
+ _##other_
+
+\{process contents}
+
+ _skip_
+
+\{annotation}
+
+ _unspecified_
+
+=== @XmlTransient
+
+ _@XmlTransient_ is used to prevent the
+mapping of a property or a field.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD,
+TYPE})
+
+public @interface XmlTransient \{}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The field or the property must not be
+mapped.
+* _@XmlTransient_ is mutually exclusive with
+all other mapping annotations.
+
+
+
+
+
+=== [[a3331]]@XmlValue
+
+=== Synopsis
+
+ _@Retention(RUNTIME) @Target(\{FIELD,
+METHOD})_
+
+ _public @interface XmlValue \{}_
+
+=== XmlValue Type Mapping
+
+The following mapping constraints must be
+enforced:
+
+. At most one field or a property in a class
+can be annotated with @ _XmlValue_ .
+. _@XmlValue_ can be used with the following
+annotations:
+. _@XmlList_ - however this is redundant
+since _@XmlList_ maps a type to a schema simple type that derives by
+list just as _@XmlValue_ would.
+. _@XmlJavaTypeAdapter_
+. If the type of the field or property is a
+collection type, then the collection item type must map to a simple
+schema type. Examples:
+
+ // Examples (not exhaustive): Legal usage of
+@XmlValue
+
+ @XmlValue List<Integer> foo; // int maps to
+xs:int
+
+ @XmlValue String[] foo; // String maps to
+xs:string
+
+ @XmlValue List<Bar> foo; // only if Bar maps
+to a simple
+
+ // schema type
+
+. If the type of the field or property is not
+a collection type, then the type of the property or field must map to a
+schema simple type.
+. The containing class must not extend another
+class (other than java.lang.Obect).
+
+=== Mapping
+
+* If the type of the property or field is a
+collection type, then the type must be must be mapped as specified in
+link:jaxb.html#a3353[See @XmlValue: Mapping to list simple
+type]”.
+* Otherwise, the schema type to which the type
+of the property or field is mapped.
+
+
+
+=== [[a3353]]@XmlValue: Mapping to list simple type
+
+\{name}
+
+ _absent_
+
+\{target namespace}
+
+\{target namespace} of the attribute or
+element to which the property or field is mapped and from where this
+type is referenced.
+
+\{base type definition}
+
+ur-type definition, _xs:anyType_ .
+
+\{facets}
+
+ _empty set_
+
+\{fundamental facets}
+
+derived
+
+\{final}
+
+#all
+
+\{variety}
+
+list
+
+\{item type definition}
+
+if the field, property or parameter is a
+collection type
+
+* if annotated with _@XmlIDREF_ , then
+_xs:IDREF_ as specified in link:jaxb.html#a3387[See @XmlIDREF]”
+* otherwise the schema type to which the
+collection item type is mapped.
+
+otherwise
+
+* if annotated with _@XmlIDREF_ , then
+_xs:IDREF_ as specified in link:jaxb.html#a3387[See @XmlIDREF]”
+* otherwise the schema type to which the type
+of the property, field or the parameter is mapped.
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3377]]@XmlID
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlID \{}
+
+=== XmlID Type Mapping
+
+The following mapping constraints must be
+enforced:
+
+* at most one field or property in a class can
+be annotated with _@XmlID_ .
+* The type of the field or property must be
+_java.lang.String_ .
+* The only other program annotations allowed
+with _@XmlID_ are: _@XmlAttribute_ and _@XmlElement_ .
+
+The type of the annotated program element must
+be mapped to _xs:ID._
+
+=== [[a3387]]@XmlIDREF
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlIDREF \{}
+
+=== XmlIDREF Type Mapping
+
+The following mapping constraints must be
+enforced:
+
+* If the type of the field or property is a
+collection type, then the collection item type must contain a property
+or field annotated with _@XmlID_ .
+* If the field or property is not a collection
+type, then the type of the property or field must contain a property or
+field annotated with _@XmlID_ .
+
+Note: If the collection item type or the type
+of the property (for non collection type) is _java.lang.Object,_ then
+the instance must contain a property/field annotated with _@XmlID_
+attribute.
+
+* The only additional mapping annotations
+allowed with _@XmlIDREF_ are: _@XmlElement_ , _@XmlAttribute, @XmlList,_
+and _@XmlElements, @XmlJavaTypeAdapter._
+
+If the type of the field or property is a
+collection type, then each collection item type must be mapped to
+_xs:IDREF_ .
+
+If the type of the field or property is single
+valued, then the type of the property or field must be mapped to
+_xs:IDREF_ .
+
+=== [[a3399]]@XmlList
+
+This annotation maps a collection type to a
+list simple type.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD,
+PARAMETER})
+
+public @interface XmlList \{}
+
+=== XmlIList Type Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The type of the field, property or parameter
+must be a collection type.
+* The collection item type must map to a
+simple schema type that does not derive by list. For example:
+
+
+
+ // Examples: Legal usage of @XmlList
+
+ @XmlList List<Integer> foo; // int maps to
+xs:int
+
+ @XmlList String[] foo; // String maps to
+xs:string
+
+ @XmlList List<Bar> foo; // only if Bar maps
+to a simple type
+
+
+
+ // Example: Illegal usage of @XmlList
+
+ public class Foo \{
+
+ // @XmlValue maps List to a XML Schema list
+simple type
+
+ @XmlValue List<Integer> a;
+
+ }
+
+ class Bar \{
+
+ // Use of @XmlList is illegal since Foo
+itself mapped
+
+ // to a XML Schema list simple type; XML
+Schema list simple
+
+ // type can't derive from another XML Schema
+list simple type
+
+ @XmlList List<Foo> y;
+
+ }
+
+* The only additional mapping annotations
+allowed with _@XmlList_ are: _@XmlElement, @XmlAttribute, @XmlValue_ and
+_@XmlIDREF, @XmlJavaTypeAdapter._
+
+The type of the property or field must be
+mapped as specified in link:jaxb.html#a3428[See @XmlList:
+Mapping to list simple type].
+
+
+
+=== [[a3428]]@XmlList: Mapping to list simple type
+
+\{name}
+
+ _absent_
+
+\{target namespace}
+
+\{target namespace} of the attribute or
+element to which the property or field is mapped and from where this
+type is referenced.
+
+\{base type definition}
+
+ur-type definition, _xs:anyType_ .
+
+\{facets}
+
+ _empty set_
+
+\{fundamental facets}
+
+derived
+
+\{final}
+
+#all
+
+\{variety}
+
+list
+
+\{item type definition}
+
+if annotated with _@XmlIDREF_ , then xs:IDREF
+as specified in link:jaxb.html#a3387[See @XmlIDREF]”
+
+
+
+otherwise the schema type to which the
+collection item type is mapped.
+
+\{annotation}
+
+ _unspecified_
+
+=== [[a3449]]@XmlMixed
+
+This annotation is used for dealing with mixed
+content in XML instances.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{FIELD, METHOD})
+
+public @interface XmlMixed \{}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* The only additional mapping annotations
+allowed with _@XmlMixed_ are: _@XmlElementRef, @XmlAnyElement,
+@XmlJavaTypeAdapter._
+
+The java.lang.String instances must be
+serialized as XML infoset text information items.
+
+=== @XmlMimeType
+
+=== Synopsis
+
+@Retention(RUNTIME)
+@Target(\{FIELD,METHOD,PARAMETER})
+
+public @interface XmlMimeType \{
+
+ // Textual representation of the MIME type,
+such as "image/jpeg"
+
+ // "image/*", "text/xml; charset=iso-8859-1"
+and so on.
+
+ String value();
+
+}
+
+=== Mapping
+
+
+
+=== @XmlMimeType: Mapping to Foreign Namespace attribute
+
+\{name}
+
+ _“expectedContentTypes”_
+
+\{target namespace}
+
+"http://www.w3.org/2005/05/xmlmime"
+
+attribute value
+
+ _@XmlMimeType.value()_
+
+=== @XmlAttachmentRef
+
+=== Synopsis
+
+@Retention(RUNTIME)
+@Target(\{FIELD,METHOD,PARAMETER})
+
+public @interface XmlAttachmentRef \{ }
+
+=== Mapping
+
+The type of property or field must map to
+_ref:swaRef_ .
+
+=== XmlInlineBinaryData
+
+@Retention(RUNTIME)
+@Target(\{FIELD,METHOD,TYPE})
+
+public @interface XmlInlineBinaryData \{
+
+}
+
+=== Mapping
+
+This annotation does not impact the schema
+generation. See the javadoc for
+_javax.xml.bind.annotation.XmlInlineBinaryData_ for more details.
+
+=== ObjectFactory Method
+
+The annotations in this section are intended
+primarily for use by schema compiler in annotating element factory
+methods in the schema derived ObjectFactory class
+(link:jaxb.html#a482[See Java Package]”). They are not expected
+to be used when mapping existing classes to schema.
+
+
+
+=== @XmlElementDecl
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{METHOD})
+
+public @interface XmlElementDecl \{
+
+ Class scope() default GLOBAL.class;
+
+
+
+ // XML namespace of element
+
+ String namespace() default "##default";
+
+
+
+ String name(); // local name of element
+
+
+
+ //XML namespace name of a substitution
+group's head element.
+
+ String substitutionHeadNamespace() default
+"##default";
+
+
+
+ //XML local name of a substitution group's
+head element.
+
+ String substitutionHeadName() default "";
+
+ public final class GLOBAL \{}
+
+}
+
+=== Mapping
+
+The following mapping constraints must be
+enforced:
+
+* annotation can only be used on an element
+factory method (link:jaxb.html#a482[See Java Package]”). The
+annotation creates a mapping between an XML schema element declaration
+and a element factory method that returns a _JAXBElement_ instance
+representing the element declaration. Typically, the element factory
+method is generated (and annotated) from a schema into the
+_ObjectFactory_ class in a Java package that represents the binding of
+the element declaration's target namespace. Thus, while the annotation
+syntax allows _@XmlElementDecl_ to be used on any method, semantically
+its use is restricted to annotation of element factory method
+* class containing the element factory method
+annotated with _@XmlElementDecl_ must be annotated with _@XmlRegistry_ .
+* element factory method must take one
+parameter assignable to _java.lang.Object_ .
+* two or more element factory methods
+annotated with _@XmlElementDecl_ must not map to element declarations
+with identical _\{name}_ _\{target namespace}_ values.
+* if type Foo has an element factory method
+and is also annotated with @XmlRootElement, then they must not map to
+element declarations with identical _\{name}_ and _\{target namespace}_
+values.
+
+One example of where the above scenario occurs
+is when a developer attempts to add behavior/data to code generated from
+schema. For e.g. schema compiler generates an element instance factory
+method (e.g. _createFoo_ ) annotated with _@XmlElementDecl_ . But the
+developer annotates _Foo_ with _@XmlRootElement_ .
+
+An element factory method must be mapped as
+specified in link:jaxb.html#a3518[See Mapping: Element Factory
+method to Element Declaration].
+
+
+
+=== [[a3518]]Mapping: Element Factory method to Element Declaration
+
+\{name}
+
+ _@XmlElementDecl.name()_
+
+\{target namespace}
+
+{empty}if _@XmlElementDecl.namespace()_ is “
+_##default_ “ _,_ then the value of the targetNamespace to which the
+package of the class containing the factory method is mapped as
+specified in link:jaxb.html#a2476[See Mapping: Package to XML
+target namespace]
+
+
+
+otherwise _@XmlElementDecl.namespace()_
+
+\{type definition}
+
+schema type to which the class is mapped as
+specified in link:jaxb.html#a2578[See @XmlType]”.
+
+\{scope}
+
+ _global_ if _@XmlElementDecl.scope()_ is
+_@XmlElementDecl.GLOBAL_
+
+
+
+otherwise the complex type definition to which
+the class containing the object factory method is mapped.
+
+\{value constraint}
+
+ _absent_
+
+\{nillable}
+
+ _false_
+
+\{identity-constraint definitions}
+
+empty set
+
+\{substitution group affiliation}
+
+element declaration derived from
+_@XmlElementDecl.name()_ and _@XmlElementDecl.substitutionHeadName()_
+
+\{substitution group exclusions}
+
+ _\{}_
+
+\{disallowed substitution}
+
+\{}
+
+\{abstract}
+
+ _false_
+
+\{annotation}
+
+ _unspecified_
+
+=== Adapter
+
+=== XmlAdapter
+
+public abstract class
+XmlAdapter<ValueType,BoundType> \{
+
+ // Do-nothing constructor for the derived
+classes.
+
+ protected XmlAdapter() \{}
+
+
+
+ // Convert a value type to a bound type.
+
+ public abstract BoundType unmarshal(ValueType
+v);
+
+
+
+ // Convert a bound type to a value type.
+
+ public abstract ValueType marshal(BoundType
+v);
+
+}
+
+For an overview, see the section,
+link:jaxb.html#a2278[See Adapter]”.
+
+For detailed information, see the javadocs for
+_javax.xml.bind.annotation.adapters.XmlAdapter_ and
+_javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter._
+
+=== [[a3561]]@XmlJavaTypeAdapter
+
+=== Synopsis
+
+@Retention(RUNTIME)
+@Target(\{PACKAGE,FIELD,METHOD,TYPE,PARAMETER})
+
+public @interface XmlJavaTypeAdapter \{
+
+ Class<? extends XmlAdapter> value();
+
+ Class type() default DEFAULT.class;
+
+ static final class DEFAULT \{}
+
+}
+
+For an overview, see
+link:jaxb.html#a2278[See Adapter]”.
+
+=== Scope
+
+The scope of _@XmlJavaTypeAdapter_ must cover
+the program elements as specified below:
+
+package:
+
+For clarity, the following code example is
+used along with normative text.
+
+// Adapts Foo type to MyFoo type
+
+FooAdapter extends XmlAdapter<MyFoo, Foo>
+
+
+
+// FooAdapter is installed at the package
+level - example.po
+
+@XmlJavaTypeAdapter(value=FooAdapter.class,
+type=Foo.class)
+
+A _@XmlJavaTypeAdapter_ that extends
+_XmlAdapter <valueType, boundType>_ and is specified as a package level
+annotation must adapt _boundType_ at the point of reference as follows:
+
+. a property/field/parameter within a class in
+package (e.g _exmple.po)_ whose reference type is _boundType_ . For e.g.
+
+ // Foo will be adapted to MyFoo
+
+ Foo foo;
+
+. a property/field/parameter within a class in
+package (e.g _exmple.po)_ , where _boundType_ is used as a parametric
+type. For e.g.
+
+ // List<Foo> will be adapted to List<MyFoo>
+
+ Foo foo;
+
+
+
+class, interface, enum type:
+
+For clarity, the following code example is
+used along with normative text.
+
+// Adapts Foo type to MyFoo type
+
+FooAdapter extends XmlAdapter<MyFoo, Foo>
+
+
+
+// FooAdapter is specified on class, interface
+or enum type. @XmlJavaTypeAdapter(FooAdapter.class)
+
+public class Foo \{...}
+
+A _@XmlJavaTypeAdapter_ that extends
+_XmlAdapter <valueType, boundType>_ and is specified on the class,
+interface or Enum type (i.e. on a program element that matches meta
+annotation @Target=\{type}) must adapt _boundType_ at the point of
+reference as follows:
+
+. a property/field whose reference type is
+_boundType_ . For e.g.
+
+ // Foo will be adapted to MyFoo
+
+ Foo foo;
+
+. a property/field where _boundType_ is used
+as a parametric type. For e.g.
+
+ // List<Foo> will be adapted to List<MyFoo>
+
+ List<Foo> foo;
+
+Note: A _@XmlJavaTypeAdapter_ on a class does
+not apply to references to it’s sub class.
+
+//Example:
+
+@XmlJavaTypeAdapter(..) public class Foo \{..}
+
+...
+
+public class DerivedFoo extends Foo \{..}
+
+...
+
+public class Bar \{
+
+ // XmlJavaTypeAdapter applies to foo;
+
+ public Foo foo;
+
+ ...
+
+ // XmlJavaTypeAdaper DOES NOT apply to
+derivedFoo;
+
+ public DerivedFoo derivedFoo;
+
+}
+
+property/field/parameter:
+
+A _@XmlJavaTypeAdapter_ that extends
+_XmlAdapter <valueType, boundType>_ and is specified on the
+property/field or parameter must adapt _boundType_ as follows:
+
+. property/field is a single valued and its
+type is _boundType_ :
+
+ // Foo will be adapted to MyFoo
+
+ @XmlJavaTypeAdapter(FooAdapter.class) Foo
+foo;
+
+. a property/field where _boundType_ is used
+as a parametric type. For e.g.
+
+ // List<Foo> will be adapted to List<MyFoo>
+
+ List<Foo> foo;
+
+=== Relationship to other annotations
+
+ _@XmlJavaTypeAdapter_ must be applied first
+before any other mapping annotation is processed. Further annotation
+processing is subject to their respective mapping constraints. For
+example,
+
+// PtoQAdapter is applied first and therefore
+converts type Q to P
+
+// Next foo is mapped with a type of P (not Q)
+subject to the
+
+// mapping constraints specified in
+@XmlElements.
+
+@XmlJavaTypeAdapter(PtoQAdapter)
+
+@XmlElements(\{
+
+ @XmlElement(name="x",type=PX.class),
+
+ @XmlElement(name="y",type=PY.class)
+
+})
+
+Q foo;
+
+
+
+@XmlType abstract class P \{}
+
+@XmlType class PX extends P \{}
+
+@XmlType class PY extends P \{}
+
+=== Class Inheritance Semantics
+
+When annotated on a class, the use of
+_@XmlJavaTypeAdapter_ annotation is subject to the class inheritance
+semantics described here. The semantics is described in terms of two
+classes: a _BaseClass_ and a _SubClass_ that derives from _BaseClass_ .
+There are two cases to consider:
+
+* _@XmlJavaTypeAdapter_ annotates the
+_BaseClass_
+* _@XmlJavaTypeAdapter_ annotates the
+_SubClass_ , a class that derives from _BaseClass_ .
+
+BaseClass: In this case, _@XmlJavaTypeAdapter_
+annotates the _BaseClass_ . In this case, the marshalling and
+unmarshalling of an instance of property or a field with a static type
+of baseClass must follow the schema to which
+_XmlJavaTypeAdapter.value()_ is mapped.
+
+//Example: code fragment
+
+@XmlJavaTypeAdapter(..) BaseClass \{..}
+
+public SubClass extends BaseClass \{..}
+
+public BaseClass foo;
+
+public SubClass subFoo = new SubClass();
+
+foo = subFoo;
+
+In the absence of _@XmlJavaTypeAdapter_
+annotation, the instance of subFoo is marshalled with an xsi:type:
+
+<foo xsi:type="subClass"/>
+
+With the _@XmlJavaTypeAdapter_ annotation,
+however, the instance of subFoo must be marshalled/unmarshalled
+following the XML schema for _@XmlJavaTypeAdapter.value()_ .
+
+Subclass: In this case, _@XmlJavaTypeAdapter_
+annotates the _SubClass_ . By definition, the annotation does not cover
+references to BaseClass. Thus, the schema types to which _SubClass_ and
+_BaseClass_ map are not in the same schema type hierarchy. Hence an
+object with a static type of _BaseClass_ but containing an instance of
+_SubClass_ can’t be marshalled or unmarshalled. An attempt to do so must
+fail. For e.g,
+
+// Example: Code fragment
+
+BaseClass\{..}
+
+...
+
+@XmlJavaTypeAdapter(..) SubClass extends
+BaseClass \{..}
+
+
+
+public class Bar \{
+
+ public BaseClass foo;
+
+ public SubClass subFoo = new SubClass();
+
+
+
+ // marshal, unmarshal of foo will fail
+
+ foo = subFoo;
+
+
+
+ // marshal, unmarshal of subFoo will succeed
+
+}
+
+=== @XmlJavaTypeAdapters
+
+This annotation is a container annotation for
+defining multiple _@XmlJavTypeAdapters_ annotations at the package
+level.
+
+=== Synopsis
+
+@Retention(RUNTIME) @Target(\{PACKAGE})
+
+public @interface XmlJavaTypeAdapters \{
+
+ // Collection of @\{@link XmlJavaTypeAdapter}
+annotations
+
+ XmlJavaTypeAdapter[] value();
+
+}
+
+=== Mapping
+
+Each _@XmlJavaTypeAdapter_ annotation in
+_@XmlJavaTypeAdapters.value()_ must be mapped as specified in
+link:jaxb.html#a3561[See @XmlJavaTypeAdapter]”.
+
+=== [[a3676]]Default Mapping
+
+This section describes the default mapping of
+program elements. The default mapping is specified in terms of default
+annotations that are considered to apply to a program element even in
+their absence.
+
+=== [[a3678]]Java Identifier To XML Name
+
+The following is the default mapping for
+different identifiers:
+
+* class name: a class name is mapped to an XML
+name by de capitalization using
+_java.beans.Introspector.decapitalize(class name )._
+* enumtype name: enumtype name is mapped to an
+XML name by de capitalization using
+_java.beans.Introspector.decapitalize(enumtype name)._
+* A property name (e.g. address) is derived
+from JavaBean access method (e.g. getAddress) by JavaBean de
+capitalization of the JavaBean property name
+_java.beans.Introspector.decapitalize(JavaBeanAccessMethod)_
+
+=== Package
+
+A package must be mapped with the following
+default package level mapping annotations:
+
+* _@XmlAccessorType( +
+javax.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER)_
+* _@XmlAccessorOrder( +
+javax.xml.bind.annotation.XmlAccessOrder.UNDEFINED)_
+*
+
+* _@XmlSchema_
+
+=== Class
+
+Unless _@XmlTransient_ annotation is present,
+a class with a public or protected no-arg constructor must be mapped
+with the following default mapping annotations: _@XmlType_ .
+
+=== enum type
+
+An enum type must be mapped with the following
+default mapping annotations:
+
+* enum type declaration:
+
+ @XmlType
+
+ @XmlEnum
+
+ enum type \{...}
+
+* each enum constant:
+
+ @XmlEnumValue (enumConstatEnum.name())
+
+=== Property / Field
+
+If the value of _@XmlAccessorType.value()_ is
+_javax.xml.bind.annotation.XmlAccessType.NONE_ , then
+
+* properties and fields, unless explicitly
+annotated, must be considered to be annotated with _@XmlTransient_ .
+
+If the value of _@XmlAccessorType.value()_ is
+_javax.xml.bind.annotation.XmlAccessType.PROPERTY_ , then
+
+* properties not explicitly annotated must be
+mapped; fields, unless explicitly annotated, must be considered to be
+annotated with _@XmlTransient._
+
+If the value of _@XmlAccessorType.value()_ is
+_javax.xml.bind.annotation.XmlAccessType.FIELD_ , then
+
+* fields not explicitly annotated must be
+mapped; properties, unless explicitly annotated, must be considered to
+be annotated with _@XmlTransient._
+
+If the value of _@XmlAccessorType.value()_ is
+_javax.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER,_ then
+
+* all properties and public fields, unless
+annotated with _@XmlTransient_ , must be mapped.
+
+See javadoc for
+_@javax.xml.bind.annotation.XmlAccessorType_ for further information on
+inheritance rules for this annotation.
+
+=== Default Mapping
+
+A property name (e.g. address) must be derived
+from JavaBean access method (e.g. getAddress) by JavaBean
+decapitalization of the JavaBean property name
+_java.beans.Introspector.decapitalize(JavaBeanAccessMethod)_
+
+A single valued property or field must be
+mapped with the following default mapping annotation:
+
+ _@XmlElement_
+
+*
+
+A property or field with a collection type
+must be mapped by with the following default mapping annotation:
+
+* if the property or field is annotated with
+_@XmlList_ , then the default mapping annotation is:
+
+ @XmlElement
+
+
+
+* otherwise the default mapping annotation is:
+
+ @XmlElements( \{ @XmlElement(nillable=true)})
+
+=== Map
+
+By default, _java.util.Map<K,V>_ must be
+mapped to the following anonymous schema type. The parameterized types K
+and V must be mapped as specified in link:jaxb.html#a2386[See
+Type Arguments and Wildcards]”. The anonymous schema type is at the
+point of reference.
+
+<!-- Default XML Schema mapping for Map<K,V>
+-->
+
+<xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name="entry"
+
+ minOccurs ="0" maxOccurs="unbounded">
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name="key" type="xs:anyType"
+
+ minOccurs="0"/>
+
+ <xs:element name="value" type="xs:anyType"
+
+ minOccurs="0"/>
+
+ </xs:sequence>
+
+ </xs:complexType>
+
+ </xs:element>
+
+ </xs:sequence>
+
+</xs:complexType>
+
+
+
+<!-- Default XML Schema mapping for
+Map<String, Integer>-->
+
+<xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name="entry"
+
+ minOccurs="0" maxOccurs="unbounded">
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name="key" type="xs:string"
+
+ minOccurs="0"/>
+
+ <xs:element name="value" type="xs:int"
+
+ minOccurs="0"/>
+
+ </xs:sequence>
+
+ </xs:complexType>
+
+ </xs:element>
+
+ </xs:sequence>
+
+</xs:complexType>
+
+The mapping of Map can be customized using
+_@XmlJavaTypeAdapter_ annotation.
+
+=== Multidimensional Array
+
+By default, a multidimensional array must be
+mapped to a complex type as follows. Note the table specifies a two
+dimensional array mapping. If an array is more than two dimensions, then
+the mapping is used recursively.
+
+
+
+=== Mapping: Two dimensional array to Complex Type Definition
+
+\{name}
+
+If the basetype is a primitive type (e.g.
+int[][]) or its corresponding wrapper class (e.g. Integer[][]), then the
+name is basetype concatenated with “Array” (e.g. intArray).
+
+
+
+otherwise if the basetype is a reference type
+(e.g. Foo[][]), then the XML name to which the reference type is mapped
+(e.g. foo) concatenated with “Array” (e.g. fooArray).
+
+\{target namespace}
+
+if the basetype is a primitive or its
+corresponding wrapper class then "http://jaxb.dev.java.net/array"
+
+ __
+
+otherwise the namespace to which the reference
+type is mapped (e.g. for Foo[][], the namespace of the XML type to which
+Foo is mapped).
+
+\{base type definition}
+
+ _xs:anyType_
+
+\{derivation method}
+
+ _restriction_
+
+\{final}
+
+ _#all_
+
+\{abstract}
+
+false
+
+\{attribute uses}
+
+empty set
+
+\{attribute wildcard}
+
+absent
+
+\{content type}
+
+ _element-only content +
+content model_ mapped as specified in link:jaxb.html#a3787[See
+Mapping: Two dimensional array to sequence model group]”.
+
+\{prohibited substitutions}
+
+Empty set
+
+\{annotations}
+
+ _absent_
+
+
+
+=== [[a3787]]Mapping: Two dimensional array to sequence model group
+
+\{compositor}
+
+ _xs:sequence_
+
+\{particles}
+
+A repeating element defined as follows:
+
+
+
+ _<xs:element name="item" type=schematype
+minOccurs="0" maxOccurs="unbounded" nillable="true"/>_
+
+
+
+where schematype is the schema to which the
+array’s component type is mapped (e.g. int[][], then “xs:int”; Foo[][]
+then “foo” assuming Foo is mapped to the schema type foo.
+
+\{annotation}
+
+ _unspecified_
+
+=== Notes
+
+This section contains a collection of notes
+intended to aid in the review of this version of the specification. They
+are collected here in a separate section and referenced from possibly
+multiple places elsewhere in the specification to make the specification
+more compact.
+
+=== [[a3800]]@XmlType: List simple type
+
+It is possible to map a homogenous collection
+to a simple type with a variety of \{list}. For e.g.
+
+// Code fragment
+
+public class USStateList \{
+
+ @XmlValue
+
+ List <int> items;
+
+}
+
+
+
+// schema fragment
+
+<xs:simpleType name=”USStateList”>
+
+ <xs:list itemType=”int”/>
+
+<xs:simpleType>
+
+Other types which can be mapped to a list
+simple type include: indexed property, single dimensional arrays.
+
+== CHAPTER 9 -
+
+[[a3815]]Compatibility
+
+This section describes conformance
+requirements for an implementor of this specification. A JAXB
+implementation must implement these constraints, without exception, to
+provide a predictable environment for application development and
+deployment.
+
+This section explicitly lists the high level
+requirements of this specification. Additional requirements can be found
+in other sections of this specification and the associated javadoc for
+package _javax.xml.bind_ and its subpackages. If any requirements listed
+here conflict with requirements listed elsewhere in the specification,
+the requirements here take precedence and replace the conflicting
+requirements.
+
+A JAXB implementation must implement the
+processing model specified in Appendix B,
+link:jaxb.html#a3856[See Runtime Processing]”.
+
+A JAXB implementation included in a product
+that supports software development must support a schema generator. A
+schema generator must support all the Java Types to XML Schema mapping
+specified in Section 8, link:jaxb.html#a2236[See Java Types To
+XML]”.
+
+A JAXB implementation included in a product
+that supports software development must support a schema compiler. All
+operating modes of a schema compiler must support all the XML
+Schema-to-Java bindings described in this specification. Additionally,
+any operating mode must not implement a default binding for XML
+Schema-to-Java bindings as an alternative to those specified in Section
+6, link:jaxb.html#a694[See Binding XML Schema to Java
+Representations]” nor alternative interpretations for the standard
+customizations described in Section 7, link:jaxb.html#a1498[See
+Customizing XML Schema to Java Representation Binding].”
+
+The default operating mode for a schema
+compiler MUST report an error when extension binding declaration is
+encountered. All operating modes for a schema compiler MUST report an
+error if an invalid binding customization is detected as defined in
+Section 7. An extension binding declaration must be introduced in the
+following cases:
+
+. to alter a binding customization that is
+allowed to be associated with a schema element as specified in Section
+7, link:jaxb.html#a1498[See Customizing XML Schema to Java
+Representation Binding].”
+. to associate a binding customization with a
+schema element where it is disallowed as specified in Section 7,
+link:jaxb.html#a1498[See Customizing XML Schema to Java
+Representation Binding].”
+
+The default operating mode for a schema
+compiler MUST report an error when processing a schema that does not
+comply with the 2001 W3C Recommendation for XML Schema, [XSD Part 1] and
+[XSD Part 2].
+
+A schema compiler MAY support non-default
+operating modes for binding schema languages other than XML Schema.
+
+A schema compiler MUST be able to generate
+Java classes that are able to run on at least one Sun's Reference
+Implementation of the J2SE Java Runtime Environment that is Java SE 5 or
+higher.
+
+A schema generator MAY support non-default
+operating modes for mapping Java types to schema languages other than
+XML Schema.
+
+A Java platform configured with any JAXB 2.0
+implementation MUST allow any JAXB 1.0 application, packaged as
+specified by the JAXB 1.0 implementation used by the application, to run
+as specified by the JAXB 1.0 specification. A JAXB 1.0 application uses
+schema-derived classes generated by a JAXB 1.0 compliant schema compiler
+and is distributed with the compatible JAXB 1.0 runtime implementation.
+Unlike JAXB 2.0, JAXB 1.0 specified a tight coupling between a JAXB 1.0
+implementation’s schema-derived code and the JAXB 1.0 implementation of
+package _javax.xml.bind_ . The required processing model for a JAXB 1.0
+schema compiler generated package is specified in
+_javax.xml.bind.JAXBContext_ class javadoc under the heading _SPEC
+REQUIREMENT_ .
+
+== CHAPTER 10 -
+
+References
+
+[XSD Part 0] XML Schema Part 0: Primer, +
+Available at _http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/ +
+_ (schema fragments borrowed from this widely used source)
+
+[XSD Part 1] XML Schema Part 1: Structures, +
+Available at _http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/_
+
+[XSD Part 2] XML Schema Part 2: Datatypes, +
+Available at _http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/_
+
+[XMl-Infoset] XML Information Set, John Cowan
+and Richard Tobin, eds., W3C, 16 March 2001. Available at
+_http://www.w3.org/TR/2001/WD-xml-infoset-20010316/_
+
+[XML 1.0] Extensible Markup Language (XML)
+1.0 (Second Edition), +
+W3C Recommendation 6 October 2000. +
+Available at _http://www.w3.org/TR/2000/REC-xml-20001006_ .
+
+[Namespaces in XML] Namespaces in XML +
+W3C Recommendation 14 January 1999. +
+Available at _http://www.w3.org/TR/1999/REC-xml-names-19990114_
+
+[XPath], XML Path Language, James Clark and
+Steve DeRose, eds., W3C, 16 November 1999. Available at
+_http://www.w3.org/TR/1999/REC-xpath-19991116_
+
+[XSLT 1.0] XSL Transformations (XSLT),
+Version 1.0, James Clark, W3C Recommendation 16 November 1999. Available
+at http://www.w3.org/TR/1999/REC-xslt-19991116.
+
+
+
+[BEANS] JavaBeans(TM), Version 1.01, July 24,
+1997. Available at _http://java.sun.com/beans_ .
+
+[XSD Primer] XML Schema Part 0: Primer, +
+W3C Recommendation 2 May 2001 +
+Available at _http://www.w3.org/TR/xmlschema-0/_
+
+[BLOCH] Joshua Bloch, Effective Java, Chapter
+3, Typesafe Enums +
+_http://developer.java.sun.com/developer/Books/shiftintojavapage1.html#replaceenum_
+
+[BLOCH_2] Joshua Bloch, Effective Java,
+Chapter 1, Item 1: Consider factory methods over constructors
+
+[RFC2396] Uniform Resource Identifiers (URI):
+Generic Syntax, _http://www.ietf.org/rfc/rfc2396.txt._
+
+[JAX-RPC] Javaª API for XML-based RPC JAX-RPC
+1.0, _http://java.sun.com/xml/downloads/jaxrpc.html_ .
+
+[JAX-WS] Javaª API for XML Web
+Services(JAX-WS) 2.0, Marc Hadley, Roberto Chinnici.
+
+[JLS] or [JLS3] The Java Language
+Specification, 3rd Edition, Gosling, Joy, Steele, Bracha. Available at
+_http://java.sun.com/docs/books/jls_ .
+
+[NIST] NIST XML Schema Test Suite, +
+_http://xw2k.sdct.itl.nist.gov/xml/page4.html._
+
+[MTOM] SOAP Message Transmission Optimization
+Mechanism, http://www.w3.org/TR/2004/WD-soap12-mtom-20040608/
+
+[XOP] Martin Gudgin, Noah Mendelsohn, Mark
+Nottingham, and Herve Ruellan. XML-binary Optimized Packaging.
+Recommendation, W3C, January 2005. http://www.w3.org/TR/xop10/.
+
+[MIME] Anish Karmarkar, Ümit Yalçinalp,
+"Describing Media Content of Binary Data in XML", W3C note,
+http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504
+
+[WSIAP] Chris Ferris, Anish Karmarkar, and
+Canyang Kevin Liu. Attachments Profile Version 1.0. Final 1 Material,
+WS-I, August 2004.
+http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html.
+
+[WSIBP] WS-I Basic Profile 1.0,
+http://www.ws-i.org/Profile/Basic/2003-08/BasicProfile-1.0a.html
+
+[CA] Common Annotations for the Javaª
+Platform, Rajiv Mordani
+
+=== [[a3855]]Appendix
+
+[[a3856]]Runtime Processing
+
+=== Introduction
+
+Two of the important goals of JAXB 2.0 are
+portability (for inclusion in J2SE) and handling of invalid XML content
+(for e.g. schema evolution). These goals imply that a JAXB Provider must
+be capable of marshalling and unmarshalling XML instances using JAXB
+annotated classes derived using another JAXB Provider. To ensure
+portable behavior of JAXB mapped classes across JAXB Providers requires
+a specification of runtime processing model of the JAXB 2.0 binding
+framework.
+
+This appendix specifies the runtime
+processing model of XML instances and requirements on JAXB 2.0
+Provider's runtime. It differs from the documentation found elsewhere in
+the specification/javadocs. Chapter 4,”Binding Framework” and the
+javadocs for the package javax.xml.bind do describe the JAXB 2.0 binding
+framework. But these are written from a JAXB 2.0 developer perspective
+rather than from a JAXB 2.0 Provider perspective and thus do not
+describe requirements on JAXB 2.0 Provider runtime. This was sufficient
+for JAXB 1.0 since portability was not a goal for JAXB 1.0 and schema
+derived implementation classes were coupled to the JAXB 1.0 Provider
+runtime. However, this is insufficient for JAXB 2.0, where portability
+and handling invalid XML content are goals.
+
+=== Scope and Conventions
+
+=== Scope
+
+This appendix describes marshalling and
+unmarshalling.
+
+=== Format
+
+The specification uses the following for
+specifying runtime behavior:
+
+* XML Infoset, Second Edition,
+http://www.w3.org/TR/xml-infoset augmented with attributes xsi:type and
+xsi:nil that can be used by a document author.
+* XML Schema abstract schema component model.
+* JAXB defined annotations as needed
+
+=== Notations
+
+The following notations/conventions are used:
+
+* For brevity, property is used but is used
+to mean JavaBean property or a field.
+* XML Infoset properties that are associated
+with an information item are enclosed in [...], for e.g. AII.[local
+name]. And program elements the constitute the Java representation to
+which an information item are identified as for e.g. AII.valuetype.
+* AII: Attribute Information Item in XML
+Infoset
+* AII.[local name] : local name property in
+infoset for AII
+* AII.[namespace] : namespace property in
+infoset for AII
+* AII.[owner element] : owner element in
+infoset for AII
+* AII.[normalized value]: normalized value in
+inforset for AII
+* AII.property : JAXB property to which AII
+is mapped. The property in in the java type to which AII.[owner element]
+is mapped.
+* AII.valuetype: Java type representing the
+XML serialized for AII.
+* AII.boundtype: Java type that is bound;
+this differs from AII.valuetype only if JAXB property is associated with
+a @XmlJavaTypeAdapter.
+* AII.schematype : schema type to which AII
+is bound statically using Java -> XML schema mapping rules.
+* EII: Element Information Item in infoset
+* EII.[local name] : local name property in
+XML infoset for EII
+* EII.[namespace] : namespace property in XML
+infoset for EII
+* EII.[children]: children property in XML
+infoset for EII
+* EII.[parent]: parent property in XML
+infoset for EII
+* EII.property : JAXB property to which EII
+is mapped. The property is in the javatype to which EII.[parent] is
+mapped.
+* EII.valuetype : java type representing the
+XML serialized for EII
+* EII.boundtype : java type that is bound;
+this differs from EII.valuetype only if JAXB property is associated with
+a @XmlJavaTypeAdapter.
+* EII.schematype : schema type to which EII
+is bound statically using java -> XML schema mapping rules.
+* EII.xsitype : the xsi:type specified in the
+XML instance by a document author. null if no xsi:type was specified.
+* EII.xsinil : the xsi:nil specified in the
+XML instance by a document author. null if no xsi:nil was specified.
+
+=== Unmarshalling
+
+This section specifies the runtime behavior
+and JAXB provider requirements related to unmarshalling. The
+specification includes unmarshalling of invalid XML content in an XML
+instance. +
+ +
+This section specifies only flexible, standard unmarshalling (flexible
+because unmarshalling deals with invalid XML content). Other
+unmarshalling modes will not be specified. Flexible unmarshalling
+specified here must be supported by all JAXB Providers.
+
+The unmarshalling methods in the binding
+framework fall into the following categories:
+
+. Unmarshal methods that do not take a
+declaredType as parameter:
+
+ _javax.xml.bind.Unmarshaller.unmarshal_
+(...) +
+_javax.xml.bind.Binder.unmarshal_ (...) +
+
+
+
+. Unmarshal methods that take a declaredType
+as a parameter:
+
+ _javax.xml.bind.Unmarshaller.unmarshal_
+(..., _java.lang.Class<T> declaredType_ ) +
+_javax.xml.bind.Binder.unmashal_ (..., _java.lang.Class<T> declaredType_
+)
+
+The unmarshal methods that do not take
+declaredType as parameter must be unmarshalled as specified in
+link:jaxb.html#a3902[See Globally Declared Root Element]”.
+
+The unmarshal methods that take a
+_declaredType_ as a parameter must be unmarshalled as specified in
+link:jaxb.html#a3953[See Declared Type]”.
+
+=== [[a3902]]Globally Declared Root Element
+
+There are two ways that a root element can be
+represented in Java representation:
+
+* as an element instance factory method that
+is generated in the public ObjectFactory class of a package when a
+schema is compiled. An element instance factory method is annotated with
+a
+
+@XmlElementDecl annotation. For e.g.
+
+ public class ObjectFactory \{
+
+ @XmlElementDecl(...)
+
+ public JAXBElement<T> createFoo(T
+elementValue);
+
+ ...
+
+ }
+
+* as a type (either an enum type or a class)
+that has been annotated with @XmlRootElement. For e.g.
+
+
+
+ @XmlRootElement(...)
+
+ public class Foo \{...}
+
+The unmarshalling of XML content results in a
+content tree with a root that is an instance of either a _JAXBElement_
+instance or a type that is annotated with _@XmlRootElement_ . The
+content tree must be created as follows:
+
+. lookup an element factory method in the
+ObjectFactory class matching on:
+
+EII.[namespace] ==
+@XmlElementDecl.namespace() && EII.[local name] ==
+@XmlElementDecl.name()
+
+or for a type annotated with @XmlRootElement
+matching on:
+
+EII.[namespace] ==
+@XmlRootElement.namespace() && EII.[local name] ==
+@XmlRootElement.name()
+
+NOTE: The lookup will only find one of the
+above not both. If both a type as well as an element factory method were
+found, it would be flagged as an error when JAXBContext is created.
+
+. if an element factory method in the
+ObjectFactory class or a type annotated with @XmlRootElement is found,
+then determine the valueType.
+. if an element factory method is found,
+there is no @XmlJavaTypeAdapter associated with the value parameter to
+the element factory method, then the valueType is the java type of the
+value parameter to the element factory method. For e.g.
+
+ @XmlElementDecl(name = "bar", namespace =
+"")
+
+ public JAXBElement<Foo> createBar(Foo value)
+\{
+
+ return new JAXBElement<Foo>(
+
+ _Bar_QNAME, ((Class) Foo.class), null,
+value);
+
+ }
+
+the valueType type is Foo.
+
+*
+
+if the parameter is associated with
+@XmlJavaTypeAdapter, then the valueType is the java type specified in
+@XmlJavaTypeAdapter.value() .
+
+. if a type annotated with @XmlRootElement is
+found then valueType is the type. For e.g.
+
+ @XmlRootElement(...)
+
+ public class Foo \{ ... }
+
+*
+
+Go to step 4, “Check for type substitution”
+
+. If neither the element factory method nor a
+type annotated with @XmlRootElement is found, then the element is
+unknown. Set valueType of the element to null.
+
+Even though the element is unknown, a
+document author can still perform type substitution. This case can arise
+if the XML schema contains only schema types and no global elements. For
+e.g a document author could have specified a xsi:type that has been
+mapped by JAXB. For e.g.
+
+ <unknownElement xsi:type="PurchaseOrder"/>
+
+So goto step 4, "Check for type substitution"
+
+. “Check for type substitution”
+. if xsi:type is not specified, and the
+valueType is null (i.e. the root element is unknown and we got to this
+step from step 3), throw a _javax.xml.bind.UnmarshalException_ and
+terminate processing.
+. otherwise, if _xsi:type_ is specified, but
+is not mapped to a JAXB mapped type (e.g. class is not marked with
+@XmlType declaration), then throw a _javax.xml.bind.UnmarshalException_
+and terminate processing.
+. otherwise, if xsi:type is specified, and is
+mapped to a JAXB mapped type set the valueType to the javatype to which
+xsi:type is mapped.
+. otherwise, xsi:type is not specified;
+valueType is unchanged.
+. Unmarshal valueType as specified in
+link:jaxb.html#a3960[See Value Type]”.
+. If the element factory method is annotated
+with @XmlJavaTypeAdapter, then convert the valueType into a boundType
+
+ boundType =
+@XmlJavaTypeAdapter.value().unmarshal(valueType)
+
+. Determine the content root type to be
+returned by unmarshal() method.
+. if the element lookup returned an element
+instance factory method, then create a JAXBElement instance using the
+boundType. The content root type is the JAXBElement instance.
+. otherwise, if the element lookup returned a
+type annotated with @XmlRootElement, then the content root type is the
+boundType.
+. otherwise, the element is an unknown
+element. Wrap the boundType using JAXBElement with an element name in
+the XML instance document (e.g. “unknown Element”). The content root
+type is the JAXBElement instance.
+. return the content root type.
+
+=== [[a3953]]Declared Type
+
+The unmarshalling process described in this
+section must be followed for the unmarshal methods that take a
+_declaredType_ as a parameter.
+
+. Determine the valueType to be unmarshalled
+as follows:
+. if _xsi:type_ is specified, but is not
+mapped to a JAXB mapped type , then throw a
+_javax.xml.bind.UnmarshalException_ and terminate processing.
+. otherwise if _xsi:type_ is specified and is
+mapped to JAXB mapped type, then valueType is the JAXB mapped type.
+. otherwise valueType is the argument passed
+to _declaredType_ parameter in the +
+_unmarshal_ (..., _java.lang.Class<T>declaredType_ ) call.
+. Unmarshal valueType as specified in
+link:jaxb.html#a3960[See Value Type]”.
+
+=== [[a3960]]Value Type
+
+The following steps unmarshal either
+EII.valuetype or AII.valuetype, depending upon whether an EII or AII is
+being unmarshalled.
+
+Note: Whether an EII or AII is being
+unmarshalled is determined by the “caller” of this section.
+AII.valuetype and EII.valuetype are assumed to be set by the time this
+section entered.
+
+. If an instance of valueType does not exist,
+create an instance of valueType as follows (for e.g. if a value of a
+property with type _java.util.List_ is non null, then unmarshal the
+value into that _java.util.List_ instance __ rather than creating a new
+instance of _java.util.List_ and assigning that to the property):
+. if valueType is a class and is the type
+parameter specified in the element factory method, then instantiate the
+class using element factory method; otherwise instantiate the class
+using factory method if specified by _@XmlType.factoryClass()_ and
+_@XmlType.factoryMethod();_ or if there is no factory method, using the
+no-arg constructor.
+. if valueType is an enum type, then obtain
+an instance of the enum type for the enum constant annotated with
+_@XmlEnumValue_ and _@XmlEnumValue.value()_ matches the lexical
+representation of the EII.
+. Invoke any event callbacks in the following
+order as follows:
+. If valueType implements an unmarshal event
+callback _beforeUnmarshal(..)_ as specified in Section 4.4.1,”Unmarshal
+Event Callback”, then invoke _beforeUnmarshal(..)_ .
+. If _Unmarshaller.getListener()_ returns
+_Unmarshaller.Listener_ that is not null, then invoke
+_Unmarshaller.Listener.beforeUnmarshal(..)_ .
+. If an EII.valuetype is being unmarshalled,
+unmarshal into this instance the following. Note: The following steps
+can be done in any order; the steps are just broken down and listed
+separately for clarity:
+
+If EII.valueType being unmarshalled
+
+. unmarshal each child element information
+item in EII.[children] as specified in link:jaxb.html#a3978[See
+Element Information Item]”.
+. unmarshal each attribute information item
+in EII.[attributes] as specified in link:jaxb.html#a4002[See
+Attribute Information Item]”.
+. Unmarshal the value of EII.schematype or
+AII.schematype following the Java to XML Schema rules defined in Chapter
+8, “Java Types to XML”. If the value in XML instance is unparseable,
+then it must be handled as specified in link:jaxb.html#a4086[See
+Unparseable Data for Simple types]”.
+. Invoke any event callbacks in the following
+order as follows:
+. If valueType implements an unmarshal event
+callback _afterUnmarshal(..)_ as specified in Section 4.4.1,”Unmarshal
+Event Callback”, then invoke _afterUnmarshal(..)_ .
+. If _Unmarshaller.getListener()_ returns
+_Unmarshaller.Listener_ that is not null, then invoke
+_Unmarshaller.Listener.afterUnmarshal(..)_ .
+. return // either AII.valuetype or
+EII.valuetype.
+
+=== [[a3978]]Element Information Item
+
+An EII must be unmarshalled as follows:
+
+. infer EII.property as specified in
+link:jaxb.html#a4023[See Property Inference - Element
+Information Item]”.
+. if EII.property is null, then there is no
+property to hold the value of the element. If validation is on (i.e.
+Unmarshaller.getSchema() is not null), then report a
+javax.xml.bind.ValidationEvent. Otherwise, this will cause any unknown
+elements to be ignored.
+
+If EII.property is not null and there is no
+setter method as specified in section link:jaxb.html#a4259[See
+Getters/Setters]” then report a javax.xml.bind.ValidationEvent.
+
+Goto step 8.
+
+. infer the EII.valuetype as described in
+link:jaxb.html#a4043[See Type Inference - Element Information
+Item]”.
+. if EII.valuetype is null, then go to step
+8.
+
+NOTE: EII.valuetype = null implies that there
+was problem. so don't attempt to unmarshal the element.
+
+. Unmarshal EII.valuetype as specified in
+link:jaxb.html#a3960[See Value Type]”.
+. if there is a @XmlJavaTypeAdapter
+associated with EII.property, then adapt the EII.valuetype as follows:
+
+ EII.boundtype = +
+@XmlJavaTypeAdapter.value().unmarshal(EII.valuetype)
+
+otherwise
+
+EII.boundtype = EII.valuetype
+
+. set the value of EII.property to
+EII.boundtype as follows:
+
+Wrap EII.boundtype into a
+javax.xml.bind.JAXBElement instance if:
+
+. the property is not a collection type and
+its type is javax.xml.bind.JAXBElement
+. the property is a collection type and is a
+collection of JAXBElement instances (annotated with @XmlElementRef or
+@XmlElementRefs)
+
+If EII.property is not a collection type:
+
+. set the value of EII.property to
+EII.boundtype.
+
+If EII.property is collection type:
+
+. add EII.boundtype to the end of the
+collection.
+
+NOTE: Adding JAXBElement instance or a type
+to the end of the collection preserves document order. And document
+order could be different from the order in XML Scheme if the instance
+contains invalid XML content.
+
+. return
+
+=== [[a4002]]Attribute Information Item
+
+An attribute information item must be
+unmarshalled as follows:
+
+. infer AII.property as described in section
+link:jaxb.html#a4033[See Property Inference - Attribute
+Information Item]”.
+. if AII.property is null, then the attribute
+is invalid with respect to the XML schema. This is possible if for e.g.
+schema has evolved. If validation is on (i.e. Unmarshaller.getSchema()
+is not null), then report a javax.xml.bind.ValidationEvent. Otherwise,
+this will cause any unknown elements to be ignored.
+
+If AII.property is not null and there is no
+setter method as specified in section link:jaxb.html#a4259[See
+Getters/Setters]” then report a javax.xml.bind.ValidationEvent. +
+ +
+Goto step 8.
+
+. infer the AII.valuetype as described in
+link:jaxb.html#a4079[See Type Inference - Attribute Information
+Item]”.
+. if AII.valuetype is null, then go to step
+8.
+
+NOTE: AII.valuetype = null implies that there
+was problem. so don't attempt to unmarshal the attribute.
+
+. Unmarshal AII.valuetype as specified in
+link:jaxb.html#a3960[See Value Type]”.
+. If AII.property is associated with a
+_@XmlJavaTypeAdapter_ , adapt AII.valuetype as follows:
+
+ AII.boundtype =
+
+
+@XmlJavaTypeAdapter.value().unmarshal(AII.valuetype)
+
+otherwise
+
+ AII.boundtype = AII.valuetype
+
+. If AII.property is single valued:
+. set the value of AII.property to
+AII.boundtype.
+
+If AII.property is a collection type (e.g.
+List<Integer> was mapped to a Xml Schema list simple type using @XmlList
+annotation):
+
+add EII.boundtype to the end of the
+collection.
+
+. return
+
+=== Property Inference
+
+Unmarshalling requires the inference of a
+property or a field that contains the value of EII and AII being
+unmarshalled.
+
+=== [[a4023]]Property Inference - Element Information Item
+
+The property to which an EII is mapped is
+inferred based on name.
+
+*
+
+Infer EII.property by matching constraints
+described below:
+
+. initialize EII.property to null
+. if property is mapped to XML Schema element
+declaration, elem, in the content model of EII.[parent].schematype &&
+EII.[local name] == elem.\{name} && EII.[namespace] == elem.\{namespace}
+
+set EII.property to property
+
+ Goto step 4.
+
+. If there is a JAXB property mapped to XML
+Schema wildcard ( _xs:any_ ) (as determined by _@XmlAnyElement_ ), set
+this JAXB property to EII.property. This property will hold wildcard
+content (e.g. invalid XML content caused by schema evolution).
+. return EII.property
+
+=== [[a4033]]Property Inference - Attribute Information Item
+
+Infer the property for the AII by matching
+constraints described below:
+
+. initialize AII.property to null
+. if property mapped to XML Schema attribute
+declaration, attr, in the content model of AII.[owner].schematype &&
+AII.[local name] == attr.\{name} && AII.[namespace] == attr.\{namespace}
+
+set AII.property to property
+
+Goto step 4.
+
+. if there is a property mapped to a XML
+Schema xs:anyAttribute (i.e. annotated with _@XmlAnyAttribute_ ), then
+set this property to AII.property. This property holds XML content
+matching wildcard attribute ( _xs:anyAttribute)_ or unknown attributes
+(which can occur for e.g. if schema has evolved).
+. return AII.property
+
+=== Type Inference
+
+Unmarshalling requires the inference of the
+type of a property or a field that to contain the value of EII and AII
+being unmarshalled.
+
+=== [[a4043]]Type Inference - Element Information Item
+
+This section describes how to infer
+EII.valuetype; this holds the value of the element (content model +
+attributes).
+
+EII.valuetype must be inferred as described
+below:
+
+. initialize EII.valuetype to null.
+. if EII.xsitype is set, document author has
+performed type substitution.
+
+Goto step 4 to handle type substitution.
+
+. if EII.schematype is not mapped to a java
+type, then
+. report a validation event.
+. Go to step 7.
+
+otherwise
+
+. set EII.valuetype to the javatype to which
+EII.schematype is mapped.
+. Go to step 7.
+
+NOTE: This case can arise for example, when
+EII.schematype is compiled into a java type at schema compilation time,
+but the javatype was not registered with _JAXBContext.newInstance(..)_ .
+
+. check if EII.xsitype is mapped to a JAXB
+mapped type. It is possible that EII.xsitype is compiled to a javatype
+at schema compilation time, but the javatype was not registered with
+_JAXBContext.newInstance(..)_
+
+If EII.xsitype is not mapped, then report a
+validation event.
+
+Goto step 7.
+
+. check if the java type to which EII.xsitype
+is mapped is assignment comparable with the static type of the
+property/field if no _@XmlJavaTypeAdapter_ is associated with the
+property/field or with the _valueType_ specified in
+_XmlAdapter<valueType, boundType>_ if a _@XmlJavaTypeAdapter_ is
+associated with the property/field.
+
+The above check can fail for e.g when a
+document author attempts to substitute a complex type that derives from
+simple type but customization to enable simple type substitution was not
+used. For e.g.
+
+. <!-- local element with simple type -->
+
+ <xs:element name="foo" type="xs:int"/>
+
+ <!-- complex type for substituting the
+simple type -->
+
+ <xs:complexType name="MyInt">
+
+ <xs:extension xs:int>
+
+ ...add attributes
+
+ </xs:extends>
+
+ </xs:complexType>
+
+. customization to handle type substitution
+of simple types is not used. So the property is
+
+ public int getFoo();
+
+ public void setFoo(int );
+
+ public class MyInt \{...}
+
+. the document author attempts to substitute
+complexType MyInt.
+
+ <foo xsi:type="MyInt"/>
+
+. The type MyInt is not assignment comparable
+with int.
+. set EII.valuetype to javatype to which
+EII.xsitype is mapped.
+
+NOTE: if we got to this step, this implies
+that type substitution is valid.
+
+. return EII.valuetype
+
+=== [[a4079]]Type Inference - Attribute Information Item
+
+Infer the AII.valuetype as follows:
+
+. initialize AII.valuetype to null.
+. if AII.schematype is not mapped to a java
+type, then report a validation event. Otherwise, set AII.valuetype to
+the java type to which AII.schematype is mapped.
+
+NOTE: This case can arise for example, when
+AII.schematype is compiled into a java type at schema compilation time,
+but the javatype is not registered with the
+_JAXBContext.newInstance(..)_
+
+. return AII.valuetype
+
+=== Invalid XML Content
+
+=== [[a4086]]Unparseable Data for Simple types
+
+If simple type data cannot be parsed into a
+java datatype, then the value of the java datatype must not change the
+current set value. An access to the datatype must return the value as
+specified in link:jaxb.html#a4095[See Missing element
+information item]”. If the conversion of lexical representation into a
+value results in an exception, then the exception must be caught and a
+validation event reported. This is to ensure that such conversion errors
+do not terminate unmarshalling.
+
+// Example : XML Schema fragment
+
+<xs:element name="foo" type="xs:int"/>
+
+
+
+// Example: XML instance.
+
+// Data is not parseable into type xs:int ;
+however unmarshal will
+
+// still succeed.
+
+<foo> SUN </foo>
+
+=== [[a4095]]Missing element information item
+
+This case arises when an element declaration
+required by a XML schema is missing from the XML instance.
+
+Property or field access must return the
+value specified in link:jaxb.html#a4101[See Value for missing
+elements/attributes]”
+
+=== Missing Attribute
+
+This case arises when a property or a field
+is mapped to an XML attribute but the attribute is missing from the XML
+instance.
+
+Property or field access must return the
+value specified in link:jaxb.html#a4101[See Value for missing
+elements/attributes]”.
+
+=== [[a4101]]Value for missing elements/attributes
+
+If an attribute or an element is missing from
+an XML instance, then unmarshal will not change the current set value.
+An access to the property will return the set value or if unset, the
+uninitialized value. The uninitialized value of the property or field
+depends upon it's type. If the type is
+
+. int - value is 0
+. boolean - value is false
+. a reference (must be mapped to a simple
+type) - value is null.
+. float - the value is +0.0f
+. double - the value is 0.0d
+. short - the value is (short) 0
+. long - the value is 0L
+
+Note The uninitialized values are returned
+only if the value is not set. A value could be set for example in a
+validation handler that catches the validation event.
+
+=== Unknown Element
+
+In this case, XML instance contains EII for
+which there is no corresponding element declaration in the XML schema.
+If the valuetype to which the EII.parent maps contains a property/field
+annotated with _@XmlAnyElement_ , this EII can be unmarshalled into the
+property/field.
+
+Unknown attribute handling during
+unmarshalling is specified in link:jaxb.html#a4023[See Property
+Inference - Element Information Item]”.
+
+=== Unknown attribute
+
+In this case, XML instance contains AII for
+which there is no corresponding attribute declaration in the XML schema.
+If the valuetype to which the AII.parent maps contains a property/field
+annotated with _@XmlAnyAttribute_ , the AII can be unmarshalled into the
+property/field.
+
+Unknown attribute handling during
+unmarshalling is specified in link:jaxb.html#a4033[See Property
+Inference - Attribute Information Item]”.
+
+=== Marshalling
+
+To marshal a content tree, a JAXB application
+invokes one of the following marshal methods:
+
+Marshaller.marshal(Object jaxbElement, ...)
+throws JAXBException;
+
+
+
+Binder.marshal(Object jaxbObject, ...) throws
+JAXBException;
+
+A JAXB Provider must marshal the content tree
+as follows:
+
+* marshal the XML root element tag as
+specified in link:jaxb.html#a4125[See XML Root Element Tag]”
+* marshal _obj_ as specified in section
+link:jaxb.html#a4132[See Type]”.
+
+=== [[a4125]]XML Root Element Tag
+
+. If _obj_ is an instance of
+_javax.xml.bind.JAXBElement_ then marshal _obj_ as specified in
+link:jaxb.html#a4139[See JAXBElement]”
+
+Goto step 4
+
+. If _obj.getClass()_ is annotated with
+_@XmlRootElement_ , then set \{EII.[local name], EII.[namespace]} by
+deriving them from the @XmlRootElement annotation following the Java to
+Schema mapping rules in chapter 8. Marshal obj instance as specified in
+link:jaxb.html#a4132[See Type]”.
+
+Goto step 4
+
+. If obj has neither an @XmlRootElement nor
+is a JAXBElement instance, then throw a _JAXBException_ and terminate
+processing.
+. done
+
+=== [[a4132]]Type
+
+The type must be marshalled as follows. If
+the type is an instance of
+
+* JAXBElement , then marshal as specified in
+link:jaxb.html#a4139[See JAXBElement]”.
+* Otherwise, marshal the type as follows. If
+the type is a :
+* class, then marshal as specified in
+link:jaxb.html#a4156[See class]”.
+* primitive type or standard class, then
+marshal as specified in link:jaxb.html#a4180[See Primitives and
+Standard classes]”
+* enum type then marshal following the schema
+to which it is mapped.
+
+=== [[a4139]]JAXBElement
+
+An _obj,_ that is an instance of
+_javax.xml.bind.JAXBElement_ must be marshalled as specified here:
+
+. _JAXBElement jaxbelem = (JAXBElement)
+obj;_
+. set \{EII.[local name] , EII.[namespace]}
+to _jaxbelem.getName()_
+. if _jaxbelem.isNil()_ , add _xsi:nil_ to
+EII.[attributes]
+.
+
+. if _jaxbelem.isTypeSubstituted()_ is true,
+then type substitution has occurred i.e. _jaxbelem.getDeclaredType()_
+(static type) is different from _jaxbelem.getValue()_ (the type of the
+value for this instance). So,
+. EII.[local name] = “type”
+. EII.[prefix]=”xsi”
+. EII.[normalized value] = QName of the
+schema type to which _jaxbelem.getValue()_ is mapped following Java ->
+Schema mapping rules in Chapter 8. For e.g.
+
+ <foo xsi:type=”MyAddrType”/>
+
+. set boundType to _jaxbelem.getValue()_ if
+_jaxbelem.isTypeSubstituted()_ is _true_ otherwise
+_jaxbelem.getDeclaredType()_
+. determine the valueType to be marshalled.
+If the program element being processed is associated with
+@XmlJavaTypeAdapter then boundType is
+
+ valueType =
+@XmlJavaTypeAdapter.value().marshal(boundType)
+
+otherwise valueType is boundType
+
+. map valueType to XML infoset information
+items as specified in link:jaxb.html#a4132[See Type]” and add
+them to EII.
+. marshal EII.
+
+=== [[a4156]]class
+
+A class must be mapped to XML infoset items
+as follows:
+
+. If a class mapped to a value as specified
+link:jaxb.html#a3331[See @XmlValue]”, then map the value to an
+XML infoset and add it to EII.[children]
+
+return
+
+. For each property that is mapped to XML
+attribute as specified in link:jaxb.html#a3230[See
+@XmlAttribute]”:
+. derive \{AII.[local name], AII.[prefix],
+AII.[namespace] } from \{name} \{target namespace}.
+. AII.[normalized value] = value of property
+as specified in link:jaxb.html#a4169[See property type]”
+. add AII to EII.[attributes]
+
+NOTE: There order in which the properties are
+marshalled is not specified (XML attributes are unordered by XML
+Schema).
+
+. For each property that is mapped to an XML
+element declaration, elem:
+. derive \{childEII.[local name],
+childEII.[prefix], childEII.[namespace] } from elem.\{name}
+elem.\{target namespace}
+. map property type to XML infoset items into
+childEII as specified in link:jaxb.html#a4169[See property
+type]”.
+. add childEII to EII.[children]
+
+=== [[a4169]]property type
+
+The value of a property with type ,
+boundType, must be marshalled into childEII (set by “caller of this
+section”) as follows:
+
+. If property does not have a getter method
+as specified in section link:jaxb.html#a4259[See
+Getters/Setters]” then report a javax.xml.bind.ValidationEvent. Goto
+step 4.
+. If the value of the property being
+marshalled is a subtype boundType, then
+. EII.[local name] = “type”
+. EII.[prefix]=”xsi”
+. EII.[normalized value] = QName of the
+schema type to which _jaxbelem.getValue()_ is mapped following Java ->
+Schema mapping rules in Chapter 8. For e.g.
+
+ <foo xsi:type=”MyAddrType”/>
+
+. add EII to childEII
+. Marshal the value as specified in
+link:jaxb.html#a4132[See Type]”.
+. Return
+
+=== [[a4180]]Primitives and Standard classes
+
+Primitive values and standard classes
+described in this section map to XML schema simple types.
+
+The value of a primitive type or a standard
+class must be marshalled to a lexical representation or unmarshalled
+from a lexical representation as specified in the below:
+
+* using a print or parse method in
+javax.xml.bind.DatatypeConverter interface:
+
+Many of the types have a corresponding print
+and parse method in javax.xml.bind.DatatypeConverter interface for
+converting a value to a lexical representation in XML and vice versa.
+The implementation of DatatypeConverter is JAXB Provider specific.
+
+A XML Schema simple type can have more than
+lexical representation (e.g. “true” “false” “0” “1”). Since the
+DatatypeConverter implementation is JAXB Provider specific, the exact
+lexical representation that a value is marshalled to can vary from one
+JAXB Provider to another. However, the lexical representation must be
+valid with respect to the XML Schema.
+
+* some data types such as
+XMLGregorianCalendar contain methods on the class that return or consume
+their XML lexical representation. For such datatypes, the method
+indicated in the table is used.
+* A wrapper class (e.g. java.lang.Integer)
+must be converted to its non wrapper counterpart (e.g. int) and then
+marshalled.
+
+
+
+=== Lexical Representation of Standard Classes
+
+Java Standard Classes
+
+printMethod
+
+parse Method
+
+ _java.lang.String_
+
+ _printString_
+
+ _parseString_
+
+ _java.util.Calendar_
+
+ _printDateTime_
+
+ _parseDateTime_
+
+ _java.util.Date_
+
+ _printDateTime_
+
+ _parseDateTime_
+
+ _java.net.URI_
+
+ _URI.toString()_
+
+ _URI(String str)_
+
+ _javax.xml.datatype._
+
+ _XMLGregorianCalendar_
+
+ _XMLGregorianCalendar._
+
+ _toXMLFormat()_
+
+ _DatatypeFactory._
+
+ _newXMLGregorianCalendar(_
+
+ _String lexicalRepresentation)_
+
+ _javax.xml.datatype._
+
+ _Duration_
+
+ _Duration._
+
+ _toString()_
+
+ _DatatypeFactory._
+
+ _newDuration(_
+
+ _String lexicalRepresentation)_
+
+ _java.util.UUID_
+
+ _UUID.toString()_
+
+ _UUID.fromString()_
+
+=== Null Value
+
+A null value in Java representation can be
+marshalled either as an absence of an element from an XML instance or as
+_xsi:nil_ . The marshalled value depends upon the values of
+_@XmlElement.required()_ and _@XmlElement.nillable()_ annotation
+elements on the property/field and must be marshalled as shown below.
+For clarity, example schema fragments (as determined by the mapping
+rules specified in Chapter 8) for the following field
+
+@XmlElement(required=”..”, nillable=”...”)
+
+foo;
+
+are reproduced here along with the XML
+representation for null value produced by marshalling.
+
+* _@XmlElement(required=true, nillable_ =
+_false)_
+
+The value of the property/field cannot be
+null.
+
+ // Example: generated schema
+
+ <xs:element name=”foo” minOccurs=”1”/ ...>
+
+ ...
+
+ </xs:element>
+
+* _@XmlElement(required=true,
+nillable=true)_
+
+null is marshalled as _xsi:nil=”true”_
+
+ // Example:generated schema
+
+ <xs:element name=”foo” minOccurs=”1”
+nillable=”true” ...>
+
+ ...
+
+ /xs:element>
+
+
+
+ <!-- marshalled XML representation for null
+value -->
+
+ <foo xsi:nil=”true” .../>
+
+* _@XmlElement(required=false,
+nillable=true)_
+
+null is marshalled as _xsi:nil=”true”_
+
+ // Examle: generated schema
+
+ <xs:element name=”foo” minOccurs=”0” ...>
+
+ ...
+
+ </xs:element>
+
+
+
+ <!-- Example: marshalled XML representation
+for null value -->
+
+ <foo xsi:nil=”true” .../>
+
+* _@XmlElement(required=false,
+nillable=false)_
+
+null is not marshalled i.e it maps to absence
+of an element from XML instance.
+
+ // Example: Generated schema
+
+ <xs:element name=”foo” minOccurs=”0” ...>
+
+ ...
+
+ </xs:element>
+
+
+
+ <!-- Example: null value for foo not
+marshalled -->
+
+=== [[a4259]]Getters/Setters
+
+When _@XmlAccessType.PUBLIC_MEMBER_ or
+_@XmlAccessType.PROPERTY_ is in effect for a class, then the instance of
+the class is marshalled using getter/setter methods as opposed to
+fields. This section outlines the constraints the must be checked at
+runtime. A constraint failure is handled as specified elsewhere in the
+chapter from where this section is referenced.
+
+Unmarshalling : A property must have a setter
+method if
+
+* _@XmlAccessorType.PUBLIC_MEMBER_ or
+_@XmlAccessorType.PROPERTY_ applies to the property.
+* or if the property’s getter/setter method
+is annotated with a mapping annotation.
+
+The one exception to the above constraint is:
+if property type is _java.util.List_ then only a getter method is
+required.
+
+*
+
+Marshalling: A property must have a getter
+method if
+
+* _@XmlAccessType.PUBLIC_MEMBER_ or
+_@XmlAccessType.PROPERTY_ applies to the class
+* or if the property’s getter/setter method
+is annotated with a mapping annotation.
+
+=== Appendix
+
+[[a4270]]Normative Binding Schema
+Syntax
+
+=== JAXB Binding Schema
+
+Online versions of JAXB Binding Schema are
+available at:
+
+
+_http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd[]http://java.sun.com/xml/ns/jaxb/bindingschema_1_0.xsd[http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd +
+http://java.sun.com/xml/ns/jaxb/bindingschema_1_0.xsd +
+]_
+
+Additions to JAXB 1.0 binding schema are in
+_bold_ .
+
+<?xml version = "1.0" encoding = "UTF-8"?>
+
+<xs:schema
+
+ targetNamespace =
+"http://java.sun.com/xml/ns/jaxb"
+
+ xmlns:jaxb =
+"http://java.sun.com/xml/ns/jaxb"
+
+ xmlns:xs =
+"http://www.w3.org/2001/XMLSchema"
+
+ elementFormDefault = "qualified" +
+attributeFormDefault = "unqualified">
+
+<xs:group name = "declaration">
+
+ <xs:choice>
+
+ <xs:element ref = "jaxb:globalBindings"/>
+
+ <xs:element ref = "jaxb:schemaBindings"/>
+
+ <xs:element ref = "jaxb:class"/>
+
+ <xs:element ref = "jaxb:property"/>
+
+ <xs:element ref = "jaxb:typesafeEnumClass"/>
+
+ <xs:element ref =
+"jaxb:typesafeEnumMember"/>
+
+ <xs:element ref = "jaxb:javaType"/>
+
+ <xs:element ref = "jaxb:dom"/>
+
+ <xs:element ref = "jaxb:inlineBinaryData"/>
+
+ <xs:any namespace = "##other"
+processContents = "lax"/>
+
+ </xs:choice>
+
+ </xs:group>
+
+ <xs:attribute name = "version"
+type="xs:token" >
+
+ _<xs:annotation><xs:documentation>_
+
+ _Used to specify the version of the binding
+schema on the schema element for inline annotations or jaxb:bindings for
+external binding._
+
+ _</xs:documentation></xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attributeGroup name =
+"propertyAttributes">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _Attributes used for property customization.
+The attribute group can be referenced either from the globalBindings
+declaration or from the_
+
+ _property declaration. The following
+defaults are defined by the JAXB specification in global scope only.
+Thus they apply when the propertyAttributes group is referenced from the
+globalBindings declaration but not when referenced from the property
+declaration._
+
+ _collectionType a class that implements
+java.util.List._
+
+ _fixedAttributeAsConstantProperty false_
+
+ _enableFailFastCheck false_
+
+ _generateIsSetMethod false_
+
+ __ _optionalProperty wrapper_
+
+ _generateElementProperty false_
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:attribute name = "collectionType"
+type="jaxb:referenceCollectionType"/>
+
+ <xs:attribute name =
+"fixedAttributeAsConstantProperty" type = "xs:boolean"/>
+
+ <xs:attribute name = "enableFailFastCheck"
+type = "xs:boolean"/>
+
+ <xs:attribute name = "generateIsSetMethod"
+type = "xs:boolean"/>
+
+ _<xs:attribute name = "optionalProperty">_
+
+ _<xs:simpleType>_
+
+ _<xs:restriction base="xs:NCName">_
+
+ _<xs:enumeration value="wrapper"/>_
+
+ _<xs:enumeration value="primitive"/>_
+
+ _<xs:enumeration value="isSet"/>_
+
+ _</xs:restriction>_
+
+ _</xs:simpleType>_
+
+ _</xs:attribute>_
+
+ _<xs:attribute name =
+"generateElementProperty" type="xs:boolean"/>_
+
+</xs:attributeGroup>
+
+ <xs:attributeGroup name =
+"XMLNameToJavaIdMappingDefaults">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Customize XMLNames to
+Java id mapping</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:attribute name = "underscoreBinding"
+default = "asWordSeparator" type = "jaxb:underscoreBindingType"/>
+
+ </xs:attributeGroup>
+
+ <xs:attributeGroup name =
+"typesafeEnumClassDefaults">
+
+ <xs:attribute name =
+"typesafeEnumMemberName" _default = "skipGeneration"_ type =
+"jaxb:typesafeEnumMemberNameType"/>
+
+ <xs:attribute name = "typesafeEnumBase"
+_default = "xs:string"_ type = "jaxb:typesafeEnumBaseType"/>
+
+ _<xs:attribute name =
+"typesafeEnumMaxMembers" type="xs:int" default="256"/>_
+
+ </xs:attributeGroup>
+
+ <xs:element name = "globalBindings">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Customization values
+defined in global scope.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:sequence minOccurs = "0"> +
+<xs:element ref = "jaxb:javaType" minOccurs = "0" maxOccurs =
+"unbounded"/> +
+_<xs:element ref = "jaxb:serializable" minOccurs = "0"/>_
+
+ <xs:any namespace = "##other"
+processContents = "lax">
+
+ _<xs:annotation> <xs:documentation>_
+
+ _allows extension binding declarations to be
+specified._
+
+ _</xs:documentation></xs:annotation>_
+
+ </xs:any>
+
+ </xs:sequence>
+
+ <xs:attributeGroup ref =
+"jaxb:XMLNameToJavaIdMappingDefaults"/>
+
+ <xs:attributeGroup ref =
+"jaxb:typesafeEnumClassDefaults"/>
+
+ <xs:attributeGroup ref =
+"jaxb:propertyAttributes"/>
+
+ _<xs:attribute name="generateValueClass"
+type="xs:boolean"_
+
+ _default= "true"/>_
+
+ _<xs:attribute name="generateElementClass"
+type="xs:boolean"_
+
+ _default= "false"/>_
+
+ _<xs:attribute name="mapSimpleTypeDef"
+type="xs:boolean"_
+
+ _default= "false"/>_
+
+ _<xs:attribute name="localScoping" default=
+"nested">_
+
+ _<xs:simpleType>_
+
+ _<xs:restriction base="xs:NCName">_
+
+ _<xs:enumeration value="nested"/>_
+
+ _<xs:enumeration value="toplevel"/>_
+
+ _</xs:restriction>_
+
+ _</xs:simpleType>_
+
+ _</xs:attribute>_
+
+ <xs:attribute name =
+"enableJavaNamingConventions" default = "true" type = "xs:boolean"/>
+
+ <xs:attribute name = "choiceContentProperty"
+default = "false" type = "xs:boolean"/>
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:element name = "schemaBindings">
+
+ <xs:annotation>
+
+ <xs:documentation>Customization values with
+schema scope<xs:documentation>
+
+ </xs:annotation>
+
+ <xs:complexType>
+
+ <xs:all>
+
+ <xs:element name = "package" type =
+"jaxb:packageType" minOccurs = "0"/>
+
+ <xs:element name = "nameXmlTransform" type =
+"jaxb:nameXmlTransformType" minOccurs = "0"/>
+
+ </xs:all>
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:element name = "class">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Customize interface and
+implementation class.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name = "javadoc" type =
+"xs:string" minOccurs = "0"/>
+
+ </xs:sequence>
+
+ <xs:attribute name = "name" type =
+"jaxb:javaIdentifierType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Java class name without
+package prefix.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute name = "implClass" type =
+"jaxb:javaIdentifierType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Implementation class name
+including package prefix. </xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ _<xs:attribute name="generateValueClass"
+type="xs:boolean" default= "true"/>_
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:element name = "property">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Customize
+property.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:all>
+
+ <xs:element name = "javadoc" type =
+"xs:string" minOccurs="0"/>
+
+ <xs:element name = "baseType"
+type="jaxb:propertyBaseType" minOccurs="0"/>
+
+ </xs:all>
+
+ _<xs:attribute name = "name" type =
+"jaxb:javaIdentifierType"/> +
+<xs:attribute name = "attachmentRef" default="default">_
+
+ _<xs:simpleType>_
+
+ _<xs:restriction base="xs:NCName">_
+
+ _<xs:enumeration value="resolve"/>_
+
+ _<xs:enumeration value="doNotResolve"/>_
+
+ _<xs:enumeration value="default"/>_
+
+ _</xs:restriction>_
+
+ _</xs:simpleType>_
+
+ _</xs:attribute>_
+
+ <xs:attributeGroup ref =
+"jaxb:propertyAttributes"/>
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:element name = "javaType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Data type conversions;
+overriding builtins</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:attribute name = "name" use = "required"
+type = "jaxb:javaIdentifierType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>name of the java type to
+which xml type is to be bound.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute name = "xmlType" type =
+"xs:QName">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> xml type to which java
+datatype has to be bound._
+
+ _Must be present when javaType is scoped to
+globalBindings._
+
+ _</xs:documentation>_
+
+ </xs:annotation>
+
+ </xs:attribute>
+
+ <xs:attribute name = "parseMethod" type =
+"jaxb:javaIdentifierType"/>
+
+ <xs:attribute name = "printMethod" type =
+"jaxb:javaIdentifierType"/>
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _If true, the parsMethod and printMethod
+must reference a method_
+
+ _signtature that has a second parameter of
+type NamespaceContext._
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ </xs:complexType>
+
+ </xs:element>
+
+<xs:element name = "typesafeEnumClass">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> Bind to a type safe
+enumeration class.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name = "javadoc" type =
+"xs:string" minOccurs = "0"/>
+
+ <xs:element ref = "jaxb:typesafeEnumMember"
+minOccurs = "0" maxOccurs = "unbounded"/>
+
+ </xs:sequence>
+
+ <xs:attribute name = "name" type =
+"jaxb:javaIdentifierType"/>
+
+ _<xs:attribute name = "map" type =
+"xs:boolean" default = "true"/>_
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:element name = "typesafeEnumMember">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> Enumeration member name
+in a type safe enumeration class.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:element name = "javadoc" type =
+"xs:string" minOccurs = "0"/>
+
+ </xs:sequence>
+
+ <xs:attribute name = "value"
+type="xs:anySimpleType"/>
+
+ <xs:attribute name = "name" use = "required"
+type = "jaxb:javaIdentifierType"/>
+
+ </xs:complexType>
+
+ </xs:element>
+
+
+
+ _<!-- TYPE DEFINITIONS -->_
+
+
+
+ <xs:complexType name = "propertyBaseType">
+
+ <xs:all>
+
+ <xs:element ref = "jaxb:javaType" minOccurs
+= "0"/>
+
+ </xs:all>
+
+ _<xs:attribute name = "name" type =
+"jaxb:javaIdentifierType">_
+
+ _<xs:annotation><xs:documentation>_
+
+ _The name attribute for [baseType] enables
+more precise control over the actual base type for a JAXB property. This
+customization enables specifying a more general/specialized base type
+than the property's default base type. The name attribute value must be
+a fully qualified Java class name. Additionally, this Java class must be
+a super interface/class or subclass of the default Java base type for
+the property. 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.This customization is useful to enable simple type
+substitution for a JAXB property representing with too restrictive of a
+default base type. It also can be used to provide stronger typing for
+the binding of an element/attribute of type xs:IDREF._
+
+ _</xs:documentation></xs:annotation>_
+
+ _</xs:attribute>_
+
+ </xs:complexType>
+
+<xs:complexType name = "packageType">
+
+ <xs:sequence>
+
+ <xs:element name = "javadoc" type =
+"xs:string" minOccurs = "0"/>
+
+ </xs:sequence>
+
+ <xs:attribute name = "name" type =
+"jaxb:javaIdentifierType"/>
+
+ </xs:complexType>
+
+ <xs:simpleType name =
+"underscoreBindingType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> +
+Treate underscore in XML Name to Java identifier mapping. +
+</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:restriction base = "xs:string">
+
+ <xs:enumeration value = "asWordSeparator"/>
+
+ <xs:enumeration value = "asCharInWord"/>
+
+ </xs:restriction>
+
+ </xs:simpleType>
+
+ <xs:simpleType name =
+"typesafeEnumBaseType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> +
+XML types or types derived from them which have enumeration facet(s)
+which are be mapped to typesafeEnumClass by default. The following types
+cannot be specified in this list: "xsd:QName", "xsd:base64Binary",
+"xsd:hexBinary", "xsd:date", "xsd:time", "xsd:dateTime",
+"xsd:duration","xsd:gDay", "xsd:gMonth", "xsd:Year", "xsd:gMonthDay",
+"xsd:gYearMonth",_ _"xsd:ID", "xsd:IDREF", "xsd:NOTATION"_
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:list itemType = "xs:QName"/>
+
+ </xs:simpleType>
+
+ <xs:simpleType name =
+"typesafeEnumMemberNameType">
+
+ _<xs:annotation><xs:documentation> +
+Used to customize how to handle name collisions._
+
+ _</xs:documentation></xs:annotation>_
+
+ <xs:restriction base = "xs:string">
+
+ <xs:enumeration value = "generateName"/>
+
+ <xs:enumeration value = "generateError"/>
+
+ _<xs:enumeration value = "skipGeneration"/>_
+
+ </xs:restriction>
+
+ </xs:simpleType>
+
+ <xs:simpleType name = "javaIdentifierType">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Placeholder type to
+indicate Legal Java identifier.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:list itemType = "xs:NCName"/>
+
+ </xs:simpleType>
+
+ <xs:complexType name =
+"nameXmlTransformRule">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Rule to transform an Xml
+name into another Xml name</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:attribute name = "prefix" type =
+"xs:string">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>prepend the string to
+QName.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute name = "suffix" type =
+"xs:string">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Append the string to
+QName.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ </xs:complexType>
+
+ <xs:complexType name =
+"nameXmlTransformType">
+
+ _<xs:annotation><xs:documentation>_
+
+ _Allows transforming an xml name into
+another xml name. Use case UDDI 2.0
+schema.</xs:documentation></xs:annotation>_
+
+ <xs:all>
+
+ <xs:element name = "typeName" type =
+"jaxb:nameXmlTransformRule" minOccurs = "0">
+
+ _<xs:annotation><xs:documentation>Mapping
+rule for type definitions.</xs:documentation></xs:annotation>_
+
+ </xs:element>
+
+ <xs:element name = "elementName" type =
+"jaxb:nameXmlTransformRule" minOccurs = "0">
+
+ _<xs:annotation><xs:documentation>Mapping
+rule for elements</xs:documentation></xs:annotation>_
+
+ </xs:element>
+
+ <xs:element name = "modelGroupName" type =
+"jaxb:nameXmlTransformRule" minOccurs = "0">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Mapping rule for model
+group</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:element>
+
+ <xs:element name = "anonymousTypeName" type
+= "jaxb:nameXmlTransformRule" minOccurs = "0">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>Mapping rule for class
+names generated for an anonymous type.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:element>
+
+ </xs:all>
+
+ </xs:complexType>
+
+ <xs:attribute name =
+"extensionBindingPrefixes">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _A schema compiler only processes this
+attribute when it occurs on an_
+
+ _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._
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ <xs:simpleType>
+
+ <xs:list itemType = "xs:normalizedString"/>
+
+ </xs:simpleType>
+
+ </xs:attribute>
+
+ <xs:element name = "bindings">
+
+ _<xs:annotation>_
+
+ _<xs:documentation> +
+Binding declaration(s) for a remote schema. If attribute node is set,
+the binding declaraions are associated with part of the remote schema
+designated by schemaLocation attribute. The node attribute identifies
+the node in the remote schema to associate the binding declaration(s)
+with._
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ _<!-- a <bindings> element can contain
+arbitrary number of binding declarations or nested <bindings> elements
+-->_
+
+ <xs:complexType>
+
+ <xs:sequence>
+
+ <xs:choice minOccurs = "0" maxOccurs =
+"unbounded">
+
+ <xs:group ref = "jaxb:declaration"/>
+
+ <xs:element ref = "jaxb:bindings"/>
+
+ </xs:choice>
+
+ </xs:sequence>
+
+ <xs:attribute name = "schemaLocation" type =
+"xs:anyURI">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _Location of the remote schema to associate
+binding declarations with._
+
+ _</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute name = "node" type =
+"xs:string">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _The value of the string is an XPATH 1.0
+compliant string that resolves to a node in a remote schema to associate
+binding declarations with. The remote schema is specified by the
+schemaLocation attribute occuring in the current element or in a parent
+of this element. </xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute name = "version" type =
+"xs:token">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _Used to indicate the version of binding
+declarations. Only valid on root level bindings element. Either this or
+"jaxb:version" attribute but not both may be specified.
+</xs:documentation>_
+
+ _</xs:annotation>_
+
+ </xs:attribute>
+
+ <xs:attribute ref = "jaxb:version">
+
+ _<xs:annotation>_
+
+ _<xs:documentation>_
+
+ _Used to indicate the version of binding
+declarations. Only valid on root level bindings element. Either this
+attribute or "version" attribute but not both may be
+specified.</xs:documentation>_
+
+ _</xs:annotation>_
+
+ _</xs:attribute>_
+
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:simpleType
+name="referenceCollectionType">
+
+ <xs:union>
+
+ <xs:simpleType>
+
+ <xs:restriction base="xs:string">
+
+ <xs:enumeration value="indexed"/>
+
+ </xs:restriction>
+
+ </xs:simpleType>
+
+ <xs:simpleType>
+
+ <xs:restriction
+base="jaxb:javaIdentifierType"/>
+
+ </xs:simpleType>
+
+ </xs:union>
+
+ </xs:simpleType>
+
+ _<xs:element name="dom">_
+
+ _<xs:complexType>_
+
+ _<xs:attribute name = "type"
+type="xs:NCName" default="w3c">_
+
+ _<xs:annotation><xs:documentation>Specify
+DOM API to bind to JAXB property to.<xs:documentation></xs:annotation>_
+
+ _</xs:attribute>_
+
+ _</xs:complexType>_
+
+ _</xs:element>_
+
+ _<xs:element name="inlineBinaryData">_
+
+ _<xs:annotation> <xs:documentation> +
+Disable MTOM/XOP encoding for this binary data. Annotation can be placed
+on a type defintion that derives from a W3C XSD binary data type or on
+an element that has a type that is or derives from a W3C XSD binary data
+type._
+
+ _</xs:documentation></xs:annotation>_
+
+ _</xs:element>_
+
+ _<xs:element name = "serializable">_
+
+ _<xs:complexType>_
+
+ _<xs:attribute name="uid" type="xs:long"
+default="1"/> +
+</xs:complexType>_
+
+ _</xs:element>_
+
+</xs:schema>
+
+
+
+
+
+=== [[a4649]]Appendix
+
+Binding XML Names to Java
+Identifiers
+
+=== Overview
+
+This section provides default mappings from:
+
+* XML Name to Java identifier
+* Model group to Java identifier
+* Namespace URI to Java package name
+
+=== [[a4656]]The Name to Identifier Mapping Algorithm
+
+Java identifiers typically follow three
+simple, well-known conventions:
+
+* Class and interface names always begin with
+an upper-case letter. The remaining characters are either digits,
+lower-case letters, or upper-case letters. Upper-case letters within a
+multi-word name serve to identify the start of each non-initial word, or
+sometimes to stand for acronyms.
+* Method names and components of a package
+name always begin with a lower-case letter, and otherwise are exactly
+like class and interface names.
+* Constant names are entirely in upper case,
+with each pair of words separated by the underscore character (‘_’,
+\u005F, LOW LINE).
+
+XML names, however, are much richer than Java
+identifiers: They may include not only the standard Java identifier
+characters but also various punctuation and special characters that are
+not permitted in Java identifiers. Like most Java identifiers, most XML
+names are in practice composed of more than one natural-language word.
+Non-initial words within an XML name typically start with an upper-case
+letter followed by a lower-case letter, as in Java language, or are
+prefixed by punctuation characters, which is not usual in the Java
+language and, for most punctuation characters, is in fact illegal.
+
+In order to map an arbitrary XML name into a
+Java class, method, or constant identifier, the XML name is first broken
+into a _word list_ . For the purpose of constructing word lists from XML
+names we use the following definitions:
+
+* A _punctuation character_ is one of the
+following:
+* A hyphen (’-’, \u002D, HYPHEN-MINUS),
+* A period (‘.’, \u002E, FULL STOP),
+* A colon (’:’, \u003A, COLON),
+* A dot (‘.’, \u00B7, MIDDLE DOT),
+* \u0387, GREEK ANO TELEIA,
+* \u06DD, ARABIC END OF AYAH, or
+* \u06DE, ARABIC START OF RUB EL HIZB.
+* An underscore (’_’, \u005F, LOW LINE) with
+following exceptionlink:#a5380[29]
+
+These are all legal characters in XML names.
+
+* A _letter_ is a character for which the
+_Character.isLetter_ method returns _true_ , _i.e._ , a letter according
+to the Unicode standard. Every letter is a legal Java identifier
+character, both initial and non-initial.
+* A _digit_ is a character for which the
+_Character.isDigit_ method returns _true_ , _i.e._ , a digit according
+to the Unicode Standard. Every digit is a legal non-initial Java
+identifier character.
+* A _mark_ is a character that is in none of
+the previous categories but for which the
+_Character.isJavaIdentifierPart_ method returns _true_ . This category
+includes numeric letters, combining marks, non-spacing marks, and
+ignorable control characters.
+
+Every XML name character falls into one of
+the above categories. We further divide letters into three
+subcategories:
+
+* An _upper-case letter_ is a letter for
+which the _Character.isUpperCase_ method returns _true_ ,
+* A _lowercase letter_ is a letter for which
+the _Character.isLowerCase_ method returns _true_ , and
+* All other letters are _uncased_ .
+
+An XML name is split into a word list by
+removing any leading and trailing punctuation characters and then
+searching for _word breaks_ . A word break is defined by three regular
+expressions: A prefix, a separator, and a suffix. The prefix matches
+part of the word that precedes the break, the separator is not part of
+any word, and the suffix matches part of the word that follows the
+break. The word breaks are defined as:
+
+=== [[a4681]]XML Word Breaks
+
+Prefix
+
+Separator
+
+Suffix
+
+Example
+
+{empty}[^punct]
+
+punct+1
+
+{empty}[^punct]
+
+foo|--|bar
+
+digit
+
+
+
+{empty}[^ _digit_ ]
+
+foo|22|bar
+
+{empty}[^digit]
+
+
+
+digit
+
+foo|22
+
+lower
+
+
+
+{empty}[^lower]
+
+foo|Bar
+
+upper
+
+
+
+upper lower
+
+FOO|Bar
+
+letter
+
+
+
+{empty}[^letter]
+
+Foo|\u2160
+
+{empty}[^letter]
+
+
+
+letter
+
+\u2160|Foo
+
+uncased
+
+
+
+{empty}[^uncased]
+
+
+
+{empty}[^uncased]
+
+
+
+uncased
+
+
+
+(The character _\u2160_ is ROMAN NUMERAL ONE,
+a numeric letter.)
+
+After splitting, if a word begins with a
+lower-case character then its first character is converted to upper
+case. The final result is a word list in which each word is either
+
+* A string of upper- and lower-case letters,
+the first character of which is upper case (includes underscore,’_’, for
+exception case1).
+* A string of digits, or
+* A string of uncased letters and marks.
+
+Given an XML name in word-list form, each of
+the three types of Java identifiers is constructed as follows:
+
+* A class or interface identifier is
+constructed by concatenating the words in the list,
+* A method identifier is constructed by
+concatenating the words in the list. A prefix verb ( _get_ , _set_ ,
+_etc._ ) is prepended to the result.
+* A constant identifier is constructed by
+converting each word in the list to upper case; the words are then
+concatenated, separated by underscores.
+
+This algorithm will not change an XML name
+that is already a legal and conventional Java class, method, or constant
+identifier, except perhaps to add an initial verb in the case of a
+property access method.
+
+To improve user experience with default
+binding, the automated resolution of frequent naming collision is
+specified in link:jaxb.html#a4770[See Standardized Name
+Collision Resolution]“.
+
+=== Example
+
+=== [[a4734]]XML Names and derived Java Class, Method, and Constant Names
+
+XML Name
+
+Class Name
+
+Method Name
+
+Constant Name
+
+mixedCaseName
+
+MixedCaseName
+
+getMixedCaseName
+
+MIXED_CASE_NAME
+
+Answer42
+
+Answer42
+
+getAnswer42
+
+ANSWER_42
+
+name-with-dashes
+
+NameWithDashes
+
+getNameWithDashes
+
+NAME_WITH_DASHES
+
+other_punct-chars
+
+OtherPunctChars
+
+getOtherPunctChars
+
+OTHER_PUNCT_CHARS
+
+=== [[a4755]]XML Names and derived Java Class, Method, and Constant Names when <jaxb:globalBindings underscoreHandling=”asCharInWord”>
+
+[width="100%",cols="25%,25%,25%,25%",options="header",]
+|===
+|XML Name |Class
+Name |Method Name
+|Constant Name
+|other_punct-chars
+|Other_punctChars
+|getOther_punctChars
+|OTHER_PUNCT_CHARS
+
+|name_with_underscore
+|Name_with_underscore
+|name_with_underscore
+|NAME_WITH_UNDERSCORE
+|===
+
+=== [[a4767]]Collisions and conflicts
+
+It is possible that the name-mapping
+algorithm will map two distinct XML names to the same word list.These
+cases will result in a _collision_ if, and only if, the same Java
+identifier is constructed from the word list and is used to name two
+distinct generated classes or two distinct methods or constants in the
+same generated class. It is also possible if two or more namespaces are
+customized to map to the same Java package, XML names that are unique
+due to belonging to distinct namespaces could mapped to the same Java
+Class identifier. Collisions are not permitted by the schema compiler
+and are reported as errors; they may be repaired by revising XML name
+within the source schema or by specifying a customized binding that maps
+one of the two XML names to an alternative Java identifier.
+
+A class name must not conflict with the
+generated JAXB class, _ObjectFactory_ , link:jaxb.html#a482[See
+Java Package], that occurs in each schema-derived Java package. Method
+names are forbidden to conflict with Java keywords or literals, with
+methods declared in _java.lang.Object_ , or with methods declared in the
+binding-framework classes. Such conflicts are reported as errors and may
+be repaired by revising the appropriate schema or by specifying an
+appropriate customized binding that resolves the name collision.
+
+=== [[a4770]]Standardized Name Collision Resolution
+
+Given the frequency of an XML element or
+attribute with the name “class” or “Class” resulting in a naming
+collision with the inherited method _java.lang.Object.getClass()_ ,
+method name mapping automatically resolves this conflict by mapping
+these XML names to the java method identifier “getClazz”.
+
+*
+
+=== [[a4773]]Deriving a legal Java identifier from an enum facet value
+
+Given that an enum facet’s value is not
+restricted to an XML name, the XML Name to Java identifier algorithm is
+not applicable to generating a Java identifier from an enum facet’s
+value. The following algorithm maps an enum facet value to a valid Java
+constant identifier name.
+
+* For each character in enum facet value, +
+copy the character to a string representation _javaId_ when
+_java.lang.Character.isJavaIdentifierPart()_ is _true_ .
+* To follow Java constant naming convention,
+each valid lower case character must be copied as its upper case
+equivalent.
+* There is no derived Java constant
+identifier when any of the following occur:
+* _javaId.length() == 0_
+*
+_java.lang.Character.isJavaIdentifierStart(javaId.get(0)) == false_
+
+=== [[a4780]]Deriving an identifier for a model group
+
+XML Schema has the concept of a group of
+element declarations. Occasionally, it is convenient to bind the
+grouping as a Java content property or a Java value class. When a
+semantically meaningful name for the group is not provided within the
+source schema or via a binding declaration customization, it is
+necessary to generate a Java identifier from the grouping. Below is an
+algorithm to generate such an identifier.
+
+A name is computed for an unnamed model group
+by concatenating together the first 3 element declarations and/or
+wildcards that occur within the model group. Each XML \{name} is mapped
+to a Java identifier for a method using the XML Name to Java Identifier
+Mapping algorithm. Since wildcard does not have a \{name} property, it
+is represented as the Java identifier “ _Any_ ”. The Java identifiers
+are concatenated together with the separator “ _And_ ” for sequence and
+all compositor and “ _Or_ ” for choice compositors. For example, a
+sequence of element _foo_ and element _bar_ would map to _“_ _FooAndBar_
+_”_ and a choice of element _foo_ and element _bar_ maps to _“_
+_FooOrBar_ _._ ” Lastly, a sequence of wildcard and element _bar_ would
+map to the Java identifier _“_ _AnyAndBar_ _”_ .
+
+=== Example:
+
+Given XML Schema fragment:
+
+<xs:choice> +
+<xs:sequence> +
+<xs:element ref="A"/> +
+<xs:any processContents="strict"/> +
+</xs:sequence> +
+<xs:element ref="C"/>
+
+</xs:choice>
+
+The generated Java identifier would be
+_AAndAnyOrC_ .
+
+=== [[a4788]]Generating a Java package name
+
+This section describes how to generate a
+package name to hold the derived Java representation. The motivation for
+specifying a default means to generate a Java package name is to
+increase the chances that a schema can be processed by a schema compiler
+without requiring the user to specify customizations.
+
+If a schema has a target namespace, the next
+subsection describes how to map the URI into a Java package name. If the
+schema has no target namespace, there is a section that describes an
+algorithm to generate a Java package name from the schema filename.
+
+=== Mapping from a Namespace URI
+
+An XML namespace is represented by a URI.
+Since XML Namespace will be mapped to a Java package, it is necessary to
+specify a default mapping from a URI to a Java package name. The URI
+format is described in [RFC2396].
+
+The following steps describe how to map a URI
+to a Java package name. The example URI,
+_http://www.acme.com/go/espeak.xsd_ , is used to illustrate each step.
+
+. Remove the scheme and _":"_ part from the
+beginning of the URI, if present. +
+Since there is no formal syntax to identify the optional URI scheme,
+restrict the schemes to be removed to case insensitive checks for
+schemes “ _http_ ” and “ _urn_ ”.
+
+ _//www.acme.com/go/espeak.xsd_
+
+. Remove the trailing file type, one of _.??_
+or _.???_ or _.html_ .
+
+ _//www.acme.com/go/espeak_
+
+. Parse the remaining string into a list of
+strings using _’/’_ and _‘:’_ as separators. Treat consecutive
+separators as a single separator.
+
+ _\{"www.acme.com", "go", "espeak" }_
+
+. For each string in the list produced by
+previous step, unescape each escape sequence octet.
+
+ _\{"www.acme.com", "go", "espeak" }_
+
+. If the scheme is a “urn”, replace all
+dashes, “-”, occurring in the first component with
+“.”.link:#a5381[30]
+. Apply algorithm described in Section 7.7
+“Unique Package Names” in [JLS] to derive a unique package name from the
+potential internet domain name contained within the first component. The
+internet domain name is reversed, component by component. Note that a
+leading “ _www_ .” is not considered part of an internet domain name and
+must be dropped.
+
+If the first component does not contain
+either one of the top-level domain names, for example, com, gov, net,
+org, edu, or one of the English two-letter codes identifying countries
+as specified in ISO Standard 3166, 1981, this step must be skipped.
+
+ _\{“com”, “acme”, “go”, “espeak”}_
+
+. For each string in the list, convert each
+string to be all lower case.
+
+ _\{"com”, “acme”, "go", "espeak" }_
+
+. For each string remaining, the following
+conventions are adopted from [JLS] Section 7.7, “Unique Package Names.”
+. If the sting component contains a hyphen,
+or any other special character not allowed in an identifier, convert it
+into an underscore.
+. If any of the resulting package name
+components are keywords then append underscore to them.
+. If any of the resulting package name
+components start with a digit, or any other character that is not
+allowed as an initial character of an identifier, have an underscore
+prefixed to the component.
+
+ _\{"com”, “acme”, "go", "espeak" }_
+
+. Concatenate the resultant list of strings
+using _’.’_ as a separating character to produce a package name.
+
+ _Final package name: "com.acme.go.espeak"._
+
+link:jaxb.html#a4767[See Collisions
+and conflicts], specifies what to do when the above algorithm results in
+an invalid Java package name.
+
+=== [[a4816]]Conforming Java Identifier Algorithm
+
+This section describes how to convert a legal
+Java identifier which may not conform to Java naming conventions to a
+Java identifier that conforms to the standard naming conventions.
+link:jaxb.html#a1608[See Customized Name Mapping]“discusses when
+this algorithm is applied to customization names.
+
+Since a legal Java identifier is also a XML
+name, this algorithm is the same as link:jaxb.html#a4656[See The
+Name to Identifier Mapping Algorithm]” with the following exception:
+constant names must not be mapped to a Java constant that conforms to
+the Java naming convention for a constant.
+
+=== Appendix
+
+External Binding Declaration
+
+=== [[a4821]]Example
+
+=== Example: Consider the following schema and external binding file:
+
+Source Schema: _A.xsd:_
+
+<xs:schema
+xmlns:xs="http://www.w3.org/2001/XMLSchema"
+
+ xmlns:ens="http://example.com/ns"
+
+ targetNamespace="http://example.com/ns"> +
+<xs:complexType name="aType">
+
+ <xs:sequence>
+
+ <xs:element name="foo" type="xs:int"/>
+
+ </xs:sequence>
+
+ <xs:attribute name="bar" type="xs:int"/>
+
+ </xs:complexType>
+
+ <xs:element name="root" type="ens:aType"/>
+
+</xs:schema>
+
+External binding declarations file:
+
+<jaxb:bindings
+xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
+
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+
+ version="1.0">
+
+ <jaxb:bindings schemaLocation=” _A.xsd_ ”>
+
+ <jaxb:bindings
+node="//xs:complexType[@name=’aType’]”>
+
+ <jaxb:class name="customNameType"/>
+
+ <jaxb:bindings
+node=”.//xs:element[@name=’foo’]”> +
+<jaxb:property name="customFoo"/>
+
+ </jaxb:bindings>
+
+ <jaxb:bindings
+node=”./xs:attribute[@name=’bar’]”> +
+<jaxb:property name="customBar"/> +
+</jaxb:bindings>
+
+ </jaxb:bindings>
+
+ </jaxb:bindings>
+
+</jaxb:bindings>
+
+Conceptually, the combination of the source
+schema and external binding file above are the equivalent of the
+following inline annotated schema.
+
+<xs:schema
+xmlns:xs="http://www.w3.org/2001/XMLSchema" +
+xmlns:ens="http://example.com/ns" +
+targetNamespace="http://example.com/ns"
+
+
+xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" +
+jaxb:version="1.0"> +
+<xs:complexType name="aType"> +
+_<xs:annotation> +
+<xs:appinfo> +
+_ _<jaxb:class name="customNameType"/> +
+_ _</xs:appinfo> +
+</xs:annotation> +
+_ <xs:sequence> +
+<xs:element name="foo" type="xs:int"> +
+_<xs:annotation> +
+<xs:appinfo> +
+_ _<jaxb:property name="customFoo"/> +
+_ _</xs:appinfo> +
+</xs:annotation> +
+_ </xs:element> +
+</xs:sequence> +
+<xs:attribute name="bar" type="xs:int"> +
+_<xs:annotation> +
+<xs:appinfo> +
+_ _<jaxb:property name="customBar"/> +
+_ _</xs:appinfo> +
+</xs:annotation> +
+_ </xs:attribute> +
+</xs:complexType> +
+<xs:element name="root" type="ens:aType"/> +
+</xs:schema>
+
+=== Transformation
+
+The intent of this section is to describe the
+transformation of external binding declarations and their target schemas
+into a set of schemas annotated with JAXB binding declarations. ready
+for processing by a JAXB compliant schema compiler.
+
+This transformation must be understood to
+work on XML data model level. Thus, this transformation is applicable
+even for those schemas which contain semantic errors.
+
+The transformation is applied as follows:
+
+. Gather all the top-most _<jaxb:bindings>_
+elements from all the schema documents and all the external binding
+files that participate in this process. _Top-most_ _<jaxb:bindings>_ are
+those _<jaxb:bindings>_ elements that are either a root element in a
+document or whose parent is an _<xs:appinfo>_ element. We will refer to
+these trees as “external binding forest.”
+. Collect all the namespaces used in the
+elements inside the external binding forest, except the taxi namespace,
+_"http://java.sun.com/xml/ns/jaxb”,_ and the no namespace. Allocate an
+unique prefix for each of them and declare the namespace binding at all
+the root _<xs:schema>_ elements of each schema documents. +
+Then add a _jaxb:extensionBindingPrefix_ attribute to each _<xs:schema>_
+element with all those allocated prefixes. If an _<xs:schema>_ element
+already carries this attribute, prefixes are just appended to the
+existing attributes. +
+ +
+Note: The net effect is that all “foreign” namespaces used in the
+external binding forest will be automatically be considered as extension
+customization declaration namespaces.
+. For each _<jaxb:bindings>_ element, we
+determine the “target element” that the binding declaration should be
+associated with. This process proceeds in a top-down fashion as follows:
+. Let _p_ be the target element of the parent
+_<jaxb:bindings>_ . If it is the top most _<jaxb:bindings>_ , then let
+_p_ be the < _jaxb:bindings>_ element itself.
+. Identify the “target element” using
+_<jaxb:bindings>_ attributes. +
+(i) If the _<jaxb:bindings>_ has a _@schemaLocation_ , the value of the
+attribute should be taken as an URI and be absolutized with the base URI
+of the _<jaxb:bindings>_ element. Then the target element will be the
+root node of the schema document identified by the absolutized URI. If
+there’s no such schema document in the current input, it is an error.
+Note: the root node of the schema document is not the document element.
+
+(ii) If the _<jaxb:bindings>_ has _@node_ ,
+the value of the attribute should be evaluated as an XPath 1.0
+expression. The context node in this evaluation should be _p_ as we
+computed in the previous step. It is an error if this evaluation results
+in something other than a node set that contains exactly one element.
+Then the target element will be this element.
+
+(iii) if the _<jaxb:bindings>_ has neither
+_@schemaLocation_ nor _@node_ , then the target element will be _p_ as
+we computed in the previous step. Note: _<jaxb:bindings>_ elements can’t
+have both _@schemaLocation_ and _@node_ at the same time.
+
+We define the target element of a binding
+declaration to be the target element of its parent _<jaxb:bindings>_
+element. The only exception to this is _<jaxb:globalBindings>_ binding
+declaraiton, in which case the target element will be the document
+element of any one of the schema documents being compiled (such choice
+is undeterministic, but the semantics of _<jaxb:globalBindings>_ is not
+affected by this choice, so the end result will be the same.) It is an
+error if a target element of a binding declaration doesn’t belong to the
+_"http://wwww.w3.org/2001/XMLSchema"_ namespace.
+
+. Next, for each target element of binding
+declarations, if it doesn’t have any _<xs:annotation> <xs:appinfo>_ in
+its children, one will be created and added as the first child of the
+target. +
+ +
+After that, we move each binding declaration under the target node of
+its parent _<jaxb:bindings>_ . Consider the first _<xs:appinfo>_ child
+of the target element. The binding declaration element will be moved
+under this _<xs:appinfo>_ element.
+
+=== Appendix
+
+XML Schema
+
+=== Abstract Schema Model
+
+The following summarization abstract schema
+component model has been extracted from [XSD Part 1] as a convenience
+for those not familiar with XML Schema component model in understanding
+the binding of XML Schema components to Java representation. One must
+refer to [XSD Part 1] for the complete normative description for these
+components.
+
+=== [[a4867]]Simple Type Definition Schema Component
+
+=== Simple Type Definition Schema Components
+
+Component
+
+Description
+
+\{name}
+
+Optional. An NCName as defined by
+[XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name.
+
+\{base type definition}
+
+A simple type definition
+
+\{facets}
+
+A set of constraining facets.
+
+\{fundamental facets}
+
+A set of fundamental facets.
+
+\{final}
+
+A subset of \{extension, list, restriction,
+union}.
+
+\{variety}
+
+One of \{atomic, list, union}. Depending on
+the value of \{variety}, further properties are defined as follows:
+
+
+
+atomic
+
+ _\{primitive type definition}_
+
+A built-in primitive simple type definition.
+
+
+
+list
+
+ _\{item type definition}_
+
+A simple type definition.
+
+
+
+union
+
+ _\{member type definitions}_
+
+A non-empty sequence of simple type
+definitions.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== [[a4899]]Enumeration Facet Schema Component
+
+=== Enumeration Facet Schema Components
+
+Component
+
+Description
+
+\{value}
+
+The actual value of the value. (Must be in
+value space of base type definition.)
+
+\{annotation}
+
+Optional annotation.
+
+=== [[a4907]]Complex Type Definition Schema Component
+
+=== Complex Type Definition Schema Components
+
+Component
+
+Description
+
+\{name}
+
+Optional. An NCName as defined by
+[XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name.
+
+\{base type definition}
+
+Either a simple type definition or a complex
+type definition.
+
+\{scope}
+
+Either _global_ or a complex type definition
+
+\{derivation method}
+
+Either extension or restriction.
+
+\{final}
+
+A subset of \{extension, restriction}.
+
+\{abstract}
+
+A boolean
+
+\{attribute uses}
+
+A set of attribute uses.
+
+\{attribute wildcard}
+
+Optional. A wildcard.
+
+\{content type}
+
+ One of empty, a simple type definition, or a
+pair consisting of a ·content model· and one of mixed, element-only.
+
+\{prohibited substitutions}
+
+A subset of \{extension, restriction}.
+
+\{substitution group affiliation}
+
+Optional. If exists, this element declaration
+belongs to a substitution group and this specified element name is the
+QName of the substitution head.
+
+\{annotations}
+
+A set of annotations.
+
+=== [[a4937]]Element Declaration Schema Component
+
+=== Element Declaration Schema Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name
+
+\{type definition}
+
+Either a simple type definition or a complex
+type definition.
+
+\{scope}
+
+Optional. Either global or a complex type
+definition.
+
+\{value constraint}
+
+Optional. A pair consisting of a value and
+one of default, fixed.
+
+\{nillable}
+
+A boolean.
+
+\{identity-constraint definitions}
+
+A set of constraint definitions.
+
+\{substitution group affiliation}
+
+Optional. A top-level element definition.
+
+\{substitution group exclusions}
+
+A subset of \{extension, restriction}.
+
+\{disallowed substitution}
+
+A subset of
+\{substitution,extension,restriction}.
+
+\{abstract}
+
+A boolean.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== [[a4965]]Attribute Declaration Schema Component
+
+=== Attribute Declaration Schema Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+If form is present and is “qualified”, or if
+form is absent and the value of @attributeFormDefault on the <schema>
+ancestor is “qualified”, then the schema’s \{targetNamespace}, or
+·absent· if there is none, otherwise ·absent·
+
+\{type definition}
+
+A simple type definition.
+
+\{scope}
+
+Optional. Either global or a complex type
+definition.
+
+\{value constraint}
+
+Optional. A pair consisting of a value and
+one of default, fixed.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Model Group Definition Schema Component
+
+=== Model Group Definition Schema Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name.
+
+\{model group}
+
+A model group.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Identity-constraint Definition Schema Component
+
+=== Identity-constraint Definition Schema Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name.
+
+\{identity-constraint category}
+
+One of key, keyref or unique.
+
+\{selector}
+
+A restricted XPath ([XPath]) expression.
+
+\{fields}
+
+A non-empty list of restricted XPath
+([XPath]) expressions.
+
+\{referenced key}
+
+Required if \{identity-constraint category}
+is keyref, forbidden otherwise.
+
+An identity-constraint definition with
+\{identity-constraint category} equal to key or unique.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== [[a5012]]Attribute Use Schema Component
+
+=== Attribute Use Schema Components
+
+Component
+
+Description
+
+\{required}
+
+A boolean.
+
+\{attribute declaration}
+
+An attribute declaration.
+
+\{value constraint}
+
+Optional. A pair consisting of a value and
+one of default, fixed.
+
+=== [[a5022]]Particle Schema Component
+
+=== Particle Schema Components
+
+Component
+
+Description
+
+\{min occurs}
+
+A non-negative integer.
+
+\{max occurs}
+
+Either a non-negative integer or unbounded.
+
+\{term}
+
+One of a model group, a wildcard, or an
+element declaration.
+
+=== [[a5032]]Wildcard Schema Component
+
+=== Wildcard Schema Components
+
+Component
+
+Description
+
+\{namespace constraint}
+
+One of any; a pair of not and a namespace
+name or ·absent·; or a set whose members are either namespace names or
+·absent·.
+
+\{process contents}
+
+One of skip, lax or strict.
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Model Group Schema Component
+
+=== Model Group Components
+
+Component
+
+Description
+
+\{compositor}
+
+One of _all, choice_ or _sequence_ .
+
+\{particles}
+
+A list of particles.
+
+\{annotation}
+
+An annotation.
+
+=== Notation Declaration Schema Component
+
+=== Notation Declaration Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+Actual value of the targetNamespace
+[attribute] of the parent schema element
+
+\{system identifier}
+
+The ·actual value· of the system [attribute],
+if present, otherwise absent.
+
+\{public identifier}
+
+{empty}The ·actual value· of the public
+[attribute]
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Wildcard Schema Component
+
+=== Wildcard Components
+
+Component
+
+Description
+
+\{namespace constraint}
+
+ One of _any_ ; a pair of _not_ and a
+namespace name or ·absent·; or a set whose members are either namespace
+names or ·absent·.
+
+\{process contents}
+
+One of _skip_ , _lax_ or _strict_ .
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Attribute Group Definition Schema Component
+
+=== Attribute Group Definition Schema Components
+
+Component
+
+Description
+
+\{name}
+
+An NCName as defined by [XML-Namespaces].
+
+\{target namespace}
+
+Either ·absent· or a namespace name.
+
+\{attribute uses}
+
+A set of attribute uses.
+
+\{attribute wildcard}
+
+Optional. A wildcard. _(part of the complete
+wildcard)_
+
+\{annotation}
+
+Optional. An annotation.
+
+=== Appendix
+
+Deprecated JAXB 1.0
+Functionality
+
+=== Overview
+
+Due to significant re-architecture in JAXB
+2.0 to improve efficiency, usability, schema-derived footprint and
+binding framework runtime footprint, certain JAXB 1.0 operations are no
+longer required to be implemented in JAXB 2.0. These deprecated
+operations do still need to be supported by a JAXB 2.0 binding runtime
+for JAXB 1.0 schema-derived classes.
+
+=== [[a5094]]On-demand Validation
+
+It is optional for a JAXB 2.0 implementation
+to implement on-demand validation for JAXB 2.0 mapped classes. There is
+no reasonable way to implement this functionality of JAXB 2.0 annotated
+classes and leverage JAXP 1.3 validation facility. For backwards
+compatibility, an implementation is required to support this
+functionality for JAXB 1.0 schema-derived classes.
+
+=== [[a5096]]Validator for JAXB 1.0 schema-derived classes
+
+ _The following text is from JAXB 1.0
+Specification and applies to JAXB 1.0 schema-derived classes._
+
+An application may wish to validate the
+correctness of the Java content tree based on schema validation
+constraints. This form of validation enables an application to initiate
+the validation process on a Java content tree at a point in time that it
+feels it should be valid. The application is notified about validation
+errors and warnings detected in the Java content tree.
+
+The _Validator_ class is responsible for
+controlling the validation of a content tree of in-memory objects. The
+following summarizes the available operations on the class.
+
+public interface Validator \{ +
+ValidationEventHandler _getEventHandler_ () +
+void _setEventHandler_ (ValidationEventHandler)
+
+ +
+boolean _validate_ (java.lang.Object subrootObject)
+
+ boolean _validateRoot_ (java.lang.Object
+rootObject) +
+
+ java.lang.Object _getProperty_
+(java.lang.String name) +
+void _setProperty_ (java.lang.String name,
+java.lang.Object value)
+
+}
+
+ _The JAXBContext_ class provides a factory
+to create a _Validator_ instance. After an application has made a series
+of modifications to a Java content tree, the application validates the
+content tree on-demand. As far as the application is concerned, this
+validation takes place against the Java content instances and validation
+constraint warnings and errors are reported to the application relative
+to the Java content tree. Validation is initiated by invoking the
+_validateRoot(Object)_ method on the root of the Java content tree or by
+invoking _validate(Object)_ method to validate any arbitrary subtree of
+the Java content tree. The only difference between these two methods is
+global constraint checking (i.e. verifying ID/IDREF constraints.) The
+_validateRoot(Object)_ method includes global constraint checking as
+part of its operation, whereas the _validate(Object)_ method does not.
+
+The validator governs the process of
+validating the content tree, serves as a registry for identifier
+references, and ensures that all local (and when appropriate, global)
+structural constraints are checked before the validation process is
+complete.
+
+If a violation of a local or global
+structural constraint is detected, then the application is notified of
+the event with a callback passing an instance of a _ValidationEvent_ as
+a parameter.
+
+=== [[a5109]]Appendix
+
+[[a5110]]Enhanced Binary Data
+Handling
+
+=== Overview
+
+Optimized transmission of binary data as
+attachments is described by standards such as Soap [MTOM]/Xml-binary
+Optimized Packaging[XOP] and WS-I Attachment Profile 1.0 [WSIAP]. To
+optimally support these standards when JAXB databinding is used within a
+message passing environment, link:jaxb.html#a5149[See
+javax.xml.bind.attachments]“specifies an API that allows for an
+integrated, cooperative implementation of these standards between a
+MIME-based package processor and the JAXB 2.0 unmarshal/marshal
+processes. An enhanced binding of MIME content to Java representation is
+specified in link:jaxb.html#a5113[See Binding MIME Binary
+Data]“.
+
+=== [[a5113]]Binding MIME Binary Data
+
+=== Binary Data Schema Annotation
+
+As specified in [MIME], the XML Schema
+annotation attribute, _xmime:expectedContentTypes_ , lists the expected
+MIME content-type(s) for element content whose type derives from the xsd
+binary datatypes, _xs:base64Binary_ or x _s:hexBinary_ .
+
+JAXB 2.0 databinding recognizes this schema
+constraint to improve the binding of MIME type constrained binary data
+to Java representation. The _xmime:expectedContentType_ attribute is
+allowed on type definitions deriving from binary datatypes and on
+element declarations with types that derive from binary datatypes. For
+JAXB 2.0 binding purposes, the schema annotation,
+_xmime:expectedContentTypes_ is evaluated for binding purposes for all
+cases EXCEPT when the annotation is on an element declaration with a
+named complex type definition. For that case, the
+_xmime:expectedContentTypes_ annotation must be located directly within
+the scope of the complex type definition in order to impact the binding
+of the complex type definition’s simple binary content.
+
+=== Binding Known Media Type
+
+When _@xmime:expectedContentTypes_ schema
+annotation only refers to one MIME type, it is considered a known media
+type for the binary data. [MIME] does not require an _xmime:contentType_
+attribute to hold the dynamic mime type for the binary data for this
+case. JAXB binding can achieve an optimal binding for this case. The
+default MIME type to Java datatype are in
+link:jaxb.html#a5119[See Default Binding for Known Media Type].
+
+=== [[a5119]]Default Binding for Known Media Type
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|MIME Type |Java
+Type
+|image/gif
+|java.awt.Image
+
+|image/jpeg
+|java.awt.Image
+
+|text/xml or application/xml
+|javax.xml.transform.Source
+
+| _any other MIME types_
+|javax.activation.DataHandler
+|===
+
+A JAXB program annotation element,
+_@XmlMimeType_ , is generated to preserve the known media type for use
+at marshal time.
+
+=== schema with a known media type
+
+<?xml version="1.0" ?> +
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" +
+xmlns:tns="http://example.com/know-type" +
+| xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
+
+
+targetNamespace="http://example.com/know-type">
+
+ <xs:import
+namespace="http://www.w3.org/2005/05/xmlmime"
+
+
+schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
+
+ <xs:element name="JPEGPicture"
+type="xs:base64binary" +
+xmime:expectedContentTypes="image/jpeg"/> +
+</xs:schema>
+
+=== JAXB 2.0 binding of Example 9-1
+
+ import java.awt.Image; +
+@XmlRegistry +
+class ObjectFactory \{ +
+@XmlElementDecl(...) +
+@XmlMimeType("image/jpeg")
+
+ JAXBELement<Image> createJPEGPicture(Image
+value); +
+}
+
+The _@XmlMimeType_ annotation provides the
+MIME content type needed by JAXB 2.0 Marshaller to specify the mime type
+to set _DataHandler.setContentType(String)_ .
+
+=== [[a5140]]Schema for local element declaration annotated with known media type
+
+ <?xml version="1.0" ?> +
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" +
+xmlns:tns="http://example.com/know-type" +
+xmlns:xmime="http://www.w3.org/2005/05/xmlmime" +
+targetNamespace="http://example.com/know-type"> +
+<xs:import namespace="http://www.w3.org/2005/05/xmlmime" +
+schemaLocation="http://www.w3.org/2005/05/xmlmime"/> +
+<xs:complexType name="Item"> +
+<xs:sequence> +
+<xs:element name="JPEGPicture" +
+type="xs:base64Binary" +
+xmime:expectedContentTypes="image/jpeg"/> +
+</xs:sequence> +
+</xs:complexType> +
+</xs:schema>
+
+=== Java Binding of link:jaxb.html#a5140[See Schema for local element declaration annotated with known media type]“
+
+import java.awt.Image; +
+public class Item \{ +
+@XmlMimeType("image/jpeg") +
+Image getJPEGPicture(); +
+void setJPEGPicture(Image value); +
+}
+
+=== Binding Preferred Media Types
+
+If there are more than one mime type listed
+in _xmime:expectedContentTypes_ or if there is one with a wildcard in
+it, the annotation specifies the Preferred Media Types and recommends
+that the binary data be simple content that has an attribute
+_xmime:contentType_ that specifies which of the
+_xmime:expectedContentTypes_ the binary data represents.
+
+Given that the exact media type is not known
+for this case, a Preferred Media Type binds to
+_javax.activation.DataHandler_ . _DataHandler_ has a property
+_get/setContentType_ that should be kept synchronized with the value of
+the JAXB binding for the _xmime:contentType_ attribute.
+
+=== [[a5147]]Binding WS-I Attachment Profile _ref:swaRef_
+
+An XML element or attribute with a type
+definition of _ref:swaRef_ is bound to a JAXB property with base type of
+_javax.activation.DataHandler_ and annotated with _@XmlAttachmentRef_ .
+
+=== [[a5149]]javax.xml.bind.attachments
+
+The abstract classes _AttachmentUnmarshaller_
+and _AttachmentMarshaller_ in package _javax.xml.bind.attachments_ are
+intended to be implemented by a MIME-based package processor, such as
+JAX-WS 2.0 implementation, and are called during JAXB unmarshal/marshal.
+The JAXB unmarshal/marshal processes the root part of a MIME-based
+package, delegating knowledge of the overall package and its other parts
+to the _Attachment*_ class implementations.
+
+=== AttachmentUnmarshaller
+
+An implementation of this abstract class by a
+MIME-based package processor provides access to package-level
+information that is outside the scope of the JAXB unmarshal process. A
+MIME-based package processor registers its processing context with a
+JAXB 2.0 processor using the method
+_setAttachmentUnmarshaller(AttachmentUnmarshaller)_ of
+_javax.xml.bind.Unmarshaller_ .
+
+Interactions between the Unmarshaller and the
+abstract class are summarized below. The javadoc specifies the details.
+
+public abstract class AttachmentUnmarshaller
+\{ +
+public boolean isXOPPackage(); +
+public abstract DataHandler getAttachmentAsDataHandler(String cid); +
+public abstract byte[] getAttachmentAsByteArray(String cid); +
+}
+
+The JAXB unmarshal process communicates with
+a MIME-based package processor via an instance of AttachmentUnmarshaller
+registered with the unmarshaller. link:jaxb.html#a5165[See JAXB
+marshal/unmarshalling of optimized binary content.] summarizes this
+processing.
+
+* MTOM/XOP processing during unmarshal: +
+When _isXOPPackage()_ returns true, the unmarshaller replaces each XOP
+include element it encounters with MIME content returned by the
+appropriate _getAttachment*()_ method.
+* WS-I AP processing: +
+Each element or attribute of type definition _ref:swaRef_ , a content-id
+uri reference to binary data, is resolved by the unmarshal process by a
+call to the appropriate _getAttachment*()_ method.
+
+=== AttachmentMarshaller
+
+An _AttachmentMarshaller_ instance is
+registered with a _javax.xml.bind.Marshaller_ instance using the method
+_Marshaller.setAttachmentMarshaller()_ .
+
+Interactions between the Marshaller and the
+abstract class is summarized below. See the javadoc for details.
+
+public abstract class AttachmentMarshaller
+\{ +
+public boolean isXOPPackage(); +
+public abstract String +
+addMtomAttachment(DataHandler data, +
+String elementNamespace, +
+String elementLocalName); +
+public abstract String +
+addMtomAttachment(byte[] data, +
+String elementNamespace, +
+String elementLocalName); +
+public abstract String addSwaRefAttachment(DataHandler data); +
+}
+
+When an AttachmentMarshaller instance is
+registered with the Marshaller, the following processing takes place.
+
+* MTOM/XOP processing: +
+When _isXOPPackage_ () is true and a JAXB property representing binary
+data is being marshalled, the method _addMtomAttachment_ (...) is called
+to provide the MIME-based package processor the opportunity to decide to
+optimize or inline the binary data. +
+ +
+Note that the schema customization specified in
+link:jaxb.html#a2193[See <inlineBinaryData> Declaration]“can be
+used to declaratively disable XOP processing for binary data.
+* WS-I AP processing: +
+The _addSwaRefAttachment_ method is called when marshalling content
+represented by a _ref:swaRef_ type definition. +
+ +
+One can declaratively customize swaRef processing within a schema using
+schema customization @attachmentRef of <jaxb:property>, specified in
+link:jaxb.html#a1786[See Usage]“.
+
+=== [[a5165]]JAXB marshal/unmarshalling of optimized binary content.
+
+image:xmlb-23.png[image]
+
+=== Appendix
+
+Change Log
+
+=== 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 link:jaxb.html#a3815[See
+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 link:jaxb.html#a1459[See
+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
+link:jaxb.html#a397[See Marshalling]” for details.
+* Prepend “_”, not “Original”, to a Java
+class name representing an XML Schema type definition that has been
+redefined in link:jaxb.html#a1316[See 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 javax.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 javax.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 javax.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
+javax.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 link:jaxb.html#a2[See
+Introduction]”.
+* Added link:jaxb.html#a151[See
+Requirements]”
+* Added link:jaxb.html#a2236[See 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 link:jaxb.html#a680[See Java Element
+Representation Summary]”, link:jaxb.html#a1023[See Element
+Declaration]” and link:jaxb.html#a630[See Element Property]”.
+* Added link:jaxb.html#a1306[See
+Attribute Wildcard]” binding
+* Support binding all wildcard content in
+link:jaxb.html#a1384[See Bind wildcard schema component]”.
+* Addition/changes in
+link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
+Types].
+* XML Schema to Java Customization
+* Added ability to doable databinding for an
+XML Schema fragment in link:jaxb.html#a2165[See <dom>
+Declaration]”.
+
+=== Changes for 1.0 Final
+
+* Added method
+_javax.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 link:jaxb.html#a3815[See
+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.
+* link:jaxb.html#a595[See List
+Property] and link:jaxb.html#a610[See 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
+link:jaxb.html#a996[See 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 link:jaxb.html#a1384[See
+Bind wildcard schema component],” to bind to a JAXB property with a
+basetype of _java.lang.Object,_ not _javax.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 link:jaxb.html#a1012[See
+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 link:jaxb.html#a1580[See
+<globalBindings> Declaration]”:
+* Replaced _modelGroupAsClass_ with
+_bindingStyle_ .
+* Specified schema types that cannot be
+listed in _typesafeEnumBase_ .
+* link:jaxb.html#a1783[See <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.
+* link:jaxb.html#a1981[See <javaType>
+Declaration]”:
+* Added
+_javax.xml.bind.DatatypeConverterInterface_ interface.
+* Added _javax.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 link:jaxb.html#a1498[See
+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
+
+* link:jaxb.html#a1442[See 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.
+* link:jaxb.html#a572[See Indexed
+Property], added getIDLenth() to indexed property.
+* Removed ObjectFactory.setImplementation
+method from link:jaxb.html#a482[See 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.
+
+'''''
+
+[.footnoteNumber]# 1.# [[a5352]]In the interest of
+terseness, JAXB 2.0 program annotations have been ommitted.
+
+[.footnoteNumber]# 2.# [[a5353]]Appropriate
+customization required to bind a fixed attribute to a constant value.
+
+[.footnoteNumber]# 3.# [[a5354]]Type constraint
+checking only performed if customization enables it and implementation
+supports fail-fast checking
+
+[.footnoteNumber]# 4.# [[a5355]]JAXB 1.0 deprecated
+class, _javax.xml.bind.Validator_ , is described in
+link:jaxb.html#a5096[See Validator for JAXB 1.0 schema-derived
+classes]”.
+
+[.footnoteNumber]# 5.# [[a5356]]Section 7.4.1.1
+“Package Annotations” in [JLS] recommends that file-system-based
+implementations have the annotated package declaration in a file called
+_package-info.java_ .
+
+[.footnoteNumber]# 6.# [[a5357]]Program annotations
+@XmlRootElement and @XmlType are specified in Section 8.0.
+
+[.footnoteNumber]# 7.# [[a5358]]Note that it is
+optional for a JAXB implementation to support type constraint checks
+when setting a property in this version of the specification.
+
+[.footnoteNumber]# 8.# [[a5359]]An unmarshalling
+implementation should distinguish between a value from an XML instance
+document and a schema specified defaulted value when possible. A
+property should only be considered to have a set value when there exists
+a corresponding value in the XML content being unmarshalled.
+Unfortunately, unmarshalling implementation paths do exist that can not
+identify schema specified default values, this situation is considered a
+one-time transformation for the property and the defaulted value will be
+treated as a set value.
+
+[.footnoteNumber]# 9.# [[a5360]]Namely, a _boolean_
+field type defaults to _false_ , _integer_ field type defaults to _0_ ,
+object reference field type defaults to _null_ , floating point field
+type defaults to _+0.0f_ .
+
+[.footnoteNumber]# 10.# [[a5361]]Note that it is
+optional for a JAXB implementation to support type constraint checks
+when setting a property in this version of the specification.
+
+[.footnoteNumber]# 11.# [[a5362]]Note that it is
+optional for a JAXB implementation to support type constraint checks
+when setting a property in this version of the specification.
+
+[.footnoteNumber]# 12.# [[a5363]]A Java application
+usually does not need to distinguish between the absence of a element
+from the infoset and when the element occurred with nil content. Thus,
+in the interest of simplifying the generated API, methods were not
+provided to distinguish between the two. Two annotation elements
+@XmlElement.required and @XmlElement.nillable allow a null value to be
+marshalled as an empty or nillable element.
+
+[.footnoteNumber]# 13.# [[a5364]]The exception case is
+that an element declaration with an anonymous type definition is bound
+to a schema-derived value class by default as described in
+link:jaxb.html#a1084[See Binding of an anonymous complex type
+definition]”.
+
+[.footnoteNumber]# 14.#
+link:jaxb.html#a1369[See Bind mixed
+content] describes why <ASimpleElement> element is bound to a Java
+Element representation.
+
+[.footnoteNumber]# 15.# [[a5366]]Assume a
+customization that binds this local element declaration to an element
+class. By default, this local declaration binds to a element instance
+factory returning JAXBElement<Integer>
+
+[.footnoteNumber]# 16.# [[a5367]]See next figure for
+default binding for anonymous type definition.
+
+[.footnoteNumber]# 17.# [[a5368]]enable type
+substitution for element of xsd:anySimpleType
+
+[.footnoteNumber]# 18.# [[a5369]]Exception cases that
+do not bind to enum type: when the base type is or derives from _xs:ID_
+and _xs:IDREF_ . Rationale for not binding these type definitions to an
+enum type is in link:jaxb.html#a2126[See Customizable Schema
+Elements]“.
+
+[.footnoteNumber]# 19.# [[a5370]]Note for this case,
+the _enumConstantValueType_ is always _java.lang.String_ .
+
+[.footnoteNumber]# 20.#
+link:jaxb.html#a1582[See Usage]”
+describes the _enableFailFastCheck_ customization and
+_link:jaxb.html#a256[See Validation]_ ” defines fail-fast
+checking.
+
+[.footnoteNumber]# 21.# [[a5372]]Note that
+link:jaxb.html#a1084[See Binding of an anonymous complex type
+definition]” defines the name and package property for anonymous type
+definitions occurring within an element declaration.
+
+[.footnoteNumber]# 22.# [[a5373]]Element substitution
+extensibility does allow element substitution(s) to be defined in a
+separate schema than a global element reference occurs. When schemas are
+not compiled at same time, the schema to java binding declaration,
+<jaxb:property generateElementProperty=”true”/> described in
+link:jaxb.html#a1786[See Usage] forces the generation of an
+element property for a global element reference, independent of it not
+belonging to a element substitution group.
+
+[.footnoteNumber]# 23.# [[a5374]]The desire to reduce
+the overall number of schema-derived classes generated by default
+influenced the decision to default to binding an element declaration to
+an element instance factory. A customization described in
+link:jaxb.html#a1580[See <globalBindings> Declaration] exists
+that binds each element declaration to a Java element class so element
+substitution checking can be enforced entirely by strongly typed method
+signatures.
+
+[.footnoteNumber]# 24.# [[a5375]]Specifying a
+customization of the local element declaration A within Derived complex
+type to a different property name than A would avoid the fallback
+position for this case.
+
+[.footnoteNumber]# 25.# [[a5376]]Note that primitive
+Java types must be represented by their Java wrapper classes when base
+type is used in the choice content property method signatures. Also, all
+sequence descendants of the choice are treated as either a general
+content property or are mapped to their own value class.
+
+[.footnoteNumber]# 26.# [[a5377]]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.
+
+[.footnoteNumber]# 27.# [[a5378]]There is no need to
+standardize the name of the generated class since
+_@XmlJavaTypeAdapter.value()_ references the class.
+
+[.footnoteNumber]# 28.# [[a5379]]There is no need to
+standardize the name of the generated class since
+_@XmlJavaTypeAdapter.value()_ references the class.
+
+[.footnoteNumber]# 29.# [[a5380]]Exception case:
+Underscore is not considered a punctuation mark for schema customization
+_<jaxb:globalBindings underscoreHandling="asCharInWord"/>_ specified in
+link:jaxb.html#a1613[See Underscore Handling]". For this
+customization, underscore is considered a special letter that never
+results in a word break as defined in link:jaxb.html#a4681[See
+XML Word Breaks] and it is definitely not considered an uncased letter.
+See example bindings in link:jaxb.html#a4755[See XML Names and
+derived Java Class, Method, and Constant Names when <jaxb:globalBindings
+underscoreHandling=”asCharInWord”>].
+
+[.footnoteNumber]# 30.# [[a5381]]Sample URN
+"urn:hl7-org:v3" \{"h17-org", "v3") transforms to \{"h17.org", "v3"}.
diff --git a/spec/src/main/asciidoc/images/xmlb-10.png b/spec/src/main/asciidoc/images/xmlb-10.png
new file mode 100644
index 0000000..1319344
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-10.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-11.png b/spec/src/main/asciidoc/images/xmlb-11.png
new file mode 100644
index 0000000..778f540
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-11.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-12.png b/spec/src/main/asciidoc/images/xmlb-12.png
new file mode 100644
index 0000000..584bfe2
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-12.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-13.png b/spec/src/main/asciidoc/images/xmlb-13.png
new file mode 100644
index 0000000..707c860
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-13.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-15.png b/spec/src/main/asciidoc/images/xmlb-15.png
new file mode 100644
index 0000000..896e80f
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-15.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-16.png b/spec/src/main/asciidoc/images/xmlb-16.png
new file mode 100644
index 0000000..90d3865
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-16.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-17.png b/spec/src/main/asciidoc/images/xmlb-17.png
new file mode 100644
index 0000000..875fda5
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-17.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-18.png b/spec/src/main/asciidoc/images/xmlb-18.png
new file mode 100644
index 0000000..658af48
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-18.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-2.png b/spec/src/main/asciidoc/images/xmlb-2.png
new file mode 100644
index 0000000..a6f45ad
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-2.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-23.png b/spec/src/main/asciidoc/images/xmlb-23.png
new file mode 100644
index 0000000..8be22ac
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-23.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-3.png b/spec/src/main/asciidoc/images/xmlb-3.png
new file mode 100644
index 0000000..a9121d9
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-3.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-4.png b/spec/src/main/asciidoc/images/xmlb-4.png
new file mode 100644
index 0000000..d20f1f7
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-4.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-8.png b/spec/src/main/asciidoc/images/xmlb-8.png
new file mode 100644
index 0000000..73c305d
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-8.png
Binary files differ
diff --git a/spec/src/main/asciidoc/images/xmlb-9.png b/spec/src/main/asciidoc/images/xmlb-9.png
new file mode 100644
index 0000000..d2eb8b3
--- /dev/null
+++ b/spec/src/main/asciidoc/images/xmlb-9.png
Binary files differ
diff --git a/spec/src/main/asciidoc/xml-binding-spec.adoc b/spec/src/main/asciidoc/xml-binding-spec.adoc
index eb4f2f2..dfdc77b 100644
--- a/spec/src/main/asciidoc/xml-binding-spec.adoc
+++ b/spec/src/main/asciidoc/xml-binding-spec.adoc
@@ -26,3 +26,4 @@
// == Jakarta XML Binding
:sectnums:
include::xml-binding.adoc[]
+include::XMLBinding.adoc[]
diff --git a/spec/src/main/asciidoc/xml-binding.adoc b/spec/src/main/asciidoc/xml-binding.adoc
index 4ce9d55..62cee9c 100644
--- a/spec/src/main/asciidoc/xml-binding.adoc
+++ b/spec/src/main/asciidoc/xml-binding.adoc
@@ -1,7 +1,7 @@
//
// Copyright (c) 2017, 2020 Contributors to the Eclipse Foundation
//
-== Introduction
+== Scope
The Jakarta XML Binding provides an API and tools that automate the mapping
between XML documents and Java objects.
\ No newline at end of file
