JAXB 2.0 | Tools | JAXB 1.0.x | JAXB RI Extensions | JAXB Community |
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="path/to/jaxb/lib" includes="*.jar" /> </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.
xjc
supports the following parameter attributes.
Attribute | Description | Required |
schema | A schema file to be compiled. A file name (can be relative to the build script base directory), or an URL. | 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 |
destdir | 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 |
header | Generate a header in each generated file indicating that this file
is generated by such and such version of JAXB RI when.
true 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 |
catalog | Specify the catalog file to resolve external entity references. Support TR9401, XCatalog, and OASIS XML Catalog format. See the catalog-resolver sample 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 |
source | Specify which version of the schema compiler to use. Must be either "1.0", "2.0", or "2.1". The compiler will parse XML Schema and bind them according to the rules specified by the given version of the specification. Note that 2.1 is backward compatible with 2.0, so these two flags won't make any difference. | No, defaults to "2.1" |
target
![]() |
Specifies the runtime environment in which the generated code is supposed to run. This value must be smaller than the source attribute, if specified (IOW, you can't do source="1.0" target="2.0") This allows more up-to-date versions of XJC to be used for developing applications that run on earlier JAXB versions. | No, defaults to "2.1" |
language
![]() |
Specifies the schema language to compile. Supported values are "WSDL", "XMLSCHEMA", and "WSDL." Case insensitive | No, defaults to "XMLSCHEMA" |
xjc
supports the following nested element parameters.
To compile more than one schema at the same time, use a nested
<schema>
element, which has the same syntax as
<fileset>
.
To specify more than one external binding file at the same time, use a
nested
<binding>
element, which has the same syntax as
<fileset>
.
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"
.
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:
To use any of these features from the xjc> Ant task, you must specify the appropriate nested < arg> elements.
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>
.
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>
.
The xmlcatalog element is used to resolve entities when parsing schema documents.
Please see the xjc page for more detail.
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.
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.
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>
More complicated example of up-to-date check. In this example, we assume that you have a large set of schema documents that reference each other, with DTDs that describe the schema documents. An explicit <depends> is necessary so that when you update one of the DTDs, XJC will recompile your schema. But <depends> don't have to re-specify all the schema files, because you've already done that via <schema>.
<mkdir dir="src/org/acme/foo" /> <xjc target="src" removeOldOutput="yes" package="org.acme.foo"> <schema dir="schema" includes="*.xsd" /> <depends dir="schema" includes="*.dtd" /> <produces dir="build/generated-src/org/acme/foo" includes="**/*" /> </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