svn commit: r581284 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/servlet/ConversationManagerSessionListener.java

[sk...@apache.org]

Author: skitching
Date: Tue Oct  2 08:42:31 2007
New Revision: 581284

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

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

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/servlet/ConversationManagerSessionListener.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/servlet/ConversationManagerSessionListener.java?rev=581284&r1=581283&r2=581284&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/servlet/ConversationManagerSessionListener.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/servlet/ConversationManagerSessionListener.java Tue Oct  2 08:42:31 2007
@@ -29,11 +29,31 @@
 import javax.servlet.http.HttpSessionEvent;
 
 /**
+ * An http session listener which periodically scans every http session for
+ * conversations and conversation contexts that have exceeded their timeout.
  * <p>
- * This listener will maintain a single thread for all conversation managers active within the system.
- * <br />
- * See {@link org.apache.myfaces.orchestra.conversation.ConversationWiperThread} for more details.
- * </p>
+ * If a web application wants to configure a conversation timeout that is
+ * shorter than the http session timeout, then this class must be specified
+ * as a listener in the web.xml file. 
+ * <p>
+ * A conversation timeout is useful because the session timeout is refreshed
+ * every time a request is made. If a user starts a conversation that uses
+ * lots of memory, then abandons it and starts working elsewhere in the same
+ * webapp then the session will continue to live, and therefore so will that
+ * old "unused" conversation. Specifying a conversation timeout allows the
+ * memory for that conversation to be reclaimed in this situation. 
+ * <p>
+ * This listener starts a single background thread that periodically wakes
+ * up and scans all http sessions to find ConversationContext objects, and
+ * checks their timeout together with the timeout for all Conversations in
+ * that context. If a conversation or context timeout has expired then it
+ * is removed.
+ * <p>
+ * This code is probably not safe for use with distributed sessions, ie
+ * a "clustered" web application setup.
+ * <p>
+ * See {@link org.apache.myfaces.orchestra.conversation.ConversationWiperThread}
+ * for more details.
  */
 public class ConversationManagerSessionListener
 	implements HttpSessionAttributeListener, ServletContextListener, HttpSessionListener