db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r965980 - in /db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator: gettingStarted.xml reference/concepts.xml reference/configuration.xml reference/internals/generatorTypes.xml reference/internals/outletTypes.xml
Date Tue, 20 Jul 2010 20:00:58 GMT
Author: tfischer
Date: Tue Jul 20 20:00:58 2010
New Revision: 965980

URL: http://svn.apache.org/viewvc?rev=965980&view=rev
Log:
updated documentation to match the current state of the code

Added:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
      - copied, changed from r917970, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/generatorTypes.xml
Removed:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/generatorTypes.xml
Modified:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/gettingStarted.xml
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/gettingStarted.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/gettingStarted.xml?rev=965980&r1=965979&r2=965980&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/gettingStarted.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/gettingStarted.xml
Tue Jul 20 20:00:58 2010
@@ -47,7 +47,7 @@ torque.some.other.property = someOtherVa
     ]]></source>
       we want produce the output
     <source><![CDATA[
-package org.apache.torque.gf.example.propertyenum;
+package org.apache.torque.generator.example.gettingstarted;
 
 /**
  * Contains all keys in the property file.
@@ -96,14 +96,14 @@ public enum PropertyKeys 
   <section name="Project setup">
     <p>
       Create a root folder for your project. In the root folder, create a 
-      src/main/torque-gf folder. This is where all the files for
+      src/main/torque-gen folder. This is where all the files for
       the torque generator go. 
-      In the torque-gf folder, create a "conf" subdirectory
+      In the torque-gen folder, create a "conf" subdirectory
       (this is where the main configuration goes), a "templates" subdirectory
-      (for the velocity templates), a "generatorDefs" subdirectory 
-      (for the definition of the generators) and a "src" directory 
+      (for the velocity templates), a "outlets" subdirectory 
+      (for the definition of the outlets) and a "src" directory 
       (for the source files, they can be anywhere in the project but if
-      you do not know a better place for them, torque-gf/src is a reasonable
+      you do not know a better place for them, torque-gen/src is a reasonable
       default).
     </p> 
   </section>
@@ -119,13 +119,14 @@ public enum PropertyKeys 
     <p>
       This file will be used to feed the generation process. 
       Name this file "propertiesData.properties" and put it into
-      the src subdirectory of the torque-gf directory.
+      the src subdirectory of the torque-gen directory.
     </p>
     <p>
-      Internally, torque-gf uses a representation similar to a xml file
-      to represent the source: Elements make up a tree or graph structure,
-      and each element has a set of named attributes. The internal
-      representation of our property source looks like
+      Internally, the Torque generator uses a representation similar 
+      to a xml file to represent the source: 
+      Elements make up a tree or graph structure,
+      and each element has a set of named attributes. 
+      The internal representation of our property source looks like
       <source><![CDATA[
 <properties>
   <entry key="torque.sample.property">sampleValue</entry>
@@ -138,14 +139,15 @@ public enum PropertyKeys 
       are used to access the textual information in the source.
     </p>
     <p>
-      Other input formats (currently xml) are also supported.
+      Other input file formats (currently xml) and input types 
+      (currently JDBC metadata) are also supported.
     </p>
   </section>
 
   <section name="Creating the templates">
     <p>
       Create the templates which produce the generated code in the
-      "templates" subdirectory of the "torque-gf" folder. Use at least one
+      "templates" subdirectory of the "torque-gen" folder. Use at least one
       template per file you want to generate; it is better to use one
       template per logical unit (this improves reusability and readability).
       A good idea is to create some sample output and start putting in
@@ -166,16 +168,16 @@ public enum PropertyKeys 
       contains the class outer frame plus mergepoints
       for the constants, fields and methods of the enum:
       <source><![CDATA[
-package org.apache.torque.gf.example.propertyenum;
+package org.apache.torque.generator.example.gettingstarted;
 
 /**
  * Contains all keys in the property file.
  */
 public enum PropertyKeys 
 {
-$torqueGf.mergepoint("constants")##
-$torqueGf.mergepoint("fields")##
-$torqueGf.mergepoint("methods")##
+$torqueGen.mergepoint("constants")##
+$torqueGen.mergepoint("fields")##
+$torqueGen.mergepoint("methods")##
 }
       ]]></source>
       As mentioned above, <a href="http://velocity.apache.org">velocity</a>
@@ -185,10 +187,10 @@ $torqueGf.mergepoint("methods")##
       <a href="http://velocity.apache.org">the velocity documentation</a>.
       <br/>
       The interesting part in the template is the call of the mergepoint method
-      of the torqueGf Object. The torqueGf object is placed into the velocity
+      of the torqueGen Object. The torqueGen object is placed into the velocity
       context by the torque generator and contains methods for defining
       mergepoints and accessing the source, options and variables. See
