myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ima...@apache.org
Subject svn commit: r513702 - /myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml
Date Fri, 02 Mar 2007 10:55:47 GMT
Author: imario
Date: Fri Mar  2 02:55:46 2007
New Revision: 513702

URL: http://svn.apache.org/viewvc?view=rev&rev=513702
Log:
doc, doc, doc

Added:
    myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml
      - copied, changed from r513687, myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml

Copied: myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml (from r513687,
myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml)
URL: http://svn.apache.org/viewvc/myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml?view=diff&rev=513702&p1=myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml&r1=513687&p2=myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml&r2=513702
==============================================================================
--- myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml (original)
+++ myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml Fri Mar  2 02:55:46
2007
@@ -3,20 +3,176 @@
 	"http://www.apache.org/dtd/xdoc.dtd">
 <document>
 	<properties>
-		<title>Conversation Use Cases</title>
+		<title>Conversation Management</title>
 	</properties>
 
 	<body>
-		<section name="Conversation Use Cases">There are some use cases a
-			conversation has:
+		<section name="Conversation Management">Possibilities to manage a conversation:
 			<ul>
 				<li>start a conversation</li>
 
 				<li>end a conversation</li>
 
 				<li>end and restart a conversation</li>
+
+				<li>add beans to a conversation</li>
 			</ul>
-			<subsection name="Start a conversation"></subsection>
+			<subsection name="Start a conversation">
+				Starting a conversation is easy, its automatically done one the first access to the bean.
+				Due to the use of
+				<code>&lt;aop:scoped-proxy /&gt;</code>
+				this is on the first access
+				of one of the methods of your bean.
+			</subsection>
+			<subsection name="End a conversation">
+				There are two ways to end a conversation:
+				<ul>
+					<li>Manually</li>
+					<li>Automatically
+						<br/>
+						After a timeout the conversation will be closed.
+					</li>
+				</ul>
+
+				<p>
+					For all methods apply: Any open entity manager will be closed and entities changed
+					are discarded if you've not committed them.
+				</p>
+
+				<p>
+					You can have as many
+					<code>flush()/commit()/@Transactional</code>
+					s as you would like to within
+					one conversation.
+				</p>
+
+				<ul>
+					<li>
+						<code>Conversation.getCurrentInstance().invalidate();</code>
+						<br/>
+						You can use this method from within the conversation bean to invalidate itself.
+						Since this is not really possible - you are within the conversation - the real
+						and will be queued until you leave the method.
+					</li>
+					<li>
+						<code>ConversationManager.getInstance().getConversation("convName").invalidate();</code>
+						<br/>
+						If called from outside the conversation bean, or if you reference another conversation,
this
+						will immediately end the conversation.
+					</li>
+				</ul>
+
+				<p>
+					This lazy invalidation mechanism applies always if you are within an conversation.
+					<br/>
+					Technically spoken: Each method invocation into a conversation bean will increment
+					an active counter, leaving the method decrements it. Only if this counter is zero
+					the conversation can be destroyed.
+				</p>
+
+				<p>
+					There is one exception to this:
+					<code>Conversation.endAndRestart</code>
+				</p>
+
+			</subsection>
+
+			<subsection name="End and restart a conversation">
+				<p>
+					Save actions are mostly a good place to end a conversation, you might have done tons
of
+					database queries to e.g. collect the data required to insert a customer into your
+					ERP database.
+				</p>
+				<p>
+					But what if you would like to present the already created entity again to the user
+					so that he/she can start to edit the data.
+				</p>
+				<p>
+					Its still a good idea to end the conversation to free the data cached by the entity
manager.
+				</p>
+				<p>
+					Thats where
+					<code>Conversation.invalidateAndRestart()</code>
+					comes in handy.
+				</p>
+				<p>
+					It allows you to immediately get access to the new conversation and reinitialize your
bean.
+				</p>
+				<p>
+					As you might see from the API
+					<code>Conversation.invalidateAndRestart()</code>
+					returns a
+					<code>Conversation</code>
+					object.
+					<br/>
+					This is not much of help, use
+					<code>ConversationUtils.invalidateAndRestart(Conversation conversation)</code>
+					if you would like to have your new bean returned.
+				</p>
+				<p>
+					A good patter might be:
+					<pre>
+						public void invalidateAndRestart()
+						{
+						    YouBean bean = (YourBean)
+						        ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance());
+						    bean.setRestartedUser(createdUser.getId());
+						}
+					</pre>
+
+					<b>Notice:</b>
+					Due to the way how the internal proxying stuff of the conversation bean works
+					it is not possible to have this init method
+					<code>private</code>
+					. You have to ensure its
+					<code>public</code>
+					, else a wrong bean instance will be initalized.
+				</p>
+			</subsection>
+
+			<subsection name="Add beans to a conversation">
+				As e.g a http session or the request map, internally the conversation is also just a
map
+				of beans.
+				<br/>
+				Using the spring configuration you're able to add just one bean, the conversation scoped
+				bean to the conversation with the same name as the bean.
+				<br/>
+				But there are ways to add beans using the Conversation API.
+
+				<p>
+					Once you have access to the conversation object using
+					<code>Conversation.getCurrentInstance()</code>
+					or the ConversationManager API you do this with:
+
+					<ul>
+						<li>Conversation.setAttribute(key, value)</li>
+						<li>Conversation.hasAttribute(key)</li>
+						<li>Conversation.getAttribute(key)</li>
+						<li>Conversation.removeAttribute(key)</li>
+					</ul>
+				</p>
+
+				<p>
+					Any bean implementing the <code>ConversationBindingListener</code> interface
+					will receive the <code>valueBound()/valueUnbound()</code>.
+
+					<ul>
+						<li>valueBound()<br/>
+							Will be invoked AFTER the bean has been added to the conversation map.
+						</li>
+
+						<li>valueUnbound()<br/>
+							Will be invoked AFTER the bean has been removed from the conversation map.<br/>
+							This will haben if you call <code>removeAttribute(key)</code> or if the
+							conversation ends, either manually or autmoatically due to a timeout.
+						</li>
+					</ul>
+
+					<b>Notice:</b> In <code>valueUnbound()</code> you can't not
assume that a faces context
+					will be available.
+				</p>
+			</subsection>
+
 		</section>
 	</body>
 </document>



Mime
View raw message