You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2010/09/26 16:51:20 UTC
svn commit: r1001442 - in /db/torque/torque4/trunk/torque-site/src/site:
site.xml xdoc/documentation/modules/templates/customizing.xml
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 "serialVersionUID"-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<xxx> getter methods
+ for boolean columns instead of get<xxx> 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