-      <a href="apidocs/org/apache/torque/gf/template/velocity/TorqueGfVelocity.html">its
javadoc</a>
+      <a href="apidocs/org/apache/torque/generator/template/velocity/TorqueGenVelocity.html">its
javadoc</a>
       for the available methods.
     </p>
     <p>
@@ -206,15 +208,15 @@ $torqueGf.mergepoint("methods")##
       Finally, we need a comma after each definition, except for the last
       definition, where we need a semicolon. To decide whether to render the
       comma or the semicolon, we fetch the current source element from 
-      torgueGf (${torqueGf.getSourceElement()) and ask it whether it
+      torgueGen (${torqueGen.getSourceElement()) and ask it whether it
       has following siblings (i.e. source elements with the same parent
       and the same name) (see
-      <a href="apidocs/org/apache/torque/gf/source/RichSourceElementImpl.html">the
RichSourceElementImpl javadoc</a>
+      <a href="apidocs/org/apache/torque/gen/source/SourceElement.html">the SourceElement
javadoc</a>
       for available methods on a source element).
     </p>
     <source><![CDATA[
     /** Key for ${key} */
-    $torqueGf.mergepoint("constantName")("${key}")#if(${torqueGf.getSourceElement().hasFollowingSibling()}),#else;#end
+    $torqueGen.mergepoint("constantName")("${key}")#if(${torqueGen.getSourceElement().hasFollowingSibling()}),#else;#end
 
 
     ]]></source>
@@ -297,14 +299,14 @@ $torqueGf.mergepoint("methods")##
     </p>
     <p>
       Each "output" tag needs a "source" tag which tells the torque generator
-      which source file to use.
+      which source files to use.
       If you want to create more than one output file per "output"
-      tag, use the "elements" attribute of the "source" tag to select the
-      root elements for the different output files.
+      tag and source file, use the "elements" attribute of the "source" tag
+      to select the root elements for the different output files.
     </p>
     <p>
-      Also, each output tag needs a "generator" tag which contains the name
-      of the generator to invoke on the root elements. For defining generators,
+      Also, each output tag needs a "outlet" tag which contains the name
+      of the outlet to invoke on the root elements. For defining outlets,
       see the next section.
     </p>
     <p>
@@ -315,15 +317,15 @@ $torqueGf.mergepoint("methods")##
 <?xml version="1.0" encoding="UTF-8"?>
 <control
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://db.apache.org/torque/gf/4.0/configuration http://db.apache.org/torque/gf/4.0/configuration.xsd"
-    xmlns="http://db.apache.org/torque/gf/4.0/configuration"
+    xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration http://db.apache.org/torque/4.0/generator/configuration.xsd"
+    xmlns="http://db.apache.org/torque/4.0/generator/configuration"
     loglevel="debug">
   <output name="propertyKeys"
-      file="org/apache/torque/gf/example/gettingstarted/PropertyKeys.java">
-    <source>
-      <include>propertiesData.properties"</include>
+      file="org/apache/torque/generator/example/gettingstarted/PropertyKeys.java">
+    <source xsi:type="fileSource">
+      <include>propertiesData.properties</include>
     </source>
-    <generator name="classFrame"/>
+    <outlet name="classFrame"/>
   </output>
 </control>
     ]]></source>
@@ -333,99 +335,101 @@ $torqueGf.mergepoint("methods")##
       the output is written to the file 
       "org/apache/torque/gf/example/propertyenum/PropertyKeys.java",
       the source is read from "propertiesData.properties" in the src directory,
-      and the generator named "classFrame" (defined below) will be the master
-      generator for the output. 
+      and the outlet named "classFrame" (defined below) will be the master
+      outlet for the output. 
     </p>
   </section>
     
-  <section name="Configuring the generators">
+  <section name="Configuring the outlets">
     <p>
       Now that we have created the templates and defined our input and output,
       we must plug the templates into each other.
-      The torque generator encapsulates each template in a concept named 
-      "generator". Each generator acts on a source element and produces a 
-      String output from it. Also, a generator can define so-called
-      "mergepoints" where it can call insert the output of other generators.
-      To define the generators, create one or more xml file in the 
-      "generatorDefs" subdirectory ending with the suffix ".xml". 
-      Into each file, put a root element "generators".
+      The Torque generator encapsulates each template in a concept named 
+      "outlet". Each outlet acts on a source element and produces a 
+      String output from it. Also, an outlet can define so-called
+      "mergepoints" where it can call insert the output of other outlets.
+      To define the outlets, create one or more xml file in the 
+      "outlets" subdirectory ending with the suffix ".xml". 
+      Into each file, put a root element "outlets".
     </p>
     
     <p>
-      You need at least one generator per template 
+      You need at least one outlet per template 
       (you might have more than one if you want to fill the mergepoints
       differently).
