Table of Contents
Table of Contents
The Java™ Architecture for XML Binding (JAXB) provides an API and tools that automate the mapping between XML documents and Java objects.
The JAXB framework enables developers to perform the following operations:
Unmarshal XML content into a Java representation
Access and update the Java representation
Marshal the Java representation of the XML content into XML content
JAXB gives Java developers an efficient and standard way of mapping between XML and Java code. Java developers using JAXB are more productive because they can write less code themselves and do not have to be experts in XML. JAXB makes it easier for developers to extend their applications with XML and Web Services technologies.
Documentation for this release consists of the following:
Running the binding compiler (XJC): [XJC, XJC Ant Task]
Running the schema generator (schemagen): [SchemaGen, SchemaGen Ant Task]
JAXB FAQs [Frequently Asked Questions, java.sun.com]
2013 Oracle Corporation and/or its affiliates. All rights reserved.
The JAXB RI ${release.impl.version}${release.impl.version.suffix} Release is covered by the dual license between Common Development and Distribution License (CDDL) and GNU Public License v2 + classpath exception
Additional copyright notices and license terms applicable to portions of the software are set forth in the 3rd Party License README
This page summarizes basic use-cases for Java-2-Schema, Schema-2-Java, and lists all of the sample applications that ship with JAXB.
Schema-2-Java is the process of compiling one or more schema files into generated Java classes. Here are some of the basic steps for developing an app:
Develop/locate your schema
Annotate the schema with binding customizations if necessary (or place them in an external bindings file)
Compile the schema with the XJC binding compiler
Develop your JAXB client application using the Java
content classes generated by the XJC binding compiler
along with the javax.xml.bind
runtime
framework
Set your CLASSPATH
to include all
of the Identifying the JAR Files
Compile all of your Java sources with
javac
Run it!
Java-2-Schema is the process of augmenting existing Java
classes with the annotations defined in the
javax.xml.bind.annotation
package so that the JAXB
runtime binding framework is capable of performing the (un)marshal
operations. Here are the basic steps for developing an app:
Develop your data model in Java
Apply the javax.xml.bind.annotation
annotations to control the binding process
Set your CLASSPATH
to include all
of the Identifying the JAR Files
Compile your data model with
javac
Make sure that you CLASSPATH
includes jaxb-xjc.jar
before
running javac.
The resulting class files will contain your annotations as well other default annotations needed by the JAXB runtime binding framework
Develop your client application that uses the data model and develop the code that uses the JAXB runtime binding framework to persist your data model using the (un)marshal operations.
Compile and run your client application!
For more information about this process, see the the Java WSDP Tutorial and the extensive Sample Apps documentation.
To run the sample applications, just go into each sample directory, and run ant without any option.
A few sample applications do not use
Ant. For those samples, refer to the included
readme.txt
files for instructions.
samples/catalog-resolver
This example demonstrates how to use the
-catalog
compiler switch to handle
references to schemas in external web sites.
samples/character-escape
This example shows how you can use the new JAXB
RI Marshaller
property
com.sun.xml.bind.characterEscapeHandler
to change the default character escaping
behavior.
samples/class-resolver
This little DI-container-by-JAXB example demonstrates how one can avoid passing in a list of classes upfront, and instead load classes lazily.
samples/create-marshal
This sample application demonstrates how to use
the ObjectFactory
class to create a
Java content tree from scratch and marshal it to XML
data. It also demonstrates how to add content to a
JAXB List property.
samples/cycle-recovery
JAXB RI's vendor extension
CycleRecoverable
provides
application a hook to handle cycles in the object
graph. Advanced.
samples/datatypeconverter
This sample application is very similar to the
inline-customize sample application (formerly
SampleApp6), but
illustrates an easier, but not as robust,
<jaxb:javaType>
customization.
samples/dtd
This sample application illustrate some of the DTD support available in the JAXB RI's extension mode. Please refer to the JAXB RI Extensions page for more detail.
samples/element-substitution
This sample application illustrates how W3C XML Schema substitution groups are supported in JAXB RI's extension mode. Please refer to the JAXB RI Extensions page for more detail.
samples/external-customize
This sample application is identical to the datatypeconverter sample application (formerly SampleApp7) except that the binding customizations are contained in an external binding file.
samples/fix-collides
Another binding customization example that
illustrates how to resolve name conflicts. Running
this sample without the binding file will result in
name collisions (see readme.txt
)
. Running ant will use the
binding customizations to resolve the name conflicts
while compiling the schema.
samples/inline-customize
This sample application demonstrates how to customize the default binding produced by the XJC binding compiler.
samples/j2s-crete-marshal
This sample application demonstrates marshalling, unmarshalling and unmarshal validation with existing Java classes annotated with JAXB annotations.
samples/j2s-xmlAccessorOrder
This sample application demonstrates the use of
mapping annotations
@XmlAccessorOrder
and
@XmlType.propOrder
in Java classes
for ordering properties and fields in Java to schema
bindings.
samples/j2s-xmlAdapter
This sample application demonstrates the use of
interface XmlAdapter
and annotation
XmlJavaTypeAdapter
for custom
marshaling/unmarshaling XML content into/out of a Java
type.
samples/j2s-xmlAttribute
This sample application demonstrates the use of
annotation @XmlAttribute
for
defining Java properties and fields as XML
attributes.
samples/j2s-xmlRootElement
This sample application demonstrates the use of
annotation @XmlRootElement
to
define a class to be an XML element.
samples/j2s-xmlSchematType
This sample application demonstrates the use of
annotation @XmlSchemaType
to
customize the mapping of a property or field to an XML
built-in type.
samples/j2s-xmlType
This sample application demonstrates the use of
mapping annotations
@XmlAccessorOrder
and
@XmlType.propOrder
in Java classes
for ordering properties and fields in Java to schema
bindings.
samples/locator-support
This sample shows how to use the new
non-standard locator support. By following the
instructions in the readme.txt file, you can cause all
of the generated impl classes to implement a new
interface that provides more information about error
locations. When a ValidationEvent
happens on your content tree, simply retrieve the
object and cast it down to
com.sun.xml.bind.extra.Locatable
.
samples/modify-marshal
This sample application demonstrates how to modify a java content tree and marshal it back to XML data.
samples/namespace-prefix
This sample application demonstrates how to use
the new JAXB RI Marshaller property
com.sun.xml.bind.namespacePrefixMapper
to customize the namespace prefixes generated during
marshalling.
samples/partial-unmarshalling
In this example, the input document will be unmarshalled a small chunk at a time, instead of unmarshalling the whole document at once.
samples/pull-parser
This sample app demonstrates how a pull-parser can be used with JAXB to increase the flexibility of processing.
samples/streaming-unmarshalling
This example illustrates a different approach to the streaming unmarshalling, which is suitable for processing a large document.
samples/synchronized-methods
This sample shows how to use the new
non-standard synchronized method support. By following
the instructions in the
readme.txt
, you can cause all of
the generated impl class methods signatures to contain
the synchronized
keyword.
samples/type-substitution
This sample app demonstrates type substitution using the W3C XML Schema Part 0: Primer international purchase order schema.
samples/ubl
This project processes a UBL (Universal Business Language) order instance and prints a report to the screen.
samples/unmarshal-read
This sample application demonstrates how to unmarshal an instance document into a Java content tree and access data contained within it.
samples/unmarshal-validate
This sample application demonstrates how to enable validation during the unmarshal operations.
samples/updateablePartialBind
This sample application demonstrates how to partially map a DOM tree to JAXB (using JAXP 1.3 XPath), modify JAXB mapped instance and then update modifications back to the DOM tree.
samples/vendor-extensions
This example demonstrates how to use
<xjc:superClass>
vendor
extensions provided by Sun's JAXB RI, as well as
<jaxb:serializable>
customization.
samples/xml-channel
This example demonstrates how one can use one communication channel (such as a socket) to send multiple XML messages, and how it can be combined with JAXB.
samples/xml-stylesheet
A common customization need for the marshalling
output is about introducing extra processing
instruction and/or DOCTYPE
declaration. This example demonstrates how such
modification can be done easily.
Table of Contents
This document contains information that should help you use this software library more effectively. See the Frequently Asked Questions for additional information.
The most up-to-date version of this document can be foundon-line.
This release of the JAXB Reference Implementation requires Java SE 7 or higher.
Use |
Description |
Jars |
---|---|---|
Runtime | Jars required to deploy a JAXB 2.x client |
|
Compiler |
Jars required at your development environment (but not runtime) |
|
You may find information about the normative binding schema defined in the JAXB Specification athttp://java.sun.com/xml/ns/jaxb.
The JAXB 2.x RI is a major reimplementation to meet the requirements of the 2.x specifications.
Please refer to the jaxb-1-0-x-changelog for older releases.
JAXB RI is now JPMS modularized:
All modules have native module descriptor.
Removed jaxb-core module, which caused split package issue on JPMS.
RI binary bundle now has single jar per dependency instead of shaded fat jars.
Removed runtime class weaving optimization.
Removed legacy technology dependencies:
com.sun.xml.bind:jaxb1-impl
net.java.dev.msv:msv-core
net.java.dev.msv:xsdlib
com.sun.xml.bind.jaxb:isorelax
Adopt Java SE 9:
JAXB api can now be loaded as a module.
JAXB RI is able to run on Java SE 9 from the classpath.
Addes support for java.util.ServiceLoader mechanism.
Security fixes
Bug fixes:
Fixed split Message bundles between modules
Changed Codemodel to allow correct functioning of BeanValidation Plugin for XJC
Security fixes
Fixed '-disableXmlSecurity'
flag usage
Fixed redundant namespace prefixes
Fixed mixed content for StAX
Now we generate OSGI manifests for jaxb-core, jaxb-impl, jaxb-xjc anc jaxb-jxc
Marked com.sun.org.apache.xml.internal.resolver
and com.sun.org.apache.xml.internal.resolver.tools
as optional. They are part of JDK.
JAXB-973: generated code should be
compilable with '-Xdoclint:all'
JAXB-598: XJC generates ordered
ObjectFactories, @XmlSeeAlso
annotations and episode files.
Bug fixes:
Fixed for preserving whitespaces within xsd:any mixed element
Security fixes
Fixed circular dependency between SAAJ and JAXB; stax-ex changed not to use SAAJ-API
Fixed catalog logging. Allow user to disable usage of system proxies. Force CatalogResolver to set verbosity level.
Fixed stream handling
Fixed EnvelopeFactory
Bug fixes:
Security fixes.
Fixed wrong ref element generation
Fixed OSGi bug: NoClassDefFoundError javax/xml/soap/soapelement
This release is integrated into JDK 8. (Build 2.2.8-b130911.1802
)
JAXB RI project is now mavenized. New maven groupId introduced: org.glassfish.jaxb So if you are use maven you can simply add dependency block:
<dependency> <groupId>org.glassfish.jaxb</groupId> <artifactId>jaxb-bom</artifactId> <version>2.2.8</version> <type>pom</type> </dependency>
From now JAXB RI project uses GIT VCS. You can get our sources from:
GitHub: git clone https://github.com/javaee/jaxb-v2.git
Bug fixes:
Integrated new osgi-fied api
Fixed the bug with namespaces. Namespace must match in order to be able to generate ref otherwise the generated element ref belongs to different namespace. Ref generation is isolated only to cases where package mapping prevails
Updated access to JAX-WS
New JAXP version support added.
Fixed broken links in documentation
Fixed userguide
JXC findBugs fixes.
Added txw to jaxb source repo
Fixed bug when JAXB marshaller setting xsi:nil as true for non-nillable elements
Fixed event handling for missing xsi type
added errorCounter
added logging level check
Updated JAXB API with licence/fbugs fixes, and osgi fix
JAX_WS-1114: Fixed marshalling of gMonth type.
To enable old behavior use switch: jaxb.ri.useOldGmonthMapping
JAXB-937: Fixed Coordinator ThreadLocal
Fixed invalid absolute URL
Removed the need for synchronization - tailor can still happen multiple times under specific circumstances, but it's better than contention within multiple threads on one class
Fixed SimpleNameClass dependency
Fixed managing of nested collections.
Fixed maven configuration: made JDK deps required, map jaxb-extra-osgi exports by version, removed
dep on com.sun.nio
Codemodel
is imported into JAXB project tree
Security fixes
Added JAXB OSGi test.
JAXB 1.0 runtime is restored. It's bundled into the jaxb-extra-osgi.jar
now. Required libraries are located in $JAXB_HOME/tools/jaxb1_libs
folder.
The processing of -source XJC option is removed. We use 2.0 version of the schema compiler. For generating 1.0.x code, please use an installation of the 1.0.x codebase.
resolver.jar
is not bundled by JAXB anymore. It's already part of JDK.
If you are using JDK which doesn't contain it - you have to download it manually
(e.g. from maven: com.sun.org.apache.xml.internal:resolver
).
JAXB project was split into several modules: core, impl, xjc and jxc. So now it is possible to use XJC
with other JAXB runtime implementation (e.g. EclipseLink MOXy). While using XJC be aware of having any runtime JAXB
implementation (respectively jaxb-impl.jar
) on classpath.
Bug fixes:
JAXB-452 - Embedded DOM Elements may lose locally defined namespace prefixes
JAXB-915 - Cannot generate java classes from xjc
JAXB-919 - xjc - proxy authentication fails
JAXB-922 - JAXB samples fail
JAXB-939 - '#' at the end of a namespace : different of behavior, sometimes a underscore is added, sometimes not.
JAXB-940 - wrong default value for "target" parameter for xjc ant task
JAXB-948
- JAXB differences in JDK 7 in
com/sun/xml/internal/bind/v2/runtime/reflect/Lister.java#Lister.CollectionLister.endPacking
Improvement:
JAXB-912 - XJC split
Project cleaning done:
JAXB 1.0 is not bundled anymore.
Libraries jaxb1-xjc.jar
, msv.jar
was removed.
Package com/sun/msv/datatype was extracted to
jaxb-extra-osgi.jar
Bug fixes:
Fixed version number in OSGi bundles
JAX_WS-1059 - wsimport Ant tasks causes NoClassDefFoundError
JAXB-415 - Marshaller.marshall throws NPE if an adapter adapts a non-null bound value to null.
JAXB-488 - compatibility issue with JAXB 2.0
JAXB-608 - javax.xml.bind.DatatypeConverter.parseBoolean incorrect
JAXB-616 - XMLCatalog not used from xjc/xjctask when strict validation is enabled
JAXB-617 - setting Marshaller CharacterEncodingHandler with utf-8 does not work
JAXB-790 - Whitespace processing for xs:anyURI type
JAXB-794
- Classes annotated with @XmlTransient
are still mapped to XML
JAXB-795 - Catalog passed to XJC is not used during the schema correctness check
JAXB-814
- Failing with 'no-arg default constructor' on @XmlTransient
JAXB-825 - Attribute with default generates different types for get and set methods
JAXB-831
- Memory leak in com.sun.xml.bind.v2.ClassFactory
JAXB-834 - Cannot use binding file on Windows
JAXB-836 - CLONE -Marshaller.marshall throws NPE if an adapter adapts a non-null bound value to null.
JAXB-837 - XJC generated code misses out some fields from XML
JAXB-843 - Marshaller holds reference after marshalling for the writer that was used to marshal into
JAXB-844 - Memory Leak in com.sun.xml.bind.v2.runtime.Coordinator
JAXB-847 - DataTypeConverterImpl patch causes corrupted stream generation in some cases
JAXB-849 - JAXB:Invalid boolean values added to lists as 'false'
JAXB-856 - xs:import namespace="http://www.w3.org/2005/05/xmlmime" is not generated
JAXB-858 - xjc generates no JAXBElement for nillable element with required attribute
JAXB-859 - Corrupt license file in the distribution
JAXB-860
- NullPointerException com.sun.xml.bind.v2.runtime.ClassBeanInfoImpl.checkOverrideProperties(ClassBeanInfoImpl.java
:205)
JAXB-867 - jax-ws / jax-b / glassfish 3.1.1 web services fail to send data from beans based on variable name.
JAXB-868 - Escape policy for quote (") is different when the serialization is performed to OutputStream or Writer
JAXB-869 - Multiple <any /> elements on a schema : second element is not loaded
JAXB-882
- Marshalling Objects extending JAXBElement
linked by
@XmlElementRef
JAXB-445 - Generated episode bindings should contain target package name
JAXB-499 - Umbrella issue for all XJC related encoding issues wrt xjc itself and maven plugins/ant tasks
JAXB-839 - More Schema Annotations/Documentation to Javadoc
JAXB-413
- Redundant cast to byte[]
in code generated by XJCTask
JAXB-416 - Ant XJC task problems with spaces in paths
JAXB-450 - Reusing unmarshaller results in an unexpected result
JAXB-549
- Unescaped javadoc in @XmlElements
JAXB-602 - Different unmarshalling behavior between primitive type and simpletype with enumeration under restriction
JAXB-618 - XJC generates certain code lines in a random order
JAXB-620
- Problems with abstract classes and @XMLValue
JAXB-652 - JAXB 2.2 API should be changed to work with old 2.1 jaxb implementation in JDK
JAXB-696 - Incorrect implementation/documentation of javax.xml.bind.annotation.adapters.NormalizedStringAdapter
JAXB-726 - Missing keyword 'throw'
JAXB-761 - DatatypeConverterInterface.printDate inconsistencies
JAXB-774 - Extra slash in XSD location prevents customization
JAXB-803 - 2.2.2 strips schemaLocation in binding files
JAXB-804 - JAXB 2.x : How to override an XmlElement annotation from parent class - Mission Impossible?
JAXB-813 - Preserving white-space in XML (xs:string enumeration value) does not work
JAXB-815 - Binding file cannot refer to schema file with space in file name.
JAXB-816 - Incorrect System property to define the provider factory class
JAXB-821 - Global customization are not applied to xjc when input document is WSDL
JAXB-824 - API files in javax.xml.bind need to be updated for references to JLS with editions/hyperlinks
JAXB-826 - JAXB fails to unmarshal attributes as properties on aix
JAXB-268 - Map handling broken
JAXB-470 - Potential changes to make JAXB work better with OSGi
JAXB-478 - jaxb2-sources : Allow compilation under Java 6
JAXB-633 - JDefinedClass getMods()
JAXB-768 - Mailing list consolidation suggestions
JAXB-784 - JAnnotationUse should provide getters for clazz and memberValues properties
JAXB-406 - Allow setting of access modifiers in JMods
JAXB-769 - Update to command-line help text
JAXB-772 - Updates to XJC.html page and -Xpropertyaccessors plugin
JAXB-783 - I18N: xjc generates localized strings of AM/PM so compilation fails
JAXB-826 - JAXB fails to unmarshal attributes as properties on AIX
JAXB-805 - SpecJ performance regression
6975714 - JAXB 2.2 throws IAE for invalid Boolean values
JAXB-620 - Problems with abstract classes (xsi type processing)
Regression in Jersey JSON mapping
This minor-minor release contains only changes relevant to GlassFish OSGi environment
Minor licencing and legal fixes. No changes to source code.
Fixed documentation that incorrectly showed that JAXB RI is CDDL only (it's actually CDDL/GPLv2+classpath dual license)
JavaSE 6 release is expected to include this version of the JAXB RI (certainly as of build 102.)
More bug fixes
The simpler and better binding mode is improved
JAXB unofficial user's guide is available now, though it's still a work in progress
Java to schema samples are added
Added <xjc:javaType> vendor customization
Added experimental <xjc:simple> vendor customization, which brings in a new simpler and better binding mode
The spec has renamed AccessType
toXmlAccessType
, and
@AccessorType
to@XmlAccessorType
.
Various error handling improvements
Experimental canonicaliztion support is added.
The '-b' option can now take a directory and recursively search for all "*.xjb" files.
Fixed various issues regarding using JAXB from codef inside a restricted security sandbox.
Added more pluggability points for plugins to customize the code generation behavior.
Some of the code is split into a separate istack-commons
project to promote more reuse among projects.
Made a few changes so that RetroTranslator can translate the JAXB RI (and its generated code) to run it on JDK 1.4 and earlier
Improved the quality of the generated code by removing unnecessary imports.
Other countless bug fixes
Map property can be now correctly bound to XML Schema
Default marshaller error handling behavior became draconian (previously errors were ignored.)
@link to a parameterized type is now correctly generated
started producing architecture document for those who want to build plugins or play with the RI internal.
XJC now uses the platform default proxy setting by default.
@XmlAccessorOrder
,
@XmlSchemaType
and
@XmlInlineBinaryData
are implemented
@XmlJavaTypeAdapter
on a class/package is implemented
Marshaller life-cycle events are implemented
Integration to FastInfoset is improved in terms of performance
XJC can generate @Generated
The unmarshaller is significantly rewritten for better performance
Added schemagen tool and its Ant task
Various improvements in error reporting during unmarshalling/marshalling
JAXB RI is now under CDDL
The default for @XmlAccessorType
was changed to PUBLIC_MEMBER
Optimized binary data handling enabled by callbacks in package javax.xml.bind.attachment. Standards supported include MTOM/XOP and WS-I AP 1.0 ref:swaRef.
Unmarshal/marshal support of element defaulting
Improved the quality of the generated Java code
Fixed bugs in default value handling
Runtime performance improvements, memory usage improvements
Added support for <xjc:superInterface> vendor extension
Migrated source code to http://jaxb2-sources.dev.java.net
Published NetBeans project file for JAXB RI
Added more support to the schema generator: anonymous complex types, attribute refs, ID/IDREF, etc
Implemented javax.xml.bind.Binder
support (not 100% done yet)
Implemented marshal-time validation
Improved xjc command line interface - better support for proxy options, more options for specifying schema files
Added schema-2-Java support for simple type substitution
Added support for the new
<jaxb:globalBindings localScoping="nested" | "toplevel">
customization which helps control deeply nested classes
Made the default ValidationEventHandler
more forgiving in 2.0 than it was in 1.0
(The class still behaves the same as it did when used by a 1.0 app)
Added wildcard support for DTD
Numerous other small changes and bugfixes....
Support for 100% W3C XML Schema (not all in EA, but planned for FCS)
Support for binding Java to XML
Addition of javax.xml.bind.annotation
package for controling the binding from Java to XML
Significant reduction in the number of generated schema-derived classes
Per complex type definition, generate one value class instead of an interface and implementation class.
Per global element declaration, generate a factory method instead of generating a schema-derived interface and implementation class.
Replaced the validation capabilities in 1.0 with JAXP 1.3 validation API's
Smaller runtime libraries
Numerous other changes...
Abstract
This document explains various interesting/complex/tricky aspects of JAXB, based on questions posted on the JAXB users forum and answers I provided. This is an ongoing work-in-progress. Any feedback appreciated.
Table of Contents
Because XML Schema is so complicated, and because there are a
lot of tools out there do not implement the spec correctly, it is
often the case that a schema you are trying to compile has some real
errors in it. When this is the case, you'll see XJC reporting somewhat
cryptic errors such as rcase-RecurseLax.2: There is not a
complete functional mapping between the particles.
The JAXB RI uses the schema correctness checker from the underlying JAXP implementation, which is the JAXP RI in a typical setup. The JAXP RI is one of the most conformant schema validators, and therefore most likely correct. So the first course of action usually is to fix problems in the schema.
However, in some situations, you might not have an authority to
make changes to the schema. If that is the case and you really need to
compile the schema, you can bypass the correctness check by using the
-nv
option in XJC. When you do this, keep in mind
that you are possibly feeding "garbage" in, so you may see XJC choke
with some random exception.
One of the typical errors you'll see when compiling a complex schema is:
Example 1. Multiple property definitions error
parsing a schema... [ERROR] Property "MiOrMoOrMn" is already defined. line 132 of file:/C:/kohsuke/Sun/JAXB/jaxb-unit/schemas/individual/MathML2/presentation/scripts.xsd [ERROR] The following location is relevant to the above error line 138 of file:/C:/kohsuke/Sun/JAXB/jaxb-unit/schemas/individual/MathML2/presentation/scripts.xsd
This is an actual example of the offending part of a schema,
taken from MathML. If you go to line 132 of
scripts.xsd
, you'll see that it has a somewhat
complicated content model definition:
Example 2. Multiple property definitions in MathML
<xs:group name="mmultiscripts.content"> <xs:sequence> <xs:group ref="Presentation-expr.class"/> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <!-- line 132 --> <xs:group ref="Presentation-expr-or-none.class"/> <xs:group ref="Presentation-expr-or-none.class"/> </xs:sequence> <xs:sequence minOccurs="0"> <xs:element ref="mprescripts"/> <xs:sequence maxOccurs="unbounded"> <!-- line 138 --> <xs:group ref="Presentation-expr-or-none.class"/> <xs:group ref="Presentation-expr-or-none.class"/> </xs:sequence> </xs:sequence> </xs:sequence> </xs:group>
This is a standard technique in designing a schema. When you
want to say "in this element, B
can occur arbitrary
times, but C
can occur only up to once", you write
this as B*,(C,B*)?
. This, however, confuses JAXB,
because it tries to bind the first B
to its own
property, then C
to its own property, then the
second B
to its own property, and so we end up
having a collision again.
In this particular case, B
isn't a single
element but it's a choice of large number of elements abstracted away
in <xs:group>
s, so they are hard to see. But
if you see the same content model referring to the same element/group
twice in a different place, you can suspect this.
In this case, you'd probably want the whole thing to map to a
single list so that you can retain the order those elements show up in
the document. You can do this by putting the same
<jaxb:property>
customization on the whole
"mmultiscripts.content
" model group, like this (or
you can do it externally with XPath):
Example 3. How to fix the problem?
<xs:groupname="mmultiscripts.content"> <xs:annotation> <xs:appinfo> <jaxb:propertyname="content"/> </xs:appinfo> </xs:annotation> <xs:sequence> <xs:groupref="Presentation-expr.class"/>
Another way to fix this problem is to use the simpler and better binding mode in XJC, which is a JAXB RI vendor extension.
When schemas contain similar looking element/type names, they
can result in "Two declarations cause a collision in the ObjectFactory
class" errors. To be more precise, for each of all types and many
elements (exactly what elements get a factory and what doesn't is bit
tricky to explain), XJC produces one method on the
ObjectFactory
class in the same package. The
ObjectFactory
class is created for each package that XJC
generates some files into. The name of the method is derived from XML
element/type names, and the error is reported if two elements/types
try to generate the same method name.
There are two approaches to fix this problem. If the collision
is coming from two different schemas with different target namespaces,
then you can easily avoid the collision by compiling them into
different Java packages. To do this, use <schemabindings>
customization on two schemas and specify the package name.
Another way to fix this problem is to use <factoryMethod>
customization on two conflicting elements/types to specify different
factory method names. This can be used in all cases, but if you have a
large number of conflicts, you'll have to specify this customization
one by one.
Notice that <class>
customization doesn't affect the ObjectFactory
method
name by itself.
External JAXB customizations are specified by using XPath (or using SCD.) This works by writing an XPath expression that matches a particular element in the schema document. For example, given the following schema and binding file:
Example 4. Schema and external binding file
test.xsd
.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexTypename="foo"/> </xs:schema>
test.xjb
.
<bindings version="2.0" xmlns="http://java.sun.com/xml/ns/jaxb" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <bindings schemaLocation="test.xsd"> <bindings node="//xs:complexType[@name='foo']"> <classname="Bar"/> </bindings> </bindings> </bindings>
will be interpreted as if the class customization is
attached to the complex type 'foo
'.
For this to work, the XPath expression needs to match one and only one element in the schema document. When the XPath expression is incorrect and it didn't match anything, you get this "XPath evaluation of ... results in empty target node" problem.
Common causes of this problem include typos, incorrect namespace URI declarations, and misunderstanding of XPath.
Sometimes a schema may refer to another schema document without indicating where the schema file can be found, like this:
In other cases, a schema may refer to another schema on the network, which often slows down your compilation process and makes it unreliable. Yet in some other cases, a schema may reference another schema in relative path, and that may not match your directory structure.
XJC bundles a catalog resolver so that you can work around these situations without changing the schema documents. The main idea behind the catalog is "redirection" --- when XJC is about to fetch resources, it will consult the catalog resolver to see if it can find the resource elsewhere (which is usually your local resources.)
The catalog resolver supports many different formats, but the
easiest one is a line based *.cat
format. Other than
comments and empty lines, the file mainly consists of two kinds of
declarations, SYSTEM
, and
PUBLIC
.
Example 6. sample-catalog.cat
-- sample catalog file. double hyphens are used to begin and end a comment section. -- SYSTEM "http://www.w3.org/2001/xml.xsd" "xml.xsd" PUBLIC "-//W3C//DTD XMLSCHEMA 200102//EN" "s4s/XMLSchema.dtd"
The SYSTEM entry has the format of "SYSTEM REFERENCE ACTUAL-LOCATION", which defines a simple redirection. Every time XJC loads any resource (be it schemas, DTDs, any entities referenced within), it will first resolve relative paths to absolute paths, then looks for a matching REFERENCE line. If it is found, the specified actual location is read instead. Otherwise XJC will attempt to resolve the absolutepath.
ACTUAL-LOCATION above accepts relative
paths, and those are resolved against the catalog file itself (so in
the above example, xml.xsd
is assumed to be in the same
directory with sample-catalog.cat
.
What you need to be careful is the fact that the REFERENCE portion must be absolute, and when XJC finds a reference in schema, it will first convert that to the absolute path before checking the catalog. So what this means is that if your schema is written like this:
Example 7. Schema reference by relative path
<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd" />
Then your catalog entry would have to look like this:
Example 8. xlink.cat
-- this doesn't work because xlink.xsd will be turned into absolute path -- SYSTEM "xlink.xsd" "http://www.w3.org/2001/xlink.xsd" -- this will work, assuming that the above schema is in /path/to/my/test.xsd -- SYSTEM "/path/to/my/xlink.xsd" "http://www.w3.org/2001/xlink.xsd"
Another kind of entry has the format of "PUBLIC PUBLICID ACTUAL-LOCATION" or "PUBLIC NAMESPACEURI ACTUAL-LOCATION".
The "PUBLICID
" version is used to resolve DTDs and entities in
DTDs. But this type of entry is also used to resolve <xs:import>
statements. XJC will match the value of the namespace attribute and
see if there's any matching entry. So given a schema like this:
Example 9. Schema import
<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd" /> <xs:import namespace="http://www.w3.org/1998/Math/MathML" />
The following catalog entries will match them.
Example 10. by-publicid.cat
PUBLIC "http://www.w3.org/1999/xlink" "http://www.w3.org/2001/xlink.xsd" PUBLIC "http://www.w3.org/1998/Math/MathML" "/path/to/my/mathml.xsd"
As you can see, XJC will check the PUBLIC entries regardless of
whether <xs:import>
has the schemaLocation attribute or not. As
with the case with the SYSTEM entry, the ACTUAL-LOCATION part can be
relative to the location of the catalog file.
Once you write a catalog file, you'd need to specify that when you invoke XJC.
To do this from the CLI, use the -catalog
option. See xjc
-help for more details.
Use the catalog attribute on the <xjc>
task.
See XJC
ant task documentation for more details.
For the Maven
plugin, use the <catalog>
element in the
configuration:
<plugin> <groupId>org.jvnet.jaxb2.maven2</groupId> <artifactId>maven-jaxb2-plugin</artifactId> <configuration> <!-- relative to the POM file --> <catalog>mycatalog.cat</catalog> </copnfiguration> </plugin>
If you are trying to write a catalog file and banging your head against a wall because it's not working, you should enable the verbose option of the catalog resolver. How you do this depends on what interface you use:
Specify export XJC_OPTS="-Dxml.catalog.verbosity=999" then run XJC.
Add -Dxml.catalog.verbosity=999
as a
command line option to Ant/Maven.
If you are otherwise invoking XJC programmatically, you can set the above system property before invoking XJC.
<xs:any />
XJC binds <xs:any />
in the following ways:
processContents="skip"
<xs:any />
with processContents=skip
means
any well-formed XML elements can be placed. Therefore, XJC binds this
to DOM Element
interface.
Example 11. Any/Skip schema
<xs:element name="person"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string" /> <xs:any processContents="skip" maxOccurs="unbounded" minOccurs="0" /> </xs:sequence> </xs:complexType> </xs:element>
Example 12. Any/Skip binding
import org.w3c.dom.Element; @XmlRootElement class Person { public String getName(); public void setName(String); @XmlAnyElement public List<Element> getAny(); }
processContents="strict"
<xs:any />
with processContents=strict
(or
<xs:any />
without any processContents attribute, since it
defaults to "strict") means any XML elements placed here must have
corresponding schema definitions. This mode is not what people
typically expect as "wildcard
", but this is the default. The following
shows this binding. (lax=true
is unintuitive, but it's
not an error in this document):
Example 13. Any/Strict schema
<xs:element name="person"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string" /> <xs:any maxOccurs="unbounded" minOccurs="0" /> </xs:sequence> </xs:complexType> </xs:element>
Example 14. Any/Strict binding
@XmlRootElement class Person { public String getName(); public void setName(String); @XmlAnyElement(lax=true) public List<Object> getAny(); }
JAXB binds any such element to an Object
, and
during unmarshalling, all elements encountered are unmarshalled into
corresponding JAXB objects (including JAXBElement
s if
necessary) and placed in this field. If it encounters elements that
cannot be unmarshalled, DOM elements are produced instead.
At runtime, you can place either DOM elements or some JAXB
objects that map to elements. A typical mistake is to put a
String
that contains XML fragment, but this won't work;
you'd have to first read that into a DOM.
processContents="lax"
<xs:any />
with processContents=lax
means any
XML elements can be placed here, but if their element names match
those defined in the schema, they have to be valid. XJC actually
handles this exactly like processContents='strict', since the strict
binding allows unknown elements anyway.
<xs:element />
to JAXBElementSometimes XJC binds an element declaration to
JAXBElement
. Sometimes XJC binds an element declaration to a
Java class. What makes this difference?
Over time schema authors have developed several techniques to modularize large schemas. Some of those techniques have some noteworthy interactions with XJC.
Chameleon schema" (read more, in particular this) is a technique used to define multiple almost-identical sets of definitions into multiple namespaces from a single schema document.
For example, with this technique, you can write just one "foo"
complex type and define it into namespace X and Y. In this case, one
tends to hope that XJC will only give you one Foo
class
for this, but unfortunately because it's actually defined in two
namespaces, JAXB needs two Java classes to distinguish X:foo
and
Y:foo
, so you'll get multiple copies.
If you find this to be problematic, there are a few ways to work around the problem.
If you are in control of the schema, see if you can rewrite the schema to avoid using this technique. In some cases, the schema doesn't actually exploit the additional power of this technique, so this translation can be done without affecting XML instance documents. In some other cases, the chameleon schema can be argued as a bad schema design, as it duplicates definitions in many places.
If you are not in control of the schema, see if you can rewrite the schema nevertheless. This will only work if your transformation doesn't affect XML instance documents.
Perhaps there can be a plugin that eases the pain of this, such as by defining common interfaces among copies.
Adding behaviors to the generated code is one area that still needs improvement. Your feedback is appreciated.
Suppose if JAXB generated the following classes.
Example 15. Simple JAXB Generated Code
package org.acme.foo; @XmlRootElement class Person { private String name; public String getName() { return name; } public void setName(String) { this.name=name; } } @XmlRegistry class ObjectFactory { Person createPerson() { ... } }
To add a behavior, first write a class that extends from
Person
. You also need to extend ObjectFactory to return this
new class. Notice that neither classes have any JAXB annotation, and I put
them in a separate package. This is because we'd like
PersonEx
class to be used in place of Person
,
and we don't want PersonEx
to be bound to its own XML
type.
Example 16. Extended Person class
package org.acme.foo.impl; class PersonEx extends Person { @Override public void setName(String name) { if(name.length()<3) throw new IllegalArgumentException(); super.setName(name); } } @XmlRegistry class ObjectFactoryEx extends ObjectFactory { @Override Person createPerson() { return new PersonEx(); } }
At runtime, you can create JAXBContext
normally, like
this.
Example 17. Creating JAXBContext
JAXBContext context = JAXBContext.newInstance(ObjectFactory.class); // or JAXBContext.newInstance("org.acme.foo");
PersonEx
can be marshalled out just like
Person
:
Example 18. Marshalling
Person p = new PersonEx(); context.createMarshaller().marshal(p,System.out); // this will produce <person />
To unmarshal XML documents into PersonEx
, you'll need
to configure the unmarshaller to use your ObjectFactoryEx
as
the factory, like this:
Example 19. Unmarshalling
Unmarshaller u = context.createUnmarshaller(); u.setProperty("com.sun.xml.bind.ObjectFactory",new ObjectFactoryEx()); PersonEx p = (PersonEx)u.unmarshal(new StringReader("<person />"));
If you have multiple packages and thus multiple
ObjectFactory
s, you can pass in an array of them (new
Object[]{new OFEx1(),new OFEx2(),...}
.)
If you have a type hierarchy and would like to insert your class
in the middle, you can use the combination of XmlTransient
and @implClass
of <class>
customization. See the following example:
Example 20. Hierarchy of types and <jaxb:class implClass>
<xs:schema ...> <xs:complexType name="vehicle"> <xs:annotation><xs:appinfo> <jaxb:class implClass="MyVehicle" /> </xs:appinfo></xs:annotation> </xs:complexType> <xs:complexType name="car"> <xs:complexContent> <xs:extension base="vehicle" /> </xs:complexContent> </xs:complexType> <xs:complexType name="bicycle"> <xs:complexContent> <xs:extension base="vehicle" /> </xs:complexContent> </xs:complexType> </xs:schema>
Example 21. This creates a class hierarchy like the following (among the generated Java code):
Vehicle ^ | MyVehicle ^ _____|______ | | Car Bicycle
You'll then manually write MyVehicle
class that
extends from Vehicle
. Annotate this class with XmlTransient
to achieve the desired effect.
Under some limited circumstances, a weaker databinding is preferable for various reasons. JAXB does offer a few ways for you to achieve this.
The following customization will stop binding a simple type to a type-safe enum. This can be convenient when number of constants is too large to be an useful enum (by default, the JAXB spec won't generate enum with more than 256 constants, but even 100 might be too large for you.)
Example 22. Avoid mapping one simple type
<xs:simpleType name="foo"> <xs:annotation><xs:appinfo> <jaxb:typesafeEnumClass map="false" /> </xs:appinfo></xs:annotation> <xs:restriction base="xs:string"> <xs:enumeration value="x" /> <xs:enumeration value="y" /> <xs:enumeration value="z" /> </xs:restriction> </xs:simpleType>
To disable such type-safe enum binding altogether for the entire schema, use a global binding setting like this (this is actually telling XJC not to generate enums if a simple type has more than 0 constants --- the net effect is no enum generation):
Example 23. Avoid generating enums at all
<xs:schema ...> <xs:annotation><xs:appinfo> <jaxb:globalBindings typesafeEnumMaxMembers="0" /> </xs:appinfo></xs:annotation> ... </xs:schema>
The <jaxb:dom>
customization allows you to map
a certain part of the schema into a DOM tree. This customization can
be attached to the following schema components:
Wildcards (<xs:any>
)
Type definitions (<xs:complexType>
and
<xs:simpleType>
)
Model groups
(<xs:choice>
,<xs:all>
,<xs:sequence>
)
Model group declarations (<xs:group>
)
Particles
Element declarations (<xs:element>
)
In the following example, a wildcard is mapped to a DOM node. Each element that matches to the wildcard will be turned into a DOM tree.
Example 24. Dom Customization example
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"> <xs:element> <xs:complexType> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="skip"> <xs:annotation><xs:appinfo> <jaxb:dom/> </xs:appinfo></xs:annotation> </xs:any> </xs:sequence> </xs:complexType> </xs:element> . . . </xs:schema>
This extension can be used to access wildcard content or can be
used to process a part of a document by using other technologies that
require "raw" XML. By default, JAXB generates a getContent()
method
for accessing wildcard content, but it only supports "lax" handling
which means that unknown content is discarded. You may find more
information in 7.12 chapter of JAXB 2
specification.
The generated beans (and in particular the
JAXBElement
class) do not support the clone operation.
There was a suggestion by another user that beanlib has been
used successfully to clone JAXB objects.
The JAXB specification provides a <jaxb:schemaBindings>
customization so that you can control which namespace goes to which
package. See the example below:
Example 25. package customization
<jaxb:schemaBindings> <jaxb:package name="org.acme.foo"/> </jaxb:schemaBindings>
You can do this as an internal customization (in which case you put
this in <xs:annotation>
<xs:appinfo>
under place it right under
the <xs:schema>
element), or do this as an external customization,
like this:
Example 26. External package customization
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" version="2.1"> <bindings schemaLocation="../path/to/my.xsd"> <schemaBindings> <package name="org.acme.foo"/> </schemaBindings> </bindings> </bindings>
Note that this customization is per namespace. That is, even if your schema is split into multiple schema documents, you cannot put them into different packages if they are all in the same namespace.
Under some rare circumstances, XJC will generate some Java
classes into a package called org.w3._2001.xmlschema
.
This happens when XJC decides that it needs some Java artifacts for
the XML Schema built-in namespace of
http://www.w3.org/2001/XMLSchema
.
Since this package name is most often problematic, you can rename this by simply saving the following text in an .xsd file and submitting it to XJC along with the other schemas you have:
Example 27. Schemalet to get rid of org.w3._2001.xmlschema
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"> <annotation><appinfo> <jaxb:schemaBindings> <jaxb:package name="org.acme.foo"/> </jaxb:schemaBindings> </appinfo></annotation> </schema>
This is bit tricky, but the idea is that since you can define a schema for one namespace in multiple schema documents, this makes XJC think that this schema is a part of the built-in "XML Schema for XML Schema".
When using an external customization file, the JAXB spec requires that you use XPath as a means to specify what your customization is attached to. For example, if you want to change the class name generated from a complex type, you'd write something like:
Example 28. External customization example
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" version="2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <bindings schemaLocation="../path/to/my.xsd" node="/xs:schema/xs:complexType[@name='foo']"> <class name="FooType"/> </bindings> </bindings>
While the above process works, the problem with this is that the
XPath+ schemaLocation
combo tends to be verbose and error
prone. It's verbose, because often a trivial target schema component like
this "global complex type foo" takes up a lot of characters. The xs
namespace declaration also takes up some space, although in this case we
managed to avoid declaring the "tns" namespace (that represents the
namespace that the schema defines.)
It's also error prone, because it relies on the way schema documents are laid out, because the schemaLocation attribute needs to point to the right schema document file. When a schema is split into multiple files for modularity (happens especially often with large schemas), then you'd have to find which schema file it is. Even though you can use relative paths, this hard-coding of path information makes it hard to pass around the binding file to other people.
JAXB RI 2.1 and onward offers a better way to do this as a vendor extension.
The key technology to solve this problem is a "schema component
designator
" (SCD.) This is a path language just like XPath, but
whereas XPath is designed to refer to XML infoset items like elements and
attributes, SCD is designed to refer to schema components like element
declarations or complex types.
With SCD, the above binding can be written more concisely as follows:
Example 29. External customization by SCD
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" version="2.1" xmlns:tns="http://my.namespace/"> <bindings scd="/type::tns:foo"> <class name="FooType"/> </bindings> </bindings>
/type::tns:foo
can be written more concisely as
/~tns:foo
, too. If you are interested in more about the
syntax of SCDs, read the
example part of the spec, and maybe EBNF.
If you know XPath, I think you'll find this fairly easy to learn.
Another benefit of an SCD is that tools will have easier time generating SCDs than XPath, as XPaths are often vulnerable to small changes in the schema document, while SCDs are much more robust. The downside of using SCD is as of JAXB 2.1, this feature is a vendor extension and not defined in the spec.
JAXB has a built-in table that determines what Java classes are used to represent what XML Schema built-in types, but this can be customized.
One of the common use cases for customization is to replace the
XMLGregorianCalendar
with the friendlier
Calendar
or Date
.
XMLGregorianCalendar
is designed to be 100% compatible with
XML Schema's date/time system, such as providing infinite precision in
sub-seconds and years, but often the ease of use of those familiar Java
classes win over the precise compatibility.
One very easy way to do this is to simply use your IDE (or even
"sed
") to replace all the references to XMLGregorianCalendar
by Calendar
. This is of course not a very attractive option
if your build process runs XJC as a part of it.
Alternatively, the following customization file can be used to do this. When using external customization file, the JAXB spec requires you to use XPath as a means to specify what your customization is attached to. For example, if you want to change the class name generated from a complex type, you'd use the following customization:
Example 30. Customization to use Calendar for xs:date
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" version="2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <globalBindings> <javaType name="java.util.Calendar" xmlType="xs:date" parseMethod="javax.xml.bind.DatatypeConverter.parseDate" printMethod="javax.xml.bind.DatatypeConverter.printDate" /> </globalBindings> </bindings>
Save this in a file and specify this to JAXB with the "-b" option.
To use the Date
class, you'll need to do a bit more
work. First, put the following class into your source tree:
Example 31. Adapter for Date
package org.acme.foo; public class DateAdapter { public static Date parseDate(String s) { return DatatypeConverter.parseDate(s).getTime(); } public static String printDate(Date dt) { Calendar cal = new GregorianCalendar(); cal.setTime(dt); return DatatypeConverter.printDate(cal); } }
... then your binding file will be the following:
Example 32. Customization to use Date for xs:date
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" version="2.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <globalBindings> <javaType name="java.util.Date" xmlType="xs:date" parseMethod="org.acme.foo.DateAadpter.parseDate" printMethod="org.acme.foo.DateAdapter.printDate" /> </globalBindings> </bindings>
JAXB (or any other databinding engine, for that matter) is for
binding strongly-typed POJO-like objects to XML, such as
AddressBook
class, PurchaseOrder
class, and
so on, where you have fields and methods that shape a class.
There are other kinds of classes that are more close to
reflection. Those classes don't have methods like
getAddress
, and instead you'd do
get("Address")
. JDBC ResultSet is one of those classes.
It's one class that represents million different data structures, be
it a customer table or a product table. Generally speaking, these
classes does not allow JAXB to statically determine what the XML
representation should look like. Instead, you almost always need to
look at an instance to determine the shape of XML.
These classes are not really suitable for binding in JAXB. If this is the only object that you'd want to write out, then you'd be better off using XMLStreamWriter or some such XML infoset writing API. There are a few online articles that cover this topic. Also, many modern database offers a native ability to export a query into XML, which is supposed to work a lot faster than you'd do in Java (and saves your time of writing code.)
If you are using ResultSet as a part of your object tree that
you want to marshal to JAXB, then you can use
XmlJavaTypeAdapter
.
JAXB spec defines a special handling for Map
when
it's used as a propety of a bean. For example, the following bean
would produce XMLs like the following:
Example 34. XML representation
<foo> <map> <entry> <key>a</key> <value>1</value> </entry> <entry> <key>b</key> <value>2</value> </entry> </map> </foo>
Unfortunately, as of 2.1, this processing is only defined for
bean properties and not when you marshal HashMap
as a
top-level object (such as a value in JAXBElement
.) In
such case, HashMap
will be treated as a Java bean, and
when you look at HashMap
as a bean it defines no
getter/setter property pair, so the following code would produce the
following XML:
Example 35. Bean with Map
m = new HashMap(); m.put("abc",1); marshaller.marshal(new JAXBElement(new QName("root"),HashMap.class,m),System.out);
This issue has been recorded as #223 and the fix needs to happen in later versions of the JAXB spec.
In the mean time, such top-level objects have to be first adapted to a bean that JAXB can process. This has added benefit of being able to control XML representation better. The following code illustrates how to do this:
Example 37. Adapting HashMap
public class MyHashMapType { public List<MyHashMapEntryType> entry = new ArrayList<MyHashMapEntryType>(); public MyHashMapType(Map<String,Integer> map) { for( Map.Entry<String,Integer> e : map.entrySet() ) entry.add(new MyHashMapEntryType(e)); } public MyHashMapType() {} } public class MyHashMapEntryType { @XmlAttribute // @XmlElement and @XmlValue are also fine public String key; @XmlAttribute // @XmlElement and @XmlValue are also fine public int value; public MyHashMapEntryType() {} public MyHashMapEntryType(Map.Entry<String,Integer> e) { key = e.getKey(); value = e.getValue(); } } marshaller.marshal(new JAXBElement(new QName("root"),MyHashMapType.class,new MyHashMapType(m)),System.out);
If you have a lot of difference kinds of Map
, you
can instead use Object
as the key and the value type. In
that way, you'll be able to use maps with different type parameters,
at the expense of seeing xsi:type
attribute on the
instance document.
Because of the difference between the XML type system induced by W3C XML Schema and the Java type system, JAXB cannot bind interfaces out of the box, but there are a few things you can do.
@XmlRootElement
When your interface is implemented by a large number of
sub-classes, consider using XmlRootElement
annotation like this:
Example 38. XmlRootElement for open-ended interfaces
@XmlRootElement class Zoo { @XmlAnyElement public List<Animal> animals; } interface Animal { void sleep(); void eat(); ... } @XmlRootElement class Dog implements Animal { ... } @XmlRootElement class Lion implements Animal { ... }
This will produce XML documents like this:
The key characteristics of this approach is:
Implementations are open-ended; anyone can implement
those interfaces, even by different people from different
modules, provided they are all given to the
JAXBContext.newInstance
method. There's no need
to list all the implementation classes in anywhere.
Each implementation of the interface needs to have an unique element name.
Every reference to interface needs to have the XmlElementRef
annotation. The
type=Object.class
portion tells JAXB that the
greatest common base type of all implementations would be
java.lang.Object
.
@XmlElementWrapper
is often useful with this,
as it allows you need to group them. Such as:
Example 40. XmlRootElement for open-ended interfaces
@XmlRootElement class Zoo { @XmlElementWrapper @XmlAnyElement public List<Animal> onExhibit; @XmlElementWrapper @XmlAnyElement public List<Animal> resting; }
Example 41. Effect of XmlElementWrapper
<zoo> <onExhibit> <lion> ... </lion> <dog> ... </dog> </onExhibit> <resting> <lion> ... </lion> <dog> ... </dog> </resting> </zoo>
@XmlJavaTypeAdapter
When you use interfaces just to hide your implementation classes
from exposure, and when there's 1-to-1 (or close to 1-on-1)
relationship between a class and an interface, XmlJavaTypeAdapter
can be used like below.
Example 42. XmlJavaTypeAdapter for interfaces
@XmlJavaTypeAdapter(FooImpl.Adapter.class) interface IFoo { ... } class FooImpl implements IFoo { @XmlAttribute private String name; @XmlElement private int x; ... static class Adapter extends XmlAdapter<FooImpl,IFoo> { IFoo unmarshal(FooImpl v) { return v; } FooImpl marshal(IFoo v) { return (FooImpl)v; } } } class Somewhere { public IFoo lhs; public IFoo rhs; }
Example 43. XML of XmlJavaTypeAdapter
<somewhere> <lhs name="..."> <x>5</x> </lhs> <rhs name="..."> <x>5</x> </rhs> </somewhere>
The key characteristics of this approach is:
Interface and implementation will be tightly coupled through an adapter, although changing an adapter code will allow you to support multiple implementations.
There's no need of any annotation in where interfaces are used.
A variation of this technique is when you have a few implementations for interface, not just one.
Example 44. XmlJavaTypeAdapter for interfaces with multiple implementations
@XmlJavaTypeAdapter(AbstractFooImpl.Adapter.class) interface IFoo { ... } abstract class AbstractFooImpl implements IFoo { ... static class Adapter extends XmlAdapter<AbstractFooImpl,IFoo> { IFoo unmarshal(AbstractFooImpl v) { return v; } AbstractFooImpl marshal(IFoo v) { return (AbstractFooImpl)v; } } } class SomeFooImpl extends AbstractFooImpl { @XmlAttribute String name; ... } class AnotherFooImpl extends AbstractFooImpl { @XmlAttribute int id; ... } class Somewhere { public IFoo lhs; public IFoo rhs; }
Example 45. XML of XmlJavaTypeAdapter with multiple implementations
<somewhere> <lhs xsi:type="someFooImpl" name="..."> </lhs> <rhs xsi:type="anotherFooImpl" id="3" /> </somewhere>
Note that SomeFooImpl
and
AnotherFooImpl
must be submitted to
JAXBContext.newInstance
one way or the other.
To take this example a bit further, you can use
Object
instead of AbstractFooImpl
. The
following example illustarates this:
Example 46. XmlJavaTypeAdapter for interfaces with multiple implementations
@XmlJavaTypeAdapter(AnyTypeAdapter.class) interface IFoo { ... } public class AnyTypeAdapter extends XmlAdapter<Object,Object> { Object unmarshal(Object v) { return v; } Object marshal(Object v) { return v; } } class SomeFooImpl implements IFoo { @XmlAttribute String name; ... } class Somewhere { public IFoo lhs; public IFoo rhs; }
Example 47. Corresponding schema
<xs:complexType name="somewhere"> <xs:sequence> <xs:element name="lhs" type="xs:anyType" minOccurs="0"/> <xs:element name="rhs" type="xs:anyType" minOccurs="0"/> </xs:sequence> </xs:complexType>
As you can see, the schema will generated to accept
xs:anyType
which is more relaxed than what the Java code
actually demands. The instance will be the same as the above example.
Starting from JAXB RI 2.1, we bundle the
com.sun.xml.bind.AnyTypeAdapter
class in the runtime that
defines this adapter. So you won't have to write this adapter in your
code.
@XmlElement
If the use of interface is very little and there's 1-to-1 (or
close to) relationship between interfaces and implementations, then
you might find XmlElement
to be the least amount of work.
Example 48. XmlElement for interfaces
interface IFoo { ... } class FooImpl implements IFoo { ... } class Somewhere { @XmlElement(type=FooImpl.class) public IFoo lhs; }
This effectively tells JAXB runtime that "even though the field
is IFoo
, it's really just FooImpl
.
In this approach, a reference to an interface has to have knowledge of the actual implementation class. So while this requires the least amount of typing, it probably wouldn't work very well if this crosses module boundaries.
Like the XmlJavaTypeAdapter
approach, this can be used
even when there are multiple implementations, provided that they share
the common ancestor.
The extreme of this case is to specify
@XmlElement(type=Object.class)
.
Occasionally the above approaches cause the generated schema to become somewhat ugly, even though it does make the JAXB runtime work correctly. In such case you can choose not to use the generated schema and instead manually modify/author schemas tht better match your needs.
With sufficient knowlege, one can also use <jaxb:class
ref="..."/>
annotation so that you can cause XJC to use the classes
you already wrote. See this
thread for an example. TODO: more details and perhaps an
example.
Some
users attempted to use the "generateValueClass
" customization
and see if they can completely replace the generated implementations
with other implementations. Unfortunately, this does not work.
Even with the interface/implementation mode, JAXB runtime still requires that the implementation classes have all the JAXB annotations. So just implementing interfaces is not sufficient. (This mode is mainly added to simplify the migration from JAXB 1.0 to JAXB 2.0, and that's a part of the reason why things are done this way.)
Here is the basic problem of evolution. You got your CoolApp v1, which contains class Foo that has some JAXB annotations. Now you are working towawrd CoolApp v2, and you want to make some changes to Foo. But you want to do so in such a way that v1 and v2 can still talk to each other.
The evolution compatibility has two different aspects. One is the schema compatibility, which is about the relationship between the v1 schema and the v2 schema. The other is about runtime compatibility, which is about reading/writing documents between two versions.
There are two directions in the runtime compatibility. One is whether v1 can still read what v2 write (forward compatible), and the other is whether v2 can read what v1 wrote (backward compatible).
Semi-compatible
"JAXB can read XML documents that don't exactly match what's expected. This is the default behavior of the JAXB unmarshaller, yet you can change it to a more draconian behavior (TODO: pointer to the unmarshalling section.)
When we are talking about evolving classes, it's often convenient to leave it in the default behavior, as that would allow JAXB to nicely ignore elements/attributes newly added in v2. So we call it backward semi-compatible if v2 can read what v1 wrote in this default unmarshalling mode, and similarly forward semi-compatible if v1 can read what v2 wrote in this default unmarshalling mode.
Technically, these are weaker than true backward/forward compatibility (since you can't do a draconian error detection), yet in practice it works just fine.
You can add, remove, or change any non-annotated fields, methods, inner/nested types, constructors, interfaces. Those changes are both backward and forward compatible, as they don't cause any change to the XML representation.
Adding super class is backward compatible and forward semi-compatible. Similarly, removing super class is forward compatible and backward semi-compatible.
Adding new annotated fields or methods is backward compatible and forward semi-compatible. Similarly, removing them is forward compatible and backward semi-compatible.
Changing a property is bit more tricky.
If you change the property name from X to Y, that would
be the equivalent of deleting X and adding Y, so it would be
backward and forward semi-compatible. What JAXB really cares
is properties' XML names and not Java names, so by using the
name
parameter of XmlElement
, XmlAttribute
et al, you can change Java
property names without affecting XML, or change XML without
affecting Java properties. These are backward and forward
semi-compatible. See below:
Example 50. Changing Java without affecting XML
// BEFORE public class Foo { public String abc; } // AFTER: Java name changed, but XML remains the same public class Foo { @XmlElement(name="abc") public String def; }
Example 51. Changing XML without affecting Java
// BEFORE public class Foo { public String abc; } // AFTER: no Java change, but XML will look different public class Foo { @XmlElement(name="def") public String abc; }
If you change a property type, generally speaking it
will be not compatible at all. For example, you can't change
from java.util.Calendar
to int
and
expect it to work. To make it a somewhat compatible change,
the old type and the new type has to be related. For example,
String
can represent all int
values,
so changing int
to String
would be a
backward compatible and forward semi-compatible change. XmlJavaTypeAdapter
allows you to make
changes to Java without affecting XML (or vice versa.)
XmlType
and XmlRootElement
allows you to change a class name
without affecting XML.
Example 52. Changing class name without affecting XML (1)
// BEFORE @XmlRootElement public class Foo { ... } // AFTER: no XML change @XmlRootElement(name="foo") @XmlType(name="foo") public class Bar { ... }
Example 53. Changing class name without affecting XML (2)
// BEFORE public class Foo { ... } // AFTER: no XML change @XmlType(name="foo") public class Bar { ... }
TODO.
Your program sometimes needs to have a different in-memory data structure from its XML representation. JAXB has a few different ways to achieve this.
XmlJavaTypeAdapter
allows you to de-couple the
in-memory representation and the XML representation by introducing an
intermediate representation. The basic model is as follows:
In-memory objects <===> Intermediate objects <===> XML adapter JAXB
Your adapter code will be responsible for converting in-memory
objects to/from intermediate objects. Intermediate objects are then
bound to XML by following the standard JAXB rules. See XmlAdapter
for a general description of how
adapters works.
Adapters extend from the XmlAdapter
class and provide two methods
"unmarshal" and "marshal" that converts values in both directions, and
then the XmlJavaTypeAdapter
annotation is used to tell
JAXB where and what adapters kick in.
(TODO: more info about XmlJavaTypeAdapter needed)
adapting a class
adapting a property
adapting an external class
adapting a collection and its effect
adapting and using interfaces
One of the common use cases of XmlJavaTypeAdapter
is to map a "value object" to
a string in XML. The following example illustrates how to do this, by
using java.awt.Color
as an example.
Example 54. Mapping Color to #RRGGBB
@XmlRootElement class Box { @XmlJavaTypeAdapter(ColorAdapter.class) @XmlElement Color fill; } class ColorAdapter extends XmlAdapter<String,Color> { public Color unmarshal(String s) { return Color.decode(s); } public String marshal(Color c) { return "#"+Integer.toHexString(c.getRGB()); } }
This maps to the following XML representation:
Since XmlJavaTypeAdapter
is on a field, this adapter
only kicks in for this particular field. If you have many
Color
fields and would like them all to use the same
adapter, you can move the annotation to a package:
Example 56. package-info.java
@XmlJavaTypeAdapter(type=Color.class,value=ColorAdapter.class) package foo;
This causes all the fields in the classes in the
foo
package to use the same specified adapter.
Also see the DatatypeConverter
class that defines a
series of basic conversion routines that you may find useful.
Another useful technique is to define two properties, one for JAXB and the other for your application. See the following example:
Example 58. Pair property sample
@XmlRootElement class Person { private int age; // This public property is for users @XmlTransient public int getAge() { return age; } public void setAge(int age) { this.age = age; } // This property is for JAXB @XmlAttribute(name="age") private String getAge_() { if(age==-1) return "dead"; else return String.valueOf(age); } private void setAge_(String v) throws NumberFormatException { if(v.equals("dead")) this.age=-1; else this.age=Integer.parseInt(age); }
The main "age
" property is public, but marked as XmlTransient
, so it's exposed in your program,
but JAXB will not map this to XML. There's another private "age_
"
property. Since this is marked with XmlAttribute
, this is what JAXB is going to use
to map to the attribute. The getter and setter methods on this
property will handle the conversion between the in-memory
representation and the XML representation.
Object models designed in Java often have cycles, which prevent straight-forward conversion to XML by JAXB. In fact, when you try to marshal an object tree that contains a cycle, the JAXB marshaller reports an error, pointing out the objects that formed the cycle. This is because JAXB by itself cannot figure out how to cut cycles into a tree.
Thus it is your responsibility to annotate classes and use other means to "tell" JAXB how to handle a cycle. This chapter talks about various techniques to do this.
One of the very common forms of cycle is a parent pointer. The following example illustrates a typical parent pointer, and how this can be turned into "natural" XML:
Example 59. Classes with parent pointer
@XmlRootElement class Department { @XmlAttribute String name; @XmlElement(name="employee") List<Employee> employees; } class Employee { @XmlTransient Department department; // parent pointer @XmlAttribute String name; public void afterUnmarshal(Unmarshaller u, Object parent) { this.department = (Department)parent; } }
This will produce the following XML:
Example 60. XML view of department
<department name="accounting"> <employee name="Joe Chin" /> <employee name="Adam Smith" /> ... </department>
And reading this document back into Java objects will produce the expected tree with all the proper parent pointers set up correctly.
The first technique here is the use of XmlTransient
on the parent pointer. This tells
JAXB that you don't need this parent pointer to be represented
explicitly in XML, because the fact that employee
is
always contained inside department
implies the
parent/child relationship. This causes the marshaller to produce the
expected XML. However, when you unmarshal it, since this field is not
bound, the Employee.department
field will be left
null.
That's where the second technique comes in, which is the use of
the afterUnmarshal
callback. This method is invoked by
the JAXB implementation on each instance when the unmarshalling of a
Employee
object completes. Furthermore, the second
parameter to the method is the parent object, which in this case is a
Department
object. So in this example, this sets up the
parent pointer correctly.
This callback can be also used to perform other post-unmarshalling set up work.
TBD
@XmlID
and
@XmlIDREF
When a reference to another object is annotated with XmlIDREF
, its corresponding XML it will be
referenced by xs:IDREF
, instead of containment. See below
for an example:
Example of @XmlID
and
@XmlIDREF
@XmlRootElement class Root { List<Foo> foos; List<Bar> bars; } class Foo { // you don't have to make it an attribute, but that's more common @XmlAttribute @XmlIDREF Bar bar; } class Bar { // you don't have to make it an attribute, but that's more common @XmlAttribute @XmlID String id; }
Example 61. Schema for above
<xs:complexType name="foo"> <xs:sequence/> <xs:attribute name="bar" type="xs:IDREF"/> </xs:sequence> </xs:complexType> <xs:complexType name="bar"> <xs:sequence/> <xs:attribute name="id" type="xs:ID"/> </xs:complexType>
Example 62. A sample instance
<root> <foo bar="x"/> <foo bar="y"/> <bar id="x"/> <bar id="y"/> </root>
There are a few things to consider when you do this. First, the
object to be referenced must have an ID that is unique within the
whole document. You'd also need to ensure that the referenced objects
are contained somewhere else (like in the
Root
class in this case), or else Bar
objects will never be marshalled. This technique can be used to remove
the cyclic references, but it's only possible when your object model
has an easy cut point.
Starting 2.1 EA2, the JAXB RI exposes CycleRecoverable
interface. Applications can
choose to implement this interface in some of its objects. When a
cyclic reference is detected during marshalling, and if the object
that formed a cycle implements this interface, then the method on this
interface is called to allow an application to nominate its
replacement to be written to XML. In this way, the application can
recover from a cycle gracefully.
This technique allows you to cope with a situation where you cannot easily determine upfront as to where a cycle might happen. On the other hand, this feature is a JAXB RI feature. Another downside of this is that unless you nominate your replacement carefully, you can make the marshalling output invalid with respect to the schema, and thus you might hit another problem when you try to read it back later.
@XmlRootElement
and unmarshallingClasses with XmlRootElement
can be unmarshalled from XML elements
simply by invoking the unmarshal method that takes one parameter. This is
the simplest mode of unmarshalling.
Unmarshalling with @XmlRootElement
@XmlRootElement class Foo { @XmlAttribute String name; @XmlElement String content; } Unmarshaller u = ...; Foo foo = (Foo)u.unmarshal(new File("foo.xml"));
However, sometimes you may need to unmarshal an instance of a type
that does not have an XmlRootElement
. For example, you might dynamically
find out at the runtime that a certain element has a certain type. For
example, the following document illustrates an XML instance where the
content of <someOtherTagName>
element is represented by the
Foo
class.
To unmarshal this into a Foo
class, use the version of
the unmarshal
method that takes the 'expectedType' argument,
as follows:
Example 65. Unmarshalling into a known type
Unmarshaller u = ...; JAXBElement<Foo> root = u.unmarshal(new StreamSource(new File("foo.xml")),Foo.class); Foo foo = root.getValue();
To reduce the number of the unmarshal
methods, this
two-argument version is not defined for every single-argument version. So
as in this example, you might need to perform additional wrapping of the
input parameter.
This instructs JAXB that the caller is expecting to unmarshal
Foo
instance. JAXB returns a JAXBElement
of
Foo
, and this JAXBElement
captures the tag name
of the root element.
There are a few common causes for this problem. These causes often exhibit similar symptoms:
Instance documents are invalid
JAXBContext
is not created correctly.
First, use an independent schema validator to check if your document is really valid with respect to the schema you compiled. When the root element of a document is invalid, then the unmarshaller will issue "unexpected element" errors. When a portion of a document is invalid, JAXB skips that portion, so the end result is that the unmarshalling returns normally, yet you notice that a part of the content tree is missing. This is often the desirable behavior, but it sometimes ends up masking a problem.
Also, try to install ValidationEventHandler
on the
unmarshaller. When a portion of a document is skipped, the
unmarshaller notifies a ValidationEventHandler
, so it
allows you to see what's going on.
Example 66. Installing ValidationEventHandler
Unmarshaller u = ...; // this implementation is a part of the API and convenient for trouble-shooting, // as it prints out errors to System.out u.setEventHandler(new javax.xml.bind.helpers.DefaultValidationEventHandler()); u.unmarshal(new File("foo.xml"));
Also consider installing a Schema
object to the
unmarshaller, so that the unmarshaller performs a schema validation
while unmarshalling. Earlier I suggested that you try an independent
schema validator, but for various reasons (not all tools are reliable,
you might have made an error and used a different schema/instance),
using validating unmarshalling is a better way to guarantee the
validity of your instance document being unmarshalled. Please follow
the JAXP
tutorial for more about how to construct a Schema
object from your schema.
If you are unmarshalling from XML parser APIs (such as DOM, SAX, StAX), then also make sure that the parser/DOM is configured with the namespace enabled.
(TODO: This also applies to the marshaller. Think about moving it.)
The other possibility is that JAXBContext
is not
set up correctly. JAXBContext
"knows" a set of classes,
and if it doesn't know a class that it's supposed to know, then the
unmarshaller may fail to perform as you expected.
To verify that you created JAXBContext
correctly,
call JAXBContext.toString()
. It will output the list of
classes it knows. If a class is not in this list, the unmarshaller
will never return an instance of that class. Make you see all the
classes you expect to be returned from the unmarshaller in the list.
When dealing with a large schema that spans across a large number of
classes and packages, this is one possible cause of a problem.
If you noticed that a class is missing, explicitly specify that
to JAXBContext.newInstance
. If you are binding classes
that are generated from XJC, then the easiest way to include all the
classes is to specify the generated ObjectFactory
class(es).
Because of the "strange" way that element default values in XML Schema work, people often get confused about their behavior. This section describes how this works.
When a class has an element property with the default value, and if the document you are reading is missing the element, then the unmarshaller does not fill the field with the default value. Instead, the unmarshaller fills in the field when the element is present but the content is missing. See below:
Example 70. Element defaults and XML
@XmlRootElement class Foo { @XmlElement(defaultValue="value") public String a=null; } Foo foo = unmarshaller.unmarshal("instance1.xml"); System.out.println(foo.a); // null Foo foo = unmarshaller.unmarshal("instance2.xml"); System.out.println(foo.a); // "value". The default kicked in. Foo foo = unmarshaller.unmarshal("instance3.xml"); System.out.println(foo.a); // "abc". Read from the instance.
This is consistent with the XML Schema spec, where it essentially states that the element defaults do not kick in when the element is absent, so unfortunately we can't change this behavior.
Depending on your expectation, using a field initializer may achieve what you are looking for. See below:
Example 71. Possible changes by using field initializer
@XmlRootElement class Foo { @XmlElement public String a="value"; } Foo foo = unmarshaller.unmarshal("instance1.xml"); System.out.println(foo.a); // "value", because JAXB didn't overwrite the value Foo foo = unmarshaller.unmarshal("instance2.xml"); System.out.println(foo.a); // "", because <a> element had 0-length string in it Foo foo = unmarshaller.unmarshal("instance3.xml"); System.out.println(foo.a); // "abc". Read from the instance.
Alternatively, attribute default values work in a way that agrees with the typical expectation, so consider using that. Also, see Element default values and marshalling.
JAXB API is designed to make it easy to read the whole XML document into a single tree of JAXB objects. This is the typical use case, but in some situations this is not desirable. Perhaps:
A document is huge and therefore the whole may not fit the memory.
A document is a live stream of XML (such as XMPP) and therefore you can't wait for the EOF.
You only need to databind the portion of a document and would like to process the rest in other XML APIs.
This section discusses several advanced techniques to deal with these situations.
When a document is large, it's usually because there's repetitive parts in it. Perhaps it's a purchase order with a large list of line items, or perhaps it's an XML log file with large number of log entries.
This kind of XML is suitable for chunk-processing; the main idea is to use the StAX API, run a loop, and unmarshal individual chunks separately. Your program acts on a single chunk, and then throws it away. In this way, you'll be only keeping at most one chunk in memory, which allows you to process large documents.
See the streaming-unmarshalling example and the
partial-unmarshalling example in the JAXB RI distribution for more
about how to do this. The streaming-unmarshalling example has an
advantage that it can handle chunks at arbitrary nest level, yet it
requires you to deal with the push model --- JAXB unmarshaller will
"push
" new chunk to you and you'll need to process them right
there.
In contrast, the partial-unmarshalling example works in a pull model (which usually makes the processing easier), but this approach has some limitations in databinding portions other than the repeated part.
The techniques discussed above can be used to handle this case as well, since they let you unmarshal chunks one by one. See the xml-channel example in the JAXB RI distribution for more about how to do this.
For further advanced cases, one could always run a streaming infoset conversion outside JAXB API and basically curve just the portion of the infoset you want to data-bind, and feed it as a complete infoset into JAXB API. JAXB API accepts XML infoset in many different forms (DOM, SAX, StAX), so there's a fair amount of flexibility in choosing the right trade off between the development effort in doing this and the runtime performance.
For more about this, refer to the respective XML infoset API.
By default, a JAXB marshaller uses random namespace prefixes (such
as ns1
, ns2
, ...) when it needs to declare new
namespace URIs. While this is perfectly valid XML wrt the schema, for
human readability, you might want to change them to something that makes
more sense.
The JAXB RI defines NamespacePrefixMapper to allow you to do this. See
the namespace-prefix
sample in the distribution for more
details.
Because of a "strange" way element default values in XML Schema work, people often get confused about its behavior. This section describes how this works.
When a class has an element property with the default value, and if a value is null, then the marshaller will not produce the corresponding element in XML:
Example 72. Element defaults and XML
@XmlRootElement class Foo { @XmlElement(defaultValue="value") public String a=null; } marshaller.marshal(new Foo(),System.out);
This is consistent with the XML Schema spec, where it essentially states that the element defaults do not kick in when the element is absent. Attribute default values do not have this problem, so if you can change the schema, changing it to an attribute is usually a better idea. Alternatively, depending on your expectation, setting the field to a default value in Java may achieve what you are looking for.
Example 74. Possible changes
@XmlRootElement class Foo { @XmlElement public String a="value"; } @XmlRootElement class Bar { @XmlAttribute public String a; } marshaller.marshal(new Foo(),System.out); marshaller.marshal(new Bar(),System.out);
Also, see Element default values and unmarshalling.
The most basic notion of the marshalling is to take a JAXB-bound
object that has @XmlRootElement
, and write it out as a
whole XML document. So perhaps you have a class like this:
Example 76. JAXB POJO
class Point { @XmlElement public int x; @XmlElement public int y; Point(...) { ... } }
Then you can do:
Example 77. Plain marshalling
marshaller.marshal( new Point(1,3), System.out ); marshaller.marshal( new Point(1,3), new File("out.xml") );
.. and so on. There're seven Marshaller.marshal
methods that takes different output media as the second parameter. If
you are writing to a file, a socket, or memory, then you should use
the version that takes OutputStream
. Unless you change
the target encoding to something else (default is UTF-8), there's a
special marshaller codepath for OutputStream
, which makes
it run really fast. You also don't have to use
BufferedOutputStream
, since the JAXB RI does the adequate
buffering.
You can also write to Writer
, but in this case
you'll be responsible for encoding characters, so in general you need
to be careful. If you want to marshal XML into an encoding other than
UTF-8, it's best to use the JAXB_ENCODING
property and
then write to OutputStream
, as it escapes characters to
things like ᠤ
correctly.
The next medium we support is W3C DOM. This is bit unintuitive, but you'll do it like this:
Example 78. Marshal to DOM
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); Document doc = dbf.newDocumentBuilder().newDocument(); marshaller.marshal( new Point(1,3), doc );
And after the method invocation you get a complete DOM tree that represents the marshalled document.
The other versions of the marshal methods are there to write XML
documents in terms of other XML APIs, such as SAX and StAX. The
version that takes ContentHandler
is useful when you need
a custom formatting needs (like you want each attribute to be in new
line, etc), but otherwise they are not very interesting if you are
writing a whole document.
Another common use of JAXB is where you are writing a bigger
document, and you use JAXB to generate part(s) of it. The JAX-WS RI is
the prime example. It produces a SOAP message, and JAXB is only used
to produce the body. When you are doing this, you first set
JAXB_FRAGMENT
property on the marshaller. This changes
the behaviors of the marshaller so that it works better in this
situation.
If you are writing to an OutputStream
or
Writer
and generally sending it to someone else, you can
do something like this:
Example 79. Marshalling into a subtree
System.out.println("<envelope>"); marshaller.marshal( object, System.out ); System.out.println("</envelope>");
Like I mentioned, this is probably the fastest, even though
println
isn't very pretty. JAXB_FRAGMENT
prevents the marshaller from producing an XML declaration, so the
above works just fine. The downside of this approach is that if the
ancestor elements declare the namespaces, JAXB won't be able to take
advantage of them.
You can also marshal an object as a subtree of an existing DOM
tree. To do this, you pass the Element
object as the
second parameter, and the marshaller will marshal an object as a child
of this node.
StAX is also very convenient for doing this sort of things. You
can create XMLStreamWriter
, write some stuff, and then
pass that to the marshaller. JAXB_FRAGMENT
prevents the
marshaller from producing startDocument
and
endDocument
token. When doing this sub-tree marshaling to
DOM and StAX, JAXB can take advantage of available in-scope namespace
bindings.
Finally, you can marshal an object as a subtree into
ContentHandler
, but it requires a fair amount of SAX
programming experience, and it goes beyond the scope of this
entry.
Another common use case is where you have an object that doesn't
have @XmlRootElement
on it. JAXB allows you to marshal it
like this:
Example 80. Marshalling a non-element
marshaller.marshal( new JAXBElement( new QName("","rootTag"),Point.class,new Point(...)));
This puts the <rootTag>
element as the root element,
followed by the contents of the object, then </rootTag>
. You can
actually use it with a class that has @XmlRootElement
,
and that simply renames the root element name.
At the first glance the second Point.class
parameter may look redundant, but it's actually necessary to determine
if the marshaller will produce (infamous)
@xsi
:type. In this example, both the class and the
instance are Point
, so you won't see
@xsi
:type. But if they are different, you'll see
it.
This can be also used to marshal a simple object, like
String
or an integer.
Marshalling a non-element with
@xsi
:type
marshaller.marshal( new JAXBElement( new QName("","rootTag"),String.class,"foo bar"));
But unfortunately it cannot be
used to marshal objects like List
or Map
, as
they aren't handled as the first-class citizen in the JAXB
world.
Because of the Source
and Result
support, JAXB objects can be easily marshalled into other XML APIs
that are not mentioned here. For example, dom4j has
DocumentResult
that extends Result
, so you
can do:
Example 81. Marshalling to dom4j
DocumentResult dr = new DocumentResult();
marshaller.marshal( object, dr );
o = dr.getDocument();
Similar mechanism is available for JDOM and XOM. This conversion
is much more efficient than first marshalling to
ByteArrayOutputStream
and then read it back into these
DOMs. The same mechanism can be used to marshal to FastInfoset or send the
marshaled document to an XSLT engine (TransformerHandler
.)
The other interesting connector is JAXBSource
,
which wraps a marshaller and allows a JAXB object to be used as a
"source" of XML. Many XML APIs take Source
as an input,
and now JAXB object can be passed to them directly.
For example, you can marshal a JAXB object and unmarshal it into another JAXBContext like this:
Example 82. Loading into a different JAXBContext
JAXBContext context1 = ... ;
JAXBContext context2 = ... ;
context1.createUnmarshaller().unmarshal( new JAXBSource(context2,object) );
This amounts to looking at the same XML by using different
schema, and again this is much more efficient than going through
ByteArrayOutputStream
.
Sometimes you may notice that JAXB is producing XML with seemingly unnecessary namespace declarations. In this section, we'll discuss the possible causes and how to resolve this.
The #1 cause of extra namespace declarations is due to the DOM
mapping. This mainly happens because of a schema construct that forces
XJC to generate a property with DOM. This includes the use of wildcard
<xs:any/>
(see more about this Mapping of <xs:any />
), as well as xs:anyType
(which can also happen by omission, such as <xs:element
name="foo"/>
, which is interpreted as <xs:element
name="foo" type="xs:anyType" />
.
During unmarshalling, when a subtree of the input XML is
converted into XML, JAXB copies all the in-scope namespace bindings
active at that time to the root of the DOM element. So for example,
given the following Java class and XML, the DOM tree that the
child
field will get will look like the following:
Example 84. Instance with subtree matching wildcard
<foo xmlns:a="a" xmlns:b="b" xmlns:c="c"> <subtree xmlns:c="cc"> <data>a:xyz</data> </subtree> </foo>
Example 85. DOM tree to be stored in Foo.child
<subtree xmlns:a="a" xmlns:b="b" xmlns:c="cc"> <data>a:xyz</data> </subtree>
Note that the two namespace declarations are copied over, but
c
is not because it's overridden. Also not that JAXB is
not touching the whitespace in document. This copying of namespace
declarations is necessary to preserve the infoset in the input
document. For example, if the <data>
is a QName, its meaning
would change if JAXB unmarshaller doesn't copy it.
Now, imagine what happens when you marshal this back to XML.
Despite the fact that in this example neither b
nor
c
prefixes are in use, JAXB cannot delete them, because
it doesn't know if those attributes are significant to the application
or not. Therefore, this could end up producing XML with "extra
namespace declarations" like:
Example 86. DOM tree to be stored in Foo.child
<foo> <subtree xmlns:a="a" xmlns:b="b" xmlns:c="cc"> <data>a:xyz</data> </subtree> </foo>
Resolving this problem is not possible in the general case, but sometimes one of the following strategy works:
Sometimes schema author incorrectly assumes that
<xs:element name="foo"/>
means
<xs:element name="foo" type="xs:string"/>
,
because attribute declarations work somewhat like this. In
such a case, adding explicit type
attribute
avoids the use of DOM, so things will work as expected.
The wildcard processing mode " strict
"
would force a typed binding, and thereby eliminate any DOM
mapping.
You might be able to manulally go into the DOM tree and remove unnecessary namespace declarations, if your application knows what are necessary and what are not.
Schemagen tools by default come in as CLI, ant task, and Maven plugin. These interfaces allow you to invoke schemagen functionality from your program.
If the classes you'd like to generate schema from are already
available as java.lang.Class
objects (meaning they are
already loaded and resolved in the current JVM), then the easiest way
to generate a schema is to use the JAXB API:
Example 87. Generate schema at runtime
File baseDir = new File("."); class MySchemaOutputResolver extends SchemaOutputResolver { public Result createOutput( String namespaceUri, String suggestedFileName ) throws IOException { return new StreamResult(new File(baseDir,suggestedFileName)); } } JAXBContext context = JAXBContext.newInstance(Foo.class, Bar.class, ...); context.generateSchema(new MySchemaOutputResolver());
The CLI
interface (public static int
com.sun.tools.jxc.SchemaGenerator.run(String[])
) is the
easiest API to access. You can pass in all the schemagen command-line
arguments as a string array, and get the exit code as an int value.
Messages are sent to System.err
and
System.out
.
Ant task can be invoked very easily from a non-Ant program. The schemagen ant task is defined in the SchemaGenTask class,
The above two interfaces are built on top of externally committed contracts, so they'll evolve only in a compatibile way. The downside is that the amount of control you can exercise over them would be limited.
So yet another approach to invoke schemagen is to use JAXB RI's internal interfaces. But be warned that those interfaces are subject to change in the future versions, despite our best effort to preserve them. This is the API that the JAX-WS RI uses to generate schema inside WSDL when they generate WSDL, so does some other web services toolkits that work with the JAXB RI.
Most of those interfaces are defined and well-documented in the com.sun.tools.xjc.api package. You can see how the schemagen tools are eventually calling into this API at the implementaion of SchemaGenerator class.
This section discusses how you can change the generated XML schema. For changes that also affect the infoset (such as changing elements to attributes, namespaces, etc.), refer to a different section "XML layout and in-memory data layout".
As of JAXB 2.1.4, currently no support for this, although there has been several discussions in the users alias.
The JAXB project is currently lacking resources to attack this problem, and therefore looking for volunteers to work on this project. The basic idea would be to define enough annotations to cover the basic constraint facets (such as length, enumerations, pattern, etc.) The schema generator would have to be then extended to honor those annotations and generate schemas accordingly.
Some users pointed out relevance of this to JSR 303: Bean Validation. If you are interested in picking up this task, let us know!
java.xml.bind:jaxb-api API classes for JAXB. Required to compile against JAXB.
org.glassfish.jaxb:jaxb-runtime Contains the main runtime used for serialization and deserialization java objects to/from xml.
org.glassfish.jaxb:jaxb-xjc: Tool to generate JAXB java sources from XML representation.
org.glassfish.jaxb:jaxb-jxc: Tool to generate XML schema from JAXB java sources.
com.sun.xml.bind:jaxb-ri: Zip distribution containing tooling scripts and all dependency jars in one archive.
Minimum requirement to compile is jaxb-api. If a client application is running on an environment where JAXB
runtime is provided, jaxb-api
is all that is needed.
Example 88. API only
<!-- API --> <dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>${jaxb.version}</version> </dependency>
If client application needs to include the runtime, e.g. running standalone on JavaSE
jaxb-runtime
should be also included.
Example 89. API + Runtime
<!-- API --> <dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>${jaxb.version}</version> </dependency> <!-- Runtime --> <dependency> <groupId>org.glassfish.jaxb</groupId> <artifactId>jaxb-runtime</artifactId> <version>${jaxb.version}</version> </dependency>
To generate JAXB classes from schema community maven-jaxb2-plugin can be used.
Example 90. Using maven-jaxb2-plugin
<build> <plugins> <plugin> <groupId>org.jvnet.jaxb2.maven2</groupId> <artifactId>maven-jaxb2-plugin</artifactId> <executions> <execution> <id>generate</id> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
Alternatively to community plugins, there are tooling artifacts jaxb-xjc and jaxb-jxc, which can be used for java from XML schema generation and vice versa.
Example 91. Using JAXB tooling artifacts
<!-- Tooling dependencies --> <dependency> <groupId>org.glassfish.jaxb</groupId> <artifactId>jaxb-xjc</artifactId> <version>${jaxb.version}</version> </dependency> <dependency> <groupId>org.glassfish.jaxb</groupId> <artifactId>jaxb-jxc</artifactId> <version>${jaxb.version}</version> </dependency> <!-- Invoke tooling API (Java 11) --> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <!-- Generate java sources from schema --> <execution> <id>xjc</id> <goals> <goal>exec</goal> </goals> <configuration> <executable>java</executable> <arguments> <argument>--module-path</argument> <modulepath/> <argument>-m</argument> <argument>com.sun.tools.xjc/com.sun.tools.xjc.XJCFacade</argument> <argument>-p</argument> <argument>com.example</argument> <argument>-d</argument> <argument>${project.build.directory}/generated-sources</argument> <argument>${project.build.directory}/classes/schema.xsd</argument> </arguments> </configuration> </execution> <!-- Generate XML Schema from sources --> <execution> <id>jxc</id> <goals> <goal>exec</goal> </goals> <configuration> <executable>java</executable> <arguments> <argument>--module-path</argument> <!-- or -p --> <modulepath/> <argument>-m</argument> <argument>com.sun.tools.jxc/com.sun.tools.jxc.SchemaGeneratorFacade</argument> <argument>-d</argument> <argument>${project.build.directory}/generated-sources</argument> <argument>${project.build.directory}/classes/com/example/Author.java</argument> <argument>${project.build.directory}/classes/com/example/Book.java</argument> </arguments> <longModulepath>false</longModulepath> </configuration> </execution> </executions> </plugin>
See also xml schema compiler usage.
Where are schemagen and xjc command line scripts available in JavaSE prior to 11? These are included only in the zip distribution.
JavaSE 9 features JSR 376 Java Platform Module System. Starting from 2.4.0 JAXB supports JPMS and can be loaded and used from module path. There are only a few things to be aware of.
JAXB does reflectively access private members of the class, so client application if loaded from module path needs to "open" packages containing jaxb classes to JAXB. There are alternative JAXB implementations, which will have different module names, JAXB requires pojo classes to be open only to API module.
Example 92. JPMS module descriptor opening JAXB pojo classes to JAXB API
//JPMS module descriptor module com.example.jaxbclasses { //jaxb-api module name requires java.xml.bind; //open jaxb pojo package to make accessing private members possible for JAXB. opens com.example.jaxbclasses.pojos to java.xml.bind;
JAXB API will delegate openness to implementation module after resolving it with service discovery mechanism.
Prior to Java 11, JavaSE contains JAXB bundled inside JDK. Module java.xml.bind
contains JAXB API and runtime.
If bundled JavaSE JAXB is used, there is no need to provide standalone JAXB jars to java runtime.
If standalone JAXB is used, JavaSE bundled java.xml.bind module should be replaced with JAXB API.
Similar to
endorsed mechanism
prior to Java 9, starting from 9 there is an "upgrade module" mechanism which can replace content of JDK module.
JavaSE bundled java.xml.bind
module contains both API and Runtime classes and
should be replaced with JAXB API module, which has the same java.xml.bind
module name.
Example 93. Upgrading JavaSE java.xml.bind module with JAXB API
# Using JAXB standalone jars # Replace JavaSE bundled java.xml.bind with standalone API jar user@host: java com.example.jaxb.Main -cp jaxbclient.jar --upgrade-module-path path/to/jaxb-api.jar --module-path path/to/jaxb-runtime.jar --add-modules com.sun.xml.bind #Same as above with client on module path user@host: java -m com.example.jaxbclasses/com.example.jaxb.Main --upgrade-module-path path/to/jaxb-api.jar --module-path path/to/jaxb-runtime.jar:jaxbclient.jar --add-modules com.sun.xml.bind
--upgrade-module-path will replace JavaSE java.xml.bind (runtime and API) with jaxb-api.jar contents.
Since java.xml.bind module is removed starting from Java 11, there is no need to upgrade this module on 11 and later.
Example 94. Using bundled JavaSE JAXB
# Using JAXB bundled in JDK # No need for standalone jars here user@host: java com.example.jaxb.Main -cp jaxbclient.jar user@host: java -m com.example.jaxbclasses/com.example.jaxb.Main --module-path jaxbclient.jar
JavaSE 6 ships with its own JAXB 2.0 implementation. This implementation is based on the JAXB RI, where the only differences are:
No RI-specific vendor extensions are supported: This is so that portability across different JavaSE 6 implementations will be guaranteed.
Code in JavaSE 6 is hosted in its own packages to avoid conflicts: This allows applications to continue to use a specific version of the JAXB RI that they choose to use.
Therefore, if you develop an application that uses JAXB 2.0 for JavaSE 5 today, the easiest way to upgrade to JavaSE 6 is to do nothing. You should keep the JAXB RI in your development environment, keep bundling the JAXB RI runtime jars to your app, just like you do that today.
If you'd like to reduce the footprint of your application by taking advantage of a JAXB implementation in JavaSE, you can take the following steps:
You will no longer have to ship
jaxb-api.jar
in your application. This doesn't
require any change to your code.
If your application does not use any of the vendor
extension features of the JAXB RI runtime (such as
unmarshaller/marshaller properties whose names start with
"com.sun.
"), then you will no longer have to ship
jaxb-impl.jar
(nor jaxb1-impl.jar
,
jaxb-libs.jar
.) When you do this, be sure to test
your application since it's not very easy to find all such
dependencies.
JavaSE comes with JAXB 2.x API/implementation in rt.jar
. Each
version of JavaSE (6, 7, 8, ...) contains different version of JAXB 2.x
API. Therefore, if you want to use different version of JAXB API/implementation
than the one present in your version of JDK, you are required to override
a portion of rt.jar
with the new API. There are
several ways to achieve this:
Place the jaxb-api.jar
into
$JRE_HOME/lib/endorsed
. Do not put other JAXB jars into the
endorsed directory. And put jaxb-impl, jaxb-core to classpath of your application.
This essentially makes your JRE to "JRE X + JAXB 2.y". This would
affect any other applications that use this JRE, and it's easy.
On the other hand, in various scenarios you may not be able to
alter the JRE.
Use the system property java.endorsed.dirs
when you launch your application, and
have it point to the directory which contains the jaxb-api.jar
only.
The directory must not contain any other jaxb artifacts (like jaxb-impl.jar or
jaxb-xjc.jar). This allows you use to use different version of JAXB for different
applications.
No matter which approach you take, make sure not to include jar
files other than jaxb-api.jar
. Doing so, for example
including jaxb-xjc.jar
, may result in classloading
related errors such as "taskdef A class needed by class
com.sun.tools.xjc.XJCTask cannot be found:
org/apache/tools/ant/...."
See the endorsed directory mechanism for more details.
JavaSE has never shipped an Ant task implementation, so we are
just following that tradition. There's an (process-wise) overhead of
adding additional dependencies during the JavaSE build, and there
would likely be some runtime dependency issues in having a class in
tools.jar
that would require the ant classes, due to
class loader delegation.
We are thinking about perhaps releasing a small jar that only contains the ant task for JDK6.
Please also note that the syntax of <xjc>
task is neither
defined in the JAXB spec nor in the JavaSE spec. Therefore other
JavaSE vendors may not implement that at all, or do so in a different
class name, etc. Therefore, from a portability perspective, if you
choose to depend on the <xjc>
task you should bundle the JAXB
RI.
This table captures the history of the JAXB RI integration into JDK. This is for information purposes only. In particular, the JAXB RI in JDK is package renamed to avoid any conflict with the stand-alone JAXB RI distribution or with the jaxb2-reflection library. You can use any version of these with any version of JDK without worrying about implementation conflicts.
JDK6 first release - JDK6 u3 | JAXB RI 2.0.3 |
JDK6 u4 | JAXB RI 2.1.3 |
JDK6 u14 | JAXB RI 2.1.10 |
JDK7 first release | JAXB RI 2.2.4-1 |
JDK8 first release | JAXB RI 2.2.8 (b130911.1802) |
JDK9 first release | JAXB RI 2.3.0 (b170531.0717) |
When you compile your sources files with JDK from Java6 and try
to run it on Java5 JVMs, you may see a ClassFormatError
at runtime like this:
main" java.lang.ClassFormatError: Illegal class modifiers in class com/alu/parentalcontrol/jaxb/package-info: 0x1600 at java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:620) at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:124) at java.net.URLClassLoader.defineClass(URLClassLoader.java:260) at java.net.URLClassLoader.access$100(URLClassLoader.java:56) at java.net.URLClassLoader$1.run(URLClassLoader.java:195) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(URLClassLoader.java:188) at java.lang.ClassLoader.loadClass(ClassLoader.java:306) at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:268) at java.lang.ClassLoader.loadClass(ClassLoader.java:251) at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:319) at java.lang.Class.forName0(Native Method) at java.lang.Class.forName(Class.java:242) at java.lang.Package.getPackageInfo(Package.java:350) at java.lang.Package.getAnnotation(Package.java:361) at com.sun.xml.bind.v2.model.annotation.RuntimeInlineAnnotationReader.getPackageAnnotation(RuntimeInlineAnnotationReader.java:125) at com.sun.xml.bind.v2.model.annotation.RuntimeInlineAnnotationReader.getPackageAnnotation(RuntimeInlineAnnotationReader.java:53) at com.sun.xml.bind.v2.model.impl.TypeInfoImpl.parseElementName(TypeInfoImpl.java:122) at com.sun.xml.bind.v2.model.impl.ClassInfoImpl.<init>(ClassInfoImpl.java:166)
This is due to a bug, and so far the only way to fix this is to compile your project with JavaSE 5.
Here is what's happening. Java5 added a new class file modifier
attribute called ACC_SYNTHETIC
, whose bit value is
0x1000. This attribute marks types and methods that are not present in
the source file but generated by the compiler. When
package-info.java
is compiled into
package-info.class
, javac in Java5 apparently only put
0x0600 (= ACC_ABSTRACT|ACC_INTERFACE
.) Some time during
Java6 development, someone filed a
bug, saying it should also include ACC_SYNTHETIC
bit, since it was a synthesized class.
Later it is discovered that the corresponding VM change needs to be made to allow this 0x1600 combination, but apparently no one realized the real implication of this --- namely, 0x1600 will break all the past JVMs. Of course, this problem is eventually discovered, but as of this writing there's still no fix for this.
So as you see, this is why the only workaround is to use javac from Java5.
The JAXBContext class is thread safe, but the Marshaller, Unmarshaller, and Validator classes are not thread safe.
For example, suppose you have a multi-thread server application that processes incoming XML documents by JAXB. In this case, for the best performance you should have just one instance of JAXBContext in your whole application like this:
Example 95. Singleton JAXBContext
class MyServlet extends HttpServlet { static final JAXBContext context = initContext(); private static JAXBContext initContext() { return JAXBContext.newInstance(Foo.class,Bar.class); } }
And each time you need to unmarshal/marshal/validate a document. Just create a new Unmarshaller/Marshaller/Validator from this context, like this:
Example 96. Thread local Unmarshaller
public void doGet( HttpServletRequest req, HttpServletResponse ) { Unmarshaller u = context.createUnmarshaller(); u.unmarshal(...); }
This is the simplest safe way to use the JAXB RI from multi-threaded applications.
If you really care about the performance, and/or your application is going to read a lot of small documents, then creating Unmarshaller could be relatively an expensive operation. In that case, consider pooling Unmarshaller objects. Different threads may reuse one Unmarshaller instance, as long as you don't use one instance from two threads at the same time.
The JAXB RI is shipped with an "experimental" DTD support, which let's you compile XML DTDs. It is marked "experimental" not because the feature is unstable nor unreliable, but rather because it's not a part of the JAXB specification and therefore the level of commitment to compatibility is lower.
All the other command-line options of the XJC binding compiler can be applied. Similarly, the XJC ant task supports DTD. The generated code will be no different from what is generated from W3C XML Schema. You'll use the same JAXB API to access the generated code, and it is portable in the sense that it will run on any JAXB 2.0 implementation.
DTD long predates XML namespace, although people since then developed various techniques to use XML namespaces in conjunction with DTD. Because of this, XJC is currently unable to reverse-engineer the use of XML namespace from DTD. If you compile DTDs that use those techniques, you'd either manuallly modify the generated code, or you can try a tool like Trang that can convert DTD into XML Schema in ways that better preserves XML namespaces.
The customization syntax for DTD is roughly based on the ver.0.21 working draft of the JAXB specification, which is available at xml.coverpages.org. The deviations from this document are:
The whitespace
attribute of the
conversion
element takes "
preserve
", " replace
", and "
collapse
" instead of " preserve
", "
normalize
", and " collapse
" as
specified in the document.
The interface
customization just generates
marker interfaces with no method.
Example 98. The following POM snippest describes how to invoke XJC to compile DTD from a Maven 2 project:
<plugin> <groupId>org.jvnet.jaxb2.maven2</groupId> <artifactId>maven-jaxb2-plugin</artifactId> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <!-- if you want to put DTD somewhere else <schemaDirectory>src/main/jaxb</schemaDirectory> --> <extension>true</extension> <schemaLanguage>DTD</schemaLanguage> <schemaIncludes> <schemaInclude>*.dtd</schemaInclude> </schemaIncludes> <bindingIncludes> <bindingInclude>*.jaxb</bindingInclude> </bindingIncludes> <args> <arg>-Xinject-listener-code</arg> </args> </configuration> </execution> </executions> <dependencies> <dependency> <groupId>org.jvnet.jaxb2-commons</groupId> <artifactId>property-listener-injector</artifactId> <version>1.0</version> </dependency> </dependencies> </plugin>
Example 99. The dependencies section inside the plugin element can be used to specify additional XJC plugins. If you'd like to use more recent version of the JAXB RI, you can specify a dependency to XJC here to do so, like this:
<dependency> <groupId>com.sun.xml.bind</groupId> <artifactId>jaxb-xjc</artifactId> <version>2.1.2</version> </dependency>
Occasionally, people try to define a custom protocol that allows multiple XML requests/responses to be sent over a single transport channel. This section discusses the non-trivial interaction between XML and sockets, and how you can design a protocol correctly.
XML1.0 requires a conforming parser to read the entire data till end
of the stream (because a parser needs to handle documents like
<root/><!-- post root comment -->
). As a result,
a naive attempt to keep one OutputStream
open and marshal
objects multiple times fails.
Example 100. One easy way to work around this limitation is to design your protocol so that the data on the wire will look like the following:
<conversation> <!-- message 1 --> <message> ... </message> <!-- message 2 --> <message> ... </message> ... </conversation>
The <conversation>
start tag is sent immediately after the
socket is opened. This works as a container to send multiple "messages",
and this is also an excellent opportunity to do the hand-shaking (e.g.,
protocol-version='1.0'
attribute.) Once the
<conversation>
tag is written, multiple messages can be marshalled
as a tree into the channel, possibly with a large time lag in between. You
can use the JAXB marshaller to produce such message. When the sender wants
to disconnect the channel, it can do so by sending the
</conversation>
end tag, followed by the socket
disconnection.
Of course, you can choose any tag names freely, and each message can have different tag names.
The receiver would use the StAX API and use
XMLStreamReader
to read this stream. You'd have to use this
to process the first <conversation>
start tag. After that, every
time you call a JAXB unmarshaller, you'll get the next message.
For the concrete code, see the xml-channel
example in
the JAXB RI distribution.
JAXB RI also provides an Ant task to run the binding complier - see the instructions for XJC Ant Task.
The binding compiler can be launched using the appropriate
xjc
shell script in the bin
directory for your platform.
Solaris/Linux
% /path/to/jaxb/bin/xjc.sh -help
Windows
> c:\path\to\jaxb\bin\xjc.bat -help
jaxb-xjc.jar
JAR
FileIf all else fails, you should be able to execute the
jaxb-xjc.jar
file:
Solaris/Linux
% java -jar $JAXB_HOME/lib/jaxb-xjc.jar -help
Windows
> java -jar %JAXB_HOME%\lib\jaxb-xjc.jar -help
This is equivalent of running xjc.sh or xjc.bat, and it allows you to set the JVM parameters.
xjc
[OPTION]... <schema file/URL/dir/jar> [-b
<binding>...]
Usage: xjc [-options ...] <schema file/URL/dir/jar> ... [-b <bindinfo>] ... If dir is specified, all schema files in it will be compiled. If jar is specified, /META-INF/sun-jaxb.episode binding file will be compiled. Options: -nv : do not perform strict validation of the input schema(s) -extension : allow vendor extensions - do not strictly follow the Compatibility Rules and App E.2 from the JAXB Spec -b <file/dir> : specify external bindings files (each <file> must have its own -b) If a directory is given, **/*.xjb is searched -d <dir> : generated files will go into this directory -p <pkg> : specifies the target package -httpproxy <proxy> : set HTTP/HTTPS proxy. Format is [user[:password]@]proxyHost:proxyPort -httpproxyfile <f> : Works like -httpproxy but takes the argument in a file to protect password -classpath <arg> : specify where to find user class files -catalog <file> : specify catalog files to resolve external entity references support TR9401, XCatalog, and OASIS XML Catalog format. -readOnly : generated files will be in read-only mode -npa : suppress generation of package level annotations (**/package-info.java) -no-header : suppress generation of a file header with timestamp -target (2.0|2.1) : behave like XJC 2.0 or 2.1 and generate code that doesn't use any 2.2 features. -encoding <encoding> : specify character encoding for generated source files -enableIntrospection : enable correct generation of Boolean getters/setters to enable Bean Introspection apis -disableXmlSecurity : disables XML security features when parsing XML documents -contentForWildcard : generates content property for types with multiple xs:any derived elements -xmlschema : treat input as W3C XML Schema (default) -relaxng : treat input as RELAX NG (experimental,unsupported) -relaxng-compact : treat input as RELAX NG compact syntax (experimental,unsupported) -dtd : treat input as XML DTD (experimental,unsupported) -wsdl : treat input as WSDL and compile schemas inside it (experimental,unsupported) -verbose : be extra verbose -quiet : suppress compiler output -help : display this help message -version : display version information -fullversion : display full version information Extensions: -Xinject-code : inject specified Java code fragments into the generated code -Xlocator : enable source location support for generated code -Xsync-methods : generate accessor methods with the 'synchronized' keyword -mark-generated : mark the generated code as @javax.annotation.Generated -episode : generate the episode file for separate compilation -Xpropertyaccessors : Use XmlAccessType PROPERTY instead of FIELD for generated classes
By default, the XJC binding compiler performs strict validation of the source schema before processing it. Use this option to disable strict schema validation. This does not mean that the binding compiler will not perform any validation, it simply means that it will perform less-strict validation.
By default, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. Appendix E.2 defines a set of W3C XML Schema features that are not completely supported by JAXB v1.0. In some cases, you may be allowed to use them in the "-extension" mode enabled by this switch. In the default (strict) mode, you are also limited to using only the binding customizations defined in the specification. By using the "-extension" switch, you will be allowed to use the Overview.
Specify one or more external binding files to
process. (Each binding file must have it's own -b
switch.) The syntax of the external
binding files is extremely flexible. You may have a
single binding file that contains customizations for
multiple schemas or you can break the customizations
into multiple bindings files:
xjc schema1.xsd schema2.xsd schema3.xsd -b bindings123.xjb xjc schema1.xsd schema2.xsd schema3.xsd -b bindings1.xjb -b bindings2.xjb -b bindings3.xjb
In addition, the ordering of the schema files and binding files on the command line does not matter.
By default, the XJC binding compiler will generate the Java content classes in the current directory. Use this option to specify an alternate output directory. The output directory must already exist, the XJC binding compiler will not create it for you.
Set the encoding name for generated sources,
such as EUC-JP or UTF-8. If -encoding
is
not specified, the platform default encoding is
used.
Specifying a target package via this command-line option overrides any binding customization for package name and the default package name algorithm defined in the specification.
Specify the HTTP/HTTPS proxy. The format is
[user[:password]@]proxyHost[:proxyPort]. The old -host
and -port
are still
supported by the RI for backwards compatibility, but
they have been deprecated.
Same as the -httpproxy
<proxy>
option, but it takes the
<proxy> parameter in a file, so that you can
protect the password (passing a password in the
argument list is not safe.)
Specify where to find client application class
files used by the <jxb:javaType>
and <xjc:superClass>
customizations.
Specify catalog files to resolve external entity
references. Supports TR9401, XCatalog, and OASIS XML
Catalog format. Please read the XML Entity and URI
Resolvers document or the
catalog-resolver
sample
application.
By default, the XJC binding compiler does not write-protect the Java source files it generates. Use this option to force the XJC binding compiler to mark the generated Java sources read-only.
Supress the generation of package level annotations into **/package-info.java. Using this switch causes the generated code to internalize those annotations into the other generated classes.
Supress the generation of a file header comment
that includes some note and timestamp. Using this
makes the generated code more
diff
-friendly.
Avoid generating code that relies on any JAXB 2.1|2.2 features. This will allow the generated code to run with JAXB 2.0 runtime (such as JavaSE 6.)
treat input schemas as W3C XML Schema (default). If you do not specify this switch, your input schemas will be treated as W3C XML Schema.
Treat input schemas as RELAX NG (experimental, unsupported). Support for RELAX NG schemas is provided as a Overview.
Treat input schemas as RELAX NG compact syntax(experimental, unsupported). Support for RELAX NG schemas is provided as a Overview.
Treat input schemas as XML DTD (experimental, unsupported). Support for RELAX NG schemas is provided as a Overview.
Treat input as WSDL and compile schemas inside it (experimental,unsupported).
Suppress compiler output, such as progress information and warnings..
Be extra verbose, such as printing informational messages or displaying stack traces upon some errors..
Display a brief summary of the compiler switches.
Display the compiler version information.
Specify one or more schema files to compile. If you specify a directory, then xjc will scan it for all schema files and compile them.
This feature causes the generated code to expose SAX Locator information about the source XML in the Java bean instances after unmarshalling.
This feature causes all of the generated method signatures to include the synchronized keyword.
This feature causes all of the generated code to
have
@Generated
annotation.
Generate an episode file from this compilation, so that other schemas that rely on this schema can be compiled later and rely on classes that are generated from this compilation. The generated episode file is really just a JAXB customization file (but with vendor extensions.)
Annotate the @XmlAccessorType
of generated classes with XmlAccessType PROPERTY
instead of FIELD
These options have been deprecated and replaced with the -httpproxy option. For backwards compatibility, we will continue to support these options, but they will no longer be documented and may be removed from future releases.
Since the JAXB 2.0 specification has defined a portable runtime, it is no longer necessary for the JAXB RI to generate **/impl/runtime packages. Therefore, this switch is obsolete and has been removed.
In general, it is safest to compile all related schemas as a single unit with the same binding compiler switches.
Please keep the following list of restrictions in mind when running xjc. Most of these issues only apply when compiling multiple schemas with multiple invocations of xjc.
To compile multiple schemas at the same time, keep the following precedence rules for the target Java package name in mind:
The -p
command line option
takes the highest precedence.
<jaxb:package>
customization
If targetNamespace
is declared,
apply targetNamespace
-> Java
package name algorithm defined in the
specification.
If no targetNamespace
is
declared, use a hardcoded package named
"generated".
It is not legal to have more than one <
jaxb:schemaBindings
> per namespace, so it is
impossible to have two schemas in the same target namespace
compiled into different Java packages.
All schemas being compiled into the same Java package must be submitted to the XJC binding compiler at the same time - they cannot be compiled independently and work as expected.
Element substitution groups spread across multiple schema files must be compiled at the same time.
XJC produces a set of packages containing Java source files and
also jaxb.properties
files, depending on the binding
options you used for compilation. When generated,
jaxb.properties
files must be kept with the compiled
source code and made available on the runtime classpath of your client
applications:
The jaxb-xjc.jar
file contains the
XJCTask.class
file, which allows the XJC binding
compiler to be invoked from the Ant build tool. To
use XJCTask
, include the following statement in
your build.xml
file:
<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask"> <classpath> <fileset dir="path/to/jaxb/lib" includes="*.jar"/> </classpath> </taskdef>
This maps XJCTask
to an Ant task named
xjc
. For detailed examples of using this task,
refer to any of the build.xml
files used by the Sample Apps.
ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.
xjc
supports the following parameter
attributes.
Attribute | Description | Required |
---|---|---|
| A schema file to be compiled. A file name (can be relative to the build script base directory), or an URL. | This or nested <
|
| An external binding file that will be applied to the schema file. | No |
| If specified, generated code will be placed under this Java package. This option is equivalent to the "-p" command-line switch. | No |
| Generated code will be written under
this directory. If you specify
| Yes |
| Set the encoding name for generated sources, such as EUC-JP or UTF-8. If it is not specified, the platform default encoding is used. | No |
| Generate Java source files in the
read-only mode if | No |
| Generate a header in each generated
file indicating that this file is generated by such
and such version of JAXB RI when.
| No |
| If set to | No |
| Specify the catalog file to resolve external entity references. Support TR9401, XCatalog, and OASIS XML Catalog format. See the catalog-resolver sample for details. | No |
| Used in pair with nested
| No |
| Specifies the runtime environment in which the generated code is supposed to run. Expects 2.0 or 2.1 values. This allows more up-to-date versions of XJC to be used for developing applications that run on earlier JAXB versions. | No, defaults to "2.2" |
| Specifies the schema language to compile. Supported values are "WSDL", "XMLSCHEMA", and "WSDL." Case insensitive. | No, defaults to "XMLSCHEMA" |
xjc
supports the following nested element
parameters.
schema
To compile more than one schema at the same time, use a
nested <schema>
element, which has
the same syntax as
<fileset>
.
binding
To specify more than one external binding file at the
same time, use a nested <binding>
element, which has the same syntax as
<fileset>
.
classpath
To specify locations of the user-defined classes
necessary during the compilation (such as an user-defined type
that is used through a <javaType>
customization), use nested
<classpath>
elements. For the syntax,
see "path-like
structure" .
arg
Additional command line arguments passed to the XJC. For details about the syntax, see the relevant section in the Ant manual. This nested element can be used to specify various options not natively supported in the xjc Ant task. For example, currently there is no native support for the following xjc command-line options:
-nv
-use-runtime
-schema
-dtd
-relaxng
-Xlocator
-Xsync-methods
To use any of these features from the
<xjc>
Ant task, you must specify the
appropriate nested < arg
> elements.
depends
Files specified with this nested element will be taken
into account when the XJC task does the up-to-date check. See
the up-to-date check section for details. For the syntax, see
<fileset>
.
produces
Files specified with this nested element will be taken
into account when the XJC task does the up-to-date check. See
the up-to-date check section for details. For the syntax, see
<fileset>
.
xmlcatalog
The xmlcatalog element is used to resolve entities when parsing schema documents.
Please see the Generated Resource Files for more detail.
By default, the XJC binding compiler always compiles the inputs. However, with a little additional setting, it can compare timestamps of the input files and output files and skip compilation if the files are up-to-date.
Ideally, the program should be able to find out all the inputs
and outputs and compare their timestamps, but this is difficult and
time-consuming. So you have to tell the task input files and output
files manually by using nested <depends>
and
<produces>
elements. Basically, the XJC
binding compiler compares the timestamps specified by the
<depends>
elements against those of the
<produces>
set. If any one of the "depends"
file has a more recent timestamp than some of the files in the
"produces" set, it will compile the inputs. Otherwise it will skip the
compilation.
This will allow you to say, for example "if any of the
.xsd
files in this directory are newer than the
.java
files in that directory, recompile the
schema".
Files specified as the schema files and binding files are
automatically added to the "depends" set as well, but if those schemas
are including/importing other schemas, you have to use a nested
<depends>
elements. No files are added to the
<produces>
set, so you have to add all of
them manually.
A change in a schema or an external binding file often results
in a Java file that stops being generated. To avoid such an "orphan"
file, it is often desirable to isolate all the generated code into a
particular package and delete it before compiling a schema. This can
be done by using the removeOldOutput
attribute.
This option allows you to remove all the files that match the
"produces" filesets before a compilation. Be careful when
you use this option so that you don't delete important
files.
This release of the JAXB RI includes experimental support for
RELAX NG, DTD, and WSDL. To compile anything other than W3C XML Schema
from the xjc Ant task, you must use the nested <
arg
> element to specify the appropriate command line
switch, such as -dtd
, -relaxng
, or -wsdl
. Otherwise, your input schemas will be treated as
W3C XML Schema and the binding compiler will fail.
Compile myschema.xsd
and place the generated
files under src/org/acme/foo:
<xjc schema="src/myschema.xsd" destdir="src" package="org.acme.foo"/>
Compile all XML Schema files in the src
directory and place the generated files under the appropriate packages
in the src
directory:
<xjc destdir="src"> <schema dir="src" includes="*.xsd"/> </xjc>
Compile all XML Schema files in the src
directory together with binding files in the same directory and places
the generated files under the appropriate packages in the
src
directory. This example assumes that binding
files contain package customizations. This example doesn't search
subdirectories of the src
directory to look for
schema files.
<xjc destdir="src"> <schema dir="src" includes="*.xsd"/> <binding dir="src" includes="*.xjb"/> </xjc>
Compile abc.xsd
with an up-to-date check.
Compilation only happens when abc.xsd
is newer than
any of the files in the src/org/acme/foo
directory
(and its impl
subdirectory). Files in these two
directories will be wiped away before a compilation, so
don't add your own code in those directories.
Note that the additional mkdir
task is necessary
because Ant's fileset requires the directory specified by the
dir
attribute to exist.
<mkdir dir="src/org/acme/foo"/> <xjc destdir="src" schema="abc.xsd" removeOldOutput="yes" package="org.acme.foo"> <produces dir="src/org/acme/foo" includes="* impl/*"/> </xjc>
More complicated example of up-to-date check. In this example, we assume that you have a large set of schema documents that reference each other, with DTDs that describe the schema documents. An explicit <depends> is necessary so that when you update one of the DTDs, XJC will recompile your schema. But <depends> don't have to re-specify all the schema files, because you've already done that via <schema>.
<mkdir dir="src/org/acme/foo"/> <xjc destdir="src" removeOldOutput="yes" package="org.acme.foo"> <schema dir="schema" includes="*.xsd"/> <depends dir="schema" includes="*.dtd"/> <produces dir="build/generated-src/org/acme/foo" includes="**/*"/> </xjc>
Compile all XML Schema files in the src
directory and subdirectories, excluding files named
debug.xsd
, and place the generated files under the
appropriate packages in the src
directory. This
example also specifies the -nv
option, which disables
the strict schema correctness checking:
<xjc destdir="src"> <schema dir="src" includes="**/*.xsd" excludes="**/debug.xsd"/> <arg value="-nv"/> </xjc>
If you depend on a proxy server to resolve the location of
imported or included schemas (as you might if you're behind a
firewall), you need to make the hostname and port number accessible to
the JVM hosting ant
. Do this by setting the
environment variable ANT_OPTS
to a string
containing the appropriate java
options. For
example, from DOS:
> set ANT_OPTS=-Dhttp.proxyHost=webcache.east > set ANT_OPTS=%ANT_OPTS% -Dhttp.proxyPort=8080 > ant
The current schema generator can process either Java source files or class files.
We also provide an Ant task to run the schema generator - see the instructions for SchemaGen Ant Task.
The schema generator can be launched using the appropriate
schemagen
shell script in the
bin
directory for your platform.
If your java sources/classes reference other classes, they must
be accessable on your system CLASSPATH environment variable, or they
need to be given to the tool by using the -classpath
/
-cp
options. Otherwise you will see errors when
generating your schema.
Solaris/Linux
% path/to/jaxb/bin/schemagen.sh Foo.java Bar.java ... Note: Writing schema1.xsd
Windows
> path\to\jaxb\bin\schemagen.bat Foo.java Bar.java ... Note: Writing schema1.xsd
schemagen
[OPTION]... <java files>
Usage: schemagen [-options ...] <java files> Options: -d <path> : Specify where to place processor and javac generated class files -cp <path> : Specify where to find user specified files -classpath <path> : Specify where to find user specified files -episode <file> : generate episode file for separate compilation -version : display version information -help : Display this usage message
Generates the "episode file", which is really just a JAXB customization file (but with vendor extensions specific to the JAXB RI, as of 2.1.) When people develop additional schemas that depend on what this schemagen invocation produces, they can use this episode file to have their generated code refer to your classes.
The current schema generator simply creates a schema file for each namespace referenced in your Java classes. There is no way to control the name of the generated schema files at this time. Use SchemaGen Ant Task for that purpose.
The jaxb-xjc.jar
file contains the
SchemaGenTask.class
file, which allows the schema
generator to be invoked from the Ant build tool. To
use SchemaGenTask
, include the following statement
in your build.xml
file:
<taskdef name="schemagen" classname="com.sun.tools.jxc.SchemaGenTask"> <classpath> <fileset dir="path/to/jaxb/lib" includes="*.jar"/> </classpath> </taskdef>
This maps SchemaGenTask
to an Ant task named
schemagen
. For detailed examples of using this
task, refer to the build.xml
files used by the java to
schema Sample Apps.
ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.
schemagen
supports most of the attributes
defined by the
javac task, plus the following parameter attributes.
Attribute | Description | Required |
---|---|---|
| Base directory to place the generated schema files | No |
| Works just like the nested <classpath> element | No |
| If specified, generate an episode file in the specified name. For more about the episode file, see -episode. | No |
xjc
supports all the nested elements
defined by the
javac task, the following nested element parameters.
schema
Control the file name of the generated schema. This
element takes a mandatory namespace
attribute and
a mandaotry file
attribute. When this element is
present, the schema document generated for the specified
namespace will be placed in the specified file name.
The file name is interpreted as relative to the destdir attribute. In the absence of the destdir attribute, file names are relative to the project base directory. This element can be specified multiple times.
classpath
A path-like structure that represents the classpath. If your Java sources/classes depend on other libraries, they need to be available in the classpath.
Generate schema files from source files in the src
dir and place them in the build/schemas
directory.
<schemagen srcdir="src" destdir="build/schemas">
Compile a portion of the source tree.
<schemagen destdir="build/schemas"> <src path="src"/> <exclude name="Main.java"/> </schemagen>
Set schema file names.
<schemagen srcdir="src" destdir="build/schemas"> <schema namespace="http://myschema.acme.org/common" file="myschema-common.xsd"/> <schema namespace="http://myschema.acme.org/onion" file="myschema-onion.xsd"/> </schemagen>
If you are using Maven, JAXB jars are available in the java.net maven repository. This repository is synced with maven central, so usually you find all JAXB releases in maven central after ~ 1 day after java.net release.
Various people in the community have developed plugins for XJC that you can use today. These plugins allow you to enhance/alter the code generation of XJC in many different ways.
Lexi has developed the HyperJAXB3 project for RDBMS persistence support for the JAXB RI.
Table of Contents
This page contains information about vendor-specific features provided by the JAXB RI.
This document describes JAXB RI specific properties that affect the way that the JAXB runtime library behaves.
This document describes additional binding customizations that can be used to control the generated source code.
This document describes the JAXB RI's experimental support for W3C XML Schema features not currently described in the JAXB Specification as well as support for other schema languages (RELAX NG and DTD).
The JAXB RI provides additional Marshaller properties that are not defined by the JAXB specification. These properties allow you to better control the marshalling process, but they only work with the JAXB RI; they may not work with other JAXB providers.
Property name: | com.sun.xml.bind.namespacePrefixMapper |
Type: | com.sun.xml.bind.marshaller.NamespacePrefixMapper |
Default value: | null |
The JAXB RI provides a mechanism for users to control declarations of namespace URIs and what prefixes they will be bound to. This is the general procedure:
The application developer provides an implementation
of
com.sun.xml.bind.marshaller.NamespacePrefixMapper
.
This class is then set on the marshaller via the RI
specific property
com.sun.xml.bind.namespacePrefixMapper
.
Each time the marshaller sees a URI, it performs a callback on the mapper: "What prefix do you want for this namespace URI?"
If the mapper returns something, the marshaller will try to use it.
The
com.sun.xml.bind.marshaller.NamespacePrefixMapper
class has the following method that you need to implement:
/** * Implemented by the user application to determine URI -> prefix * mapping. * * This is considered as an interface, though it's implemented * as an abstract class to make it easy to add new methods in * a future. * * @author * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com) */ public abstract class NamespacePrefixMapper { private static final String[] EMPTY_STRING = new String[0]; /** * Returns a preferred prefix for the given namespace URI. * * This method is intended to be overrided by a derived class. * * <p> * As noted in the return value portion of the javadoc, there * are several cases where the preference cannot be honored. * Specifically, as of JAXB RI 2.0 and onward: * * <ol> * <li> * If the prefix returned is already in use as one of the in-scope * namespace bindings. This is partly necessary for correctness * (so that we don't unexpectedly change the meaning of QNames * bound to {@link String}), partly to simplify the marshaller. * <li> * If the prefix returned is "" yet the current {@link JAXBContext} * includes classes that use the empty namespace URI. This allows * the JAXB RI to reserve the "" prefix for the empty namespace URI, * which is the only possible prefix for the URI. * This restriction is also to simplify the marshaller. * </ol> * * @param namespaceUri * The namespace URI for which the prefix needs to be found. * Never be null. "" is used to denote the default namespace. * @param suggestion * When the content tree has a suggestion for the prefix * to the given namespaceUri, that suggestion is passed as a * parameter. Typicall this value comes from the QName.getPrefix * to show the preference of the content tree. This parameter * may be null, and this parameter may represent an already * occupied prefix. * @param requirePrefix * If this method is expected to return non-empty prefix. * When this flag is true, it means that the given namespace URI * cannot be set as the default namespace. * * @return * null if there's no prefered prefix for the namespace URI. * In this case, the system will generate a prefix for you. * * Otherwise the system will try to use the returned prefix, * but generally there's no guarantee if the prefix will be * actually used or not. * * return "" to map this namespace URI to the default namespace. * Again, there's no guarantee that this preference will be * honored. * * If this method returns "" when requirePrefix=true, the return * value will be ignored and the system will generate one. * * @since JAXB 1.0.1 */ public abstract String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix); /** * Returns a list of namespace URIs that should be declared * at the root element. * * <p> * By default, the JAXB RI 1.0.x produces namespace declarations only when * they are necessary, only at where they are used. Because of this * lack of look-ahead, sometimes the marshaller produces a lot of * namespace declarations that look redundant to human eyes. For example, * <pre><xmp> * <?xml version="1.0"?> * <root> * <ns1:child xmlns:ns1="urn:foo"> ... </ns1:child> * <ns2:child xmlns:ns2="urn:foo"> ... </ns2:child> * <ns3:child xmlns:ns3="urn:foo"> ... </ns3:child> * ... * </root> * </xmp></pre> * * <p> * The JAXB RI 2.x mostly doesn't exhibit this behavior any more, * as it declares all statically known namespace URIs (those URIs * that are used as element/attribute names in JAXB annotations), * but it may still declare additional namespaces in the middle of * a document, for example when (i) a QName as an attribute/element value * requires a new namespace URI, or (ii) DOM nodes as a portion of an object * tree requires a new namespace URI. * * <p> * If you know in advance that you are going to use a certain set of * namespace URIs, you can override this method and have the marshaller * declare those namespace URIs at the root element. * * <p> * For example, by returning <code>new String[]{"urn:foo"}</code>, * the marshaller will produce: * <pre><xmp> * <?xml version="1.0"?> * <root xmlns:ns1="urn:foo"> * <ns1:child> ... </ns1:child> * <ns1:child> ... </ns1:child> * <ns1:child> ... </ns1:child> * ... * </root> * </xmp></pre> * <p> * To control prefixes assigned to those namespace URIs, use the * {@link #getPreferredPrefix(String, String, boolean)} method. * * @return * A list of namespace URIs as an array of {@link String}s. * This method can return a length-zero array but not null. * None of the array component can be null. To represent * the empty namespace, use the empty string <code>""</code>. * * @since * JAXB RI 1.0.2 */ public String[] getPreDeclaredNamespaceUris() { return EMPTY_STRING; } /** * Similar to {@link #getPreDeclaredNamespaceUris()} but allows the * (prefix,nsUri) pairs to be returned. * * <p> * With {@link #getPreDeclaredNamespaceUris()}, applications who wish to control * the prefixes as well as the namespaces needed to implement both * {@link #getPreDeclaredNamespaceUris()} and {@link #getPreferredPrefix(String, String, boolean)}. * * <p> * This version eliminates the needs by returning an array of pairs. * * @return * always return a non-null (but possibly empty) array. The array stores * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent * the empty namespace URI and the default prefix. Null is not allowed as a value * in the array. * * @since * JAXB RI 2.0 beta */ public String[] getPreDeclaredNamespaceUris2() { return EMPTY_STRING; } /** * Returns a list of (prefix,namespace URI) pairs that represents * namespace bindings available on ancestor elements (that need not be repeated * by the JAXB RI.) * * <p> * Sometimes JAXB is used to marshal an XML document, which will be * used as a subtree of a bigger document. When this happens, it's nice * for a JAXB marshaller to be able to use in-scope namespace bindings * of the larger document and avoid declaring redundant namespace URIs. * * <p> * This is automatically done when you are marshalling to {@link XMLStreamWriter}, * {@link XMLEventWriter}, {@link DOMResult}, or {@link Node}, because * those output format allows us to inspect what's currently available * as in-scope namespace binding. However, with other output format, * such as {@link OutputStream}, the JAXB RI cannot do this automatically. * That's when this method comes into play. * * <p> * Namespace bindings returned by this method will be used by the JAXB RI, * but will not be re-declared. They are assumed to be available when you insert * this subtree into a bigger document. * * <p> * It is <b>NOT</b> OK to return the same binding, or give * the receiver a conflicting binding information. * It's a responsibility of the caller to make sure that this doesn't happen * even if the ancestor elements look like: * <pre><xmp> * <foo:abc xmlns:foo="abc"> * <foo:abc xmlns:foo="def"> * <foo:abc xmlns:foo="abc"> * ... JAXB marshalling into here. * </foo:abc> * </foo:abc> * </foo:abc> * </xmp></pre> * * @return * always return a non-null (but possibly empty) array. The array stores * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent * the empty namespace URI and the default prefix. Null is not allowed as a value * in the array. * * @since JAXB RI 2.0 beta */ public String[] getContextualNamespaceDecls() { return EMPTY_STRING; } }
See the Sample Apps sample application for a detailed example.
Property name: | com.sun.xml.bind.indentString |
Type: | java.lang.String |
Default value: | " " (four whitespaces) |
This property controls the string used for the indentation
of XML. An element of depth k will be
indented by printing this string k times.
Note that the "jaxb.formatted.output
" property
needs to be set to "true" for the formatting/indentation of the
output to occur. See the API documentation for
javax.xml.bind.Marshaller
interface for
details of this property.
Property name: | com.sun.xml.bind.characterEscapeHandler |
Type: | com.sun.xml.bind.marshaller.CharacterEscapeHandler |
Default value: | null |
By default, the marshaller implementation of the JAXB RI tries to escape characters so they can be safely represented in the output encoding (by using Unicode numeric character references of the form &#dddd;)
Unfortunately, due to various technical reasons, the default behavior may not meet your expectations. If you need to handle escaping more adroitly than the default manner, you can do so by doing the following:
Write a class that implements the
com.sun.xml.bind.marshaller.CharacterEscapeHandler
interface.
Create a new instance of it.
Set that instance to the Marshaller by using this property.
See the Sample Apps sample application for more details.
Property name: | com.sun.xml.bind.xmlDeclaration |
Type: | boolean |
Default value: | true |
This experimental JAXB RI 1.0.x property has been adopted as a standard in JAXB 2.0. The 2.0 RI will continue to support this property, but client code should be using the Marshaller.JAXB_FRAGMENT property instead. Please refer to the Marshaller javadoc for a complete description of the behavior.
In JAXB 2.0, calling:
marshaller.setProperty("com.sun.xml.bind.xmlDeclaration", true);
is equivalent to calling:
marshaller.setProperty(Marshaller.JAXB_FRAGMENT, true);
JAXB 1.0 generated code and clients will continue to work exactly the same on the JAXB 2.0 runtime as they did on the JAXB 1.0 runtime.
Enabling fragment marshalling could be useful if you are inserting the output of the XML into another XML.
Property name: | com.sun.xml.bind.xmlHeaders |
Type: | java.lang.String |
Default value: | null |
This property allows you to specify an XML preamble
(<?xml ...> declaration) and any additional PIs, comments,
DOCTYPE declaration that follows it. This property takes effect
only when you are marshalling to OutputStream
,
Writer
, or StreamResult
. Note that this
property interacts with the Marshaller.JAXB_FRAGMENT
property. If that property is untouched or set to false, then JAXB
would always write its XML preamble, so this property can be only
used to write PIs, comments, DOCTYPE, etc. On the other hand, if
it is set to true, then JAXB will not write its own XML preamble,
so this property may contain custom XML preamble.
Property name: | com.sun.xml.bind.XmlAccessorFactory |
Type: | boolean |
Default value: | false |
This property provides support for a custom com.sun.xml.bind.v2.runtime.reflect.Accessor implementation. It allows the user to control the access to class fields and properties.
In JAXB 2.1, set the property to enable:
marshaller.setProperty("com.sun.xml.bind.XmlAccessorFactory", true);
The JAXB RI provides additional customizations that are not defined by the JAXB specification. Note the following:
These features may only be used when the JAXB XJC
binding compiler is run in the -extension
mode.
All of the JAXB RI vendor extensions are defined in the
"http://java.sun.com/xml/ns/jaxb/xjc
"
namespace.
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. For more information, please refer to
section 6.1.1 of the JAXB Specification.
Extending a Common Super Class - Extending a Common Super Class
Extending a Common Super Interface - Extending a Common Super Interface
Enhanced <jaxb:javaType> - Enhanced <jaxb:javaType> customization
Experimental simpler & better binding mode - Experimental simpler & better binding mode
Alternative Derivation-by-restriction Binding Mode - Alternative derivation-by-restriction binding mode
Allow separate compilations to perform element substitutions - Allow separate compilations to perform element substitutions
The JAXB RI supports the use of schema
component designator as a means of specifying the
customization target (of all standard JAXB customizations as well
as vendor extensions explained below.) To use this feature, use
the scd
attribute on <bindings> element instead
of the schemaLocation
and node
attributes.
<bindings xmlns:tns="http://example.com/myns" xmlns="http://java.sun.com/xml/ns/jaxb" version="2.1"> <bindings ... scd="tns:foo"> <!-- this customization applies to the global element declaration --> <!-- 'foo' in the http://example.com/myns namespace --> <class name="FooElement"/> </bindings> <bindings ... scd="~tns:bar"> <!-- this customization applies to the global type declaration --> <!-- 'bar' in the http://example.com/myns namespace --> <class name="BarType"/> </bindings> </bindings>
Compared to the standard XPath based approach, SCD allows more robust and concise way of identifying a target of a customization. For more about SCD, refer to the scd example. Note that SCD is a W3C working draft, and may change in the future.
The <xjc:superClass>
customization allows
you to specify the fully qualified name of the Java class that is
to be used as the super class of all the generated implementation
classes. The <xjc:superClass>
customization can
only occur within your <jaxb:globalBindings>
customization on the <xs:schema>
element:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" jaxb:version="2.0"> <xs:annotation> <xs:appinfo> <jaxb:globalBindings> <xjc:superClass name="org.acme.RocketBooster"/> </jaxb:globalBindings> </xs:appinfo> </xs:annotation> ... </xs:schema>
In the sample above, the <xjc:superClass>
customization will cause all of the generated implementation
classes to extend the named class,
org.acme.RocketBooster
.
The <xjc:superInterface>
customization
allows you to specify the fully qualified name of the Java
interface that is to be used as the root interface of all the
generated interfaces. The <xjc:superInterface>
customization can only occur within your
<jaxb:globalBindings>
customization on the
<xs:schema>
element:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" jaxb:version="2.0"> <xs:annotation> <xs:appinfo> <jaxb:globalBindings> <xjc:superInterface name="org.acme.RocketBooster"/> </jaxb:globalBindings> </xs:appinfo> </xs:annotation> ... </xs:schema>
In the sample above, the
<xjc:superInterface>
customization will cause
all of the generated interfaces to extend the named interface,
org.acme.RocketBooster
.
The <xjc:javaType> customization can be used just like
the standard <jaxb:javaType> customization, except that it
allows you to specify an XmlAdapter
-derived
class, instead of parse&print method pair.
This customization can be used in all the places <jaxb:javaType> is used, but nowhere else:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" jaxb:version="2.0"> ... <xsd:simpleType name="LayerRate_T"> <xsd:annotation> <xsd:appinfo> <xjc:javaType name="org.acme.foo.LayerRate" adapter="org.acme.foo.LayerRateAdapter"/> </xsd:appinfo> </xsd:annotation> ... gory simple type definition here ... </xsd:simpleType> </xsd:schema>
In the above example, LayerRate_T
simple type
is adapted by org.acme.foo.LayerRateAdapter
, which
extends from XmlAdapter
.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" jaxb:version="2.0"> <xsd:annotation> <xsd:appinfo> <jaxb:globalBindings> <xjc:javaType name="org.acme.foo.MyDateType" xmlType="xsd:dateTime" adapter="org.acme.foo.MyAdapterImpl"/> </jaxb:globalBindings> </xsd:appinfo> </xsd:annotation> ... </xsd:schema>
In the above example, all the use of
xsd:dateTime
type is adapter by
org.acme.foo.MyAdapterImpl
to
org.acme.foo.MyDateType
This experimental binding mode can be enabled as a part of the global binding. See below:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" jaxb:version="2.0"> <xs:annotation> <xs:appinfo> <jaxb:globalBindings generateValueClass="false"> <xjc:simple/> </jaxb:globalBindings> </xs:appinfo> </xs:annotation> ... </xs:schema>
When enabled, XJC produces Java source code that are more concise and easier to use. Improvements include:
Some content model definitions, such as
A,B,A
, which used to cause an XJC compilation
error and required manual intervention, now compile out of
the box without any customization.
Some content model definitions that used to bind to a non-intuitive Java class now binds to a much better Java class:
<!-- schema --> <xs:complexType name="foo"> <xs:choice> <xs:sequence> <xs:element name="a" type="xs:int"/> <xs:element name="b" type="xs:int"/> </xs:sequence> <xs:sequence> <xs:element name="b" type="xs:int"/> <xs:element name="c" type="xs:int"/> </xs:sequence> </xs:choice> </xs:complexType>
// before class Foo { List<JAXBElement<Integer>> content; } // in <xjc:simple> binding class Foo { Integer a; int b; // notice that b is effectively mandatory, hence primitive Integer c; }
When repetable elements are bound, the method name will become plural.
<!-- schema --> <xs:complexType name="person"> <xs:sequence> <xs:element name="child" type="xs:string" maxOccurs="unbounded"/> <xs:element name="parent" type="xs:string" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>
// before public class Person { protected List<String> child; protected List<String> parent; } // in <xjc:simple> binding public class Person { protected List<String> children; protected List<String> parents; }
Once again, readers are warned that this is an experimental binding mode, and therefore the binding is subject to change in future versions of the JAXB RI without notice. Please send feedbacks on this binding to https://javaee.groups.io/g/metro
Normally, the JAXB specification requires that a derivation-by-restriction be mapped to an inheritance betwee n two Java classes. This is necessary to preserve the type hierarchy, but one of the downsides is that the derived class does not really provide easy-to-use properties that reflect the restricted content model.
This experimental <xjc:treatRestrictionLikeNewType> changes this behavior by not preserving the type inheritance to Java. Instead, it generates two unrelated Java classes, both with proper properties. For example, given the following schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" jaxb:extensionBindingPrefixes="xjc" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0" elementFormDefault="qualified"> <xs:annotation> <xs:appinfo> <jaxb:globalBindings> <xjc:treatRestrictionLikeNewType/> </jaxb:globalBindings> </xs:appinfo> </xs:annotation> <xs:complexType name="DerivedType"> <xs:complexContent> <xs:restriction base="ResponseOptionType"> <xs:sequence> <xs:element name="foo" type="xs:string"/> </xs:sequence> </xs:restriction> </xs:complexContent> </xs:complexType> <xs:complexType name="ResponseOptionType"> <xs:sequence> <xs:element name="foo" type="xs:string" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:schema>
The generated Derived
class will look like this
(comment and annotations removed for brevity):
public class DerivedType { protected String foo; public String getFoo() { return foo; } public void setFoo(String value) { this.foo = value; } }
In contrast, without this customization the
Derived
class would look like the following:
public class DerivedType extends ResponseOptionType { // it simply inherits List<String> ResponseOptionType.getFoo() }
In an attempt to make the generated code easier to use, the JAXB specification sometimes choose bindings based on how certain feature is used. One of them is element substitution feature. If no actual element substitution happens in the schema, JAXB assumes that the element is not used for substitution, and generates code that assumes it.
Most of the time this is fine, but when you expect other "extension" schemas to be compiled later on top of your base schema, and if those extension schemas do element substitutions, this binding causes a problem ( see example.)
<xjc:substitutable> customization is a work around for this issue. It explicitly tells XJC that a certain element is used for element substitution head, even though no actual substitution might be present in the current compilation. This customization should be attached in the element declaration itself, like this:
<xs:element name="Model" type="Model"> <xs:annotation> <xs:appinfo> <xjc:substitutable/> </xs:appinfo> </xs:annotation> </xs:element>
The JAXB RI is shipped with experimental DTD support, which lets you compile XML DTDs.
To compile a DTD test.dtd
, run the XJC
binding compiler as follows:
$ xjc.sh -dtd test.dtd
All the other command-line options of the XJC binding compiler can be applied. Similarly, the xjc ant task supports DTD. The generated code will be no different from what is generated from W3C XML Schema. You'll use the same JAXB API to access the generated code, and it is portable in the sense that it will run on any JAXB 2.0 implementation.
The customization syntax for DTD is roughly based on the ver.0.21 working draft of the JAXB specification, which is available at xml.coverpages.org. The deviations from this document are:
The whitespace
attribute of the
conversion
element takes "
preserve
", " replace
", and "
collapse
" instead of "
preserve
"," normalize
", and "
collapse
" as specified in the
document.
The interface
customization just
generates marker interfaces with no method.
This document describes how to write an XJC plugin to extend the code generation of XJC.
An XJC plugin participates in the code generation from a schema. It can define its own customizations that users can use to control it, it can access the code that the JAXB RI generates, it can generate additional classes/methods/fields/annotations/comments, and it can also replace some of the pluggability points in the compilation process, such as XML name -> Java name conversion.
As a show case of what a plugin can do, take a look at plugins hosted at JAXB2-commons.
To write a plugin, do the following simple steps.
Write a class, say, org.acme.MyPlugin
by extending com.sun.tools.xjc.Plugin
. See
javadoc for how to implement methods.
Write the name of your plugin class in a text file
and put it as
/META-INF/services/com.sun.tools.xjc.Plugin
in your jar file.
Users can then use your plugins by declaring an XJC ant task with your jar files.
<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask"> <classpath> <fileset dir="jaxb-ri/lib" includes="*.jar"/> <fileset dir="your-plugin" includes="*.jar"/> </classpath> </taskdef>
Although we will do our best to maintain the compatibility of the interfaces, it is still subject to change at this point.
1. JAXB 2.0 | |
Q: | Which version of J2SE does JAXB 2.0 require? |
A: | Java SE 6 or higher. |
Q: | Can I run my existing JAXB 1.0.x applications on the JAXB 2.0 runtime? |
A: | This is no longer supported. However, you should be able to deploy
|
Q: | What if I want to port my JAXB 1.0.x application to JAXB 2.0? |
A: | You need to recompile your schema with the newer JAXB 2.0 xjc and modify your application code to work with the new bindings. |
Q: | Are the JAXB runtime API's thread safe? |
A: | The JAXB Specification currently does not address
the thread safety of any of the runtime classes. In the
case of the Oracle JAXB RI, the
For example, suppose you have a multi-thread server
application that processes incoming XML documents by JAXB.
In this case, for the best performance you should have
just one instance of class MyServlet extends HttpServlet { static final JAXBContext context = initContext(); private static JAXBContext initContext() { return JAXBContext.newInstance("....", MyServlet.class.getClassLoader()); } } And each time you need to unmarshal/marshal/validate
a document. Just create a new
public void doGet(HttpServletRequest req, HttpServletResponse resp) { Unmarshaller u = context.createUnmarshaller(); u.unmarshal(...); } This is the simplest safe way to use the JAXB RI from multi-threaded applications. If you really care about the performance, and/or
your application is going to read a lot of small
documents, then creating |
Q: | Why can't I cast the unmarshalled object into the generated type. |
A: | When you invoke
With some applications, things get even more
complicated when the JAXB-generated code can be loaded by
either classloader. In this case,
The solution for both situations is to pass your curent class loader like this: JAXBContext.newInstance("aaa.bbb.ccc", this.getClass().getClassLoader()); In general, if you are writing code that uses JAXB, it is always better to explicitly pass in a class loader, so that your code will work no matter where it is deployed. |
Q: | Which jar files do I need to distribute with my application that uses the JAXB RI? |
A: | For JAXB 2.2.x: $JAXB_HOME/lib/jaxb-api.jar $JAXB_HOME/lib/jaxb-impl.jar |
Q: | How can I cause the |
A: | This functionality is not available from JAXB
directly, but you can configure an Apache Xerces-J
|
Q: | Can I access <xs:any/> as a DOM node? |
A: | In JAXB 2.0, <xs:any/> is handled correctly without any customization.
|
Q: | How do I find out which version of the JAXB RI I'm using? |
A: | Run the following command $ java -jar jaxb-xjc.jar -version Alternatively, each JAXB jar has version information
in its Manifest-Version: 1.0 Ant-Version: Apache Ant 1.8.2 Created-By: 1.6.0_29-b11 (Sun Microsystems Inc.) Specification-Title: Java Architecture for XML Binding Specification-Version: 2.2.6 Specification-Vendor: Oracle Corporation Implementation-Title: JAXB Reference Implementation Implementation-Version: 2.2.5-SNAPSHOT Implementation-Vendor: Oracle Corporation Implementation-Vendor-Id: com.sun Extension-Name: com.sun.xml.bind Build-Id: 02/09/2012 01:42PM (hudson) Class-Path: jaxb-api.jar |
Table of Contents
Exchanging Data with XML and JAXB, Part I and Part II by Jennie Hall