You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by im...@apache.org on 2007/03/02 11:55:47 UTC
svn commit: r513702 -
/myfaces/fusion/trunk/core/src/site/xdoc/conversationManagement.xml
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><aop:scoped-proxy /></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>