Miscellaneous

Legend

Table of Contents

Overview of Customization

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:

Making the generated Java classes include application specific code in
addition to the core Torque code.

Using the generator to maintain other configuration files that are effected
by changes to the DB schema, e.g. custom DTDs, betwixt map files.

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.

Setting up to use/create Overrides

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:

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:

For individual template files, the ${torque.override.dir}/template directory
is searched first.

Next, all *override.jar files in the ${torque.override.dir} directory are
searched for templates and class files.

Finally, the distribution files are searched for Templates and jars.

Installing an existing add-on

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.

Creating an add-on or local customization

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.