Author: tfischer
Date: Tue Sep 26 04:21:10 2006
New Revision: 449985
URL: http://svn.apache.org/viewvc?view=rev&rev=449985
Log:
Added support for customizing templates.
Thanks to Greg Monroe for the patch.
Nearly fixes TORQUE-50, except the section in documentation about how to submit
contributions.
Added:
db/torque/generator/trunk/xdocs/custom-templates.xml
db/torque/generator/trunk/xdocs/how-templates-work.xml
Modified:
db/torque/generator/trunk/src/conf/build-torque.xml
db/torque/generator/trunk/xdocs/navigation.xml
db/torque/generator/trunk/xdocs/properties-reference.xml
db/torque/maven-plugin/trunk/plugin.jelly
db/torque/site/trunk/xdocs/changes.xml
Modified: db/torque/generator/trunk/src/conf/build-torque.xml
URL:
http://svn.apache.org/viewvc/db/torque/generator/trunk/src/conf/build-torque.xml?view=diff&rev=449985&r1=449984&r2=449985
==============================================================================
--- db/torque/generator/trunk/src/conf/build-torque.xml (original)
+++ db/torque/generator/trunk/src/conf/build-torque.xml Tue Sep 26 04:21:10 2006
@@ -41,19 +41,44 @@
<property name="torque.jar" value="torque-gen-3.2.1-dev.jar"/>
<!--
- Build the classpath. Specifically point to each file we're including to
avoid
- version conflicts in the case of the torque.lib.dir being something like
lib.repo.
- However, we still need to pull in the user's database driver and since we
don't
- know which jar that will be, after we've got all of our specific,
version-safe jars,
- do a general inclusion of the torque.lib.dir to catch any drivers.
- In the maven-built versions, ${torque.jar} is in the working directory.
+ Build the classpath used by all torque ant tasks.
+
+ First, defines the template/generator override directories/jars based on
the
+ torque.override.dir build property. If this property is not set, use
+ the torque.lib.dir as a default to keep ant happy.
+
+ Note: To prevent version conflicts in the default case, jars being
+ overridden need to end in "override.jar".
+
+ Next, specifically point to each file we're including to avoid version
+ conflicts in the case of the torque.lib.dir being something like lib.repo.
+ However, we still need to pull in the user's database driver and since we
+ don't know which jar that will be, after we've got all of our specific,
+ version-safe jars, do a general inclusion of the torque.lib.dir to catch
+ any drivers. In the maven-built versions, ${torque.jar} is in the working
+ directory.
-->
+ <condition property="valid.override.directory"
+ value="${torque.override.dir}">
+ <isset property="torque.override.dir" />
+ </condition>
+ <condition property="valid.override.directory"
+ value="${torque.lib.dir}">
+ <not>
+ <isset property="torque.override.dir" />
+ </not>
+ </condition>
+
<path id="torque-classpath">
+ <pathelement location="${valid.override.directory}/templates"/>
+ <fileset dir="${valid.override.directory}">
+ <include name="*override.jar"/>
+ </fileset>
<pathelement path="${torque.jar}" />
<fileset dir="${torque.lib.dir}">
<include name="**/commons-collections-3.1.jar"/>
<include name="**/commons-lang-2.1.jar"/>
- <include name="**/log4j-1.2.8.jar"/>
+ <include name="**/commons-logging-1.0.4.jar"/>
<include name="**/velocity-1.3.1.jar"/>
<include name="**/village-2.0.jar"/>
<include name="**/xercesImpl-2.6.2.jar"/>
Added: db/torque/generator/trunk/xdocs/custom-templates.xml
URL:
http://svn.apache.org/viewvc/db/torque/generator/trunk/xdocs/custom-templates.xml?view=auto&rev=449985
==============================================================================
--- db/torque/generator/trunk/xdocs/custom-templates.xml (added)
+++ db/torque/generator/trunk/xdocs/custom-templates.xml Tue Sep 26 04:21:10
2006
@@ -0,0 +1,293 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2001-2006 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License")
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+ <properties>
+ <title>Creating and Using Custom Generator Add-ons</title>
+ <author email="[EMAIL PROTECTED]">Greg Monroe</author>
+ </properties>
+
+ <body>
+ <section name="Table of Contents">
+ <p>
+ <ol>
+ <li>
+ <a href="#Overview of Customization">Overview of Customization</a>
+ </li>
+ <li>
+ <a href="#Setting up to use/create Overrides">
+ Setting up to use/create Overrides
+ </a>
+ </li>
+ <li>
+ <a href="#Installing an existing add-on">
+ Installing an existing add-on
+ </a>
+ </li>
+ <li>
+ <a href="#Creating an add-on or local customization">
+ Creating an add-on or local customization
+ </a>
+ </li>
+<!-- <li>
+ <a href="#Packaging an Add-on for General Distribution">
+ Packaging an Add-on for General Distribution
+ </a>
+ </li> -->
+ </ol>
+ </p>
+ </section>
+
+ <section name="Overview of Customization">
+ <p>
+ 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:
+ </p>
+ <ul>
+ <li>
+ Making the Torque generated SQL include DB server type and/or version
+ specific items. E.g., MySQL Table types or MS SQL Version 7 SQL syntax.
+ <br />
+ </li>
+ <li>
+ Making the generated Java classes include application specific code in
+ addition to the core Torque code.<br />
+ </li>
+ <li>
+ Using the generator to maintain other configuration files that are effected
+ by changes to the DB schema, e.g. custom DTDs, betwixt map files.<br />
+ </li>
+ </ul>
+ <p>
+ 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.2.1, 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ This page shows how to set up and use add-ons, and how to
+ create own custom templates.
+ <!--
+ Provide guidelines on how to package a general add-on for submission to
+ the Torque site. -->
+ </p>
+ </section>
+
+ <section name="Setting up to use/create Overrides">
+ <p>
+ 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 <i>toque-local-lib</i> directory under
the
+ project root if you are just using add-ons or under your <i>src</i>
+ directory if you are planning to create your own.
+ </p>
+ <p>
+ 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:
+ </p>
+ <ul>
+ <pre>
+ # Define the Override directory location
+ torque.override.dir = ${basedir}/toque-local-lib
+ </pre>
+ </ul>
+ <p>
+ If you are going to be creating override templates, create a
+ <i>templates</i> directory under the the override directory.
+ </p>
+ <p>
+ Once you have finished these steps, the Torque generator build scripts will
+ now use the following to find its templates and classes:
+ </p>
+ <ul>
+ <li>
+ For individual template files, the ${torque.override.dir}/template
directory
+ is searched first.<br />
+ </li>
+ <li>
+ Next, all *override.jar files in the ${torque.override.dir} directory are
+ searched for templates and class files.<br />
+ </li>
+ <li>
+ Finally, the distribution files are searched for Templates and jars.<br />
+ </li>
+ </ul>
+ </section>
+
+ <section name="Installing an existing add-on">
+
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+
+ </section>
+
+ <section name="Creating an add-on or local customization">
+ <p>
+ If you want to modify the generated sql files or java classes,
+ first look at the overview
+ <a href="how-templates-work.html">"how templates work"</a> if you are not
+ familiar with the way Torque uses velocity templates.
+ After doing that, proceed as follows:
+ </p>
+ <p>
+ First, create a <i>templates</i> 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: <i>sql\base\mysql</i> and then put the
+ table.vm file in this directory.
+ </p>
+ <p>
+ 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.
+ </p>
+ </section>
+
+ <!-- The procedure needs more discussion -->
+ <!--
+ <section name="Packaging an Add-on for General Distribution">
+ <p>
+ So you've gotten all your mods done, offered them as a core Torque
+ enhancement, but they were outside the scope/too DB specific, etc.
+ Now you want to share it with the world as a separate Torque add-on.
+ What should you do?
+ </p>
+ <p>
+ You need to package your templates and possibly any changes to the model
+ classes into separate jar files. The names of these jars must end in
+ <i>override.jar</i>. A good convention is to call them something like:
+ <purpose>-template-override.jar, eg.
+ betwixt-template-override.jar
+ </p>
+ <p>
+ Optionally, if you created model class override jar, create a src jar for
+ these classes.
+ </p>
+ <p>
+ Next you need to create a <purpose>-readme.html (or txt) file, with
+ the applicable following information:
+ </p>
+ <table>
+ <tr>
+ <td width="30%">Title:</td><td>Torque add-in extraordinaire.</td>
+ </tr>
+ <tr>
+ <td>Author:</td><td>Ima Helpen <[EMAIL PROTECTED]>></td>
+ </tr>
+ <tr>
+ <td>Date:</td><td>9 Aug 2006</td>
+ </tr>
+ <tr><td>Torque-Version:</td><td>3.2.1 (Dev)</td>
+ </tr>
+ <tr>
+ <td>Goal/Target Effected:</td><td>datadtd</td>
+ </tr>
+ <tr><td colspan="2">
+ <p>
+ License:
+ </p>
+ <p>
+ Your preferred license.. (Torque's is the Apache License of course 8)
).
+ </p>
+ </td></tr>
+ <tr><td colspan="2">
+ <p>
+ Description:
+ </p>
+ <p>
+ This modifies the ... task in the Torque Generator so that it will ...
+ </p>
+ </td></tr>
+ <tr><td colspan="2">
+ <p>
+ Installation:
+ </p>
+ <p>
+ Follow the How-To instructions on setting up for add-on overrides, then
+ unzip this into the override directory.
+ </p>
+ </td></tr>
+ <tr><td colspan="2">
+ <p>
+ Usage Notes:
+ </p>
+ <p>
+ Set these new properties to what you want...
+ </p>
+ </td></tr>
+ <tr><td colspan="2">
+ <p>
+ New Properties:
+ </p>
+ <table>
+ <tr>
+ <td width="20%">Property</td><td width="20%">Default</td><td
width="60%">Description</td>
+ </tr>
+ <tr>
+ <td width="20%">torque.myAddon.option1</td><td
width="20%">none</td><td width="60%">If set, ...</td>
+ </tr>
+ </table>
+ </td></tr>
+ </table>
+ <p>
+ Finally, all the jar and readme files should be tar.gz-ed and/or zipped into
a
+ single distribution file.
+ </p>
+ <p>
+ You can either submit this via Jira for possible inclusion on the
+ Torque site, or you can announce it on the Torque-users mailing
+ list.
+ </p>
+ </section>
+
+ -->
+ </body>
+</document>
Added: db/torque/generator/trunk/xdocs/how-templates-work.xml
URL:
http://svn.apache.org/viewvc/db/torque/generator/trunk/xdocs/how-templates-work.xml?view=auto&rev=449985
==============================================================================
--- db/torque/generator/trunk/xdocs/how-templates-work.xml (added)
+++ db/torque/generator/trunk/xdocs/how-templates-work.xml Tue Sep 26 04:21:10
2006
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2001-2006 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License")
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+ <properties>
+ <title>How Templates Work</title>
+ <author email="[EMAIL PROTECTED]">Greg Monroe</author>
+ </properties>
+
+ <body>
+
+ <section name="How Templates work">
+ <p>
+ This section explains how the generator works internally. If you
+ are happy with the generator as it is, you need not read this section.
+ </p>
+ </section>
+ <section name="Location of Templates">
+ <p>
+ Before starting to do any modifications, you should understand the main
+ "driver" for the Torque generator tasks is the
+ <a href="http://jakarta.apache.org/velocity";>Velocity</a> Java-based
+ template engine. All the tasks make use of Velocity template files. You
+ should become familiar with the Velocity template syntax by reviewing
the
+ <a
href="http://jakarta.apache.org/velocity/docs/user-guide.html";>Velocity
+ user guide</a>.
+ </p>
+ <p>
+ The Torque template files are packaged in the
+ torque-gen-templates<version>.jar in the lib directory of the
binary
+ distribution. This contains serveral different directories with
templates
+ under them. Each of these directories is related to a Torque Task.
+ </p>
+ <p>
+ To learn which directories apply to which generator task, you need to
+ identify the Control.vm template associated with that task.
+ The Control.vm is the main Velocity controller that calls all of the
+ task related template files as required. Matching Control.vm file to
+ a task can be done in various ways. You can look at the settings of the
+ torque.template.* properties in the default.properties file
+ (in the root of the binary distribution). Alternatively, you can look
+ at the Torque task definitions in the build-torque.xml Ant build file.
+ </p>
+ </section>
+
+ <section name="Template variables">
+ <p>
+ Once you start looking at the code in the templates, you'll wonder where
+ all the Velocity variables are getting set. Well, there are two places
+ these come from.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ Second, the *-schema.xml files are converted into the OM objects in the
+ <code>org.apache.torque.engine.database.model</code> 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 ).
+ </p>
+ </section>
+ </body>
+</document>
Modified: db/torque/generator/trunk/xdocs/navigation.xml
URL:
http://svn.apache.org/viewvc/db/torque/generator/trunk/xdocs/navigation.xml?view=diff&rev=449985&r1=449984&r2=449985
==============================================================================
--- db/torque/generator/trunk/xdocs/navigation.xml (original)
+++ db/torque/generator/trunk/xdocs/navigation.xml Tue Sep 26 04:21:10 2006
@@ -35,6 +35,8 @@
<item name="Schema Reference" href="/schema-reference.html"/>
<item name="Properties Reference" href="/properties-reference.html"/>
<item name="database.dtd" href="/database.dtd.txt"
target="_blank"/>
+ <item name="How Templates work" href="/how-templates-work.html"/>
+ <item name="Custom Templates" href="/custom-templates.html"/>
<item name="Dependencies" href="/dependencies.html"/>
<item name="Project Reports" href="/maven-reports.html"
collapse="true">
<item name="Metrics" href="/jdepend-report.html"/>
Modified: db/torque/generator/trunk/xdocs/properties-reference.xml
URL:
http://svn.apache.org/viewvc/db/torque/generator/trunk/xdocs/properties-reference.xml?view=diff&rev=449985&r1=449984&r2=449985
==============================================================================
--- db/torque/generator/trunk/xdocs/properties-reference.xml (original)
+++ db/torque/generator/trunk/xdocs/properties-reference.xml Tue Sep 26
04:21:10 2006
@@ -201,6 +201,15 @@
<td><code>${torque.output.dir}</code></td>
<td>The directory to place the jar files output by the om-zip goal.</td>
</tr>
+ <tr>
+ <td><code>torque.override.dir</code></td>
+ <td><code>${torque.output.dir}</code></td>
+ <td>The directory where Torque will look for template overrides.<br/>
+ NOTE: This directory will only be used if torque.useClasspath is set to
+ true. If torque.useClasspath is set to false, template overriding
+ will not work.
+ </td>
+ </tr>
<tr>
<td colspan="3"><strong> Database Settings </strong></td>
@@ -336,7 +345,9 @@
<td>
If true, Torque will not look in the <code>templatePath</code>
directory,
for templates, but instead load them from the classpath, allowing you
to
- use Torque without extracting it from the jar.
+ use Torque without extracting it from the jar.<br/>
+ NOTE: if torque.useClasspath is set to false, the torque.override.dir
+ will no longer be used (i.e. local template overrides will not work).
</td>
</tr>
<tr>
Modified: db/torque/maven-plugin/trunk/plugin.jelly
URL:
http://svn.apache.org/viewvc/db/torque/maven-plugin/trunk/plugin.jelly?view=diff&rev=449985&r1=449984&r2=449985
==============================================================================
--- db/torque/maven-plugin/trunk/plugin.jelly (original)
+++ db/torque/maven-plugin/trunk/plugin.jelly Tue Sep 26 04:21:10 2006
@@ -48,12 +48,53 @@
name="torque:init"
description="Build classpath and define tasks">
- <!-- Setup the classpath for torque plugins -->
+ <!--
+ Build the classpath used by all torque plugin tasks.
+
+ First, defines the template/generator override directories/jars based on
the
+ torque.override.dir build property. If this property is not set, use
+ the torque.lib.dir as a default to keep the Ant's fileset happy.
+
+ Note: To prevent version conflicts in the default case, jars being
+ overridden need to end in "override.jar".
+
+ Next, specifically point to each file we're including to avoid version
+ conflicts in the case of the torque.lib.dir being something like lib.repo.
+ However, we still need to pull in the user's database driver and since we
+ don't know which jar that will be, after we've got all of our specific,
+ version-safe jars, do a general inclusion of the torque.lib.dir to catch
+ any drivers. In the maven-built versions, ${torque.jar} is in the working
+ directory.
+ -->
+ <condition property="valid.override.directory"
+ value="${torque.override.dir}">
+ <isset property="torque.override.dir" />
+ </condition>
+ <condition property="valid.override.directory"
+ value="${torque.lib.dir}">
+ <and>
+ <isset property="torque.lib.dir"/>
+ <not>
+ <isset property="torque.override.dir" />
+ </not>
+ </and>
+ </condition>
+ <condition property="valid.override.directory"
+ value="${basedir}">
+ <not>
+ <isset property="valid.override.directory"/>
+ </not>
+ </condition>
+
<path id="torque-classpath">
+ <pathelement location="${valid.override.directory}/templates"/>
+ <fileset dir="${valid.override.directory}">
+ <include name="*override.jar"/>
+ </fileset>
<pathelement path="${plugin.getDependencyPath('ant')}"/>
<pathelement path="${plugin.getDependencyPath('commons-collections')}"/>
<pathelement path="${plugin.getDependencyPath('commons-lang')}"/>
- <pathelement path="${plugin.getDependencyPath('log4j')}"/>
+ <pathelement path="${plugin.getDependencyPath('commons-logging')}"/>
<pathelement path="${plugin.getDependencyPath('velocity')}"/>
<pathelement path="${plugin.getDependencyPath('village')}"/>
<pathelement path="${plugin.getDependencyPath('xercesImpl')}"/>
Modified: db/torque/site/trunk/xdocs/changes.xml
URL:
http://svn.apache.org/viewvc/db/torque/site/trunk/xdocs/changes.xml?view=diff&rev=449985&r1=449984&r2=449985
==============================================================================
--- db/torque/site/trunk/xdocs/changes.xml (original)
+++ db/torque/site/trunk/xdocs/changes.xml Tue Sep 26 04:21:10 2006
@@ -29,6 +29,9 @@
<release version="3.2.1-dev" date="in SVN">
+ <action type="add" dev="tfischer" issue="TORQUE-50" due-to="Greg Monroe">
+ Added support for customizing generator templates.
+ </action>
<action type="add" dev="tv">
Add a "serialVersionUID" to the generated classes that
implement Serializable. The entry is generated if
"addTimeStamp"
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
