<?xml version="1.0"?>
<!--
 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>Torque ORM Reference - Running the Generator</title>
 </properties>

 <body>
 
  <section name="Introduction to the Generator">
    <p>
      Torque uses the information from the database schema
      to generate classes by which the database can be accessed.
      Also, Torque can generate SQL scripts and documentation in
      HTML and xdoc format from the schema.
      The Torque generator must be invoked in order to generate these artifacts.
      This can be done in three different ways: via Maven 2/3, via ant or via
      plain Java.
    </p>
    <p>
      As the Torque generator is a general-purpose code generator,
      it must also know how to generate these classes.
      This is done by referencing the Torque templates from the generator run.
    </p>
    <p>
      In the templates, the different generation goals (om classes, sql, doc...)
      are organized in different packages. For each generation goal,
      the correct package needs to be accessed. This is described in detail
      in the following sections.<br/>
    </p>
  </section>

  <section name="Using Maven 2/3">
    <subsection name="Preparation">
      <p>
        When using Maven, the Torque generator is invoked
        by the Torque Maven Plugin.
        There is no need to invoke the generator manually or to add
        the generator to the runtime dependencies of your project.
        For adding the Torque Maven plugin to your build,
        add the following to your pom.xml:
      </p>
      <source><![CDATA[
      <plugin>
        <groupId>org.apache.torque</groupId>
        <artifactId>torque-maven-plugin</artifactId>
        <version>4.0</version>
        <executions>
           ...(see below)
        </executions
        <dependencies>
          <dependency>
            <groupId>org.apache.torque</groupId>
            <artifactId>torque-templates</artifactId>
            <version>4.0</version>
          </dependency>
        </dependencies>
      </plugin>
      ]]></source>
      <p>
        In the following, only basic configuration of the Torque Maven Plugin
        is covered. For details of configuration of the Torque Maven Plugin,
        refer to the 
        <a href="../modules/maven-plugin/reference/generate-goal.html">generate goal reference</a>.
      </p>
    </subsection>
    <subsection name="Generation of om classes">
      <p>
        For generating the OM classes, add the following execution to the
        executions list of the torque-generator plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-sources</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.om</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <options>
                <torque.om.package>${torque.target.package}</torque.om.package>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). Replace ${torque.target.package} 
        with the base package for your generation, e.g. org.apache.torque.test.
      </p>
      <p>
        You can add additional options to the configuration inside the options
        tag. The available options are described below.
      </p>
      <p>
        This execution will generate the om code for all source files 
        in the schema directory ending on -schema.xml, 
        but excluding id-table-schema.xml. 
        The output will be produced in the directories 
        target/generated-sources and src/main/generated-java.
      </p>
      <p>
        See the <a href="customizing-generation.html">Customizing</a> page for a
        documentation of available options which can be used to customize
        the generated output.
      </p>
    </subsection> 
    <subsection name="Generation of ddl sql">
      <p>
        For generating the data description language(ddl) sql for the tables,
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-sql</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.sql</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <defaultOutputDir>target/generated-sql</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.database>${torque.target.database}</torque.database>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.target.database} with the target database type 
        (e.g. mysql, oracle). Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). 
      </p>
      <p>
        This will generate the sql code for all source files in the schema
        directory ending on -schema.xml; the output goes to the directory 
        target/generated-sql.
      </p>
      <p>
        See the <a href="customizing-generation.html">Customizing</a> page for a
        documentation of available options which can be used to customize
        the generated output.
      </p>
    </subsection>
    <subsection name="Generation of IDBroker SQL">
      <p>
        For generating the SQL to fill the IDBroker tables,
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-idtable-sql</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.idtable</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <defaultOutputDir>target/generated-sql</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.database>${torque.target.database}</torque.database>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.target.database} with the target database type 
        (e.g. mysql, oracle). Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). 
      </p>
      <p>
        This will generate the sql code for all source files in the schema
        directory ending on -schema.xml; the output goes to the directory 
        target/generated-sql.
      </p>
      <p>
        See the <a href="customizing-generation.html">Customizing</a> page for a
        documentation of available options which can be used to customize
        the generated output.
      </p>
      <p>
        Note that for generating the ddl for the id tables, 
        you need to generate the ddl sql for the following schema file:
      </p>
      <source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<database name="${database.name}"
    xmlns="http://db.apache.org/torque/5.0/templates/database"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://db.apache.org/torque/5.0/templates/database 
        http://db.apache.org/torque/torque-5.0/documentation/orm-reference/database-5-0-strict.xsd">

  <table name="ID_TABLE" idMethod="idbroker">
    <column name="ID_TABLE_ID" required="true" primaryKey="true" type="INTEGER"/>
    <column name="TABLE_NAME" required="true" size="250" type="VARCHAR"/>
    <column name="NEXT_ID" type="INTEGER"/>
    <column name="QUANTITY" type="INTEGER"/>

    <unique>
      <unique-column name="TABLE_NAME"/>
    </unique>

  </table>
