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 in mind:
A typical use of the Ant task looks like this:
<target name="taskdef">
<taskdef name="xjc"
classname="net.sf.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>
In other words: Typically you define a target like "taskdef", which loads the ant task under a given name ("xjc" in the above example, or "jaxme"). The task is actually used in another 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 are accepted, which are specified by the JAXB binding compiler. | JAXB XJC | No, defaults to "false" |
| force | Setting this option to "true" forces the up-to-date check to fail, in which case the nested <produces> elements are ignored. This attribute isn't of much use for the JaxMe user. It is mainly designed for JaxMe developers who want to specify a value from the command line, because they have updated the schema compiler and want to run 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 values specified in the schema bindings, if any. | 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" |
| schemaReader | Configures the schema reader to use. Defaults to "net.sf.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant schema reader. An alternative schema readers is, for example, "net.sf.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader with JaxMe specific extensions). | JaxMe | No, defaults to "net.sf.jaxme.generator.sg.impl.JAXBSchemaReader" |
| 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 |
| target | Specifies the target directory, where generated sources are being created in a package structure. 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 compatibility to the JAXB ant task only. A warning is logged, if you use it anyways. 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 you use this attribute anyways. | 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" attribute may be such a type. The JAXB binding compiler is using this classpath for 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 generated sources. | JAXB XJC | 0..Unbounded |
| depends | By default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only. This is insufficient, if other 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 being 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 by the various source generators to configure the behaviour. 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 |
By default, the JaxMe ant task will always run the generator and create new files. This is typically inappropriate for an ant script where your desire is to have as little modifications as possible, because new files also need to be recompiled, which is slow and time consuming.
To achieve a better behaviour, 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: