svn commit: r564903 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/CurrentConversationAdvice.java

[sk...@apache.org]

Author: skitching
Date: Sat Aug 11 05:08:15 2007
New Revision: 564903

URL: http://svn.apache.org/viewvc?view=rev&rev=564903
Log:
Add javadoc and comments only.

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

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/CurrentConversationAdvice.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/CurrentConversationAdvice.java?view=diff&rev=564903&r1=564902&r2=564903
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/CurrentConversationAdvice.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/CurrentConversationAdvice.java Sat Aug 11 05:08:15 2007
@@ -30,6 +30,14 @@
  * <li>End the conversation if it has been invalidated</li>
  * </ul>
  * </p>
+ * 
+ * <p>A spring bean that is declared as belonging to a particular conversation is
+ * always wrapped in a proxy object. When any method is called on that proxy,
+ * the call is forwarded to the "invoke" method here. This class then ensures
+ * that the "current conversation" is set to the conversation configured for
+ * that target bean. The result is that the real bean can call
+ * Conversation.getCurrentInstance() and always receives a reference to the
+ * conversation object that has been configured for it.</p>
  */
 public class CurrentConversationAdvice implements MethodInterceptor
 {
@@ -42,7 +50,11 @@
 
 	public Object invoke(MethodInvocation methodInvocation) throws Throwable
 	{
+		// Save the current conversation so it can be restored later.
+		// Note that for "top-level" calls, the saved value is null.
 		Conversation previous = Conversation.getCurrentInstance();
+
+		// Set the appropriate conversation for the target object. 
 		Conversation.setCurrentInstance(conversation);
 
 		try
@@ -60,6 +72,7 @@
 				conversation.invalidate();
 			}
 
+			// always restore the previous conversation (which may be null)
 			Conversation.setCurrentInstance(previous);
 		}
 	}