myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From skitch...@apache.org
Subject svn commit: r581950 - in /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation: Conversation.java ConversationAspect.java ConversationTimeoutableAspect.java
Date Thu, 04 Oct 2007 15:28:14 GMT
Author: skitching
Date: Thu Oct  4 08:28:13 2007
New Revision: 581950

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

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/Conversation.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationAspect.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationTimeoutableAspect.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/Conversation.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/Conversation.java?rev=581950&r1=581949&r2=581950&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/Conversation.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/Conversation.java
Thu Oct  4 08:28:13 2007
@@ -26,22 +26,32 @@
 import org.apache.commons.logging.LogFactory;
 
 /**
- * The container for all beans managed by this conversation.
- * <p>
- * There is a (not yet configureable) timeout which is responsible to destory
- * the conversation if it has not been accessed.
- * </p>
- * <p>
- * Beans implementing the {@link ConversationBindingListener} will receive a message
- * when removed from (e.g. during destroy) or added to the conversation.
- * </p>
- * <p>
- * There are various ways how to get access to the conversation:
+ * A Conversation is a container for a set of beans.
+ * 
+ * <p>Optionally, a PersistenceContext can also be associated with a conversation.</p>
+ * 
+ * <p>There are various ways how to get access to a Conversation instance:
  * <ul>
- * <li>{@link Conversation#getCurrentInstance} if you are within a conversation</li>
+ * <li>{@link Conversation#getCurrentInstance} if you are calling from a
+ * conversation-scoped bean, or something that is called from such a bean.</li>
  * <li>{@link ConversationManager#getConversation(String)}</li>
- * <li>or by implementing the {@link ConversationAware} or {@link ConversationBindingListener}
- * interface in your bean and get the {@link Conversation} from them.
+ * <li>by implementing the {@link ConversationAware} or {@link ConversationBindingListener}
+ * interface in a bean.</li>
+ * </ul>
+ * </p>
+ * 
+ * <p>Conversation instances are typically created when an EL expression references
a
+ * bean whose definition indicates that it is in a conversation scope.</p>
+ * 
+ * <p>Conversation instances are typically destroyed:
+ * <ul>
+ * <li>At the end of a request when they are marked as a "flash" conversation but
+ * no bean in the conversation scope was accessed during the just-completed request.</li>
+ * <li>Via an ox:endConversation component</li>
+ * <li>Via an action method calling Conversation.invalidate()</li>
+ * <li>Due to a conversation timeout, ie when no object in the conversation has been
+ * accessed for N minutes. See ConversationManagedSessionListener,
+ * ConversationTimeoutableAspect, and ConversationManager.checkTimeouts.</li>
  * </ul>
  * </p>
  */
@@ -54,19 +64,28 @@
 
 	private final String name;
 	
-	// the factory that created this conversation instance; needed
+	// The factory that created this conversation instance; needed
 	// when restarting the conversation.
 	private final ConversationFactory factory;
 
+	// The set of managed beans that are associated with this conversation.
 	private final Map beans = new TreeMap();
 
+	// The parent context to which this conversation belongs. This is needed
+	// when restarting the conversation.
 	private final ConversationContext conversationContext;
 
+	// See addAspect.
 	private ConversationAspects conversationAspects = new ConversationAspects();
 
+	// Is this object usable, or "destroyed"?
 	private boolean invalid = false;
+
+	// Is this object going to be destroyed as soon as it is no longer "active"?
 	private boolean queueInvalid = false;
 
+	// system timestamp in milliseconds at which this object was last accessed;
+	// see method touch().
 	private long lastAccess;
 
 	private Object activeCountMutex = new Object();
@@ -86,13 +105,27 @@
 		touch();
 	}
 
