The JavaTM Architecture for XML Binding (JAXB) Version 1.0 Early-Access Release Specification Version 0.21 2001/5/30

This is an early-access release of Sun's implementation of JAXB, the Java Architecture for XML Binding. JAXB is being developed in the Java Community Process under JSR-31: XML Data Binding for the Java Platform.

Further information on JAXB, including the current working draft of the JAXB specification as well as an early draft of the JAXB user guide, may be found at http://java.sun.com/xml/jaxb.

Contents	Platform requirements
	Installation
	Running the schema compiler
	Limitations of this release

Please send comments, suggestions, bug reports, and other feedback via e-mail, in plain ASCII, to jaxb-feedback@java.sun.com.

JAXB requires an implementation of the Java 2 platform, Standard Edition, version 1.3 or later. See http://java.sun.com/j2se/1.3 for instructions on how to download Sun's J2SE implementation for Solaris, Linux, and Windows. You'll need the full J2SDK download, not just the runtime environment (J2RE), assuming that you want to compile the Java classes that are generated by the schema compiler.

This release is believed to work with releases in the 1.2 series of the Java 2 platform, but it has not been thoroughly tested on those releases. It will not work with any releases in the 1.1 series.

This release is known to work on both Solaris and Linux. We have not yet tested it on Windows, but we know of no reason why it should not also work on that platform. The only immediate obstacle to using this release on Windows is the fact that the xjc launcher script for the schema compiler is Unix-specific.

This release is distributed as a single compressed zip file. Unzipping this file will create a directory named jaxb-1.0-ea with the following contents:

bin/xjc	Shell-script launcher for the schema compiler
lib/jaxb-rt-1.0-ea.jar	Runtime library (the binding framework)
jaxb-xjc-1.0-ea.jar	Schema compiler
doc/release.html	Release notes (which you are reading now)
api/index.html	Specification for the runtime API (javadoc)
xjs.dtd	DTD for the binding language
examples	Example DTDs and binding schemas

Easy installation   The easiest way to install JAXB is to perform the following two steps:

1. Copy both jar files into the jre/lib/ext directory of a previously-installed J2SE distribution.

2. Copy the xjc script into your ~/bin directory. Uncomment the line beginning with #JAVA and change it, if necessary, to point to the actual location of your virtual machine.

These two actions make the xjc command available on your shell command line and install the jar files so that they're available to both the schema compiler and your derived classes.

Touchless installation   If you prefer not to modify anything then you can use JAXB directly from the unbundled release directory. The xjc script will find the jar files as long as they're in the adjacent lib directory. Perform the following three steps:

1. Define the environment variable JAVA_HOME to name the location of your previously-installed J2SE distribution, for example, /usr/local/jdk1.3.1.

2. Assuming that $DIR names the directory in which you unbundled the release, define a shell alias xjc that expands to $DIR/jaxb-1.0-ea/bin/xjc.

3. Define the environment variable CLASSPATH to have the value .:$DIR/jaxb-1.0-ea/lib/jaxb-rt-1.0-ea.jar.

The last step is required so that the virtual machine can locate the binding-framework classes when you attempt to run your derived classes.

Assuming that you've installed JAXB as above, you can generate a set of Java classes for an existing source DTD foo.dtd via the command

% xjc -roots foo foo.dtd

This command will create Java source files, in the current directory, that are derived from foo.dtd by applying the default binding-declaration rules. The -roots option tells the compiler that foo is the only element that will appear as a root element. This option is needed when you don't provide a binding schema because DTDs have no way of specifying root elements.

A custom binding schema can also be specified:

% xjc foo.dtd foo.xjs

In this case the -roots option is unnecessary and is in fact illegal.

A different output directory can be specified with the -d option:

% xjc foo.dtd foo.xjs -d dir

The xjc command also supports the familiar -version and -help options.

Once you've generated Java source files from your DTD and (optional) binding schema, compile them in the usual way with javac.

This early-access release is known to have the following limitations:

• The only supported schema language is the DTD sublanguage of the XML 1.0 Recommendation. A future revision of the specification, and a future version of this implementation, are expected to include support for the W3C XML Schema language.

• Error handling in the schema compiler is very primitive. The first failure during DTD parsing, binding-schema parsing, or code generation causes the compiler to exit immediately with an error message of sometimes-dubious quality. There is not yet any support for localized error messages.

• The schema compiler does not enforce all of the source constraints defined in the specification.

• The declaration of constructors in binding schemas is not yet supported.

• Element types with a content specification of ANY are not yet supported.

• The declaration of conversions in binding schemas is supported, but the DT4DTD conventions described in the specification are not yet implemented.

• The marshallable and unmarshallable options of the binding-schema <option> declaration are not yet implemented.

• Validation for general-content and rest properties is very incomplete; validation for model-based content properties is not quite complete. In general, derived classes generated by this release will validate some invalid documents, and when presented with invalid documents they may fail.

• Generated unmarshalling code always collapses whitespace; the schema compiler will ignore any attempt to specify a different whitespace policy, except for printing a warning message.

• The mutation methods in generated code invalidate content objects way too agressively.

• Defining an array property with a primitive base type will generate incorrect code that will not compile.

• The access methods for array properties derived from fixed or defaulted attributes do not copy the argument or returned array as required by the specification.

• When an enumeration attribute is bound to a property whose base type is not a typesafe enumeration, the property's set method does not check the validity of its argument.

• The values of string properties derived from attributes of type NMTOKEN or NMTOKENS are not checked to ensure that they only contain legal name-token characters.

• IDREF attributes work, but only when bound to simple reference properties; IDREFS attributes are not yet fully implemented.

• Properties derived from fixed attributes are not handled quite correctly.

• Derived classes contain some redundant code and state; in general the generated code is not (yet) very efficient.

• There is no xjc launcher for Windows.

There are, no doubt, other bugs and omissions. Please submit bug reports to jaxb-feedback@java.sun.com; be sure to include the output of xjc  -version as well as any relevant input files.

Copyright 2001 by Sun Microsystems, Inc.
All rights reserved