You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/10/04 17:28:14 UTC
svn commit: r581950 - in
/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation:
Conversation.java ConversationAspect.java ConversationTimeoutableAspect.java
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)