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.
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.
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. |
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.
For an example of how to integrate Torque within the build process, see the Maven Howto.