</database>
      ]]></source>
      <p>
        where ${database.name} should be replaced by the symbolic name of the 
        database for which you want to use the idbroker. 
        The generation of om classes is not required for the idbroker table.
      </p>
    </subsection>
    <subsection name="Generation of database create scripts">
      <p>
        For generating the SQL scripts for creating a database
        (which does not make sense for every database vendor),
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-createdb-sql</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.sql.createdb</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <defaultOutputDir>target/generated-createdb-sql</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.database>${torque.target.database}</torque.database>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.target.database} with the target database type 
        (e.g. mysql, oracle). Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). 
      </p>
      <p>
        This will generate the createdb sql code for all source files
        in the schema directory ending on -schema.xml; 
        the output goes to the directory target/generated-createdb-sql.
      </p>
    </subsection>
    <subsection name="Generation of html documentation">
      <p>
        For generating html documentation for the tables,
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-html-doc</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.doc.html</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <defaultOutputDir>target/generated-docs</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.om.package>${torque.target.package}</torque.om.package>
                <torque.database>${torque.target.database}</torque.database>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.target.database} with the target database type 
        (e.g. mysql, oracle). Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). Replace ${torque.target.package} 
        with the base package for your generation, e.g. org.apache.torque.test.
      </p>
      <p>
        This will generate the html documentation for all source files
        in the schema directory ending on -schema.xml.
        The output will be produced in the directory target/generated-docs.
      </p>
    </subsection> 
    <subsection name="Generation of xdoc documentation">
      <p>
        For generating xdoc documentation for the tables 
        (to be included into your maven site),
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-xdoc</id>
            <phase>pre-site</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.doc.xdoc</configPackage>
              <sourceDir>${torque.schema.source.dir}</sourceDir>
              <defaultOutputDir>target/generated-xdocs</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.om.package>${torque.target.package}</torque.om.package>
                <torque.database>${torque.target.database}</torque.database>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.target.database} with the target database type 
        (e.g. mysql, oracle). Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). Replace ${torque.target.package} 
        with the base package for your generation, e.g. org.apache.torque.test.
      </p>
      <p>
        This will generate the xdoc documentation
        for all source files in the schema directory ending on -schema.xml.
        The output is produced in the directory target/generated-xdocs.
        You may then want to add the following configuration to your pom
        to include this directory in your site:
      </p>
      <source><![CDATA[
      <plugin>
        <artifactId>maven-site-plugin</artifactId>
        <groupId>org.apache.maven.plugins</groupId>
        <configuration>
          <xdocDirectory>target/generated-xdocs</xdocDirectory>
        </configuration>
      </plugin>
      ]]></source>        
    </subsection> 
    <subsection name="Generation of XML schema from an existing database">
      <p>
        For extracting the structure of an existing database into
        a schema file,
        add the following execution to the executions list
        of the Torque Maven plugin:
      </p>
      <source><![CDATA[
          <execution>
            <id>generate-schema-from-jdbc</id>
            <phase>generate-test-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <packaging>classpath</packaging>
              <configPackage>org.apache.torque.templates.jdbc2schema</configPackage>
              <defaultOutputDir>target/generated-schema</defaultOutputDir>
              <defaultOutputDirUsage>none</defaultOutputDirUsage>
              <options>
                <torque.jdbc2schema.driver>${torque.driver}</torque.jdbc2schema.driver>
                <torque.jdbc2schema.url>${torque.database.url}</torque.jdbc2schema.url>
                <torque.jdbc2schema.user>${torque.database.user}</torque.jdbc2schema.user>
                <torque.jdbc2schema.password>${torque.database.password}</torque.jdbc2schema.password>
                <torque.jdbc2schema.schema>${torque.database.schema}</torque.jdbc2schema.schema>
              </options>
            </configuration>
          </execution>
      ]]></source>
      <p>
        Replace ${torque.driver} with the fully qualified class name of the
        database driver. Replace ${torque.database.url} 
        with the url to connect to the database.
        Replace ${torque.database.user} and ${torque.database.password} 
        with the database username and the corresponding password.
        You may want to replace ${torque.database.schema} with the database 
        schema to read, if not please remove the line containing it.
      </p>
      <p>
        Note that Torque relies on metainformation supplied by the database
        driver for creating the schema file.
        This metainformation does not contain all information which is
        contained in the schema file, so the created file can only serve
        as a starting point. 
        The information which can be read from the database differs from 
        database to database.
        Table and column names can be read for almost every database.
        Column types, primary key information, and information about
        nullability and column default values is available 
        for most databases, but there might be edge cases where type information
        is not detailed enough to determine the correct column type.
        Foreign key information and information about indices are typically
        not read.
      </p>
    </subsection> 
  </section>


  <section name="Using Ant">
    <subsection name="Preparation">
      <p>
        When using Ant, the Torque generator is invoked
        by the generator task, which is defined in the torque-ant-tasks
        project. 
        Thus, the generator task needs to be defined as follows in the
        buildfile before it can be used:
      </p>
      <source><![CDATA[
    <taskdef
      name="torque-generator"
      classpathref="ant-classpath"
      classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>
      ]]></source>
      <p>
        where ant-classpath points to a path which contains all jars from the
        binary Torque ant tasks distribution, plus the torque-templates jar.
      </p>
      <p>
        In the following, only basic configuration of the Torque Ant Tasks
        is covered. For details of configuration of the Torque Ant Tasks,
        refer to the 
        <a href="../modules/ant-tasks/reference/generator-task.html">generator task reference</a> and 
         <a href="../modules/ant-tasks/reference/jdbc2schema-task.html">generator task reference</a>.
      </p>
    </subsection>
    <subsection name="Generation of om classes">
      <p>
        A basic configuration for generating the om classes would be
      </p>
      <source><![CDATA[
      <torque-generator 
          packaging="classpath"
          configPackage="org.apache.torque.templates.om"
          sourceDir="${torque.schema.source.dir}">
        <option key="torque.om.package" value="${torque.target.package}"/>
      </torque-generator>
      ]]></source>
      <p>
        Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). Replace ${torque.target.package} 
        with the base package for your generation, e.g. org.apache.torque.test.
      </p>
    </subsection>
    <subsection name="Other generated artifacts">
      <p>
        See the maven example above for the settings necessary 
        to generate the other possible artifacts and apply them to the
        ant tasks.
        TODO describe in detail.
      </p> 
      <p>
        See <a href="../tutorial/orm/step1-ant.html">the ORM tutorial</a>
        for a complete build file example.
      </p> 
    </subsection>
  </section>


  <section name="Using Java">
    <subsection name="Preparation">
      <p>
        Using Java to generate classes should not normally be necessary.
        However, it can be useful if you neither use Maven nor Ant
        as build system.
        To use the generator from Maven, the Torque generato jar
        and its dependencies must be on the class path.
      </p>
      <p>
        In the following, only basic configuration of the Torque Generator
        is covered. For details of configuration of the Torque Generator,
        refer to the 
        <a href="../modules/generator/reports/apidocs/index.html">its javadocs</a>.
      </p>
    </subsection>
    <subsection name="Generation of om classes">
      <p>
        A basic set-up for generating the om classes would be
      </p>
      <source><![CDATA[
         Controller controller = new Controller();
         List<UnitDescriptor> unitDescriptors = new ArrayList<UnitDescriptor>();

         Map<String, String> overrideOptions = new HashMap<String, String>();
         overrideOptions.put("torque.om.package", "${torque.target.package}");

         CustomProjectPaths projectPaths
                 = new CustomProjectPaths(
                     new Maven2DirectoryProjectPaths(new File(".")));
         projectPaths.setConfigurationPackage("org.apache.torque.templates.om");
         projectPaths.setConfigurationDir(null);
         projectPaths.setSourceDir(new File("${sourceDir}"));
         projectPaths.setOutputDirectory(
                 null,
                 new File("target/generated-sources"));
         projectPaths.setOutputDirectory(
                 Maven2ProjectPaths.MODIFIABLE_OUTPUT_DIR_KEY,
                 new File("src/main/generated-java"));
         UnitDescriptor unitDescriptor = new UnitDescriptor(
                 UnitDescriptor.Packaging.CLASSPATH,
                 projectPaths,
                 new DefaultTorqueGeneratorPaths());
         unitDescriptor.setOverrideOptions(
                 new MapOptionsConfiguration(overrideOptions));
         unitDescriptors.add(unitDescriptor);

         controller.run(unitDescriptors);
      ]]></source>
      <p>
        Replace ${torque.schema.source.dir} 
        with the directory where you put your database schemata 
        (e.g. /src/main/schema). Replace ${torque.target.package} 
        with the base package for your generation, e.g. org.apache.torque.test.
      </p>
    </subsection>
    <subsection name="Other generated artifacts">
      <p>
        See the maven example above for the settings necessary 
        to generate the other possible artifacts and apply them to the
        ant tasks.
      </p> 
    </subsection>
  </section>
 </body>
</document>
