db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r449985 - in /db/torque: generator/trunk/src/conf/ generator/trunk/xdocs/ maven-plugin/trunk/ site/trunk/xdocs/
Date Tue, 26 Sep 2006 11:21:10 GMT
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="monroe@dukece.com">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: 
+  &lt;purpose&gt;-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 &lt;purpose&gt;-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 &lt;iHelpen@foobar.com&gt;></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="monroe@dukece.com">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&lt;version&gt;.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 &quot;serialVersionUID&quot; to the generated classes that
       implement Serializable. The entry is generated if &quot;addTimeStamp&quot;



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message