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-unsubscr...@db.apache.org For additional commands, e-mail: torque-dev-h...@db.apache.org