+	/**
+	 * Mark this conversation as having been used at the current time.
+	 * <p>
+	 * Conversations can have "timeouts" associated with them, so that when a user stops
+	 * a conversation and goes off to work on some other part of the webapp then the
+	 * conversation's memory can eventually be reclaimed.
+	 * <p>
+	 * Whenever user code causes this conversation object to be looked up and returned,
+	 * this "touch" method is invoked to indicate that the conversation is in use. Direct
+	 * conversation lookups by user code can occur, but the most common access is expected
+	 * to be via an EL expression which a lookup of a bean that is declared as being in
+	 * conversation scope. The bean lookup causes the corresponding conversation to be
+	 * looked up, which triggers this method.
+	 */
 	protected void touch()
 	{
 		lastAccess = System.currentTimeMillis();
 	}
 
 	/**
-	 * the system time in millis when this conversation has been accessed last
+	 * The system time in millis when this conversation has been accessed last
 	 */
 	public long getLastAccess()
 	{
@@ -100,9 +133,16 @@
 	}
 
 	/**
-	 * <p>Add the given bean to the conversation scope</p>
-	 * <p>This will fire a {@link ConversationBindingEvent} if the bean
-	 * implements the {@link ConversationBindingListener} interface</p>
+	 * Add the given bean to the conversation scope.
+	 * 
+	 * <p>This will fire a {@link ConversationBindingEvent} on the bean parameter
+	 * object if the bean implements the {@link ConversationBindingListener}
+	 * interface</p>
+	 * 
+	 * <p>Note that any object can be stored into the conversation; it is not
+	 * limited to managed beans declared in a configuration file. This
+	 * feature is not expected to be heavily used however; most attributes of
+	 * a conversation are expected to be externally-declared "managed beans".</p>
 	 */
 	public void setAttribute(String name, Object bean)
 	{
@@ -128,7 +168,10 @@
 	}
 
 	/**
-	 * assert the conversation is valid.
+	 * Assert the conversation is valid.
+	 * 
+	 * Throws IllegalStateException if this conversation has been destroyed;
+	 * see method setInvalid.
 	 */
 	protected void checkValid()
 	{
@@ -139,7 +182,9 @@
 	}
 
 	/**
-	 * the conversation name
+	 * Return the name of this conversation.
+	 * <p>
+	 * A conversation name is unique within a conversation context.
 	 */
 	public String getName()
 	{
@@ -147,7 +192,11 @@
 	}
 
 	/**
-	 * the policy the conversation should use. the policy will define the lifetime of the conversation
+	 * Return the factory that created this conversation.
+	 * <p>
+	 * Note that this factory will have set the initial aspects of this factory, which
+	 * configure such things as the lifetime (flash, manual, etc) and conversation
+	 * timeout properties.
 	 */
 	public ConversationFactory getFactory()
 	{
@@ -155,13 +204,20 @@
 	}
 
 	/**
-	 * <p>Invalidate/End the conversation</p>
+	 * Invalidate (end) the conversation.
 	 * <p>
-	 * If you are within a conversation (the conversation is active) this
-	 * will just queue the destroy to the next possible time.
-	 * A conversation is active if you are within a method of one of the
-	 * beans within this scope.
-	 * </p>
+	 * If the conversation is currently active (ie the current call stack contains an object
that
+	 * belongs to this conversation) then the conversation will just queue the object for later
+	 * destruction. Calls to methods like ConversationManager.getConversation(...) may still
+	 * return this object, and it will continue to function as a normal instance.
+	 * <p>
+	 * Only when the conversation is no longer active will the conversation (and the beans
+	 * it contains) actually be marked as invalid ("destroyed"). Once the conversation has been
+	 * destroyed, the ConversationManager will discard all references to it, meaning it will
no
+	 * longer be accessable via lookups like ConversationManager.getConversation(). If something
+	 * does still have a reference to a destroyed conversation, then invoking almost any method
+	 * on that object will throw an IllegalStateException. In particular, adding a bean to the
+	 * conversation (invoking addAttribute) is not allowed.
 	 */
 	public void invalidate()
 	{
@@ -181,7 +237,14 @@
 	}
 
 	/**
-	 * <p>Invalidate/End and restart the conversation</p>
+	 * Invalidate/End and restart the conversation.
+	 * <p>
+	 * This conversation object is immediately "destroyed" (see comments for method
+	 * invalidate), and a new instance is registered with the conversation manager
+	 * using the same name. The new instance is returned from this method.
+	 * <p>
+	 * Any code holding a reference to the old conversation instance will receive
+	 * an IllegalStateException when calling almost any method on that instance.
 	 *
 	 * @returns the new conversation
 	 */
