[seam-commits] Seam SVN: r9330 - trunk/doc/Seam_Reference_Guide/en-US.

[seam-commits at lists.jboss.org]

Author: jacob.orshalick
Date: 2008-10-14 22:39:39 -0400 (Tue, 14 Oct 2008)
New Revision: 9330

Modified:
   trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml
Log:
JBSEAM-2094

Modified: trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml	2008-10-15 01:52:09 UTC (rev 9329)
+++ trunk/doc/Seam_Reference_Guide/en-US/Conversations.xml	2008-10-15 02:39:39 UTC (rev 9330)
@@ -232,9 +232,35 @@
             A nested conversation is created by invoking a method marked
             <literal>@Begin(nested=true)</literal> inside the scope of an
             existing conversation. A nested conversation has its own
-            conversation context, and also has read-only access to the
-            context of the outer conversation. (It can read the outer
-            conversation's context variables, but not write to them.)
+            conversation context, but can read values from the outer
+            conversation's context.  The outer conversation's context is 
+            read-only within a nested conversation, but because objects 
+            are obtained by reference, changes to the objects themselves 
+            will be reflected in the outer context.
+        </para>
+        
+        <itemizedlist>
+        	<listitem>
+        		<para>Nesting a conversation through initializes a context that is 
+        		stacked on the context of the original, or outer, conversation.
+        		The outer conversation is considered the parent.
+        		</para>
+        	</listitem>
+        	<listitem>
+        	 	<para>Any values outjected or directly set into the nested 
+        	 	conversation’s context do not affect the objects accessible in 
+        	 	the parent conversation’s context.</para>
+        	</listitem>
+        	<listitem>
+        		<para>Injection or a context lookup from the conversation context
+        		will first lookup the value in the current conversation context and, 
+        		if no value is found, will proceed down the conversation stack if the
+        		conversation is nested.  As you will see in moment, this behavior 
+        		can be overriden.
+        	</listitem>
+        </itemizedlist>
+        
+        <para>
             When an <literal>@End</literal> is subsequently encountered,
             the nested conversation will be destroyed, and the outer
             conversation will resume, by "popping" the conversation stack.
@@ -250,23 +276,25 @@
             a nested conversation ends, Seam destroys all nested conversation
             contexts along with the outer context.
         </para>
+	    
+        <para>
+        	The conversation at the bottom of the conversation stack is the root 
+        	conversation.  Destroying this conversation always destroy all of its 
+        	descendents.  You can achieve this declaratively by specifying
+        	<literal>@End(root=true)</literal>.
+        </para>
         
         <para>
             A conversation may be thought of as a <emphasis>continuable state</emphasis>.
             Nested conversations allow the application to capture a consistent
             continuable state at various points in a user interaction, thus
-            insuring truly correct behavior in the face of backbuttoning and
+            ensuring truly correct behavior in the face of backbuttoning and
             workspace management.
         </para>
         
         <para>
-            TODO: an example to show how a nested conversation prevents bad 
-            stuff happening when you backbutton.
-        </para>
-        
-        <para>
-            Usually, if a component exists in a parent conversation of the 
-            current nested conversation, the nested conversation will use
+            As mentioned previously, if a component exists in a parent conversation of 
+            the current nested conversation, the nested conversation will use
             the same instance. Occasionally, it is useful to have a different
             instance in each nested conversation, so that the component 
             instance that exists in the parent conversation is invisible to