svn commit: r581886 - in /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation: FlashScopeManager.java FlashScopeManagerConfiguration.java

[sk...@apache.org]

Author: skitching
Date: Thu Oct  4 06:06:12 2007
New Revision: 581886

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

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

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManager.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManager.java?rev=581886&r1=581885&r2=581886&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManager.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManager.java Thu Oct  4 06:06:12 2007
@@ -24,7 +24,11 @@
 import java.util.Set;
 
 /**
- * manager to deal with page scoped beans
+ * Manager to deal with page scoped beans.
+ * <p>
+ * Instances of this type are expected to be request-scoped, ie a new instance is used for
+ * each request. The FlashScopeManagerConfiguration object that it references can be
+ * of application scope.
  */
 public final class FlashScopeManager
 {
@@ -37,9 +41,18 @@
 
 	public static FlashScopeManager getInstance()
 	{
+		// Get the instance by looking up a variable whose name is this class name, using the normal
+		// managed bean lookup process. When an IOC framework like Spring is being used to extend
+		// the standard JSF managed bean declaration facilities, then the bean may be retrieved
+		// from there.
+		//
+		// Using a lookup of a managed bean allows the user to set configuration properties on the
+		// manager class and its properties.
 		FlashScopeManager manager = (FlashScopeManager) FrameworkAdapter.getInstance().getBean(FlashScopeManager.class.getName());
 		if (manager == null)
 		{
+			// TODO: Make this error message less spring-specific. Spring is not the only IOC container
+			// that Orchestra can be used with.
 			throw new IllegalArgumentException("no FlashScopeManager found. Propably you forgot to add <import resource=\"classpath*:/META-INF/spring-orchestra-init.xml\" /> to your spring configuration.");
 		}
 
@@ -57,11 +70,18 @@
 	}
 
 	/**
-	 * add a conversation to the list of accessed conversations. <br />
+	 * Add a conversation to the list of accessed conversations.
+	 * <p>
 	 * Notice: this method is final for performance reasons.
+	 * <p>
+	 * This method is expected to be called via AOP proxies wrapped around each conversation-scoped
+	 * bean; any invocation of a method on such a bean causes the conversation associated with that
+	 * bean to be added to the accessed list here.
 	 */
 	public final void addConversationAccess(String conversationName)
 	{
+		// Don't bother tracking accessed conversations if we will never use the data.
+		// Otherwise, add this conversation name to the list of accessed conversations.
 		if (!ignoreRequest && !accessedConversations.contains(conversationName))
 		{
 			accessedConversations.add(conversationName);
@@ -73,6 +93,13 @@
 		return ignoreRequest;
 	}
 
+	/**
+	 * Suppress flash scope for the current request, ie do not terminate conversations that are
+	 * not accessed by this request.
+	 * <p>
+	 * This can come in useful occasionally, particularly when handling AJAX requests which
+	 * only access some of the beans associated with the current view.
+	 */
 	public void setIgnoreRequest()
 	{
 		this.ignoreRequest = true;

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManagerConfiguration.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManagerConfiguration.java?rev=581886&r1=581885&r2=581886&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManagerConfiguration.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/FlashScopeManagerConfiguration.java Thu Oct  4 06:06:12 2007
@@ -20,6 +20,12 @@
 
 import java.util.Set;
 
+/**
+ * Provides configuration information to a FlashScopeManager instance.
+ * <p>
+ * While a FlashScopeManager object is expected to be request-scoped, an instance
+ * of this type is usually application-scoped (aka singleton scoped).
+ */
 public class FlashScopeManagerConfiguration
 {
 	private Set ignoreViewIds;
@@ -29,6 +35,14 @@
 		return ignoreViewIds;
 	}
 
+	/**
+	 * Do not terminate any "unaccessed conversations" after handling a request to
+	 * any of the specified views.
+	 * 
+	 * Special "ignored views" are useful when dealing with things like nested
+	 * frames within a page that periodically refresh themselves while the "main"
+	 * part of the page remains unsubmitted.
+	 */
 	public void setIgnoreViewIds(Set ignoreViewIds)
 	{
 		this.ignoreViewIds = ignoreViewIds;