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 2013/02/21 22:46:26 UTC
svn commit: r1448818 -
/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml
Author: tfischer
Date: Thu Feb 21 21:46:25 2013
New Revision: 1448818
URL: http://svn.apache.org/r1448818
Log:
Docs for TORQUE-266 and TORQUE-267
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml?rev=1448818&r1=1448817&r2=1448818&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml Thu Feb 21 21:46:25 2013
@@ -876,14 +876,16 @@ List<String> authorNames = BasePeer.doSe
</source>
</section>
- <section name="Partal selects">
+ <section name="Partial selects">
<p>
In a partial select, only a part of the attributes of an object
is filled. This is often done for performance reasons, especially
if one of the columns is a BLOB or CLOB column.
A partial select is constructed by using the addSelectColumn method
- in the Criteria object. For example, to read all books but fill only
+ in the Criteria object, and then executing the criteria using one of
+ the standard SomePeer.doSelect() methods.
+ For example, to read all books but fill only
the bookId and title attributes, use the following Criteria:
</p>
@@ -891,10 +893,11 @@ List<String> authorNames = BasePeer.doSe
Criteria criteria = new Criteria()
.addSelectColumn(BookPeer.BOOK_ID)
.addSelectColumn(BookPeer.TITLE);
+List<Book> books = BookPeer.doSelect(criteria);
</source>
<p>
- whic corresponds to the expected SQL query
+ which corresponds to the expected SQL query
</p>
<source>
@@ -918,6 +921,80 @@ SELECT BOOK.BOOK_ID, BOOK.TITLE FROM BOO
</section>
+ <section name="Locking">
+ <subsection name="Pessimistically lock table rows within a transaction">
+ <p>
+ Usually, the database will write lock a table row if it is updated
+ or inserted. The lock persists until the transaction is committed.
+ This means that other transactions which want to update the same row
+ need to wait until the first transaction is ended.
+ </p>
+ <p>
+ The same effect can be achieved by doing a "select for update" query.
+ This will also acquire a write lock for the selected table rows.
+ For example, to write lock the book with id 5, do
+ </p>
+<source>
+Criteria criteria = new Criteria()
+ .where(BookPeer.BOOK_ID, 5)
+ .forUpdate();
+BookPeer.doSelect(criteria);
+</source>
+ </subsection>
+ <subsection name="Optimistically lock table rows between transactions">
+ <p>
+ Optimistic locking means that a version column is used in an update
+ to check that a table row was not updated since the last read.
+ In each update, the version column is set to a new value.
+ Also it is checked that the database contains the same value
+ for the version column as the object to save, which means that
+ the row was not updated since the last read.
+ </p>
+ <p>
+ Torque supports optimistic locking using an integer version column.
+ Torque will automatically increase the version column by one
+ in each update, and check in an update that the version value in memory
+ is still the same as the value in the database.
+ </p>
+ <p>
+ There are two optimistic locking modes.
+ The first mode, <code>selectForUpdate</code>,
+ does a select for update using the primary key in the where clause.
+ It then checks that a row was selected and that the version column
+ in the database contain the same values as in the update values.
+ If all is ok, the version column is increased in memory
+ and an update using the increased version column is performed.
+ If no row is found, this could mean that the row was deleted in the
+ meantime and a <code>NoRowsException</code> is thrown.
+ (Note that another reason could be that the row with the given
+ primary key has never existed in the database.)
+ If the version column has a different value, another process
+ has modified the same row in the meantime and an
+ <code>OptimisticLockingFailedException</code> is thrown.
+ </p>
+ <p>
+ The second mode, <code>simpleSelect</code>,
+ does an update using an increased version column as update value,
+ and the version column and the primary key
+ in the where clause.
+ It then checks whether a row was updated.
+ If yes, all is ok, because the version value in memory matched
+ the version column in the database for the chosen row.
+ In this case, the version number in memory is also increased.
+ If no row was updated, an <code>OptimisticLockingFailedException</code>
+ is thrown by Torque.
+ This could be due to the row being updated in the meantime
+ by another process, or the row was deleted, or it never existed.
+ </p>
+<source>
+Criteria criteria = new Criteria()
+ .where(BookPeer.BOOK_ID, 5)
+ .forUpdate();
+BookPeer.doSelect(criteria);
+</source>
+ </subsection>
+ </section>
+
<section name="Using a Column twice in a Criteria">
<p>
@@ -929,7 +1006,7 @@ SELECT BOOK.BOOK_ID, BOOK.TITLE FROM BOO
</p>
<source>
-Criteria criteria = new Criteria();
+org.apache.torque.criteria.Criteria criteria = new Criteria();
criteria.where(AuthorPeer.AUTHOR_ID, 5, Criteria.GREATER_EQUAL);
criteria.and(AuthorPeer.AUTHOR_ID, 10, Criteria.GREATER_EQUAL);
</source>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org