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 2011/06/25 20:45:19 UTC
svn commit: r1139591 - in
/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules:
runtime/reference/read-from-db.xml templates/index.xml
Author: tfischer
Date: Sat Jun 25 18:45:19 2011
New Revision: 1139591
URL: http://svn.apache.org/viewvc?rev=1139591&view=rev
Log:
TORQUE-161:
Add description for fillers and generation options descriptions
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/index.xml
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml?rev=1139591&r1=1139590&r2=1139591&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml Sat Jun 25 18:45:19 2011
@@ -196,12 +196,14 @@ List authors = AuthorPeer.doSelect(crite
<p>
Note that by default, the getters query the database for the
- corresponding objects if they hev not been read already. For example,
+ corresponding objects if they have not been read already. For example,
the method <code>Author.getBooks()</code> silently queries the database
for the books for the author, if they have not been read before.
If you do not like this behaviour (e.g. if you want to make sure that
all reads occur within one database transaction), set the generator option
- <code>torque.silentDbFetch</code> to <code>false</code>.
+ <code>torque.om.silentDbFetch</code> to <code>false</code>.
+ You can also query the database for corresponding objects for several
+ other objects at once. See the sections on Joins and Fillers below.
</p>
</section>
@@ -406,6 +408,43 @@ List authors = AuthorPeer.doSelect(crite
</section>
+ <section name="Fillers">
+
+ <p>
+ A very effisiont way of reading corresponding objects for a set of
+ data objects is to query all corresponding objects in one query using
+ IN. E.g. if you have three authors with the ids 1,3 and 7 and want to
+ read the related books, you can use the SQL statement
+ <code>SELECT * FROM BOOK WHERE AUTHOR_ID IN(1,3,7)</code>.
+ This is usually faster than the standard lazy-loading approach
+ by calling the java method author.getBook() for each author which will
+ silently issue one select statement for each author if the corresponding
+ books have not been read.
+ </p>
+
+ <p>
+ Torque can generate filler methods which use the IN approach.
+ To generate these methods, the generation option
+ <code>torque.om.complexObjectModel.generateFillers</code>
+ needs to be set to true for the generation process.
+ Then, for the author-book example, Torque will generate a method
+ fillAuthors(List<Book>) in the BookPeer class and a method
+ fillBooks(List<Author>) in the AuthorPeer class which will
+ fill all authors and books in the passed lists, respectively, using
+ the IN approach. Once the corresponding objects have been filled,
+ you can use the author.getBooks() and book.getAuthor() methods
+ and Torque will not query the database again.
+ </p>
+
+ <p>
+ The filler methods use chunk querying for large lists
+ (i.e. there is a maximum number of ids they will put into a single
+ IN clause; if necessary several SQL statements will be issued).
+ The chunk size can be modified by overriding the getFillerChunkSize()
+ method.
+ </p>
+ </section>
+
<section name="Using DISTINCT with Criteria">
<p>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/index.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/index.xml?rev=1139591&r1=1139590&r2=1139591&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/index.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/index.xml Sat Jun 25 18:45:19 2011
@@ -91,11 +91,87 @@
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 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>
+ Below are the most commonly used options which are available
+ for the generation om classes. A list of all options can be found
+ in the torque templates jar in the path
+ org/apache/torque/templates/om/conf/options.properties.
+ </p>
+ <table>
+ <tr>
+ <th>option</th>
+ <th>default value</th>
+ <th>description</th>
+ </tr>
+ <tr>
+ <td>torque.om.package</td>
+ <td>-</td>
+ <td>The name of the root package for the generated classes</td>
+ </tr>
+ <tr>
+ <td>torque.database</td>
+ <td>-</td>
+ <td>The database to generate for. One of derby, mssql, mysql, oracle
+ or postgresql.
+ TODO check whether this is still needed for OM generation; generated
+ code should be independent of database.
+ </td>
+ </tr>
+ <tr>
+ <td>torque.om.useManagers</td>
+ <td>false</td>
+ <td>
+ Whether Manager classes should be generated which cache data objects
+ using JCS.
+ </td>
+ </tr>
+ <tr>
+ <td>torque.om.generateBeans</td>
+ <td>false</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>torque.om.silentDbFetch</td>
+ <td>true</td>
+ <td>
+ If true, Torque silently fetches data objects related by foreign
+ key relations if the getter of a related data object is invoked
+ and the field read from the getter is not yet initialized.
+ If false, Torque simply returns null if the related objects
+ have not yet been read.
+ This option has no effect if torque.objectIsCaching is set to false.
+ </td>
+ </tr>
+ <tr>
+ <td>torque.om.addGetByNameMethods</td>
+ <td>true</td>
+ <td>
+ If true, Torque adds methods to get database fields
+ by name/position.
+ </td>
+ </tr>
+ <tr>
+ <td>torque.om.complexObjectModel.generateFillers</td>
+ <td>false</td>
+ <td>
+ Whether filler methods are generated which can efficiently read
+ data objects related by a foreign key relation for a list of other
+ data objects.
+ </td>
+ </tr>
+ </table>
</subsection>
<subsection name="Generation of ddl sql">
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org