-      For each generator, create a "generator" tag in the "generators" root 
-      element. Set the "type" attribute to "velocity", the "path" attribute
-      with the path to the template relative to the "templates" subdirectory,
+      For each outlet, create a "outlet" tag in the "outlets" root 
+      element. Set the "xsi:type" attribute to "velocityOutlet",
+      the "path" attribute to the path to the template
+      relative to the "templates" subdirectory,
       and give it an unique name using the "name" attribute.
-      For each mergepoint you want to fill in the generator, create 
-      a "mergepoint" tag in the "generator" tag with the "name" attribute 
+      For each mergepoint you want to fill in the outlet, create 
+      a "mergepoint" tag in the "outlet" tag with the "name" attribute 
       set to the name of the mergepoint in the template.
       Define the action you want to execute 
       (e.g. for calling another generator, use the apply action, 
       or for looping through several elements, use the traverse-all action).
     </p>
     <p>
-      In our example, we define the following generators in the file
-      "generatorDefs/enumGenerators.xml":
+      In our example, we define the following outlets in the file
+      "outlets/enumOutlets.xml":
     </p>
     <source><![CDATA[
 <?xml version="1.0" encoding="UTF-8"?>
-<generators xmlns="http://db.apache.org/torque/gf/4.0/configuration"
-    xsi:schemaLocation="http://db.apache.org/torque/gf/4.0/configuration http://db.apache.org/torque/gf/4.0/generator.xsd"
+<outlets xmlns="http://db.apache.org/torque/4.0/generator/configuration"
+    xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration http://db.apache.org/torque/4.0/generator/configuration.xsd"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-  <generator name="classFrame" xsi:type="velocityGenerator" path="classFrame.vm">
+  <outlet name="classFrame" xsi:type="velocityOutlet" path="classFrame.vm">
     <mergepoint name="constants">
-      <action xsi:type="traverseAllAction" element="entry" generator="constant"/>
+      <action xsi:type="traverseAllAction" element="entry" outlet="constant"/>
     </mergepoint>
     <mergepoint name="fields">
-      <action xsi:type="applyAction" generator="keyField"/>
-      <action xsi:type="applyAction" generator="newline"/>
+      <action xsi:type="applyAction" outlet="keyField"/>
+      <action xsi:type="applyAction" outlet="newline"/>
     </mergepoint>
     <mergepoint name="methods">
-      <action xsi:type="applyAction" generator="constructor"/>
-      <action xsi:type="applyAction" generator="newline"/>
-      <action xsi:type="applyAction" generator="getKey"/>
-      <action xsi:type="applyAction" generator="newline"/>
-      <action xsi:type="applyAction" generator="toString"/>
+      <action xsi:type="applyAction" outlet="constructor"/>
+      <action xsi:type="applyAction" outlet="newline"/>
+      <action xsi:type="applyAction" outlet="getKey"/>
+      <action xsi:type="applyAction" outlet="newline"/>
+      <action xsi:type="applyAction" outlet="toString"/>
     </mergepoint>
-  </generator>
-  <generator name="constant" xsi:type="velocityGenerator" path="constant.vm">
+  </outlet>
+  <outlet name="constant" xsi:type="velocityOutlet" path="constant.vm">
     <mergepoint name="constantName">
-      <action xsi:type="applyAction" generator="constantName"/>
+      <action xsi:type="applyAction" outlet="constantName"/>
     </mergepoint>
-  </generator>
-  <generator name="constantName" xsi:type="javaGenerator" class="org.apache.torque.gf.generator.java.ConstantNameGenerator">
+  </outlet>
+  <outlet name="constantName" xsi:type="javaOutlet" class="org.apache.torque.generator.outlet.java.ConstantNameOutlet">
     <inputSourceElement>.</inputSourceElement>
     <sourceElementAttribute>key</sourceElementAttribute>
-  </generator>
-  <generator name="keyField" xsi:type="velocityGenerator" path="keyField.vm"/>
-  <generator name="constructor" xsi:type="velocityGenerator" path="constructor.vm"/>
-  <generator name="getKey" xsi:type="velocityGenerator" path="getKey.vm"/>
-  <generator name="toString" xsi:type="velocityGenerator" path="toString.vm"/>
-  <generator name="newline" xsi:type="javaGenerator" class="org.apache.torque.gf.generator.java.NewlineGenerator"/>
-</generators>    ]]></source>
+  </outlet>
+  <outlet name="keyField" xsi:type="velocityOutlet" path="keyField.vm"/>
+  <outlet name="constructor" xsi:type="velocityOutlet" path="constructor.vm"/>
+  <outlet name="getKey" xsi:type="velocityOutlet" path="getKey.vm"/>
+  <outlet name="toString" xsi:type="velocityOutlet" path="toString.vm"/>
+  <outlet name="newline" xsi:type="javaOutlet" class="org.apache.torque.generator.outlet.java.NewlineOutlet"/>
+</outlets>    ]]></source>
 
     <p>
