Google Git
Sign in
third-party-mirror / jaxb-api / 700582cf61ce396647a4874f8f0b0b7acf710201 / . / spec / src / main / asciidoc / XMLBinding.adoc
blob: ad878b7d86308680ad98564f6fc93cfc21325259 [file] [log] [blame]
//
// 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 _jakarta.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 _jakarta.xml.bind_ .
The binding framework resides in two main
packages. The _jakarta.xml.bind_ package defines abstract classes and
interfaces that are used directly with content classes. The
_jakarta.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 _jakarta.xml.bind.helper_ package provides partial
default implementations for some of the _jakarta.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,
_jakarta.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 _jakarta.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
jakarta.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 _jakarta.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 _jakarta.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 _jakarta.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 jakarta.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.
=== jakarta.xml.bind.Binder
The class _jakarta.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 jakarta.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 _jakarta.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
_jakarta.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 \{
jakarta.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 _jakarta.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 +
jakarta.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 _jakarta.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
_jakarta.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 _jakarta.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 _jakarta.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,
_jakarta.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
|jakarta.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; +
import javax.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 jakarta.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 _jakarta.xml.bind.JAXBElement<T>_ or a JAXB class
annotated with _@XmlRootElement. +
_ Corresponds to a recognized global element tag name registered with
the instance _jakarta.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 _jakarta.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 |
_jakarta.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 _jakarta.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 jakarta.xml.bind.JAXBElement; +
public class ObjectFactory \{ +
// element instance factories only +
// JAXBElement<String> createBaseA(String value); //default code +
JAXBElement<String> createBaseBar(String value); //Customized +
JAXBElement<String> createBaseB(String value); +
JAXBElement<Integer> createBaseC(Integer value); +
} +
public class Base \{ +
static public class Bar extends JAXBElement<String> \{...}// Customized
code +
/** +
* A general content list that can contain element +
* instances of JAXBElement<String> or JAXBElement<Integer>. +
*/ +
List<Object> getBarOrBOrC()\{...} +
}
=== [[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
_jakarta.xml.bind.annotation.adapter.XmlAdapter_ . The generated class’
_unmarshal_ method must call the <javaType> customization’s parse
method, which is specified in link:jaxb.html#a1981[See
<javaType> Declaration]. The generated class’ _marshal_ method must call
the <javaType> customization’s print method.
=== [[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="jakarta.xml.bind.DatatypeConverter.parseInteger" +
printMethod="jakarta.xml.bind.DatatypeConverter.printInteger"/> +
</jaxb:baseType> +
</jaxb:property> +
</xs:appinfo></xs:annotation> +
</xs:attribute> +
</xs:complexType>
The code generated is:
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
_jakarta.xml.bind.DatatypeConverterInterface_ .
The _DatatypeConverter_ class defines a
static parse and print method corresponding to each parse and print
method respectively in the _DatatypeConverterInterface_ interface. The
property _jakarta.xml.bind.DatatypeConverter_ can be used to select the
name of a class that provides an implementation of the parse and print
methods. The name specified in the property must be a fully qualified
class name and must implement the interface _DatatypeConverterInterface_
. The class is fully specified by the Javadoc specified in
_jakarta.xml.bind.DatatypeConverter_ .
=== Usage
The following example demonstrates the use of
the _DatatypeConverter_ class for writing a customized parse and print
method.
=== [[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 jakarta.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
_jakarta.xml.bind.annotation.adapter.XmlAdapter_ . The generated class’
_unmarshal_ method must call the <javaType> customization’s parse
method, which is specified in link:jaxb.html#a1981[See
<javaType> Declaration]. The generated class’ _marshal_ method must call
the <javaType> customization’s print method.
=== _GlobalBindings_
A _<javaType>_ binding declaration is allowed
as part of _<globalBindings>._ The _javaType_ overrides the default
binding of _xmlType_ to the Java datatype specified in
link:jaxb.html#a725[See Java Mapping for XML Schema Built-in
Types]. The customization values defined have global scope.
For each element or attribute declaration
that references an _xmlType_ that has a globalBindings _<javaType>_
customization specified for it, the corresponding JAXB property is
annotated with _@XmlJavaTypeAdapter_ .
=== _<property><baseType>_ declaration
A _<javaType>_ binding declaration is allowed
as part of _<baseType>_ in the _<property>_ binding declaration. The
_javaType_ overrides the default binding of _xmlType_ to the Java
datatype specified in link:jaxb.html#a725[See Java Mapping for
XML Schema Built-in Types]. Additional semantics are specified in
link:jaxb.html#a1801[See baseType]” also
apply.
The schema-derived JAXB property is annotated
with _@XmlJavaTypeAdapter_ as specified in
link:jaxb.html#a1801[See baseType]”.
=== [[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 _&lt;_ to escape embedded HTML tags.
<javadoc>
Contents in &lt;b>Javadoc&lt;\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
_jakarta.xml.bind.annotation_ and _jakarta.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 _@jakarta.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
_jakarta.xml.bind.annotation.JAXBContext.newInstance(..)_ method. Any
cycles resulting from a combination of annotations or default mapping
must be detected in
_jakarta.xml.bind.annotation.JAXBContext.newInstance(..)_ method and also
constitutes a constraint violation. A _jakarta.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
_jakarta.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;
@jakarta.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 _jakarta.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
_jakarta.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
_jakarta.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 _jakarta.xml.bind.JAXBElement_ ,
then the _@XmlElementRef.name()_
\{target namespace}
if _@XmlElementRef.type()_ is
_@XmlElementRef.DEFAULT.class_ and the property type is not
_jakarta.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 _jakarta.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
_jakarta.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
_jakarta.xml.bind.annotation.adapters.XmlAdapter_ and
_jakarta.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( +
jakarta.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER)_
* _@XmlAccessorOrder( +
jakarta.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
_jakarta.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
_jakarta.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
_jakarta.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
_jakarta.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER,_ then
* all properties and public fields, unless
annotated with _@XmlTransient_ , must be mapped.
See javadoc for
_@jakarta.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 _jakarta.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 _jakarta.xml.bind_ . The required processing model for a JAXB 1.0
schema compiler generated package is specified in
_jakarta.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 jakarta.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:
_jakarta.xml.bind.Unmarshaller.unmarshal_
(...) +
_jakarta.xml.bind.Binder.unmarshal_ (...) +
. Unmarshal methods that take a declaredType
as a parameter:
_jakarta.xml.bind.Unmarshaller.unmarshal_
(..., _java.lang.Class<T> declaredType_ ) +
_jakarta.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 _jakarta.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 _jakarta.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
_jakarta.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
jakarta.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 jakarta.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
jakarta.xml.bind.JAXBElement instance if:
. the property is not a collection type and
its type is jakarta.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 jakarta.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 jakarta.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
_jakarta.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
_jakarta.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 jakarta.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
jakarta.xml.bind.DatatypeConverter interface:
Many of the types have a corresponding print
and parse method in jakarta.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
jakarta.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]]jakarta.xml.bind.attachments
The abstract classes _AttachmentUnmarshaller_
and _AttachmentMarshaller_ in package _jakarta.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
_jakarta.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 _jakarta.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 jakarta.xml.bind.Binder class to
Section 4.8.2.
* Runtime generation of schema from JAXB
mapping annotations: JAXBContext.generateSchema().
* Chapter 8: added @XmlList: bind
property/field to simple list type
* Chapter 8: added @XmlAnyElement: bind
property/field to xs:any
* Chapter 8: added @XmlAnyAttribute - bind
property/field to xs:anyAttribute
* Chapter 8. added @XmlMixed - for mixed
content
* Chapter 8, added annotations for
attachment/MTOM support: @XmlMimeType, @XmlAttachmentRef
* Chapter 8: added @XmlAccessorOrder - to
specify default ordering.
* Chapter 8: added @XmlSchemaType mainly for
use in mapping XMLGregorianCalendar.
* Chapter 8: map java.lang.Object to
xs:anyType
* Chapter 8: added mapping of
XMLGregorianCalendar
* Chapter 8: added mapping of generics - type
variables, wildcardType
* Chapter 8: added mapping of binary data
types.
* Chapter 8: default mappings changed for
class, enum type.
* Chapter 8: default mapping of propOrder
specified.
* Chapter 8: mapping of classes - zero arg
constructor, factory method.
* Chapter 8: added Runtime schema generation
requirement.
* Chapter 8: Clarified mapping constraints
and other bug fixes.
* Added Appendix B new: Added Runtime
Processing Model to specify the marshalling/unmarshalling for dealing
with invalid XML content and schema evolution.
* Updated Appendix C to JAXB 2.0 binding
schema.
=== Changes since Early Draft
* Updated goals in Introduction.
* Update to Section 3 “Architecture”
introducing Java to Schema binding.
* section on portable annotation-driven
architecture.
* section on handling of invalid XML content
* Binding Framework
* Replaced _IXmlElement<T>_ interface with
_JAXBElement<T>_ class. (JAXBElement is used for schema to java binding)
* _JAXBIntrospector_ introduced _._
* Add flexible (by-name) unmarshal and
describe JAXB 1.0 structural unmarshalling.
* Moved deprecated on-demand validation,
accessible via jakarta.xml.bind.Validator, to Appendix H.
* XSD to Java Binding
* Bind complex type definition to value class
by default.
* Schema-derived code is annotated with JAXB
java annotations.
* Bind XSD simpleType with enum facet to J2SE
5.0 enum type. Change default for jaxb:globalBinding @typeEnumBase from
xs:NCName to xs:string.
* _ObjectFactory_ factory methods no longer
throws _JAXBException_ .
* Added customizations +
[jaxb:globalBindings] @generateValueClass, @generateElementClass,
@serializable, @optionalProperty, @nullInCollection +
[jaxb:property] @generateElementProperty
* Add binding support for redefine
* Simplified following bindings: +
- union by binding to String rather than Object. +
- Attribute Wildcard binds to portable abstraction of a
java.util.Map<QName, String>, not jakarta.xml.bind.AttributeMap. +
- bind xsd:anyType to java.lang.Object in JAXB property method
signatures and element factory method(support element/type substitution)
* Changes required for default and customized
binding in order to support flexible unmarshalling described in Section
4.4.3.
* Java to XSD Binding
* Added @XmlAccessorType for controlling
whether fields or properties are mapped by default.
* Added @XmlEnum and @XmlEnumValue for
mapping of enum types.
* Collections has been redesigned to allow
them to be used in annotation of schema derived code:
- removed @XmlCollectionItem and
@XmlCollection
- Added annotations parameters to @XmlElement
- added @XmlElementRef
- added @XmlElements and @XmlElementRefs as
containers for collections of @XmlElements or @XmlElementRefs.
- added @XmlElementWrapper for wrapping of
collections.
* Added mapping of anonymous types.
* Added mapping of nested classes to schema
* Added @XmlRootElement for annotating
classes. @XmlElement can now only be used to annotate properties/fields.
* Added @XmlElementRef for supporting schema
derived code as well as mapping of existing object model to XML
representation. javadoc for @XmlElementRef contains an example
* Added @XmlElementDecl on object factory
methods for supporting mapping of substitution groups for schema -> java
binding.
* Redesigned Adapter support for mapping of
non Java Beans.
- new package
jakarta.xml.bind.annotation.adapters for adapters.
- Added XmlAdapter base abstract class for
all adapters.
- redesigned and moved XmlJavaTypeAdapter to
the package.
* Moved default mapping from each section to
“Default Mapping” section.
* Consistent treatment of defaults
“##default”
* Removed JAX-RPC 1.1 Alignment. JAX-WS 2.0
is deferring its databinding to JAXB 2.0.
=== Changes for 2.0 +
Early Draft v0.4
* Updated 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
_jakarta.xml.bind.Marshaller.getNode(Object)_ which returns a DOM view of
the Java content tree. See method's javadoc for details.
=== Changes for Proposed Final
* Added 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 _jakarta.xml.bind.Element._ Strict and
lax wildcard validation processing allows for contents constrained only
by _xsi:type_ attribute. Current APIs should allow for future support of
_xsi:type_ .
* Simplify anonymous simple type definition
binding to typesafe enum class. Replace incomplete approach to derive a
name with the requirement that the @name attribute for element
typesafeEnumClass is mandatory when associated with an anonymous simple
type definition.
* Changed 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
_jakarta.xml.bind.DatatypeConverterInterface_ interface.
* Added _jakarta.xml.bind.DatatypeConverter_
class for use by user specified parse and print methods.
* Added
_javax.xml.namespace.NamespaceContext_ class for processing of QNames.
* Clarified print and parse method
requirements.
* Added narrowing and widening conversion
requirements.
* Throughout 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, _jakarta.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"}.