svn commit: r627560 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java

[sk...@apache.org]

Author: skitching
Date: Wed Feb 13 10:55:04 2008
New Revision: 627560

URL: http://svn.apache.org/viewvc?rev=627560&view=rev
Log:
Add docs only

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java?rev=627560&r1=627559&r2=627560&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/AccessScopePhaseListener.java Wed Feb 13 10:55:04 2008
@@ -35,7 +35,33 @@
  * Handle access-scoped conversations.
  * <p>
  * At the end of request processing, delete any access-scope conversations for which no
- * bean in that scope has been accessed during the request.
+ * bean in that scope has been accessed during the <i>render phase</> of the request.
+ * Therefore if a postback occurs which accesses a specific conversation A, and that
+ * conversation then forwards to a different view whose render phase does not refer
+ * to any bean in conversation A, then the conversation is discarded. This ensures
+ * that conversations are discarded as soon as possible, and in particular that if
+ * control returns to the a view that accesses conversation A on the next cycle then
+ * a new conversation instance is created.
+ * <p>
+ * If a view happens to want its postbacks handled by a bean in conversation A,
+ * but the render phase never references anything in that conversation, then the
+ * conversation will be effectively request-scoped. This is not expected to be a
+ * problem in practice as it would be a pretty odd view that has stateful event
+ * handling but either renders nothing or fetches its data from somewhere other 
+ * than the same conversation. If such a case is necessary, the view can be modified
+ * to "ping" the conversation in order to keep it active via something like an
+ * h:outputText with rendered="#{backingBean.class is null}" (which always resolves
+ * to false, ie not rendered, but does force a method-invocation on the backingBean
+ * instance). Alternatively, a manual-scoped conversation can be used.
+ * <p>
+ * Note that if FacesContext.responseComplete is called during processing, then
+ * no phase-listeners for the RENDER_RESPONSE phase are executed. And any navigation
+ * rule that specifies "redirect" causes responseComplete to be invoked. Therefore
+ * access-scoped beans are not cleaned up immediately. However the view being
+ * redirected to always runs its "render" phase only, no postback. The effect, 
+ * therefore, is exactly the same as when an internal forward is performed to
+ * the same view: in both cases, the access-scoped beans are kept if the next view
+ * refers to them, and discarded otherwise. 
  * 
  * @since 1.1
  */