-      So, e.g. in the "classFrame" generator, the three mergepoints 
+      So, e.g. in the "classFrame" outlet, the three mergepoints 
       "constants", "fields" and "methods" are filled. In the "constants"
-      mergepoint, the generator "constant" is invoked for each "entry" 
+      mergepoint, the outlet "constant" is invoked for each "entry" 
       child element of the current source element. The output is then
       concatenated and filled into the mergepoint. In the "fields" and
-      "methods" mergepoints, a bunch of generators is invoked on the current
+      "methods" mergepoints, a bunch of outlets is invoked on the current
       source element ("properties"), the output is concatenated for each
       mergepoint and inserted into the mergepoint.
     </p>
     <p>
-      The "constantName" and the "newline" generators are a special case.
-      The "constantName" generator generates the name of a java constant
+      The "constantName" and the "newline" outlets are a special case.
+      The "constantName" outlet generates the name of a java constant
       from an input (e.h. converting to upper case, inserting underscores.)
-      The "newline"  generator simply prints a newline (\n) each time it is 
+      The "newline" outlet simply prints a newline (\n) each time it is 
       called, and is used to beautify the output.
-      Both generators are java generators which are provided by torque-gf 
-      and are referenced by their class name. The "constantName" generator
-      needs some additional configuration to know from where to read its input. 
+      Both outlets are java outlets which are provided 
+      by the Torque generator and are referenced by their class name.
+      The "constantName" outlet needs some additional configuration
+      to know from where to read its input. 
     </p>
   </section>
   
@@ -436,7 +440,7 @@ $torqueGf.mergepoint("methods")##
       or a simple java program can be used.
     </p>
     
-    <subsection name="Using the Torque-gf Maven 2 plugin">
+    <subsection name="Using the Torque Maven 2 plugin">
       <p>
         To hook the generation process into your Maven 2 build, you need to
         install Maven 2.
@@ -449,7 +453,7 @@ $torqueGf.mergepoint("methods")##
     <plugins>
       <plugin>
         <groupId>org.apache.torque</groupId>
-        <artifactId>maven-torque-gf-plugin</artifactId>
+        <artifactId>maven-torque-generator-plugin</artifactId>
         <version>0.2-SNAPSHOT</version>
         <executions>
           <execution>
@@ -459,7 +463,7 @@ $torqueGf.mergepoint("methods")##
               <goal>generate</goal>
             </goals>
             <configuration>
-              <!-- The torque-gf files are provided in a project directory -->
+              <!-- The torque generator files are provided in a project directory -->
               <packaging>directory</packaging>
             </configuration>
           </execution>
@@ -482,21 +486,21 @@ $torqueGf.mergepoint("methods")##
         program:
       </p>
       <source><![CDATA[
-package org.apache.torque.gf.example.gettingstarted;
+package org.apache.torque.generator.example.gettingstarted;
 
 import java.io.File;
 import java.util.ArrayList;
 import java.util.List;
 
 import org.apache.commons.io.FileUtils;
-import org.apache.torque.gf.configuration.UnitDescriptor;
-import org.apache.torque.gf.configuration.paths.DefaultTorqueGfPaths;
-import org.apache.torque.gf.configuration.paths.Maven2DirectoryProjectPaths;
-import org.apache.torque.gf.control.Controller;
+import org.apache.torque.generator.configuration.UnitDescriptor;
+import org.apache.torque.generator.configuration.paths.DefaultTorqueGeneratorPaths;
+import org.apache.torque.generator.configuration.paths.Maven2DirectoryProjectPaths;
+import org.apache.torque.generator.control.Controller;
 
 public class GettingStarted
 {
-    public static void main(String argv[]) throws Exception
+    public static void main(String[] argv) throws Exception
     {
         File target = new File("target");
         FileUtils.deleteDirectory(target);
@@ -506,10 +510,11 @@ public class GettingStarted
                 UnitDescriptor.Packaging.DIRECTORY,
                 new Maven2DirectoryProjectPaths(
                         new File(".")),
-                new DefaultTorqueGfPaths()));
+                new DefaultTorqueGeneratorPaths()));
         controller.run(unitDescriptors);
     }
-}]]></source>
+}
+]]></source>
       <p>
         Add all the dependencies of the torquegenerator into the classpath,
         and start this java program in the root directory of your project.

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml?rev=965980&r1=965979&r2=965980&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
Tue Jul 20 20:00:58 2010
@@ -31,7 +31,7 @@
     The following concepts are explained:
     <ul>
       <li>
-        <a href="#Generators">Generators</a>
+        <a href="#Outlets">Outlets</a>
       </li>
       <li>
         <a href="#Sources">Sources</a>
@@ -40,6 +40,9 @@
         <a href="#Transformers">Transformers</a>
       </li>
       <li>
+        <a href="#SkipDeciders">SkipDeciders</a>
+      </li>
+      <li>
         <a href="#Controller">Controller</a>
       </li>
       <li>
@@ -57,29 +60,30 @@
     </ul>
   </section>
   
