<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you 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>Concepts</title>
 </properties>

 <body>
  <section name="Introduction">
    This document introduces the main concepts of the Torque generator.
    The following concepts are explained:
    <ul>
      <li>
        <a href="#Outlets">Outlets</a>
      </li>
      <li>
        <a href="#Sources">Sources</a>
      </li>
      <li>
        <a href="#Transformers">Transformers</a>
      </li>
      <li>
        <a href="#SkipDeciders">SkipDeciders</a>
      </li>
      <li>
        <a href="#Postprocessors">Postprocessors</a>
      </li>
      <li>
        <a href="#Controller">Controller</a>
      </li>
      <li>
        <a href="#Options">Options</a>
      </li>
      <li>
        <a href="#Variables">Variables</a>
      </li>
      <li>
        <a href="#Mergepoints">Mergepoints</a>
      </li>
      <li>
        <a href="#Namespaces">Namespaces</a>
      </li>
      <li>
        <a href="#Configuration">Configuration</a>
      </li>
      <li>
        <a href="#Overriding">Overriding</a>
      </li>
    </ul>
  </section>
  
  <section name="Outlets">
    <p>
      A outlet generates String output from sources.
      An example for an outlet is a VelocityOutlet,
      which uses a velocity template to create the output.
      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, 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 outlets, or it may be transformed
      in an intermediate step. Each outlet can access the transformed graph
      to produce its output.
    </p>
    <p>
      Initially (when loaded), the graph is represented similarly 
      to the structure which is normally used to represent XML files: 
      The nodes are called "elements", and each element has a list of children
      and a list of parents (i.e. parents and children are ordered).
      Elements without parents
      are also allowed, but usually there will be only one such element 
      (the "root").<br/>
      Each element can also have attributes. Each attribute has a name and a
      value. There can be at most one attribute with a given name for each
      element. <br/>
      Additionally to the attributes, each element also has a name. 
    </p>
  </section>
  
  <section name="Transformers">
    <p>
      In the simplest generation projects, it suffices to pass the sources
      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 model to an
      output model. The output model is then used for generation.
      In general, the input model and the output model do not need to have the
      same structure. For example, it is common to transform the element graph
      from reading the sources to a typed model. An example is shown below.
    </p>
     
    <p>  
      A typical example is that different source elements reference each other
      (e.g. by name,  or by even more complex relations), 
      and one would like to have this reference resolved before the 
      generation phase. E.g. the source looks (in XML representation) like 
      <source><![CDATA[
      <root>
        <element name="element1">
          <related name="element2">
        </element>
        <element name="element2"/>
        <element name="element3"/>
      </root>
      ]]>
      </source>
      and it would be transformed to
      <source><![CDATA[
      <root>
        <element name="element1">
          <related name="element2">
          <relatedElements>
            <element name="element2"/> <-- This is typically element2 itself, not a copy
          </relatedElements>
        </element>
        <element name="element2"/>
        <element name="element3"/>
      </root>
      ]]>
      </source>
      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
      associated to one table will be used in more than one place. To make sure
      that the same name is used everywhere, it makes sense to generate the
      java class name of the table beforehand, like:
      <source><![CDATA[
      <database>
        <table name="FIRST_TABLE" />
      </database>
      ]]>
      </source>
      would be transformed to
      <source><![CDATA[
      <database>
        <table name="FIRST_TABLE" javaName="FirstTable"/>
      </database>
      ]]>
      </source>      
    </p>
    <p>
      A third typical example is to transform the graph model to a typed model.
      Consider again the example source
      <source><![CDATA[
      <database>
        <table name="FIRST_TABLE" />
      </database>
      ]]>
      </source>
      Now, in generation, we want to use not the graph model, but a java model
      representing the XML structure, for example
      <source><![CDATA[
      // Database.java
      public class Database {
        public List<Table> tableList;
      }
      
      // Table.java
      public class Table {
        public String name;
      }
      ]]>
      </source>
      Torque brings a transformer which can do the above transformation 
      out of the box: the SourceElementToModelTransformer.
      This transformer needs the root class of the typed model as argument,
      e.g. in the above case (assuming the class Database is in the package
      "model")
      <source><![CDATA[
      ...
      <transformer class="org.apache.torque.generator.source.transform.SourceElementToModelTransformer">
         <modelRootClass>model.Database</modelRootClass>
      </transformer>
      ...
      ]]>
      </source>
      This transformer brings a few restrictions:
      <ul>
        <li>
          The attribute types must be concrete classes with a default
          constructor.
        </li>
        <li>
          Each attribute in the source graph must have an associated property
          in the target model.
        </li>
        <li>
          Each child element in the source graph must have an associated 
          property in the target model.
        </li>
        <li>
          The name of the associated property must be either the name of the 
          attribute/child element, 
          or the the name of the attribute/child element with suffix "s",
          or the the name of the attribute/child element with suffix "List".
          Should the name of the attribute/child element be a reserved
          java word, the java property name must be prefixed by an 
          underscore (_). (e.g. attribute "default" -> java field "_default")  
        </li>
        <li>
          The java property can either consist of a public field or a public 
          setter using the JavaBeans conventions. If using setters for arrays
          or collections, a public getter must also be available in the case
          more than one element needs to be filled into the array or collection.
        </li>
      </ul>
    </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 
      org.apache.torque.generator.source.skipDecider.SkipDecider interface.
    </p>
  </section>
  
  <section name="Postprocessors">
    <p>
      Postprocessors process the generated content after generation.
      I.e. they do not know the source model any more, they just operate
      on the generated text. Postprocessors are java classes which implement
      the org.apache.torque.generator.processor.string.StringProcessor
      interface. They are useful for e.g. fixing the line end mode of files
      (org.apache.torque.generator.processor.string.UnixLinefeedProcessor)
      or for removing unused imports in java class files
      (org.apache.torque.generator.processor.string.OrganizeImportsProcessor).
    </p>
  </section>
  
  <section name="Controller">
    <p>
      The Controller makes sure that the configuration files
      are read, reads the source and options, performs possible transformations 
      on the source and feeds the result into the generators.
    </p>
  </section>
  
  <section name="Options">
    <p>
      Options can be used in the generation process
      to influence the output.  Note that sometimes, there might be an
      ambiguity between sources and options.  The difference is more of a
      philosophical nature: Sources are the data to be processed, whereas
      options influence the way the data is processed.
    </p>
  </section>
  
  <section name="Variables">
    <p>
      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 "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>
    <p>
      Note that scopes and <a href="#Namespaces">namespaces</a> 
      are orthogonal concepts, i.e. a variable is visible only if it
      has a sufficient scope and the correct namespace.
    </p>
  </section>
  
  <section name="Mergepoints">
    <p>
      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 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 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 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 unused extension
      points where additional methods can be inserted (without changing the 
      template).  
    </p>
  </section>

  <section name="Namespaces">
    <p>
      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 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 outlets.
    </p>
    <p>
      You do not need to use namespaces; if you do not prefix any name with 
      a namespace, every option and variable will be seen by every template.
    </p>
  </section>

  <section name="Configuration">
    <p>
      The configuration of the Torque generator tells the 
      <a href="#Controller">Controller</a> which <a href="#Options">option</a>
      files are read, which output files are produced from which
      <a href="#Outlets">Outlets</a> and <a href="#Sources">Sources</a>,
      which <a href="#SkipDeciders">SkipDeciders</a> and which 
      <a href="#Transformers">Transformers</a> should be used, and which
      <a href="#Outlets">Outlets</a> are connected to which
      <a href="#Mergepoints">Mergepoints</a>.
       The configuration of the Torque generator is described in detail
       in the <a href="configuration.html">configuration section</a>
       of the Torque generation documentation.
    </p>
  </section>

  <section name="Overriding">
    <p>
      The Torque generator offers overriding via a parent-child mechanism.
      A generator configuration can inherit from another generator
      configuration; and settings can be overridden or added.
      This can be used to customize the generation output.
      A common way to change the output is to add or change
      <a href="#Outlets">Outlets</a> which are used by the generation mechanism.
      E.g. one can replace a template in all places by overriding
      an <a href="#Outlets">Outlet</a> definition in a child configuration,
      or one can disable the use of an outlet in a place by overriding a 
      <a href="#Mergepoints">Mergepoint</a> definition.
    </p>
  </section>
 </body>
</document>
