svn commit: r567255 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java

[sk...@apache.org]

Author: skitching
Date: Sat Aug 18 03:00:19 2007
New Revision: 567255

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

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java?view=diff&rev=567255&r1=567254&r2=567255
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/jsf/lib/EndConversationMethodBindingFacade.java Sat Aug 18 03:00:19 2007
@@ -32,7 +32,19 @@
 import java.util.Collection;
 
 /**
- * a facade for the original method binding to deal with end conversation conditions
+ * A facade for the original method binding to deal with end conversation conditions.
+ * <p>
+ * This class implements MethodBinding, ie represents an EL expression string that specifies
+ * a method to call. It is expected to be used when invoking action methods when the current
+ * conversation should be closed upon success of the action. 
+ * <p>
+ * This facade also enhances error-handling for action methods. If the invoked method throws
+ * an exception of any kind, and an errorOutcome value has been specified then the errorOutcome
+ * is returned instead of allowing the exception to propagate. Note that the conversation is
+ * <i>not</> ended. The exception that occurred is reported to the ConversationMessager object
+ * associated with the conversation, so it can choose whether and how to present the error
+ * to the user.
+ * <p>
  */
 public class EndConversationMethodBindingFacade extends MethodBinding implements StateHolder
 {
@@ -49,6 +61,28 @@
 	{
 	}
 
+	/**
+	 * Constructor.
+	 * 
+	 * @param conversation is the name of the conversation to conditionally be closed.
+	 * 
+	 * @param onOutcomes is a collection of navigation strings that may be returned from the
+	 * invoked method. If the returned value <i>is</i> in this list then the named conversation
+	 * is ended (and possibly restarted), ie all beans currently in the conversation are discarded.
+	 * If the returned value is not in this list then the conversation is not affected.
+	 * 
+	 * @param original is the EL expression to be invoked.
+	 * 
+	 * @param errorOutcome is a JSF navigation string to be returned if the action method
+	 * throws an exception of any kind. Note that in this situation the conversation is
+	 * never ended.
+	 * 
+	 * @param restart determines whether the conversation will be restarted when the value
+	 * returned matches an onOutcome. Null and false both mean "do not restart".
+	 * 
+	 * @param restartAction is an optional EL expression string to be invoked when restarting
+	 * a conversation. This is ignored unless restart=true.
+	 */
 	public EndConversationMethodBindingFacade(
 		String conversation, Collection onOutcomes, MethodBinding original,
 		String errorOutcome, Boolean restart, MethodBinding restartAction)
@@ -131,11 +165,13 @@
 		return returnValue;
 	}
 
+	/** Required by StateHolder interface. */
 	public void setTransient(boolean newTransientValue)
 	{
 		_transient = newTransientValue;
 	}
 
+	/** Required by StateHolder interface. */
 	public boolean isTransient()
 	{
 		return _transient;