-  <section name="Generators">
+  <section name="Outlets">
     <p>
-      A generator generates String output from sources.
-      An example for a generator is a VelocityTemplateGenerator,
+      A outlet generates String output from sources.
+      An example for an outlet is a VelocityOutlet,
       which uses a velocity template to create the output.
-      A generator may be used in several generation processes.
-      The output of a generator can be used as file name or (part of a) 
-      file content.
+      An outlet may be used in several generation processes.
+      The output of an outlet can be used as file name or (part of a) 
+      generated file.
     </p>
   </section>
   
   <section name="Sources">
     <p>
       Sources are the input of the generation process. They can be read 
-      from different formats, e.g. properties files and XML.
+      from different formats, e.g. properties files, XML files, 
+      or jdbc metadata.
       For each generation process, a directed weighted
       <a href="http://en.wikipedia.org/wiki/Graph_(mathematics)">graph</a>
       (which is usually, but not necessarily, a 
       <a href="http://en.wikipedia.org/wiki/Tree_(graph_theory)">tree</a>) 
       is constructed from the sources.
-      The graph may then be fed into the generators, or it may be transformed
-      in an intermediate step. Each generator can access the original 
-      respectively transformed graph to produce its output.
+      The graph may then be fed into the outlets, or it may be transformed
+      in an intermediate step. Each outlet can access the transformed graph
+      to produce its output.
     </p>
     <p>
       The graph is represented similarly to the structure which is normally 
@@ -99,9 +103,9 @@
   <section name="Transformers">
     <p>
       In the simplest generation projects, it suffices to pass the sources
-      directly to the generators. But in more complex projects, it makes sense
+      directly to the outlets. But in more complex projects, it makes sense
       to transform the source before generating output from it.
-      A Transformer performs the transformation from an input graph to an
+      A transformer performs the transformation from an input graph to an
       output graph. The output graph is then used for generation.
     </p>
      
@@ -134,7 +138,7 @@
       </root>
       ]]>
       </source>
-      Another  typical example is where part of the generation process will be
+      Another typical example is where part of the generation process will be
       used in different places. E.g. imagine a set of database tables from
       which java classes are generated. Because the tables are connected,
       so should the generated java classes be. Thus, the java class name
@@ -157,6 +161,16 @@
     </p>
   </section>
   
+  <section name="SkipDeciders">
+    <p>
+      SkipDeciders do what their name promise, they decide whether
+      the generation of certain files is skipped. E.g. a SkipDecider
+      could read an option value and skip the generation of a file
+      if the option is not set. SkipDeciders are java classes which
+      implement the SkipDecider interface.
+    </p>
+  </section>
+  
   <section name="Controller">
     <p>
       The Controller makes sure that the configuration files
@@ -177,16 +191,16 @@
   
   <section name="Variables">
     <p>
-      To ease communication between generators, the concept of a variable
-      is also known outside of the single generators. This makes it possible
-      e.g. to pass a variable from a Java generator to a Velocity template
+      To ease communication between outlets, the concept of a variable
+      is also known outside of the single outlets. This makes it possible
+      e.g. to pass a variable from a Java outlet to a Velocity template
       in the same generation process.
     </p>
     <p>
       Variables have different scopes. The scope defines where a certain
-      variable is visible. The current scopes are "GENERATOR" (the variable
-      is only visible in this generator), "CHILDREN" (the variable is visible 
-      to the current generator and all generators called by it), "FILE"
+      variable is visible. The current scopes are "OUTLET" (the variable
+      is only visible in this outlet), "CHILDREN" (the variable is visible 
+      to the current outlet and all outlets called by it), "FILE"
       (the variable is visible during the generation of the current file),
       and "GLOBAL" (the variable is always visible).
     </p>
@@ -199,25 +213,25 @@
   
   <section name="Mergepoints">
     <p>
-      The Torque generation framework encourages to use modularized generators,
+      The Torque generator encourages to use modularized outlets,
       in order to reuse them or drop, replace or add parts into the generation
       process. 
-      To connect one generator to another, mergepoints can be used.
-      A mergepoint is a place where the output of one generator can be fed
-      into another generator.
+      To connect one outlet to another, mergepoints can be used.
+      A mergepoint is a place where the output of one outlet can be fed
+      into another outlet.
     </p>
     <p>
       If a mergepoint is encountered during the generation process,
       one or more actions may be performed, depending of the configuration
-      of the current generator. Typically, these actions describe how to
-      traverse the source tree. An example would be "invoke the generator xyz
+      of the current outlet. Typically, these actions describe how to
+      traverse the source tree. An example would be "invoke the outlet xyz
       for all children of the current element and insert the output here".
     </p>
     <p>
       If no action is defined at a mergepoint, it is left unused. This should
-      be used to insert extension points in the generators, as a placeholder
+      be used to insert extension points in the outlets, as a placeholder
       for additional output. E.g. if you write a velocity template which
