Java^TM Architecture for XML Binding
Release Notes

This document contains installation instructions and other notes that may help you use this software library more effectively. See also the JAXB FAQ for more information.

Installation

After downloading the JAXB distribution and uncompressing it, you should have the following directory layout:

         <jaxb-1.0-beta>
             bin            <-- contains scripts to run the binding compiler and ant
             docs           <-- contains user's guide, javadocs, and release notes
             examples       <-- contains sample applications
             lib            <-- contains all of the jar files necessary to use JAXB
    

Java^TM 2 Platform, Standard Edition (J2SE^TM) Requirements

This release of the JAXB RI requires at least J2SE1.3.1

Identifying the JAR Files

This beta 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-ri.jar

The JAXB RI binding runtime framework classes

jaxb-libs.jar

Supporting classes for the binding compiler and the binding runtime framework

JAXP 1.2 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

The implementation classes for the SAX and DOM parsers, as well as Xerces-specific implementations of the JAXP APIs

Other jar files

jax-qname.jar

A class for handling QName's shared by several JAX* Technologies

ant.jar

Ant 1.5

Using the Binding Compiler (XJC)

Launching xjc

The binding compiler can be launched using the appropriate xjc shell script in the bin directory for your platform.

For Solaris/Linux

1. % export JAVA_HOME=<your J2SE installation directory>
2. % export JAXB_HOME=<your JAXB installation directory>
3. % $JAXB_HOME/bin/xjc.sh -help

     Usage: xjc [-options ...] <schema> 
     Options:
       -nv      :  do not perform strict validation of the input schema(s)
       -d <dir> :  generated files will go into this directory
       -p <pkg> :  specifies the target package
       -readOnly:  generated files will be in read-only mode
       -help    :  display this help message
                 

For WindowsNT/2000/XP

1. > set JAVA_HOME="<your J2SE installation directory>"
2. > set JAXB_HOME="<your JAXB installation directory>"
3. > %JAXB_HOME%\bin\xjc.bat -help

  Usage: xjc [-options ...] <schema> 
  Options:
    -nv      :  do not perform strict validation of the input schema(s)
    -d <dir> :  generated files will go into this directory
    -p <pkg> :  specifies the target package
    -readOnly:  generated files will be in read-only mode
    -help    :  display this help message
	          

Execute the Jar File

If all else fails, you should be able to execute the jaxb-xjc.jar:

For Solaris/Linux:

% java -jar $JAXB_HOME/lib/jaxb-xjc.jar -help

For Windows:

> java -jar %JAXB_HOME%\lib\jaxb-xjc.jar -help

Summary of Command Line Options

-nv

By default, xjc 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.

-d <dir>

By default, xjc 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, xjc will not create it for you.

-p <pkg>

Specifying a target package via this command line option over-rides any binding customization for package name and the default package name algorithm defined in the specification.

-readOnly

By default, xjc does not write-protect the Java source files it generates. Use this option to force xjc to mark the generated Java sources read-only.

Specifying Schemas to Compile

In order to compile a single schema, simply list it on the xjc command line.

When compiling multiple schemas at the same time, please keep in mind the following precedence rules for the target Java package name:

1. The "-p" command line option takes the highest precedence
2. <jaxb:package> customization
3. if targetNamespace declared, apply targetNamespace -> Java package name alogirthm defined in the specification
4. if no targetNamespace declared, use a hardcoded package named "generated"

Also keep in mind that 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.

The only other thing to keep in mind about compiling multiple schemas is that all schemas being compiled into the same Java package must be submitted to xjc at the same time - they can not be compiled idependently and work as expected.

Using the Runtime Binding Framework

In order 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
3. Compile the schema with xjc
4. Develop your JAXB client application using Java content classes generated by xjc along with the javax.xml.bind JAXB interfaces
5. Set CLASSPATH
6. Compile all of your java sources with javac
7. Run it!

For more details on this process, please refer to the User's Guide

For the specific details of setting classpath and compiling the java sources, please refer to the Sample Apps 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.

Known Limitations of this Release

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