svn commit: r749103 - /myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml

[sk...@apache.org]

Author: skitching
Date: Sun Mar  1 21:03:46 2009
New Revision: 749103

URL: http://svn.apache.org/viewvc?rev=749103&view=rev
Log:
Add docs for Seam/Webflow users (apply r749100 from 1.3.1 release branch)

Modified:
    myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml

Modified: myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml?rev=749103&r1=749102&r2=749103&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml Sun Mar  1 21:03:46 2009
@@ -186,5 +186,76 @@
       This means that Orchestra requires server-side storage.
       </p>
     </section>
+    <section name="Notes for Seam Users">
+      <p>
+      The JBoss Seam library also provides a conversation scope. The purpose of this
+      scope is the same in Orchestra and Seam, but the details are a little different.
+      We aren't Seam experts, so this section is just our best attempt at describing
+      the fundamental differences; please contact the mailing list if you are a Seam
+      expert and have corrections for this section...
+      </p>
+      <p>
+      Seam's conversations are "request-centric", ie a request always has an associated
+      conversation (which may be "transient", ie of request scope!). Beans can be bound
+      to the current conversation via "out-jection" annotations. Therefore it makes sense
+      to ask "what is the current conversation for this request" from anywhere, even when
+      the object making the call is not "in" a conversation. 
+      </p>
+      <p>
+      Orchestra instead is "bean-centric", ie a bean instance may have an associated
+      conversation, but a request does not. A request can access multiple beans, and each
+      of those beans can potentially be in a different conversation. A method can ask
+      "what conversation am I being invoked in", ie what conversation-scoped bean has
+      invoked the current method (and the answer may be "none"). Note that having
+      multiple conversations is really useful for pages where different parts of the page
+      (different "panels") have different lifetimes.
+      </p>
+      <p>
+      Seam's concept of "nested" conversations isn't generally needed in Orchestra, as
+      Orchestra supports multiple concurrent conversations (each with a separate "name").
+      In the case where a page calls itself, Orchestra <i>does</i> then need to "nest" data,
+      as the beans will try to use the same conversation. In this case, a nested
+      conversation-context must be used.
+      </p>
+      <p>
+      Seam uses an @Begin annotation on a method (or a non-standard "begin-conversation"
+      JSF navigation rule) to create a long-lived conversation. Orchestra does it automatically;
+      whenever an instance of a bean is created which is marked as being in a conversation "foo"
+      then conversation "foo" starts. Seam uses out-jection annotations to indicate which beans
+      belong in the conversation; instead with Orchestra the bean declarations themselves indicate
+      which conversation the bean instance is in.
+      </p>
+      <p>
+      Both Seam and Orchestra need a mechanism to end a conversation. For Orchestra's
+      "manual-lifetime" conversations, the o:endConversation tag or a call to method
+      Conversation.getCurrentInstance().invalidate() are pretty much equivalent to the
+      Seam @End annotation. For Orchestra's "access-lifetime" conversations, the conversation
+      is terminated automatically; we are not aware of any Seam equivalent for this.     
+      </p>
+      <p>
+      Seam's conversation-context is almost identical to Orchestra's conversation-context.
+      However with Seam, pages need to explicitly include the context id into urls, by
+      using EL expression #{conversation.id} or the s:conversationPropagation tag where
+      appropriate. Orchestra automatically does this; instead, only links that should <i>not</i>
+      propagate the conversation context need to be marked (using the o:separateConversationContext
+      tag). This works for all JSF components as long as they call ExternalContext.encodeURL(),
+      which all code that generates URLs should do.
+      </p>
+      <p>
+      Seam's "conversation switcher" functionality is equivalent to switching between different
+      Orchestra "conversation contexts".
+      </p>
+    </section>
+    <section name="Notes for Spring WebFlow Users">
+      <p>
+      The Spring WebFlow library also provides a conversation scope. The purpose of this
+      scope is the same in Orchestra and Seam, but the details are a little different.
+      </p>
+      <p>
+      WebFlow appears to have a similar approach to Seam (request-centric rather than
+      Orchestra's bean-centric approach). See the first couple of paragraphs above
+      describing the Seam/Orchestra differences for the implications of this.
+      </p>
+    </section>
   </body>
 </document>