# The JaxMe Ant Task

The JaxMe Ant task was written with the following goals in mind:

- To preserve as much compatibility as possible with the JAXB xjc task
- To provide access to JaxMe extensions

In other words, if you have existing build scripts using JAXB's xjc, you should be able to convert them to JaxMe with a single switch (by exchanging the class name in the task definition). However, if you like to make use of JaxMe's extensions at a later time, you are free to do so.

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:

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 `Foo.java`. 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:

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: -nv -catalog -use-runtime -schema -dtd -relaxng | 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

## The Up-to-date check

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:

1. If the "force" attribute is set to true, then the up-to-date check fails.
2. If there are no nested <produces> elements, then the up-to-date check fails.
3. Otherwise the set of target files will be computed by evaluating all the nested <produces> elements. If either of these nested elements computes an empty set, then the up-to-date check fails.
4. Otherwise the set of source files will be created by considering the "schema" and "binding" attributes, and the nested <schema>, <binding>, and <depends> elements. If either of the files in the source set is more recent than any of the files in the target set, then the up-to-date check fails.
5. Otherwise the up-to-date check succeeds.