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
