Table of Contents
This chapter is more formal and can be assumed to be the JaxMe reference documentation.
The JaxMe Ant task was written with the following goals in mind:
A typical use of the Ant task looks like this:
<target name="taskdef">
<taskdef name="xjc"
classname="org.apache.ws.jaxme.generator.XJCTask"
classpathref="generate.class.path"/>
</target>
<target name="generate" depends="taskdef">
<xjc schema="schema.xsd" target="build/src">
<produces includes="com/acme/*.java"/>
</xjc>
</target>
A target (called "taskdef" above) defines the ant task under a given name ("xjc" in the above example). It is important to remember to include the JaxMe jars in the classpath when defining the task. This task is then called by the source generation target.
The ant task supports the following attributes:
Table 2.1. Attributes of the JaxMe ant task
| Name | Description | Origin | Required/Default |
|---|---|---|---|
| binding | Name of an external binding file being applied to the schema file. This attribute and the nested <binding> element are mutually exclusive. As of this writing, external schema bindings are unsupported by JaxMe. A BuildException is thrown, if you use this attribute anyways. | JAXB XJC | No |
| extension | If this attribute has the value "true", then the XJC binding compiler will run in the extension mode. Otherwise, it will run in the strict conformance mode. Extension mode indicates that the proprietary "xjc" tags (specific to the JAXB binding compiler) are accepted. | JAXB XJC | No, defaults to "false" |
| force | Setting this option to "true" forces the up-to-date check to fail (and so the nested <produces> elements are ignored). This attribute isn't of much use to the JaxMe user. It is mainly intended for JaxMe developers who want to specify a value from the command line. This is useful when they have updated the schema compiler and want to run against the old schema with the new version. | JaxMe | No, defaults to "false" |
| package | Specifies the package name of the generated sources. If this attribute is specified, then it overrides any values specified in the schema bindings. | JAXB XJC | No, defaults to values specified in the schema bindings or to a package name derived from the target namespace URI. |
| schema | Name of a schema file being compiled. This attribute and the nested <schema> element are mutually exclusive. | JAXB XJC | Yes, unless a nested <schema> element is present |
| readonly | If this attribute has the value "true" then the generated source files will have read-only mode. | JAXB XJC | No, defaults to "false" |
| removeOldOutput | If one or more nested <produces> elements are specified and this attribute is
set to "true", then the Ant task will ensure that only generated files will remain. In other
words, if you had removed an element named "Foo" from the previous schema version, then the
Ant task will remove Note, that this behaviour is slightly different from the JAXB ant task "xjc", which removes all files matched by any <produces> element, before running the binding compiler. | JAXB XJC | No, defaults to "false" |
| stackSize | Specifies 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"). This attribute is ignored by the JaxMe ant task and present for compatibility reasons only. A warning is emitted, if you use it. | JAXB XJC | No |
| resourceTarget | Specifies the target directory for generating resource files.
If required, a package structure is created automatically below
the resource target directory. For example, if the "target" attribute
has the value "src" and the "package" attribute is "com.acme", then
the directory src/com/acme will be used.
| JaxMe | No, defaults to the "target" directory |
| target | Specifies the target directory for generating Java source files.
If required, a package structure is created automatically below
the resource target directory. For example, if the "target" attribute
has the value "src" and the "package" attribute is "com.acme", then
the directory src/com/acme will be used. | JAXB XJC | No, defaults to the current directory |
| validating | Depending on this attributes value, the XML parser used to parse the XML schema file will either be validating or not. | JaxMe | No, defaults to "false" |
The ant task also supports the following nested elements:
Table 2.2. Nested elements of the JaxMe ant task
| Name | Description | Origin | Multiplicity |
|---|---|---|---|
| arg | This nested element is ignored by the JaxMe ant task and exists for JAXB compatibility only. If this element is present, a warning will be logged. In the case of JAXB it specifies additional command line arguments being 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 JAXB xjc Ant task. For example, currently there is no native support for the following xjc command-line options:
| JAXB XJC | 0..Unbounded |
| binding | Multiple external binding files may be specified. The element syntax is equivalent to a nested <fileset>. Use of a nested <binding> element is mutually exclusive with the use of a "binding" attribute. As of this writing, external schema bindings are unsupported by JaxMe. A BuildException is thrown if this attribute is used. | JAXB XJC | 0..Unbounded |
| classpath | This nested element specifies the classpath for loading user defined classes. For example, the schema reader specified by the "schemaReader" nested element may be such a type. The JAXB binding compiler uses this classpath when loading user defined types, as specified by the <javaType> customization. This is currently not the case for JaxMe: The type names are simply compiled in without an attempt to actually load them. This has the advantage that user defined classes may refer to sources which will generated. | JAXB XJC | 0..Unbounded |
| depends | By default the up-to-date check (used by the JaxMe task) considers the specified schema and binding files only. This is insufficient when auxiliary schema files are included, imported or redefined. The nested <depends> element allows to specify additional files to consider for the up-to-date check. Typically these are the additional schema files. Syntactically the <depends> element specifies a nested <fileset>. | JAXB XJC | 0..Unbounded |
| produces | Specifies the set of files to be created by the JaxMe ant task. These files are considered as targets for the up-to-date check. The syntax of the <produces> element is equivalent to a nested <fileset>. However, you typically do not need to set the "dir" attribute, because it defaults to the target directory. (Note that the JAXB XJC requires setting the "dir" attribute.) | JAXB XJC | 0..Unbounded |
| property | Sets a property value. These properties may be used to pass configuration information to the various source generators. For example, the JDBC schema reader uses the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to configure the database connection. Each property must have attributes "name" (the property name) and "value" (the property value). | JaxMe | 0..Unbounded |
| schema | Multiple schema files may be compiled in one or more nested <schema> elements. The element syntax is equivalent to a nested <fileset>. Use of a nested <schema> element is mutually exclusive with the use of a "schema" attribute. | JAXB XJC | 0..Unbounded |
| sgFactoryChain | If the schema reader is an instance of JAXBSchemaReader,
then you may add instances of SGFactoryChain to
the schema generation process. For example, such chains are used to create
the persistency layer. The best example is the JaxMeJdbcSG,
which is able to populate the schema with tables and columns read from a database
via JDBC metadata. | JaxMe | 0..Unbounded |
| dtd | Specifies, that the input files are no instances of XML Schema,
but DTD's. The schema reader will use the DTDParser
to convert the DTD's into instances of XML Schema. If you do use DTD's,
you will possibly also set the "targetNamespace" attribute, which
specifies a target namespace. (There is no possibility, to specify the
target namespace within a DTD.) | JaxMe; the JAXB RI has a similar possibility by specifying the command line argument "-dtd". | 0..1 |
| schemaReader | Configures the schema reader to use. Defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant schema reader. An alternative schema reader is, for example, "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader with JaxMe specific extensions). | JaxMe | 0..1 |
| xmlCatalog | Adds an XML catalog, which is being used to resolve external entities and URI's. See the Ant documentation for details on XML catalogs. | JaxMe | 0..Unbounded |
By default, the JaxMe ant task will always run the generator and create new files. When this task is part of a general ant build script, this behaviour will result in new files being generated and recompiled each time the build is run.
To achieve greater efficiency, use the nested <produces> and <depends> elements. If one or more <produces> element is specified, then an up-to-date check is performed as follows: