# JavaTM Architecture for XML Binding
Using XJC with Ant

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

The `jaxb-xjc.jar` file contains the `XJCTask.class` file, which allows the XJC binding compiler to be invoked from the Ant build tool. To use `XJCTask`, include the following statement in your `build.xml` file:

>     <taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
>       <classpath>
>         <fileset dir="../../lib" includes="*.jar" excludes="ant.jar"/>
>         <fileset dir="../../..">
>           <include name="jaxp/**/*.jar"/>
>           <include name="jwsdp-shared/lib/**/*.jar"/>
>         </fileset>
>       </classpath>
>     </taskdef>

This maps `XJCTask` to an Ant task named `xjc`. For detailed examples of using this task, refer to any of the `build.xml` files used by the sample applications.

## Synopsis

#### Environment Variables

- ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.

#### Parameter Attributes

`xjc` supports the following parameter attributes.

Attribute | Description | Required
schema | A schema file to be compiled | This or nested <`schema`> elements are required.
binding | An external binding file that will be applied to the schema file. | No
package | If specified, generated code will be placed under this Java package. This option is equivalent to the "-p" command-line switch. | No
target | Generated code will be written under this directory. If you specify `target="abc/def"` and `package="org.acme"`, then files are generated to `abc/def/org/acme`. | Yes
readonly | Generate Java source files in the read-only mode if `true` is specified. `false` by default. | No
extension | If set to `true`, the XJC binding compiler will run in the extension mode. Otherwise, it will run in the strict conformance mode. Equivalent of the "`-extension`" command line switch. The default is `false`. | No
stackSize | Specify the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher). The XJC binding compiler can fail to compile large schemas with `StackOverflowError` and, in that case, this option can be used to extend the stack size. If unspecified, the default VM size is used. The format is equivalent to the `-Xss` command-line argument for Sun Microsystems JVM. This value can be specified in bytes (`stackSize="2097152"`), kilobytes (`stackSize="2048kb"`), or megabytes (`stackSize="2mb"`). | No
catalog | Specify the catalog file to resolve external entity references. Support TR9401, XCatalog, and OASIS XML Catalog format. See the catalog-resolver sample and this article for details. | No
removeOldOutput | Used in pair with nested `<produces>` elements. When this attribute is specified as "`yes`", the files pointed to by the `<produces>` elements will be all deleted before the XJC binding compiler recompiles the source files. See the up-to-date check section for details. | No

`xjc` supports the following nested element parameters.

> ### schema

> To compile more than one schema at the same time, use a nested `<schema>` element, which has the same syntax as `<fileset>`.

> ### binding

> To specify more than one external binding file at the same time, use a nested `<binding>` element, which has the same syntax as `<fileset>`.

> ### classpath

> To specify locations of the user-defined classes necessary during the compilation (such as an user-defined type that is used through a `<javaType>` customization), use nested `<classpath>` elements. For the syntax, see "path-like structure" .

> ### arg

> Additional command line arguments passed to the XJC. For details about the syntax, see the relevant section in the Ant manual. This nested element can be used to specify various options not natively supported in the `xjc` Ant task. For example, currently there is no native support for the following `xjc` command-line options:

> - `-nv`
> - `-use-runtime`
> - `-schema`
> - `-dtd`
> - `-relaxng`
> - `-Xlocator`
> - `-Xsync-methods`

> To use any of these features from the `xjc>` Ant task, you must specify the appropriate nested <`arg`> elements.

> ### depends

> Files specified with this nested element will be taken into account when the XJC task does the up-to-date check. See the up-to-date check section for details. For the syntax, see `<fileset>`.

> ### produces

> Files specified with this nested element will be taken into account when the XJC task does the up-to-date check. See the up-to-date check section for details. For the syntax, see `<fileset>`.

## Generated Resource Files

Please see the xjc page for more detail.

## Up-to-date Check

By default, the XJC binding compiler always compiles the inputs. However, with a little additional setting, it can compare timestamps of the input files and output files and skip compilation if the files are up-to-date.

