<?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>Torque templates - Changing the default behaviour</title>
 </properties>

 <body>
  <section name="Introduction">
    <p>
      This page gives an overview what can be done to customize the
      output of the generation process.  In most cases, there is
      more than one possibility; the same thing can be achieved through
      high-level changes as well as through low-level changes.
      This page is organized such that the high level changes are described
      first and the low-level changes are described later.
      It is recommended to use the first technique which solves
      your problem.
    </p>
  </section>
  <section name ="Options">
    <p>
      The Torque templates come with a lot of options, which can be used
      to customize behaviour. The following table lists the most commonly
      used options (more might be found and described in the 
      conf/options.properties file of the template package
      of the current unit of generation) :
    </p>
    <table>
    <tr>
      <th> Property </th>
      <th> Default </th>
      <th> Description </th>
      <th> Used for generation of</th>
    </tr>

    <tr>
      <td colspan="3"><strong> Basic Properties </strong></td>
    </tr>
    <tr>
      <td><code>torque.database</code></td>
      <td><code>N/A</code></td>
      <td>
        Torque must know the target database platform in order to generate the
        appropriate Java and SQL code, i.e. this option is required.
        Currently supported values are:
        derby, hsqldb, mssql, mysql, oracle, postgresql.
        <br/>
        For SQL generation, you can also specify the a custom name.
        In this case you need to provide an implementation of the interface
        <i>org.apache.torque.templates.platform.Platform</i>
        interface which must be in the package 
        <i>org.apache.torque.templates.platform</i>.
        Its name must be <code>Platform${CustomName}Impl</code>,
        where ${CustomName} must start with an upper case character.
      </td>
      <td>sql, html, xdoc</td>
    </tr>

    <tr>
      <td colspan="3"><strong> Java Template Variables </strong>
      (only used for the generation of java classes)</td>
    </tr>
    <tr>
      <td><code>torque.om.addGetByNameMethods</code></td>
      <td><code>true</code></td>
      <td>
        If true, Torque adds methods to get database fields
        by name/position.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.save.addSaveMethods</code></td>
      <td><code>true</code></td>
      <td>Determines whether a save method is generated.</td>
    </tr>
    <tr>
      <td><code>torque.om.save.saveException</code></td>
      <td><code>Exception</code></td>
      <td>Defines which Exception should be thrown by the DbObject.save() method.</td>
    </tr>
    <tr>
      <td><code>torque.om.trackModified</code></td>
      <td><code>true</code></td>
      <td>
        Determines whether code should be added to track
        whether a DbObject was modified.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.trackNew</code></td>
      <td><code>true</code></td>
      <td>
        Determines whether code should be added to track
        whether a DbObject was read from or already written to the database.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.addTimeStamp</code></td>
      <td><code>true</code></td>
      <td>
        If true, Torque puts time stamps in generated om files.
        This also triggers the generation of &quot;serialVersionUID&quot;-constants
        in the classes that implement Serializable (object, peer and manager).
        The version is equal to the generation timestamp.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package</code></td>
      <td><code>N/A</code></td>
      <td>
        The Java package that Torque will put the generated classes in.
        This option is required if you generate the java classes.
        A valid value would be <code>com.company.project.om</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.peerPackageSuffix</code></td>
      <td>Not set</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated Peer Java classes.
        If set, the property needs to start with a dot.
        If not set, the Peer classes will be generated in
        <code>${torque.om.package}</code>.
        A valid value would be <code>.peer</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.dbObjectPackageSuffix</code></td>
      <td>Not set</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated Database Object Java classes.
        If set, the property needs to start with a dot.
        If not set, the Database Object classes will be generated in
        <code>${torque.om.package}</code>.
        A valid value would be <code>.dbobject</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.mapPackageSuffix</code></td>
      <td><code>.map</code></td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated Java classes for the database map.
        If set, the property needs to start with a dot.
        If set to empty, the the database map classes will be generated in
        <code>${torque.om.package}</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.managerPackageSuffix</code></td>
      <td>.manager</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated Java Manager classes,
        if they are generated at all.
        If set, the property needs to start with a dot.
        If set to empty, the Manager classes will be generated in
        <code>${torque.om.package}</code>
      </td>
    </tr>
    <tr>
      <td><code>option:torque.om.package.beanPackageSuffix</code></td>
      <td><code>.bean</code></td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated JavaBean classes, if they are
        generated at all.
        If set, the property needs to start with a dot.
        If set to empty, the the database map classes will be generated in
        <code>${torque.om.package}</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.baseDbObjectPackageSuffix</code></td>
      <td>Not set</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated BaseObject Java classes.
        If set, the property needs to start with a dot.
        If not set, the BaseObject classes will be generated in
        <code>${torque.om.package}</code>
        A valid value would be <code>.dbobject.base</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.basePeerPackageSuffix</code></td>
      <td>Not set</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated BasePeer Java classes.
        If set, the property needs to start with a dot.
        If not set, the BasePeer classes will be generated in
        <code>${torque.om.package}</code>
        A valid value would be <code>.peer.base</code>.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.baseManagerPackageSuffix</code></td>
      <td>.manager.base</td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated BaseManager Java classes,
        if they are generated at all.
        If set, the property needs to start with a dot.
        If set to empty, the BaseManager classes will be generated in
        <code>${torque.om.package}</code>
      </td>
    </tr>
    <tr>
      <td><code>torque.om.package.baseBeanPackageSuffix</code></td>
      <td><code>.bean</code></td>
      <td>
        The subpackage (relative to <code>${torque.om.package}</code>)
        where Torque will put the generated BaseBean Java classes,
        if they are generated at all.
        If set, the property needs to start with a dot.
        If set to empty, the BaseBean classes will be generated in
        <code>${torque.om.package}</code>
      </td>
    </tr>
    <tr>
      <td><code>torque.om.className.baseDbObjectClassNamePrefix</code></td>
      <td><code>Base</code></td>
      <td>A string to pre-pend to the file names of base data objects.</td>
    </tr>
    <tr>
      <td><code>torque.om.className.basePeerClassNamePrefix</code></td>
      <td><code>Base</code></td>
      <td>A string to pre-pend to the file names of base peer objects.</td>
    </tr>
    <tr>
      <td><code>torque.om.useManagers</code></td>
      <td><code>false</code></td>
      <td>
        If true, Torque will generate Manager classes that use JCS for caching.
        Still considered experimental.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.complexObjectModel</code></td>
      <td><code>true</code></td>
      <td>
        If true, Torque generates data objects with collection support and
        methods to easily retrieve foreign key relationships.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.objectIsCaching</code></td>
      <td><code>true</code></td>
      <td>
        If true, Torque generates data objects that cache their foreign
        key relationships. If this is not desired (because the underlying objects
        can be manipulated from other code), set this property to false.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.silentDbFetch</code></td>
      <td><code>true</code></td>
      <td>
        If true and torque.objectIsCaching is true, Torque silently fetches
        foreign key relation collections if the collection is not yet
        initialized.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.useIsForBooleanGetters</code></td>
      <td><code>false</code></td>
      <td>
        If true, Torque generates is&lt;xxx&gt; getter methods
        for boolean columns instead of get&lt;xxx&gt; methods.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.generateBeans</code></td>
      <td><code>false</code></td>
      <td>
        If true, Torque generates a bean object for each data object,
        plus methods to convert data objects to beans and vice versa.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.className.beanClassNameSuffix</code></td>
      <td><code>Bean</code></td>
      <td>
        A string to append to the name of generated Beans.
      </td>
    </tr>
    <tr>
      <td><code>torque.om.bean.beanExtendsClass</code></td>
      <td><code>Not set</code></td>
      <td>
        A fully qualified class name (e.g. org.apache.struts.action.ActionForm)
        that the generated base bean classes will extend.
      </td>
    </tr>

    <tr>
      <td colspan="3"><strong> SQL Template Variables </strong>
      (only used for the generation of sql ddl)</td>
    </tr>
    <tr>
      <td><code>torque.sql.generate.drops</code></td>
      <td><code>true</code></td>
      <td>
        If set to true (default), Torque will generate drop commands
        in the sql which drop and re-create all known tables.
        If set to false, Torque will not generate any drop commands - 
        Then you need to male sure to execute the sql file(s)
        against an empty schema.
      </td>
    </tr>

    <tr>
      <td colspan="3"><strong> JDBC2Schema settings </strong>
        (not used for other generation targets)</td>
    </tr>
    <tr>
      <td><code>torque.jdbc2schema.url</code></td>
      <td><code>N/A</code></td>
      <td>
        The connection url to the database.
      </td>
    </tr>
    <tr>
      <td><code>torque.jdbc2schema.driver</code></td>
      <td><code>N/A</code></td>
      <td>
        The fully qualified name of the driver class.
        The driver class must be in the classpath.
      </td>
    </tr>
    <tr>
      <td><code>torque.jdbc2schema.user</code></td>
      <td><code>N/A</code></td>
      <td>
        The database user which is used to read table information.
      </td>
    </tr>
    <tr>
      <td><code>torque.jdbc2schema.password</code></td>
      <td><code>N/A</code></td>
      <td>The administrative password for the supplied username.</td>
    </tr>


    <tr>
      <td colspan="3"><strong> IDBroker settings </strong>
        (not used for other generation targets)</td>
    </tr>
    <tr>
      <td><code>torque.idbroker.initialId</code></td>
      <td><code>101</code></td>
      <td>
        Controls the starting id of table entries when creating SQL for the id-table. If you
        have two projects that use the same id-table in the same database with different tables,
        make sure that they have different initialID settings and the ranges (initialID is incremented
        for every new table) don't overlap.
      </td>
    </tr>
    <tr>
      <td><code>torque.idBroker.initialIdValue</code></td>
      <td><code>1000</code></td>
      <td>
        The start value of the ID broker for supplying IDs to Torque. This value is incremented every
        time Torque requests ID keys from the broker. If you pre-load your table straight from SQL,
        make sure that you don't accidentially overlap with this setting, because Torque doesn't keep
        record of what IDs are already taken in the database. If you overlap, inserting new objects
        will fail because the ID assigned by Torque is already taken.
      </td>
    </tr>
    <tr>
      <td><code>torque.idbroker.initialIdStep</code></td>
      <td><code>10</code></td>
      <td>
        For performance reasons, the ID Broker does not request a single ID at a time but fetches a
        whole range and increments the current next ID Value in the ID Table by this step. If you have
        to do lots of inserts straight in a row, increment this value to get slightly better performance.
      </td>
    </tr>
    </table>
  </section>

  <section name="Altering the SQL type mapping">
    If you want to alter the way the Torque data types are mapped to SQL types
    or generate SQL for a dtadabase type not supported by Torque,
    you can write a custom platform class. This class must implement the
    <code>Platform</code> interface in the package 
    <code>org.apache.torque.templates.platform</code>.
    The class itself must be in the same 
    <code>org.apache.torque.templates.platform</code> package and 
    its name must be Platform${CustomName}Impl.
    Then, put the class file in the class path from where it
    can be accessed by the templates, and set the option
    <code>torque.database</code> to ${customName}.
  </section>

  <section name="Overriding templates">
    If there is no option which does what you want, you can override
    some of the templates. See the generator reference and the ant tasks
    or maven plugin documentation on how to do this.
  </section>
 </body>
</document>