Jython Task for Apache Ant

The ant wrappers in dbmstools (for xml2ddl, xml2doc or filterdml) are written as Jython scripts (Jython is a Python interpreter that runs inside a Java Virtual Machine). To be able to run these scripts, you must be able to run Jython from an ant build script.

Ant provides a script task, but this is a bit limited, not least because it assumes that the script is embedded in the build script. dbmstools provides its own Jython task, which has the following attributes:

The script can be loaded from the filesystem, or from the jar containing the Jython ant task

Arguments are injected directly into the script's namespace, as if they were local variables

Also supports map (aka dict) arguments

The Jython ant task itself is also injected as the local variable _jythonTask (so you can call back on ant to get anything you want)

Runs the script either once, or once per file in a fileset

Optionally allows specification of the Jython directory (for location of jython.jar and python modules), although the supplied Jython jar includes all the python modules

Allows specification of extra Python directories (equivalent to PYTHONPATH), for loading other python modules

Allows specification of extra Java directories (containing jar files to be imported)

Stores jar caches under the system temp directory by default, although the supplied Jython jar doesn't cache jars.

Build Script

Classpath for Jython Task

The first thing to set up in your build script (or in another script that it includes) is the classpath for the Jython Ant task.

<path id="jython-classpath">
    <pathelement location="lib/dbmstools-jython-2.2.1.jar" />
</path>

Taskdef for Jython Task

Now it's time to taskdef the Jython task. This allows you to refer to it by the task name jython.

<!-- Taskdef the Jython task, so we can call it to run our scripts -->
<taskdef name="jython" classname="net.sourceforge.dbmstools.JythonTask" classpathref="jython-classpath"/>

Using the Jython Task

Now we can use the task as much as we like.

The task supports the following attributes and elements:

script:

Attribute, required. Path to the Python script to run. To run the dbmstools scripts, you will use one of the following:

dbmstoolsjar/xml2ddl-ant.py

dbmstoolsjar/xml2doc-ant.py

dbmstoolsjar/filterdml-ant.py

Can also point to any Python script, either relative to the build directory, somewhere in the PYTHONPATH (see pythonDir below) or absolute.

argument:

Element, zero or more. Declares an argument to the script that will be inserted as a local variable in the interpreter. All the dbmstools Ant wrapper scripts use this method to pass values to the scripts. Attributes are:

name:	Mandatory. The argument/local variable name
value:	Mandatory. The string value for the argument/local variable

mapargument:

Element, zero or more. Declares an argument to the script which is a map of name:value pairs. This contains an argument element for each name:value pair. Attributes are:

name:	Mandatory. The argument/local variable name for this map variable

pythonDir:

Not required for dbmstools. Element, zero or more. Directories containing other python modules to be imported, equivalent of PYTHONPATH. If you specified a relative script that isn't immediately under $basedir, you'll need one of these entries for the dbmstools base directory. Attributes are:

dir:	Mandatory. The directory containing python modules

javaLibDir:

Not required for dbmstools. Element, zero or more. Directories containing jar files to be imported. This is required because Ant uses its own classloaders instead of using the Java CLASSPATH. Jython needs to both be able to load the classes (set these in the classpath for the Jython task when you taskdef it) and to find the jar files (via one of these elements). Attributes are:

dir:	Mandatory. The directory containing jar files

If you supply a fileset to the task, the script will be executed once for each file, with the file path added to the script as _filePath.

IMPORTANT NOTE ON PATHS:

All paths passed to this task are first checked relative to the current directory. Only if the file or directory is not found is the path checked relative to the project directory.

Jython Task Example

This example is to run the xml2doc-ant wrapper.

<jython script="dbmstoolsjar/xml2doc-ant.py">
    <argument name="xmlSchema" value="test/data/testSchema.xml"/>
    <argument name="outputDir" value="${output-dir}"/>
    <argument name="dbmsList" value="postgres8, mssql, hsql"/>
    <argument name="embedStyles" value="Y"/>
    <argument name="includeColumnDescriptions" value="Y"/>
    <argument name="numIndexTableColumns" value="3"/>
    <mapargument name="variables">
        <argument name="fooVar" value="valueC"/>
    </mapargument>
</jython>

Liberated Code...

Parts of the code in my Jython task have been copied from code available with Jython, and from other Jython-related code I've seen around over the years. Hope that's OK...