Ideally, the program should be able to find out all the inputs and outputs and compare their timestamps, but this is difficult and time-consuming. So you have to tell the task input files and output files manually by using nested `<depends>` and `<produces>` elements. Basically, the XJC binding compiler compares the timestamps specified by the `<depends>` elements against those of the `<produces>` set. If any one of the "depends" file has a more recent timestamp than some of the files in the "produces" set, it will compile the inputs. Otherwise it will skip the compilation.

This will allow you to say, for example "if any of the `.xsd` files in this directory are newer than the `.java` files in that directory, recompile the schema".

Files specified as the schema files and binding files are automatically added to the "depends" set as well, but if those schemas are including/importing other schemas, you have to use a nested `<depends>` elements. No files are added to the `<produces>` set, so you have to add all of them manually.

A change in a schema or an external binding file often results in a Java file that stops being generated. To avoid such an "orphan" file, it is often desirable to isolate all the generated code into a particular package and delete it before compiling a schema. This can be done by using the `removeOldOutput` attribute. This option allows you to remove all the files that match the "produces" filesets before a compilation. Be careful when you use this option so that you don't delete important files.

## Schema Language Support

This release of the JAXB RI includes experimental support for RELAX NG, DTD, and WSDL. To compile anything other than W3C XML Schema from the `xjc` Ant task, you must use the nested <`arg`> element to specify the appropriate command line switch, such as "`-dtd`", "`-relaxng`", or "`-wsdl`". Otherwise, your input schemas will be treated as W3C XML Schema and the binding compiler will fail.

## Examples

Compile `myschema.xsd` and place the generated files under `src/org/acme/foo`:

>     <xjc schema="src/myschema.xsd" target="src" package="org.acme.foo"/>

Compile all XML Schema files in the `src` directory and place the generated files under the appropriate packages in the `src` directory:

>     <xjc target="src">
>       <schema  dir="src" includes="*.xsd"/>
>     </xjc>

Compile all XML Schema files in the `src` directory together with binding files in the same directory and places the generated files under the appropriate packages in the `src` directory. This example assumes that binding files contain package customizations. This example doesn't search subdirectories of the `src` directory to look for schema files.

>     <xjc target="src">
>       <schema  dir="src" includes="*.xsd"/>
>       <binding dir="src" includes="*.xjb"/>
>     </xjc>

Compile `abc.xsd` with an up-to-date check. Compilation only happens when `abc.xsd` is newer than any of the files in the `src/org/acme/foo` directory (and its `impl` subdirectory). Files in these two directories will be wiped away before a compilation, so don't add your own code in those directories. Note that the additional `mkdir` task is necessary because Ant's fileset requires the directory specified by the `dir` attribute to exist.

>     <mkdir dir="src/org/acme/foo" />
>     <xjc target="src" schema="abc.xsd" removeOldOutput="yes" package="org.acme.foo">
>       <produces dir="src/org/acme/foo" includes="* impl/*" />
>     </xjc>

Compile all XML Schema files in the `src` directory and subdirectories, excluding files named `debug.xsd`, and place the generated files under the appropriate packages in the `src` directory. This example also specifies the "`-nv`" option, which disables the strict schema correctness checking:

>     <xjc target="src">
>       <schema dir="src" includes="**/*.xsd" excludes="**/debug.xsd"/>
>       <arg value="-nv" />
>     </xjc>

If you depend on a proxy server to resolve the location of imported or included schemas (as you might if you're behind a firewall), you need to make the hostname and port number accessible to the JVM hosting `ant`. Do this by setting the environment variable `ANT_OPTS` to a string containing the appropriate `java` options. For example, from DOS:

>     > set ANT_OPTS=-Dhttp.proxyHost=webcache.east
>     > set ANT_OPTS=%ANT_OPTS% -Dhttp.proxyPort=8080
>     > ant

$Revision: 1.1 $
$Date: 2008/11/03 06:51:11 $