This section explains how the generator works internally. If you are happy with the generator as it is, you need not read this section. It is not intended to be a tutorial, but rather a overview framework that points people interested in enhancing or creating custom templates to the resources needed to work with Torque templates.
Once you understand the Template internals, see the Custom Templates document for information on how to use it.
The Torque Generator is designed to do many different tasks. (see the Tasks Reference documentation). These tasks generate text based output like: Java code; SQL scripts; etc. Many of these outputs specific to the database type specified in the generation setting.
The Generator tasks are based on a Java based template engine called Velocity (in particular, the Texen component). The Velocity engine uses a set of task specific template files written in the Velocity Template Language (VTL), the XML schema info, and project build properties to produce the required output.
To understand how the Torque template files work, you should become familiar with the VTL syntax by reviewing the Velocity user guide.
The Torque template files are plain text VTL files with the extention of ".vm". These files are packaged in the torque-gen-templates<version>.jar in the lib directory of the binary distribution. This jar file can be unpacked to access this files. Or alternatively, you can find them under the torque/templates/src directory in the source distribution or SVN repository.
The template files are organized under a main directory called templates which has five or so different directory branches under it. Each of these branches is roughly related to a Torque Task. To learn which directories and templates apply to which Generator task, you need to identify the Control.vm template associated with that task. The Control.vm files are the main entry points for all tasks.
The easiest way to find a task's Control.vm file is to use the default.properties file (located in the root directory of the binary distribution). Search thru this file for properties that start with "torque.templates." The ending part of the property key is generally the task name and the value is the associated Control.vm file. E.g. the property, "torque.template.sql = sql/base/Control.vm", means the sql task Control file is the templates/sql/base/Control.vm file in the template jar.
These Control.vm files can be examined to understand the overall flow of a task's process and to find the main template files that will be parsed to produce various parts of the output. Note that in some cases, the parsed template files may call other templates.
Once you start looking at the VTL code in the templates, you'll wonder where all the Velocity variables are getting set. Well, there are two places these come from.
First, all the torque.* build properties defined in the default.properties file and any project related property file are passed into the templates. These are converted to Velocity format by removing the "torque." prefix, removing the remaining dots (".") and capitalizing the letter after it. E.g. torque.output.dir becomes $outputDir.
Second, the *-schema.xml files are converted into the OM objects in the
org.apache.torque.engine.database.model package. These are
passed to the Velocity controller as object variables, like $dataModel.
In Velocity, any object property (e.g. getProp), can be referred to by
$objectVar.prop. In addition, any methods in this object can also be
called by referring to them as $objectVar.getSomething( parm, parm ).
With the release of Version 3.3, the XML DTD supports an <option key="key" value="value"> element intended for use by custom templates. Zero or more of these elements can be nested (as the first item) inside the dataset, table, column, foreign-key, index, and unique schema elements. For example:
These key/value attributes will then populate the options map in the associated database model class. Custom templates can access these values with code like: