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 2012/06/27 02:51:18 UTC
svn commit: r1354296 - in
/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference:
read-from-db.xml write-to-db.xml
Author: tfischer
Date: Wed Jun 27 00:51:17 2012
New Revision: 1354296
URL: http://svn.apache.org/viewvc?rev=1354296&view=rev
Log:
improve runtime documentation
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/runtime/reference/write-to-db.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=1354296&r1=1354295&r2=1354296&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 Wed Jun 27 00:51:17 2012
@@ -45,9 +45,11 @@
The former is recommended for new projects, the latter is deprecated
but can be used for legacy projects.
Apart from obvious API differences, there are a few subtle semantics
- differences between the two classes.
- Check the <a href="../../../migration-from-torque-3.html">migration guide</a>
- for details.
+ differences between the two classes
+ (Check the
+ <a href="../../../../migration-from-torque-3.html">migration guide</a>
+ for details).
+ All examples in this document use the new criteria.Criteria object.
</p>
<p>
All following examples are using generated classes
@@ -111,7 +113,8 @@ List authors = AuthorPeer.doSelect(crite
<code>Criteria.NOT_EQUAL</code> (<>)
</li>
<li>
- <code>Criteria.ALT_NOT_EQUAL</code> (!=)
+ <code>Criteria.ALT_NOT_EQUAL</code> (!=) (not needed,
+ in the suported dbs use <code>Criteria.NOT_EQUAL</code>)
</li>
<li>
<code>Criteria.EQUALS</code> (Default)
@@ -160,8 +163,8 @@ List authors = AuthorPeer.doSelect(crite
<p>
Foreign keys define a link between rows in different tables. They are
defined in the database schema on generation time. If the generator
- option <code>complexObjectModel</code> is not set to false, getters
- and setters are generated for linked objects.
+ option <code>torque.om.complexObjectModel</code> is not explicitly
+ set to false, getters and setters are generated for linked objects.
</p>
<p>
@@ -205,7 +208,7 @@ List authors = AuthorPeer.doSelect(crite
</p>
<p>
- In the Book Object, the Torque generator generates the methods
+ In the Book Object, the Torque Generator generates the methods
<code>getAuthor()</code> and <code>setAuthor(Author author)</code>
which can be used to access and set the corresponding author object.
In the Author object, the methods <code>getBooks()</code> and
@@ -221,7 +224,7 @@ List authors = AuthorPeer.doSelect(crite
all reads occur within one database transaction), set the generator option
<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.
+ other objects at once, see the sections on Joins and Fillers below.
</p>
</section>
@@ -280,7 +283,7 @@ List authorAndBooks = AuthorPeer.doSelec
<p>
You can also put constraints on the related books. For example, to read
- only the related book witht the title
+ only the related book with the title
"TCP/IP Illustrated, Volume 1":
</p>
@@ -303,9 +306,14 @@ List authorAndBooks = AuthorPeer.doSelec
At the moment, there is no method which can read nested data which are
more than one foreign key relation apart. For example,
if a table A has a foreign key reference to a table B,
- which has a foreign key reference to a table C, there is no way
+ which has a foreign key reference to a table C, there is no easy way
to read the data in table A and the related datasets in table B
<em>and</em> table C in one single select.
+ However, you can look at the generated code of the
+ <code>doSelectJoin<tablename></code> methods and adopt it
+ for the special combination of tables you need to join.
+ Also, you can use the filler methods (see below)
+ for reading associated data with good performance.
</p>
</subsection>
@@ -424,8 +432,9 @@ List authors = AuthorPeer.doSelect(crite
<p>
Usually, outer joins are used for reading in several tables at once
- (not ?yet? supported by Torque), or for ordering the contents
- of one table by the contents of another table.
+ (not ?yet? supported by Torque out of the box),
+ or for ordering the contents of one table
+ by the contents of another table.
</p>
</subsection>
@@ -439,10 +448,10 @@ List authors = AuthorPeer.doSelect(crite
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.
+ This is in nearly all cases 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>
@@ -466,6 +475,15 @@ List authors = AuthorPeer.doSelect(crite
The chunk size can be modified by overriding the getFillerChunkSize()
method.
</p>
+ <p>
+ The filler approach has the advantage over joins that it minimizes the
+ amount of transferred data. Consider data where each author has written
+ 10 books. If the author/book data is written by joins,
+ the data of one author will be transferred ten times
+ (once for each corresponding book).
+ This is not the case when using fillers; the filler approach will
+ transfer each row data only once.
+ </p>
</section>
<section name="Using DISTINCT">
@@ -480,11 +498,11 @@ List authors = AuthorPeer.doSelect(crite
In the first example in the section
"Inner joins for qualifying", the author would appear
for every book that is attached to it.
- If an author has published 10 books, the author would appear
- in the returned List 10 times.
- To avoid this problem so that our returned List only returns one author
- once despite the number of times it appears, we have used the
- setDistinct() method in Criteria. For instance:
+ If an author has published 10 books, the author would appear 10 times
+ in the returned list.
+ To avoid this problem, and return each author only once,
+ use the setDistinct() method in Criteria.
+ For instance:
</p>
<source>
@@ -548,8 +566,8 @@ SELECT ... from AUTHOR where LAST_NAME='
</source>
<p>
- To explicitly specify which operator should be used to link the constraints
- in a Criteria, use the methods
+ To explicitly specify which operator should be used
+ to link the constraints in a Criteria, use the methods
<code>Criteria.and()</code> and
<code>Criteria.or()</code>.
The former and's a condition with all the other conditions already in the
@@ -577,14 +595,14 @@ Criteria crit = new Criteria()
<p>
For more complex queries, use the
- <code>org.apache.torque.critzeria.Criterion</code> object, and the methods
+ <code>org.apache.torque.criteria.Criterion</code> object, and the methods
<code>Criterion.and()</code> and
<code>Criterion.or()</code>
to combine them.
</p>
<p>
- For example, the criterion which corresponds to the SQL query
+ For example, the Criteria which corresponds to the SQL query
</p>
<source><![CDATA[
@@ -606,8 +624,8 @@ crit.where(a1.and(b2).or(a5.and(b3)));
]]></source>
<p>
- Note that the tables used in the last example are not defined
- in the bookstore schema in the tutorial.
+ (Note that the tables used in the last examples are not defined
+ in the bookstore schema in the tutorial).
</p>
</section>
@@ -615,17 +633,21 @@ crit.where(a1.and(b2).or(a5.and(b3)));
<section name="Case insensitivity">
<p>
- String comparisons is are usually case sensitive (unless the underlying
- database only provides case sensitive LIKE clauses - e.g. MySQL). To get
- a case insensitive comparison, you need to tell the criteria that it
- should ignore the case thus:
+ String comparisons are usually case sensitive (unless the underlying
+ database compare strings in a case-insensitive way - e.g. MySQL
+ in the default configuration).
+ To get a case insensitive comparison, you need to tell the criteria
+ that it should ignore the case thus:
</p>
<source>
Criteria criteria = new Criteria();
-criteria.where(InvoicePeer.TABLE_NAME, searchField,
- (Object) ("%" + searchCriteria + "%"), Criteria.LIKE);
-criteria.getCriterion(InvoicePeer.TABLE_NAME, searchField).setIgnoreCase(true);
+Criterion criterion = new Criterion(
+ searchColumn,
+ (%" + searchString + "%",
+ Criteria.LIKE);
+criterion.setIgnoreCase(true);
+criteria.where(criterion);
List invoices = InvoicePeer.doSelect(criteria);
</source>
@@ -729,59 +751,60 @@ List authors = AuthorPeer.doSelect(crite
This is not recommended as you will have to specify the FROM clause
manually, which will not be as portable as the second method and also
the compiler won't warn you if a column you use in the FROM clause
- disappears from your model. Still, this method may be needed at times.
+ disappears from your database model.
+ Still, this method may be needed at times.
</p>
<p>
The second way is by specifying an alias which contains the subselect.
This is the preferred way to add a subselect to the FROM clause.
- For example, a very complicated way to retrieve all authors would be
+ For example, a very complicated way to retrieve the names of all authors
+ would be
</p>
-<source>
-TODO
+<source><![CDATA[
Criteria subquery = new Criteria();
-subquery.addSelectColumn("MAX(" + AuthorPeer.AUTHOR_ID + ")");
+subquery.addSelectColumn(AuthorPeer.NAME);
Criteria criteria = new Criteria();
-criteria.where(AuthorPeer.AUTHOR_ID, subquery);
+criteria.addAlias("A", subquery);
+criteria.addSelectColumn(new ColumnImpl("A" + AuthorPeer.NAME.getColumnName()));
-List authors = AuthorPeer.doSelect(criteria);
+List<String> authorNames = BasePeer.doSelect(
+ criteria,
+ new StringMapper(),
+ AuthorPeer.getTableMap());
+]]></source>
+ <p>
+ This code will result in the following SQL:
+ </p>
+<source>
+ SELECT A.name from (SELECT name from AUTHOR) A;
</source>
</section>
- <section name="Using Criterion to use a Column twice in a Criteria">
+ <section name="Using a Column twice in a Criteria">
<p>
- The Criteria Object extends the functionality of a Hashtable and as such
- suffers from the Hashtable limitation of the key having to be unique in
- the Hashtable. When a Criteria is set to use the same column twice, it
- overwrites the previous key. The way around this is to use the Criterion
- Object. The Criterion is a final inner class of Criteria. Because it is
- a member class the Criterion can "look" into Criteria's instance fields
- and methods including ones declared private. The Criterion also carries
- the default package visibility which means it can be used in a sub-class
- of Criteria.
+ In Torque 3.x and in the deprecated util.Criteria object,
+ the add methods replaced a condition which already existed in a Criteria
+ for the same column name. This is no longer the case with the new
+ criteria.Criterion object, so no special treatment is needed to use
+ a column twice. The Criteria
</p>
- <p>
- For example, we may want to search for authors which Author Ids are
- within a certain Range, such as 5 and 10. For this
- we would need to use the Criterion:
- </p>
-
<source>
Criteria criteria = new Criteria();
criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_EQUAL);
+criteria.and(AuthorPeer.AUTHOR_ID, 10, Criteria.GREATER_EQUAL);
+</source>
-Criteria.Criterion criterion = criteria.getCriterion(AuthorPeer.AUTHOR_ID);
-criterion.and(
- criteria.getNewCriterion(
- criterion.getTable(),
- criterion.getColumn(),
- new Integer(10),
- Criteria.LESS_EQUAL)
- );
+ <p>
+ corresponds to the expected SQL query
+ </p>
+
+<source>
+SELECT ... FROM ... WHERE AUTHOR.AUTHOR_ID >= 5 AND AUTHOR.AUTHOR_ID <= 10;
</source>
</section>
@@ -792,13 +815,13 @@ criterion.and(
The Criteria Object can be verbose to use directly in your code.
Often in an application the 80:20 rule applies when dealing with queries.
The same 20% of queries are used 80% of the time. While Criteria
- and Criterion offer a tonne of flexibility, often having something
+ and Criterion offer a lot of flexibility, often having something
simple to use is easier.
</p>
<p>
Also, it is often desirable in an application to separate code which is
- used to accesss the database from the other application code.
+ used to access the database from the other application code.
For example, the application may need to retrieve an author by his last
name. One can, of course, construct a Criteria in the
application code and use <code>AuthorPeer</code>'s <code>doSelect()</code>
@@ -807,7 +830,7 @@ criterion.and(
</p>
<p>
- So there are basically two approaces to this. The first one is adding
+ So there are basically two approaches to this. The first one is adding
additional methods to the Peer classes, the second one is writing
custom filter classes, and the third one is inheriting
from the Criteria object. Usually, the first approach is preferable
@@ -822,7 +845,8 @@ criterion.and(
<p>
To achieve encapsulation and code reuse for queries, you can
extend the Peer classes. For example, if you need to select authors
- by last name, you could extend the author class in the following way:
+ by last name, you could extend the AuthorPeer class in the following
+ way:
</p>
<source>
@@ -903,7 +927,7 @@ public class AuthorFilter
<p>
In reality, you would also add getters and setters for first and
- last name, and allow for wildcards and case-insensitive serach,
+ last name, and allow for wildcards and case-insensitive search,
but this example should show the basic idea.
</p>
@@ -912,34 +936,16 @@ public class AuthorFilter
<subsection name="Inheriting from Criteria">
<p>
- Another way to achieve code-reuse is to create a class that extends
- Criteria and add convenience methods for your application.
- In this case the example Object will be the SimpleCriteria with the
- methods that allow access to the examples above.
+ In some special cases, it might make sense to create a class
+ that extends Criteria and add convenience methods.
+ For example:
</p>
<source>
-//Turbine
-import org.apache.torque.util.Criteria;
+import org.apache.torque.criteria.Criteria;
-/**
- * SimpleCriteria is a simple case of the more powerful Criteria
- * Object.
- */
-
-public class SimpleCriteria extends Criteria
+public class CompareCriteria extends Criteria
{
- /** currently used as DEFAULT_CAPACITY in Criteria is private */
- private static final int DEFAULT_CAPACITY = 10;
-
- /*
- * Constructor
- */
- public SimpleCriteria()
- {
- super(DEFAULT_CAPACITY);
- }
-
/*
* Represents the Greater Than in the WHERE
* clause of an SQL Statement
@@ -947,9 +953,9 @@ public class SimpleCriteria extends Crit
* @param columnname the column name
* @param columnvalue the column value to be compared against
*/
- public SimpleCriteria greaterThan(String columnname, int columnvalue)
+ public CompareCriteria greaterThan(Column column, int columnvalue)
{
- super.where(columnname, columnvalue, Criteria.GREATER_THAN);
+ super.where(column, columnvalue, Criteria.GREATER_THAN);
return this;
}
@@ -959,41 +965,16 @@ public class SimpleCriteria extends Crit
*
* @param columnname the column name
*/
- public SimpleCriteria isBetween(String columnname, int min, int max)
+ public CompareCriteria isBetween(Column column, int min, int max)
{
- super.where(columnname, min, Criteria.GREATER_THAN);
- super.Criterion criterion = criteria.getCriterion(columnname);
- criterion.and(
- super.getNewCriterion(
- criterion.getTable(),
- criterion.getColumn(),
- new Integer(max),
- Criteria.LESS_EQUAL )
- );
+ super.where(column, min, Criteria.GREATER_THAN);
+ super.and(column, max, Criteria.LESS_THAN);
return this;
}
}
</source>
-
- <p>
- This will simplify the code being written in the Business Objects or
- Actions and condense all the Criteria knowledge into the SimpleCriteria
- Object. The SimpleCriteria Object used in the same manner as Criteria.
- For example, the example from the section
- "Using Criterion to use a Column twice in a Criteria"
- above would be
- </p>
-
-<source>
-SimpleCriteria criteria = new SimpleCriteria();
-criteria.isBetween(AuthorPeer.AUTHOR_ID, 5, 10);
-
-List authors = AuthorPeer.doSelect(criteria);
-</source>
-
</subsection>
-
</section>
<section name="Debugging Criteria's">
@@ -1001,8 +982,9 @@ List authors = AuthorPeer.doSelect(crite
<p>
Criteria contains a toString() method which will output a representation
of the Criteria as a String. A Criteria to a large extent represents the
- statements in a WHERE clause of SQL. To see the queries being processed
- by your application you can configure the logging system to capture
+ statements in a WHERE clause of SQL. However, there might be details
+ which are hidden when invoking the Criteria.toString() method.
+ In this case, you can configure the logging system to capture
the SQL by adding the following to your <code>log4j.properties</code>
file:
</p>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml?rev=1354296&r1=1354295&r2=1354296&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml Wed Jun 27 00:51:17 2012
@@ -40,8 +40,7 @@
<p>
As an example, consider the following code, which creates an Author
- object and inserts it into the database. Then the object is loaded again,
- modified. and updates the corresponding row in the databse.
+ object and inserts it into the database.
</p>
<source>
@@ -84,34 +83,74 @@ bloch.save(); //also saves the book "eff
<p>
If the object which save method is called is neither new nor modified,
it is not saved. Internally, this is handled via the <code>isNew</code>
- and <code>modifed</code> flags of the object.
+ and <code>modified</code> flags of the object.
</p>
<p>
There are alternative ways to insert or update an object in the database:
you can pass the objects to the <code>doInsert()</code> or
<code>doUpdate</code> methods of their corresponding Peers, or you can
- create a criteria object which contains the data of the object and pass
- the Criteria object to the <code>doInsert()</code> or
+ create a ColumnValues object which contains the data of the object
+ and pass the Criteria object to the <code>doInsert()</code> or
<code>doUpdate</code> methods of the Peer class.
- Note that if you construct a criteria, the id field is not added to the
- Criteria. It is taken care of by underlying database system (or perhaps
- the ID BROKER when it is in use).
- The object that is returned by doInsert is the id of the newly added row.
+ Note that if you construct a ColumnValues object for a new object,
+ the id field need not be added to the ColumnValues.
+ It is taken care of by Torque internally.
</p>
</section>
+ <section name="Mass updates">
+ <p>
+ If you want to update many objects at once, use the
+ doUpdate(Criteria, ColumnValues) method in BasePeer.
+ For example, to set the name attribute to null
+ for all authors with an id greater than 5, use:
+ </p>
+
+<source>
+Criteria criteria = new Criteria();
+criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_THAN);
+ColumnValues columnValues = new ColumnValues();
+columnValues.put(AuthorPeer.NAME,
+ new JdbcTypedValue(
+ null,
+ java.sql.Types.VARCHAR));
+BasePeer.doUpdate(criteria, columnValues);
+</source>
+
+ </section>
+
<section name="Deleting objects">
<p>
- Deletes work much in the same way as a select. If you, for example,
- want to delete the author with id = 3 then you simply add it to the
- Criteria and call doDelete.
+ If you want to delete an author which was already loaded,
+ then you simply pass it to the doDelete method of the peer:
+ </p>
+
+<source>
+AuthorPeer.doDelete(author);
+</source>
+
+ <p>
+ You do not need to load authors to delete them, you can also use a
+ Criteria object to perform deletes. For example, to delete the author
+ with the id 3 without loading the author object, use:
+ </p>
+
+<source>
+Criteria criteria = new Criteria();
+criteria.where(AuthorPeer.AUTHOR_ID, 3);
+AuthorPeer.doDelete(criteria);
+</source>
+
+ <p>
+ The latter method can also be used for mass deletes.
+ E.g. to delete all authors with an id greater than 5, use:
</p>
<source>
Criteria criteria = new Criteria();
-crit.add(AuthorPeer.AUTHOR_ID, 3);
+criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_THAN);
AuthorPeer.doDelete(criteria);
</source>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org