JavaTM Architecture for XML Binding
Release Notes

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 JAXB FAQ for additional information.

The most up-to-date version of this document can be found on-line.

JavaTM WSDP Directory Structure

After installing the Java WSDP 1.3, you will find JAXB and its dependent JAR files in the following directories:

         jwsdp-1.3
             jaxb
                 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
             jaxp
                 lib            <-- jaxp-api.jar
                    endorsed    <-- sax.jar, dom.jar, xercesImpl.jar, xalan.jar
             jwsdp-shared
                 lib            <-- jax-qname.jar, namespace.jar, xsdlib.jar, relaxngDatatype.jar
             apache-ant
                 lib            <-- ant.jar

JavaTM 2 Platform, Standard Edition (J2SETM) Requirements

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)
jaxb-api.jar
The javax.xml.bind interfaces and helper classes
jaxb-xjc.jar
The JAXB RI binding compiler classes
jaxb-impl.jar (formerly named jaxb-ri.jar)
The JAXB RI binding runtime framework classes
jaxb-libs.jar
Supporting classes for the binding compiler and the binding runtime framework
JAXP jar files (contained in jwsdp-1.3/jaxp/lib and jwsdp-1.3/jaxp/lib/endorsed)
jaxp-api.jar
The javax.xml.parsers and javax.xml.transform components of JAXP
sax.jar
The APIs and helper classes for the Simple API for XML (SAX)
dom.jar
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.jar
Xalan is an XSLT processor for transforming XML documents into other document types
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 jwsdp-1.3/jwsdp-shared/lib)
XML Schema type library shared by several JAX* technologies (formerly contained in jaxb-libs.jar)
relaxngDatatype.jar (contained in jwsdp-1.3/jwsdp-shared/lib)
RELAX NG datatype library shared by several JAX* technologies (formerly contained in jaxb-libs.jar)
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 general steps:

  1. Develop your schema.
  2. Annotate the schema with binding customizations if necessary (or place them in an external bindings file).
  3. Compile the schema with the XJC binding compiler.
  4. Develop your JAXB client application using the Java content classes generated by the XJC binding compiler along with the javax.xml.bind JAXB interfaces
  5. Set your CLASSPATH to include all of the JAR files except for the ant.jar file.
  6. Compile all of your Java sources with the javac Java compiler.
  7. 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 the JAXB Specification at http://java.sun.com/xml/ns/jaxb.

Changelog

See the changelog document for a comprehensive list of changes between JAXB version 1.0.1 and version 1.0.2.

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 java.lang.OutOfMemoryError
  • 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 "&lt;". 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 representation.
  • 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:
    java -Xss2m
    If you run out of memory, try increasing the maximum memory size. For example, to increase the maximum memory to 128 megabytes:
    java -Xmx128m
  • 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 xjc command.
  • 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 $