The Torque Generator component as distributed (the "distro") is designed to support a large number of database servers in stable generic way. For most users, the distro is perfectly fine. However, there are some users who want the generator to behave differently. Some examples of these are:
Torque has always supported customizing its generator thru creating complete template file replacement directorys/jar and/or a custom Java class generator jar. However, starting with version 3.3, the Torque build scripts (Maven 1.0 and Ant, Maven 2.0 is coming), support an "override" method that is intended to allow specific templates and classes to be customized, rather than a complete replacement.
The override method supports two main objectives. First, to make it easier to maintain local modifications as versions change. Rather than having to merge two complete template sets, the override method clearly identifies the subset that needs to be checked/merged. Second, support user contributed add-ons that may not be part of the core Torque purpose but are generally usefull. For example, there is an XML import/export tool based on the Apache Commons Betwixt package that is packaged as an add-on.
This document shows how to set up your Torque project to use overrides, general information on how to install packaged add-ons, and how to get started in creating custom templates.
The first step is to create a directory in your project that will contain any override files. This can be anywhere under your main project directory. Some suggestions are to create a toque-local-lib directory under the project root if you are just using add-ons or under your src directory if you are planning to create your own.
Next, you need to set the torque.override.dir property to this new directory in your Torque build properties. For Maven users, this is done in the project.properties file. For Ant users, this is done in the build.properties file. In the appropriate file, add a torque.override.dir property that points to your override directory. For example to point to a top level torque-local-lib use:
# Define the Override directory location
torque.override.dir = ${basedir}/toque-local-lib
If you are going to be creating override templates, create a templates directory under the the override directory.
Once you have finished these steps, the Torque generator build scripts will now use the following to find its templates and classes:
To install a single existing add-on, simply place any *override.jar files in the torque.override.dir location. Then follow any special configuration setup the contributor has specified.
If you want to modify the templates in the add-on, simply un-jar the templates into the ${torque.override.dir}/templates directory and modify them there.
If you need to install more than one add-on, the add-ons might have modified the same file. You will have to check the jars (or compare contributor instructions) for any conflicts. If there are none, there is not problem using both add-ons. If there are conflicts, you will have to resolve/merge the differences in these files and use the modified version.
If you want to modify the generated sql files or java classes, first look at the overview "How Templates Work" if you are not familiar with the way Torque uses velocity templates. After doing that, proceed as follows:
First, create a templates directory under the torque.override.dir. Then create the directory structure required to locate the template file(s) you are planning to modify. E.g., for the mysql table.vm template file, create a directory structure like: sql\base\mysql and then put the table.vm file in this directory.
Now you can modify the template file(s) to meet your needs. The Ant and Maven 1 generators will look in the {torque.override.dir}/template directory first for templates, so you do not need to remove the modified templates from the Torque distribution.