-      generates a java class, it makes sense to create an unused extension
+      generates a java class, it makes sense to create unused extension
       points where additional methods can be inserted (without changing the 
       template).  
     </p>
@@ -225,21 +239,20 @@
 
   <section name="Namespaces">
     <p>
-      If generators are created in a modular manner, it is desirable that 
-      some options and variables are visible only to one generator,
-      while others should be visible to all generators. To support this,
-      generators, options and variables can be assigned a namespace. 
-      Namespace elements are separated by dots, and are separated from the 
-      name by colons. Generators see only options and variables which live 
-      in their namespace or in parent namespaces.
+      If outlets are created in a modular manner, it is desirable that 
+      some options and variables are visible only to one outlet,
+      while others should be visible to all outlets. To support this,
+      outlets, options and variables can be assigned a namespace. 
+      Namespace elements are separated by dots. Generators see only options
+      and variables which live in their namespace or in parent namespaces.
     </p>
     <p>
-      For example, the generator with the fully qualified name 
-      "org.apache.torque.generator:classnameToFilename" lives in the namespace
+      For example, the outlet with the fully qualified name 
+      "org.apache.torque.generator.classnameToFilename" lives in the namespace
       "org.apache.torque.generator" and will only see variables and options
       set in that namespace or in the parent namespaces "org.apache.torque", 
       "org.apache", "org" and "". The namespace "" is also called the root
-      namespace, variables and options therein are visible to all generators.
+      namespace, variables and options therein are visible to all outlets.
     </p>
     <p>
       You do not need to use namespaces; if you do not prefix any name with 

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml?rev=965980&r1=965979&r2=965980&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
Tue Jul 20 20:00:58 2010
@@ -26,27 +26,25 @@
 
  <body>
   <section name="Introduction">
-    The Torque generation framework can be configured by the following files:
+    The Torque generator can be configured by the following files:
     <ul>
       <li>
         The file conf/control.xml tells the generator which files should be
-        generated, and which sources, options and generators should be
+        generated, and which sources, options and outlets should be
         used to generate them.
-        This is the only file you should have to edit if you are using
-        a given set of templates and generators.
       </li>
       <li>
-        For the generation process, generators (which create String output
+        For the generation process, outlets (which create String output
         out of sources) must be defined.
-        In each generator configuration file, one or more generators 
-        can be defined. 
-        The minimum information needed for each generator is a unique name,
-        its type, and the information to invoke the generator of this 
+        In each outlet XML configuration file in the outlets directory,
+        one or more outlets can be defined. 
+        The minimum information needed for each outlet is a unique name,
+        its type, and the information to invoke the outlet of this 
         given type. 
-        For example, if the generator has the type &quot;velocity&quot;
-        i.e. the generator is a velocity template, then the path to
+        For example, if the outlet has the type &quot;velocityOutlet&quot;
+        i.e. the outlet is a velocity template, then the path to
         the template is needed as well.<br/>
-        All generator properties can be overridden in the controller
+        All outlet properties can be overridden in the controller
         configuration.
       </li>
       <li>
@@ -57,23 +55,23 @@
     </ul>
   </section>
   <section name="Standard directory layout">
-    The Torque generation framework uses a standard directory layout for its
+    The Torque generator uses a standard directory layout for its
     configuration:
     <source>
-      - torque-gf directory (e.g. src/main/torque-gf for maven 2)
+      - torque-gen directory (e.g. src/main/torque-gen for maven 2)
         - conf
           - control.xml
           - options.properties (not always present, name can differ)
-        - generatorDefs
-          - generation_config_example.xml (name not fixed)
-          - ... (other generator definitions)
+        - outlets
+          - outlet_config_example.xml (name not fixed)
+          - ... (other outlet definition files)
         - templates (only if template generators are used)
           - template_example.vm (name not fixed)
           - ... (other templates)
     </source>
     The sources are not considered part of the configuration; thus they do not
     appear here (If you have no idea where to put the sources,
-    create a src directory in the torque-gf directory and put them there.)
+    create a src directory in the torque-gen directory and put them there.)
     The content of the various directories is described below.  
   </section>
   
