db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r1001442 - in /db/torque/torque4/trunk/torque-site/src/site: site.xml xdoc/documentation/modules/templates/customizing.xml
Date Sun, 26 Sep 2010 14:51:20 GMT
Author: tfischer
Date: Sun Sep 26 14:51:19 2010
New Revision: 1001442

URL: http://svn.apache.org/viewvc?rev=1001442&view=rev
Log:
Added docs for template options

Added:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/customizing.xml
Modified:
    db/torque/torque4/trunk/torque-site/src/site/site.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/site.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/site.xml?rev=1001442&r1=1001441&r2=1001442&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/site.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/site.xml Sun Sep 26 14:51:19 2010
@@ -78,6 +78,7 @@
           </item>
         </item>
         <item name="Templates"           href="/documentation/modules/templates/index.html"
collapse="true">
+          <item name="Customizing the output" href="/documentation/modules/templates/customizing.html"/>
           <item name="Dependencies"      href="/documentation/modules/templates/dependencies.html"/>
           <item name="Project Reports"   href="/documentation/modules/templates/reports/index.html"
collapse="true">
             <item name="Metrics"         href="/documentation/modules/templates/reports/jdepend-report.html"/>

Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/customizing.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/customizing.xml?rev=1001442&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/customizing.xml
(added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/customizing.xml
Sun Sep 26 14:51:19 2010
@@ -0,0 +1,402 @@
+<?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 Torque templates.  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. Thhe 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>
+    </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, 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>
+    </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 colspan="3"><strong> Java Template Variables </strong>
+      (only used for the om generation target)</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.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><code>torque.om.java5</code></td>
+      <td><code>true</code></td>
+      <td>
+        Whether Java5 generics and iteration shorthand should be used
+        in generated code.
+      </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="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 maven2 plugin documentation on how to do this.
+    
+  </section>
+ </body>
+</document>
\ No newline at end of file



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