JavaTM Architecture for XML Binding
Specification Version: 1.0
Reference Implementation (RI) Version: 1.0.2
This document contains information that should help you use this
software library more effectively. See the
for additional information.
The most up-to-date version of this document can be found
JavaTM WSDP Directory Structure
After installing the Java WSDP 1.3, you will find JAXB and its
dependent JAR files in the following directories:
bin <-- contains scripts to run the binding compiler
docs <-- contains release notes and useful information
samples <-- contains sample applications
lib <-- contains all of the JAXB specific jar files
lib <-- jaxp-api.jar
endorsed <-- sax.jar, dom.jar, xercesImpl.jar, xalan.jar
lib <-- jax-qname.jar, namespace.jar, xsdlib.jar, relaxngDatatype.jar
lib <-- ant.jar
JavaTM 2 Platform, Standard Edition
This release of the JAXB Reference Implementation requires J2SE SDK,
version 1.3.1 or higher.
Identifying the JAR Files
This release of JAXB is contained in several JAR files:
- JAXB jar files (contained in jwsdp-1.3/jaxb/lib)
- The javax.xml.bind interfaces and helper classes
- The JAXB RI binding compiler classes
- jaxb-impl.jar (formerly named jaxb-ri.jar)
- The JAXB RI binding runtime framework classes
- Supporting classes for the binding compiler and the binding
- JAXP jar files (contained in jwsdp-1.3/jaxp/lib and
javax.xml.transform components of JAXP
- The APIs and helper classes for the Simple API for XML (SAX)
- The APIs and helper classes for the Document Object Model (DOM)
- xercesImpl.jar (v2.3.0)
- The implementation classes for the SAX and DOM parsers, as well as
Xerces-specific implementations of the JAXP APIs
- Xalan is an XSLT processor for transforming XML documents into other document
- Other JAR files
- jax-qname.jar (contained in jwsdp-1.3/jwsdp-shared/lib)
- A class for handling QNames shared by several JAX* technologies
- namespace.jar (contained in jwsdp-1.3/jwsdp-shared/lib)
- Classes for handling XML namespace contexts shared by several JAX* technologies
- xsdlib.jar (contained in
- XML Schema type library shared by several JAX* technologies (formerly contained
- relaxngDatatype.jar (contained in
- RELAX NG datatype library shared by several JAX* technologies (formerly contained
- ant.jar (contained in apache-ant/lib)
- Ant 1.5.4
Using the Binding Compiler (XJC)
See the Binding Compiler documentation for full details
on using the XJC binding compiler.
Using the Runtime Binding Framework
To use the JAXB Runtime Binding Framework, you should follow these
- Develop 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 JAXB interfaces
- Set your CLASSPATH to include all of the JAR files
except for the ant.jar file.
- Compile all of your Java sources with the javac Java compiler.
- Run it!
For more information about this process, see the the
Java WSDP Tutorial
and the extensive sample application documentation.
Locating the Normative Binding Schema
You may find information about the normative binding schema defined in
See the changelog document for a
comprehensive list of changes between JAXB version 1.0.1 and version
Known Limitations of this Release
The following list summarizes the known limitations of this release
of the JAXB Reference Implementation.
- The JAXB Specification does not require full W3C XML Schema support in version
1.0. Please refer to Appendix E.2 for full details.
- Specifying large values for maxOccurs attributes can cause
- The @enableFailFastCheck optional customization of
<jaxb:globalBindings> is not implemented yet.
- Specifying HTML markup tags within <jaxb:javadoc> customizations
requires you to enclose the data within a CDATA section or escape all
left angle brackets using "<". See
XML 1.0 2nd
Edition for more detail. In addition, you must include <body> tags
when specifying javadoc under the <jaxb:package> customization.
- The RI has some difficulty handling fixed attributes. For example, the validator
does not detect errors when the XML data has a value different from the fixed
value defined for the attribute in the schema.
- The RI can fail to properly validate content trees with elements of date,
dateTime, and time. The reason for this is because these XML
Schema datatypes are mapped to java.util.Calender by default and there
are discrepancies over the number of fraction digits (always either three or zero
in Java but can be arbitrary in XML datatypes). In general, when you unmarshal a
lexical value and then marshal it back, you are not guaranteed to get the same
- Compilations of sufficiently large and/or complex schemas may fail with
java.lang.StackOverflowError. Try working around this problem by
increasing the native stack size. For example, to increase the stack size to 2 megabytes:
If you run out of memory, try increasing the maximum memory
size. For example, to increase the maximum memory to 128 megabytes:
- The runtime unmarshals instances containing invalid elements defined by wildcards.
- The JAXB Specification currently does not address the thread safety of any of
the runtime classes. In the case of the Sun JAXB RI, the JAXBContext
class is thread safe, but the Marshaller, Unmarshaller,
and Validator classes are not thread safe.
- In rare cases, you may see: "java.lang.Error: unable to load schema-for-schema
for W3C XML Schema" while attempting to compile your schemas.
If you see this error, try updating your version of J2SE SDK.
- If you are getting error messages like:
[ERROR] Unable to load "CustomString" Is this class available in the classpath?
line 15 of test.xsd
Make sure that the classes you are referencing in your <jxb:javaType> and
<xjc:superClass> customizations are compiled and added to the classpath
via the "-classpath" command-line option for the
- A new list of compiler
restrictions has been added to the binding compiler documentation.
- Under certain conditions, xjc may give this warning:
Unable to validate your schema. Most likely,
the JVM has loaded an incompatible XML parser
implementation. You should fix this before
relying on the generated code.
Please see the release notes for details.
The usual condition is that a version of xercesImpl.jar (as might be bundled
with ant, an IDE, or an AppServer e.g.) is in your CLASSPATH before the one
shipped with the Java WSDP. This deters xjc from resolving dependencies it has
on internal Xerces APIs. In previous releases of JAXB, this error condition
would manifest itself as an IllegalAccessError.
To fix this, make sure jwsdp-1.3/jaxp/lib/endorsed/xercesImpl.jar
precedes any other version of Xerces in your CLASSPATH. Otherwise, xjc can't
validate your schema and you shouldn't rely on the generated code.
- The fact that javax.xml.bind.util.JAXBSource derives
from javax.xml.transform.sax.SAXSource is an implementation detail. Thus in
general applications are strongly discouraged from accessing methods defined on
SAXSource. In particular, the setXMLReader and setInputSource
methods shall never be called. The XMLReader object obtained by the
getXMLReader method shall be used only for parsing the InputSource
object returned by the getInputSource method. Similarly the InputSource
object obtained by the getInputSource method shall be used only for being
parsed by the XMLReader object returned by the getXMLReader.
For javax.xml.bind.util.JAXBResult, applications are strongly discouraged
from accessing methods defined on javax.xml.transform.sax.SAXResult. In
particular it shall never attempt to call the setHandler,
setLexicalHandler, and setSystemId methods.
These limitations will be incorporated into the next version of the javadocs
$Revision: 1.41 $
$Date: 2003/09/15 15:22:29 $