@@ -85,56 +83,73 @@
     and the output files are defined. A control file may like this:
     <source><![CDATA[
 <?xml version="1.0" encoding="UTF-8"?>
-<control loglevel="debug">
-  <options path="options.properties"/>
-  
-  <!-- Documentation html -->
-  <output file="datamodel.html">
-    <source elements="database" path="schema.xml"/>
-    <generator name="torque.doc.html:html"/>
-  </output>
-  
-  <!-- Base DB object classes -->
-  <output>
-    <filenameGenerator
-        type="java" 
-        class="org.apache.torque.gf.generator.java.FilenameGenerator">
+<control loglevel="info"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration http://db.apache.org/torque/4.0/generator/configuration.xsd"
+    xmlns="http://db.apache.org/torque/4.0/generator/configuration">
+
+  <options xsi:type="propertiesOptions" path="options.properties"/>
+
+  <output name="torque.om.dbObject" skipIfExists="true">
+    <filenameOutlet
+        xsi:type="javaOutlet"
+        class="org.apache.torque.generator.outlet.java.JavaFilenameOutlet">
       <mergepoint name="package">
-        <action type="sourceElement" element="." attribute="baseDbObjectPackage" acceptEmpty="false"/>
+        <action
+           xsi:type="sourceElementAttributeAction"
+           element="."
+           attribute="dbObjectPackage"
+           acceptNotSet="false"/>
       </mergepoint>
       <mergepoint name="classname">
-        <action type="sourceElement" element="." attribute="baseDbObjectClassName" acceptEmpty="false"/>
+        <action 
+            xsi:type="sourceElementAttributeAction"
+            element="."
+            attribute="dbObjectClassName"
+            acceptNotSet="false"/>
       </mergepoint>
-    </filenameGenerator>
-    <source elements="database/table" path="schema.xml">
+    </filenameOutlet>
+    <source xsi:type="fileSource" 
+        elements="database/table"
+        skipDecider="org.apache.torque.templates.sourcefilter.OmSkipDecider">
       <transformer class="org.apache.torque.templates.transformer.om.OMTransformer"/>
-      <transformer class="org.apache.torque.templates.transformer.om.dbobject.base.BaseDbObjectTransformer"/>
+      <include>*schema.xml</include>
+      <exclude>id-table-schema.xml</exclude>
     </source>
-    <generator name="torque.om:baseDbObject"/>
-  </output>  
+    <outlet name="torque.om.dbObject"/>
+  </output>
 </control>
     ]]></source>
     The loglevel attribute on the control file defines the amount of logging
     during generation. Possible values are "debug", "info", "warn" and "error",
     default is "info".<br/>
     The "options" elements define which option files should be read
-    (one can define more than one).
+    (more than one options file is possible).
     If the same option is defined in different files, the value in the 
     last file takes precedence.<br/>
-    The output tags define which output files are generated. 
+    The output tags define which output files are generated.
+    The name attribute of the output is used for debugging purposes and
+    must be set. 
     The filename of the output files can either be defined in the "filename"
-    attribute if the filename is fixed, or in the filenameGenerator 
+    attribute if the filename is fixed, or in the filenameOutlet 
     child element if the filename is generated from the sources.
