svn commit: r586457 - /myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java

[sk...@apache.org]

Author: skitching
Date: Fri Oct 19 06:53:16 2007
New Revision: 586457

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

Modified:
    myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java

Modified: myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java?rev=586457&r1=586456&r2=586457&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java (original)
+++ myfaces/orchestra/trunk/core15/src/main/java/org/apache/myfaces/orchestra/conversation/annotations/ConversationRequire.java Fri Oct 19 06:53:16 2007
@@ -25,20 +25,45 @@
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Defines a class as ViewController to receive ViewController events for
- * the given viewId(s)
+ * Can be used to prevent access to a view where the expected bean state
+ * (ie conversation) does not exist, and redirect instead to another view.
+ * <p>
+ * When a workflow passes through a number of different views, all views
+ * except the first one will expect a conversation to exist, with the
+ * beans in that conversation holding appropriate state. If the
+ * conversation does not exist then the view will fail to work correctly.
+ * Possible causes for this kind of invalid state include:
+ * <ul>
+ * <li>A user selecting a bookmark
+ * <li>A user directly manipulating a URL
+ * <li>A conversation expiring
+ * </ul>
+ * <p>
+ * To resolve these issues, a bean can use the Orchestra ViewController
+ * to configure itself as being associated with specific views, then
+ * use this ConversationRequire annotation to declare what conversation(s)
+ * it expects to exist. When an associated view is activated and the
+ * conversation does not exist then a redirect immediately occurs to the
+ * specified page - which is usually set to the first page in the relevant
+ * workflow.  
  */
 @Target(value = {ElementType.TYPE})
 @Retention(value = RetentionPolicy.RUNTIME)
 public @interface ConversationRequire
 {
 	/**
-	 * <p>
 	 * The view(s) which acts as the entry point(s) to the conversation.
 	 * For views configured here no check if the conversation is already running happens.
-	 * You have to configure it to avoid endless redirects to the start page.
-	 * </p>
-	 * TODO: Is there a way to avoid this configuration option?
+	 * <p>
+	 * This is necessary when the same bean is used to handle lifecycle events for
+	 * multiple views in a workflow, and also to check for the existence of a
+	 * conversation on every view except the first. Without knowing which of the
+	 * views is the first, endless redirects will occur.
+	 * <p>
+	 * TODO: Is there a way to avoid this configuration option? One possibility
+	 * is to somehow detect that a view is being created due to a redirect or
+	 * navigationAction caused by a ConversationRequire on the previous request
+	 * for the current ConversationContext...
 	 */
 	String[] entryPointViewIds() default "";