Purpose of running Torque from a jar

The standard practice for using Torque has been to download the jar, unjar it to get the directory structure given in the user guide , and somehow either integrate your source tree and Torque's un-jared directory structure. While doable, this was less than desirable, especially when working with prespecified directory structures, such as that used by Maven.

Complex build scripts, such as Scarab's , which dynamically unjar Torque during the build process and copy over all the correct files, can get around this, but having to re-develop or even copy such capabilities on a project-by-project basis is undesirable do to the relative complexity.

Instead, it is possible to run Torque without un-jaring it. All that is needed is the venerable build-torque.xml and build.properties . Everything else can be read from the classpath and outputted directly to the directories that are desired instead of the previous rigid structure.

Requirements

Along with the build-torque.xml and build.properties , you must ensure that Torque and all of it's dependencies are in the classpath. For a list of dependencies, please refer to dependencies.html .

Along with the classpath, you must edit the build.properties and set a minimum set of variables:

Note , if you set only the above properties, Torque will default to using the old directory structure to read and output files from. This maintains backwards compatibility, but is not always what is wanted. The next section addresses telling Torque where to read and output files.

Configuring Directories

The following directory properties allow you to control with a good deal of granularity where Torque will read and output files. The table contains each of the properties, along with it's default value and description.

Property Default Description
torque.home . Serves as the base directory when defining other default directories.
torque.output.dir ${torque.home}/src Serves as a general directory to output files to.
torque.schema.dir ${torque.home}/schema Where the *-schema.xml files are read from.
torque.doc.dir ${torque.output.dir}/doc Where the schema documentation is output.
torque.java.dir ${torque.output.dir}/java Where the java files are output.
torque.javadoc.dir ${torque.output.dir}/javadoc Where the javadoc files for the om classes are output.
torque.ojb.dir ${torque.output.dir}/ojb Where the OJB files are output.
torque.sql.dir ${torque.output.dir}/sql Where the SQL files are output.

Invoking Torque

Once the build properties have been set, you can invoke torque via the build-torque.xml : ant -f build-torque.xml .

Also, a few of the Torque targets, currently om and sql, are smart enough to not run unless the schema has changed. This would allow you to automatically call ant -f build-torque.xml on each compile and only worry about the time it takes to generate the templates being taken if the schema has changed.

Example using Jar'd Torque and Maven

For an example of how to integrate Torque within the build process, see the Maven Howto .