-    The source elements for which output files are generated are defined in
-    the source child element of the output tag. A XPath-like notation
-    can be used to traverse the source graph (note that only the simplest 
-    XPath elements are recognized, i.e. explicit element names and the Tokens 
-    "/", ".." and "."). For each source element which matches the description
-    in the elements attribute, an output file is generated 
-    (note that this also applies for fixed output filenames).<br/>
-    The filename generator can be either referenced by name (if it is defined
+    The files to read as input and the source elements for which 
+    output files are generated are defined in the source child element
+    of the output tag.
+    The filename outlet can be either referenced by name (if it is defined
     elsewhere), or can be defined here by using the "type" and "class"
-    attributes.
+    attributes.<br/>
+    A XPath-like notation can be used to traverse the source graph 
+    (note that only the simplest XPath elements are recognized,
+     i.e. explicit element names and the Tokens "/", ".." and ".").
+    In principle, for each source element which matches the description
+    in the elements attribute in each source file matching the include/exclude
+    pattern, an output file is generated. 
+    However, the SkipDecider class which can be configured in the
+    "skipDecider" attribute of the "source" element can determine to
+    skip generation under certain circumstances.
+    Note that this multiple processing also applies for fixed output filenames.
+    <br/>
     If the source needs to be transformed before generation, transformer
     tags are included as children of the source tag. For each transformer,
     the class must be given. If more than one transformer is defined for a 
@@ -143,48 +158,79 @@
     fed into the generators.
   </section>
   
-  <section name="Configuring the generators">
+  <section name="Configuring the outlets">
     <p>
-      The generators can be defined and wired together in the generatorDefs 
+      The outlets can be defined and wired together in the outlets 
       subdirectory (recommended) or in the control.xml file 
       (should only be used when overriding settings in existing 
       template sets).
-      Each file in this directory defines one or more generators.
-      Each generator must be given an unique name; it is recommended to use
+      Each file in this directory defines one or more outlets.
+      Each outlet must have an unique name; it is recommended to use
       namespaces for avoiding name conflicts if more than one template set 
-      is used. Also, the type of the generator must be given (currently
+      is used. Also, the type of the outlet must be given (currently
       supported are "velocity" and "java"). Depending on the type, further
-      informations need to be given: The velocity generators need the path
+      informations need to be given: The velocity outlets need the path
       to the template (relative to the templates subdirectory),
-      the java generators need the class of the generator class.
-      For example, this defines a java and a velocity generator:
+      the java outlets need the class of the outlet class.
+      For example, this defines a java and a velocity outlet:
     </p>
     
 <source><![CDATA[
 <?xml version="1.0" encoding="UTF-8"?>
-<generators>
-  <generator name="org.apache.torque.gf:javaGenerator"
-      type="java" 
-      class="org.apache.torque.gf.JavaGenerator">
+<outlets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration http://db.apache.org/torque/4.0/generator/configuration.xsd"
+    xmlns="http://db.apache.org/torque/4.0/generator/configuration">
+  <outlet name="org.apache.torque.generator.javaOutlet"
+      xsi:type="javaOutlet" 
+      class="org.apache.torque.generator.JavaGenerator">
   </generator>
-  <generator name="org.apache.torque.gf:velocityGenerator"
-      type="velocity" 
-      path="testTemplate.vm"/>
-</generators>
+  <outlet name="torque.om.bean.baseBean" 
+      xsi:type="velocityOutlet"
+      path="bean/base/baseBean.vm"/>
+</outlets>
 ]]></source>
 
     <subsection name="mergepoints">
       <p>
-        In each generator, mergepoints can be defined. 
+        In each outlet, mergepoints can be defined. 
         Into each mergepoint, external content may be inserted 
         (e.g. the value of an option or a 
         variable or the output of another template). To keep your templates
         flexible, it makes sense to define mergepoints where you do not need
         them now but may need them in the future (you do not have to assign
         content to a mergepoint, it can also stay empty).
-        The mergepoint inside the generator is referenced by
-        its name. 
+        The mergepoint inside the outlet is referenced by
+        its name. For example, the following configuration defines three outlets,
+        and the output of the last two outlet is used in mergepoints of
+        the first outlet:
       </p>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<outlets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration http://db.apache.org/torque/4.0/generator/configuration.xsd"
+    xmlns="http://db.apache.org/torque/4.0/generator/configuration">
+  <outlet name="torque.om.bean.base.getterSetter"
+      xsi:type="velocityOutlet"
+      path="general/getterSetter.vm">
+    <mergepoint name="getter">
+      <action xsi:type="applyAction" outlet="torque.om.bean.base.getter"/>
+    </mergepoint>
+    <mergepoint name="setter">
+      <action xsi:type="applyAction" outlet="torque.om.bean.base.setter"/>
+    </mergepoint>
+  </outlet>
+
+  <outlet name="torque.om.bean.base.getter"
+      xsi:type="velocityOutlet"
+      path="bean/base/getter.vm">
+  </outlet>
+
+  <outlet name="torque.om.bean.base.setter"
+      xsi:type="velocityOutlet"
+      path="bean/base/setter.vm">
+  </outlet>
+</outlets>
+]]></source>
     </subsection>
   </section>
  </body>

Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
(from r917970, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/generatorTypes.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/generatorTypes.xml&r1=917970&r2=965980&rev=965980&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/generatorTypes.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
Tue Jul 20 20:00:58 2010
@@ -21,28 +21,31 @@
 <document>
 
  <properties>
-  <title>Generator Types</title>
+  <title>Outlet Types</title>
  </properties>
 
  <body>
   <section name="Introduction">
-    The Torque generator can handle different generator types, 
-    currently velocity and java generators.
-    The Velocity generators use templates to produce the output, 
-    the java generators create their output directly in java.
+    The Torque generator can handle different outlet types, 
+    currently velocity and java outlets.
+    The velocity outlets use templates to produce the output, 
+    the java outlets create their output directly in java.
   </section>
   
   <section name="Configuration">
-    As the different generator types need different configurations, a
-    custom configuration parser is needed for each generator type. 
-    (The generator type is determined by the "type" attribute of the
-    generator and filenameGenerator elements in the project configuration).
+    As the different outlet types need different configurations, a
+    custom configuration parser is needed for each outlet type. 
+    (The generator type is determined by the "xsi:type" attribute of the
+    outlet and filenameOutlet elements in the project configuration).
     The Torque generator needs to be told which parser it should use for which 
-    generator type. This is done by registering a generatorHandlerFactory
+    outlet type. This is done by registering a outletHandlerFactory
     for each generator type, see 
-    <code>ControllerState.registerGeneratorHandlerFactory(GeneratorSaxHandlerFactory)</code>.
-    This could in principle be used to plug in new generator types,
-    but alas, the plug-in process it is not yet configurable :-(.
+    <code>OutletTypes.registerOutletHandlerFactory(OutletSaxHandlerFactory)</code>.
+    The outletTypes instance is accessible via the ConfigurationHandlers
+    instance passed from the Configuration object. 
+    This could in principle be used to plug in new outlet types,
+    but alas, the configuration object is hidden in the controller instance
+    and not accessible from the outside :-(.
   </section>
   
  </body>



---------------------------------------------------------------------
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