# JavaTM Architecture for XML Binding
Release Notes

Specification Version: 1.0
Reference Implementation (RI) Version: 1.0.6

Main: Release Notes | XJC | Ant task | Sample Apps | Changelog
JAXB RI Extensions: Runtime Properties | XJC Customizations
JAXB RI Schema Languages: W3C XML Schema | RELAX NG | DTD
JAXB Community: Java.net Homepage | Developer interest list | FAQ

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.

## Directory Structure

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

                 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 jar files

## 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
>   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
>   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
>     A class for handling QNames shared by several JAX* technologies
>   namespace.jar
>     Classes for handling XML namespace contexts shared by several JAX* technologies
>   xsdlib.jar
>     XML Schema type library shared by several JAX* technologies (formerly contained in `jaxb-libs.jar`)
>   relaxngDatatype.jar
>     RELAX NG datatype library shared by several JAX* technologies (formerly contained in `jaxb-libs.jar`)
>   ant.jar
>     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 in the latest release of JAXB.

## Known Limitations of this Release

The following list summarizes the known limitations of this release of the JAXB Reference Implementation.

Think you've found a new bug? File an issue on java.net!

- 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. 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 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/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.1 $
$Date: 2008/11/03 06:51:11 $