9.2. Apache Ant
Prev | Chapter 9. Third Party Integration Features | Next

## 9.2. Apache Ant

Ant is a very popular tool for building java projects. It is similar to the make command, but is java-centric and has more modern features. Ant is open-source, and can be downloaded from Apache's Ant web page at http://jakarta.apache.org/ant/. Ant has become the de-facto standard build tool for java, and many commercial integrated development environments provide some support for using ant build files. The remainder of this section assumes familiarity with writing Ant `build.xml` files.

Kodo provides three pre-built Ant task definitions for use in `build.xml` files:

- XDoclet: Allows you to auto-generate `.jdo` metadata files from java source code that includes certain well-formed comments.

- JDOEnhancer: Allows the JDOEnhancer to be invoked directly from within ant.

- SchemaTool: Allows the SchemaTool to be invoked directly from within ant.

The source code for all the ant tasks is provided with the distribution under the `source/` directory. This allows developers to customize various aspects of the ant tasks in order to better integrate into their development environment.

### 9.2.1. Common Ant Configuration Options

Both the JDOEnhancer task and the SchemaTool task can take a nested `<config>` element, which defines the configuration environment in which the specified task will run. The attributes for the `<config>` tag are defined by the JDBCConfiguration bean methods. Note that excluding the `<config>` element will cause the Ant task to use the default system configuration mechanism, such as the configuration defined in the `kodo.properties` file.

Following is an example of how the nested `<config>` tag can be used in a `build.xml` file:

Example 9.1. Using the <config> tag in an ant build.xml file

    <schematool action="refresh" ignoreErrors="true">
      <fileset dir="${basedir}">
        <include name="**/*.jdo" />
      </fileset>
      <config connectionUsername="scott" connectionPassword="tiger"
        licenseKey="1234-5678-90ab-cdef"
        connectionUrl="jdbc:oracle:thin:@saturn:1521:solarsid"
        connectionDriverName="oracle.jdbc.driver.OracleDriver" />
    </schematool>

It is also possible to specify a `properties` or `propertiesFile` attribute to the `<config>` tag. The `properties` attribute will be used to locate a properties file resource, relative to the current CLASSPATH. The `propertiesFile` can be the relative or absolute path to a properties file.

Example 9.2. Using the properties attribute of the <config> tag

    <schematool action="refresh" ignoreErrors="true">
      <fileset dir="${basedir}">
        <include name="**/*.jdo" />
      </fileset>
      <config properties="/kodo.properties" />
    </schematool>

The JDOEnhancer task and the SchemaTool task can also take a nested `<classpath>` element, which can be used if the default classpath is not desired. The `<classpath>` argument behaves the same as it does for ant's standard `<javac>` element. It is sometimes the case that projects are compiled to a separate directory than the source tree. If the target path for compiled classes is not included in the project's classpath, then a `<classpath>` element that includes the target class directory needs to be included in enhancer and schematool tags so that the tools can locate the classes.

Following is an example of using a `<classpath>` tag:

Example 9.3. Using the <classpath> tag in an ant build.xml file

    <jdoc>
      <fileset dir="${basedir}/source">
        <include name="**/*.jdo" />
      </fileset>
      <classpath>
        <pathelement location="${basedir}/classes"/>
        <pathelement location="${basedir}/source"/>
        <pathelement path="${java.class.path}"/>
      </classpath>
    </jdoc>

### 9.2.2. JDOEnhancer Ant Task

The JDOEnhancer Ant task allows you to invoke the JDOEnhancer directly from within the Ant build process. It takes a nested `<fileset>` tag to specify the `.jdo` that should be processed. For more details on the JDOEnhancer, see the enhancer section.

Following is an example of using the JDOEnhancer task in a `build.xml` file:

Example 9.4. Invoking the JDOEnhancer from an Ant build.xml file

    <target name="enhanceAll">
      <!-- Define the jdoc task definition. This can
           be done at the top of the build.xml file,
           so it will be available for all targets. -->
      <taskdef name="jdoc"
        classname="com.solarmetric.modules.integration.ant.JDOEnhancerTask"/>

      <!-- Invoke the JDOEnhancer on all .jdo files
           below the current directory. -->
      <jdoc>
        <fileset dir=".">
          <include name="**/*.jdo" />
        </fileset>
      </jdoc>
    </target>

### 9.2.3. SchemaTool Ant Task

The SchemaTool Ant Task allows you to directly invoke the SchemaTool from within the Ant build process. It is useful for refreshing a development database after refactoring a `.jdo` metadata file without needing to remember to invoke `schematool` manually each time.

The task accepts the following parameters:

- `action`: can be one of "add", "refresh", or "drop". The meaning of these attributes is identical to the value of the "-action" flag for the schematool command.

- `ignoreErrors`: a value of "false" will cause the build process to abort if there are any SQL errors when communicating with the data store.

- `outputFile`: If specified, output generated SQL to a file instead of sending it to the database.

Following is an example of a `build.xml` target that invokes the SchemaTool:

Example 9.5. Invoking the SchemaTool from an Ant build.xml file

    <target name="refreshDataStore">
      <!-- Define the schematool task definition. This can
           be done at the top of the build.xml file,
           so it will be available for all targets. -->
      <taskdef name="schematool"
        classname="com.solarmetric.modules.integration.ant.SchemaToolTask"/>

      <!-- Locate all the .jdo files below this, and
           refresh the data store's schema to be in synch
           with the current state of the metadata. -->
      <schematool action="refresh" ignoreErrors="true">
        <fileset dir=".">
          <include name="**/*.jdo" />
        </fileset>
      </schematool>
    </target>

Prev | Up | Next
Chapter 9. Third Party Integration Features | Home | 9.3. XDoclet