svn commit: r1419793 - /db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml

[tf...@apache.org]

Author: tfischer
Date: Mon Dec 10 21:32:45 2012
New Revision: 1419793

URL: http://svn.apache.org/viewvc?rev=1419793&view=rev
Log:
TORQUE-182 add documentation for setAndSave methods in the orm reference

Modified:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml?rev=1419793&r1=1419792&r2=1419793&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml Mon Dec 10 21:32:45 2012
@@ -99,6 +99,58 @@ bloch.save(); //also saves the book "eff
     </p>
 
   </section>
+  
+  <section name="Bulk modifying linked objects">
+    <p>
+      In the tutorial database, the book table has a foreign key
+      to the author table. So as discussed above, the author object
+      has a collection of books, and books added to this collection get saved
+      when the corresponding author object is saved.
+      However, this does not mean that the collection of books associated
+      to that author is actually synced to the book collection in the author
+      object. For example, if books are removed from the author's book 
+      collection and the author object is saved afterwards,
+      the book is not deleted or unbound from the author,
+      it is just disregarded in the save and the collection
+      in the author object and the database are out of sync.
+    </p>
+    <p>
+      To provide am simple means of syncing the state of such a collection
+      to the database, Torque generates methods to set the state of linked
+      objects in an object and the database: the setAndSave methods.
+      For example, the AuthorPeer class has a method 
+      <code>setAndSaveBooks(Author toLinkTo, Collection&lt;Book&gt; toSave)</code>
+      which does the following:
+    </p>
+    <ul>
+      <li>
+        The current collection of books which are linked to the author toLinkTo
+        and which are also in the list toSave is read from the database
+        into the list intersection.
+      </li>
+      <li>
+        All books in toSave which are not in intersection are inserted.
+      </li>
+      <li>
+        All books in intersection which are also in toSave are updated
+        with the corresponding values in toSave and saved.
+      </li>
+      <li>
+        All books in the database which are linked to the author but are 
+        not in toSave are deleted from the database.
+      </li>
+    </ul>
+    <p>
+      After this procedure, the list of books which are linked to the passed
+      author object in the database and the cached list of books in the
+      passed author object are exactly the passed list of books. 
+      This is an easy way to specify the list of linked objects
+      in the database; and it is better than just deleting and re-inserting the
+      linked books because it preserves primary keys of existing objects
+      and does not execute any database writes for unmodified objects.
+    </p>
+    
+  </section>
 
   <section name="Mass updates">
     <p>



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org