svn commit: r592712 - in /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController: ViewController.java spring/SpringViewControllerScope.java

[sk...@apache.org]

Author: skitching
Date: Wed Nov  7 03:18:27 2007
New Revision: 592712

URL: http://svn.apache.org/viewvc?rev=592712&view=rev
Log:
Add docs.

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewController.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/spring/SpringViewControllerScope.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewController.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewController.java?rev=592712&r1=592711&r2=592712&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewController.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewController.java Wed Nov  7 03:18:27 2007
@@ -26,6 +26,11 @@
  * When the InterfaceViewControllerExecutor has been selected as the technique for mapping
  * lifecycle events onto bean methods, then the target bean must implement this interface
  * in order to get callbacks.
+ * <p>
+ * Note that the expression "view controller bean" is used to generally refer to an object
+ * that can handle lifecycle events for a view. Such beans may implement this interface, but
+ * may not - they might be accessed via the ReflectiveViewControllerExecutor or other
+ * implementations that do not require this interface. 
  */
 public interface ViewController
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/spring/SpringViewControllerScope.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/spring/SpringViewControllerScope.java?rev=592712&r1=592711&r2=592712&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/spring/SpringViewControllerScope.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/spring/SpringViewControllerScope.java Wed Nov  7 03:18:27 2007
@@ -29,10 +29,32 @@
 import org.apache.myfaces.orchestra.viewController.ViewControllerManager;
 
 /**
- * This hooks into the Spring2.x scope-handling mechanism to provide a dummy scope which
- * will place a bean configured for into the same conversation as the viewController.
+ * This hooks into the Spring2.x scope-handling mechanism to provide a dummy scope type
+ * which will place a bean configured for it into the same conversation that the current
+ * viewController lives in.
  * <p>
- * TODO: why is this useful?
+ * To use this, in the spring config file add an element with id=N that defines a spring
+ * scope with this class as its controller. Then define managed beans with scope="N". When
+ * code references such a bean, then the current "view controller" bean is located
+ * (ie the bean handling lifecycle events for the current view), and the instance of
+ * the target bean from the same conversation is returned. If no such instance currently
+ * exists, then one is created and added to that conversation (even when an instance
+ * already exists in a different scope).
+ * <p>
+ * Note that this means a bean configured with a scope of this type will actually
+ * have a separate instance per conversation.
+ * <p>
+ * In particular, this works well with spring aop-proxy, where the proxy looks up the
+ * bean on each method call, and so always returns the instance in the conversation
+ * associated with the current view.
+ * <p>
+ * One use for this is implementing custom JSF converters or validators that access
+ * persistent objects. When accessing the database they need to use the same
+ * PersistenceContext that the beans handing this view use. Defining the converter
+ * using this scope type ensures that this happens.
+ * <p>
+ * It is an error (ie an exception is thrown) if a bean of this scope is referenced
+ * but there is no "view controller" bean associated with the current view.
  */
 public class SpringViewControllerScope extends AbstractSpringOrchestraScope
 {