db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r1448818 - /db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml
Date Thu, 21 Feb 2013 21:46:26 GMT
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&lt;Book&gt; 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


Mime
View raw message