@@ -196,7 +259,7 @@
 	}
 
 	/**
-	 * return true if the conversation is invalid
+	 * Return true if the conversation is invalid, ie should not be used.
 	 */
 	public boolean isInvalid()
 	{
@@ -204,7 +267,7 @@
 	}
 
 	/**
-	 * return true if the conversation has been queued to be invalidated
+	 * Return true if the conversation has been queued to be invalidated.
 	 */
 	boolean isQueueInvalid()
 	{
@@ -212,7 +275,7 @@
 	}
 
 	/**
-	 * destroy the conversation <br />
+	 * Destroy the conversation.
 	 * <ul>
 	 * <li>inform all beans implementing the {@link ConversationBindingListener} about
the conversation end</li>
 	 * <li>free all beans</li>
@@ -240,7 +303,8 @@
 	}
 
 	/**
-	 * check if this conversation holds a specific attribute
+	 * Check if this conversation holds a specific attribute (ie has a specific
+	 * named managed bean instance).
 	 */
 	public boolean hasAttribute(String name)
 	{
@@ -251,7 +315,7 @@
 	}
 
 	/**
-	 * get a specific attribute
+	 * Get a specific attribute, ie a named managed bean.
 	 */
 	public Object getAttribute(String name)
 	{
@@ -262,11 +326,10 @@
 	}
 
 	/**
-	 * <p>remove a bean from the conversation.</p>
-	 * <p/>
-	 * This will fire a {@link ConversationBindingEvent} if the bean implements the
-	 * {@link ConversationBindingListener} interface.
-	 * </p>
+	 * Remove a bean from the conversation.
+	 * 
+	 * <p>This will fire a {@link ConversationBindingEvent} if the bean implements the
+	 * {@link ConversationBindingListener} interface.</p>
 	 */
 	public Object removeAttribute(String name)
 	{
@@ -371,14 +434,20 @@
 	}
 
 	/**
-	 * get the aspect corresponding to the given class.
-	 * @return null if such an apsect has not been attached to this conversation
+	 * Get the aspect corresponding to the given class.
+	 * 
+	 * @return null if such an aspect has not been attached to this conversation
 	 */
 	public ConversationAspect getAspect(Class conversationAspectClass)
 	{
 		return conversationAspects.getAspect(conversationAspectClass);
 	}
-	
+
+	/**
+	 * Add an Aspect to this conversation. 
+	 * 
+	 * See class ConversationAspects for further details.
+	 */
 	public void addAspect(ConversationAspect aspect)
 	{
 		conversationAspects.addAspect(aspect);

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationAspect.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationAspect.java?rev=581950&r1=581949&r2=581950&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationAspect.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationAspect.java
Thu Oct  4 08:28:13 2007
@@ -19,16 +19,9 @@
 package org.apache.myfaces.orchestra.conversation;
 
 /**
+ * The base class for any "aspect" that can be attached to a conversation.
  * <p>
- * A conversation aspect which can be attached to an conversation.
- * </p>
- * <p>
- * Orchestra uses this thing to
- * <ul>
- *     <li>Check the timeout of a conversation</li>
- *     <li>Connect the conversation to the FlashScopeManager</li>
- * </ul>
- * </p>
+ * See class ConversationAspects for further details.
  */
 public abstract class ConversationAspect
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationTimeoutableAspect.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationTimeoutableAspect.java?rev=581950&r1=581949&r2=581950&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationTimeoutableAspect.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/ConversationTimeoutableAspect.java
Thu Oct  4 08:28:13 2007
@@ -23,6 +23,7 @@
  */
 public class ConversationTimeoutableAspect extends ConversationAspect
 {
+	// Number of milliseconds
 	private long timeout = -1;
 
 	public ConversationTimeoutableAspect(Conversation conversation)



Mime
View raw message