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

[tf...@apache.org]

Author: tfischer
Date: Wed Dec 12 20:08:12 2012
New Revision: 1420942

URL: http://svn.apache.org/viewvc?rev=1420942&view=rev
Log:
Add documentation of linking objects

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=1420942&r1=1420941&r2=1420942&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 Wed Dec 12 20:08:12 2012
@@ -97,9 +97,49 @@ bloch.save(); //also saves the book "eff
       the id field need not be added to the ColumnValues;
       it is taken care of by Torque internally.
     </p>
-
   </section>
   
+  <section name="Linking objects">
+    <p>
+      This section is about how to establish foreign-key relations between
+      objects. As explained above, if the generator properties 
+      &quot;torque.complexObjectModel&quot; and 
+      &quot;torque.objectIsCaching&quot; were not set to false at generation 
+      time, collection fields will be created for each foreign key in the
+      object which is referenced by the foreign key, 
+      and objects which are contained in such a collection will also be saved.
+      On the other hand, if the referencing object is saved, the referenced
+      object will not be saved. This default behavior can be overridden by
+      overriding the save methods of the respective objects. 
+    </p>
+    
+    <p>
+      To make this more clear, let's consider an example where the table book
+      has a foreign key on the table author. This means, a book object
+      can reference an author object. In this case, Torque will generate
+      a collection of books in the author object which can be accessed by
+      the methods <code>getBooks()</code>, <code>addBook()</code>
+      and <code>isBooksInitialized()</code>.
+      The collection can contain the books referencing the author object.
+      Also, in the book object, there are methods <code>getAuthor()</code>
+      and <code>setAuthor()</code> which can manipulate the referenced author.
+      <br/>
+      In the case where we have a new author object, and we add a book object
+      to the referencing books via the author's <code>addBook()</code> method
+      and then save the author object, the linked book object will be saved
+      as well.
+      <br/>
+      On the other hand, if we have the same situation (a book added to an 
+      author via the <code>addBook()</code> method) and then save the book,
+      the referenced author will _NOT_ be saved.
+      <br/>
+      This is because foreign keys often represent a logical tree structure:
+      A parent object (in our case author) has potentially many child objects
+      (in our case books). If a parent is saved, the children are also saved
+      by default, but not the other way round.
+    </p>
+  </section>
+
   <section name="Bulk modifying linked objects">
     <p>
       In the tutorial database, the book table has a foreign key



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