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

[sk...@apache.org]

Author: skitching
Date: Mon Nov 10 04:40:24 2008
New Revision: 712654

URL: http://svn.apache.org/viewvc?rev=712654&view=rev
Log:
Improve javadoc

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

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationManager.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationManager.java?rev=712654&r1=712653&r2=712654&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationManager.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationManager.java Mon Nov 10 04:40:24 2008
@@ -36,8 +36,14 @@
 /**
  * Deals with the various conversation contexts in the current session.
  * <p>
- * A new conversation context will be created if the servlet request did
- * not specify an existing conversation context id.
+ * There is expected to be one instance of this class per http-session, managing all of the
+ * data associated with all browser windows that use that http-session.
+ * <p>
+ * One particular task of this class is to return "the current" ConversationContext object for
+ * the current http request (from the set of ConversationContext objects that this manager
+ * object holds). The request url is presumed to include a query-parameter that specifies the
+ * id of the appropriate ConversationContext object to be used. If no such query-parameter is
+ * present, then a new ConversationContext object will automatically be created.
  * <p>
  * At the current time, this object does not serialize well. Any attempt to serialize
  * this object (including any serialization of the user session) will just cause it
@@ -76,7 +82,13 @@
     }
 
     /**
-     * Get the conversation manager. This creates a new one if none exists.
+     * Get the conversation manager for the current http session.
+     * <p>
+     * If none exists, then a new instance is allocated and stored in the current http session.
+     * Null is never returned.
+     * <p>
+     * Throws IllegalStateException if the Orchestra FrameworkAdapter has not been correctly
+     * configured.
      */
     public static ConversationManager getInstance()
     {
@@ -84,13 +96,12 @@
     }
 
     /**
-     * Get the conversation manager.
+     * Get the conversation manager for the current http session.
      * <p>
-     * When create is true, an instance is always returned; one is
-     * created if none currently exists for the current user session.
+     * When create is true, an instance is always returned; one is created if none currently exists
+     * for the current user session.
      * <p>
-     * When create is false, null is returned if no instance yet
-     * exists for the current user session.
+     * When create is false, null is returned if no instance yet exists for the current user session.
      */
     public static ConversationManager getInstance(boolean create)
     {