myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From skitch...@apache.org
Subject svn commit: r592546 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/
Date Tue, 06 Nov 2007 20:43:01 GMT
Author: skitching
Date: Tue Nov  6 12:43:00 2007
New Revision: 592546

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

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerExecutor.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerManager.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerExecutor.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerNameMapper.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerManager.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerNameMapper.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/InterfaceViewControllerExecutor.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ReflectiveViewControllerExecutor.java
    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/ViewControllerExecutor.java
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerNameMapper.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerExecutor.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerExecutor.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerExecutor.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerExecutor.java
Tue Nov  6 12:43:00 2007
@@ -22,11 +22,12 @@
 
 
 /**
- * <p>The abstract basis class you have to use as basis class for any custom view controller
executor.</p>
- * <p>Notice: This abstract class is a helper as the interface can be extended between
releases,
- * thats why its an abstract class instead of an interface.
- * New methods not implemented by your custom excecutor will not harm your system that way
- * if you inherit from this abstract class .</p>
+ * An implementation of ViewControllerExecutor that can be subclassed to customise 
+ * the mapping of lifecycle events to bean methods.
+ * <p>
+ * Orchestra provides this class so that the executor responsibilities can be extended
+ * between releases without breaking binary compatibility (something that cannot be done
+ * with an interface).
  */
 public abstract class AbstractViewControllerExecutor implements ViewControllerExecutor
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerManager.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerManager.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerManager.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/AbstractViewControllerManager.java
Tue Nov  6 12:43:00 2007
@@ -23,7 +23,20 @@
 import org.apache.myfaces.orchestra.frameworkAdapter.FrameworkAdapter;
 
 /**
- * @see org.apache.myfaces.orchestra.viewController.ViewControllerManager
+ * A partial implementation of the ViewControllerManager interface which
+ * allows subclasses to just implement two simple abstract methods in order
+ * to provide a fully functional ViewControllerManager implementation.
+ * <p>
+ * This implementation splits responsibility for invoking view lifecycle
+ * events into three parts:
+ * <ul>
+ * <li>A "name mapper" that maps a view identifier to a bean name
+ * <li>An "executor" that decides which methods on a bean to invoke, and
+ * <li>A controller that invokes the mapper and executor.
+ * </ul>
+ * This class implements the "controller" bit itself, and leaves subclasses
+ * to just choose the "name mapper" and "executor" to use by overriding
+ * the abstract methods defined here.
  */
 public abstract class AbstractViewControllerManager implements ViewControllerManager
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerExecutor.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerExecutor.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerExecutor.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerExecutor.java
Tue Nov  6 12:43:00 2007
@@ -22,6 +22,10 @@
 /**
  * Each executor configured with the constructor will be asked to execute the
  * requested method on the bean. The search will end if the executor returns "true".
+ * <p>
+ * As an example, this can be configured to first try an executor that checks whether
+ * the bean implements a specific interface, then try one that uses reflection to find
+ * magic method-names, then try one that looks for annotations.
  */
 public class CompositeViewControllerExecutor implements ViewControllerExecutor
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerNameMapper.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerNameMapper.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerNameMapper.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/CompositeViewControllerNameMapper.java
Tue Nov  6 12:43:00 2007
@@ -22,6 +22,10 @@
 /**
  * Each view controller configured with the constructor will be asked to map the given viewId.
  * The first one not returning NULL wins. 
+ * <p>
+ * As an example, this can be configured to first try a mapper that converts the viewId to
+ * a beanname, then if that fails to find a match try a mapper that uses class annotations
+ * to find an appropriate bean.
  */
 public class CompositeViewControllerNameMapper implements ViewControllerNameMapper
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerManager.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerManager.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerManager.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerManager.java
Tue Nov  6 12:43:00 2007
@@ -21,11 +21,9 @@
 package org.apache.myfaces.orchestra.viewController;
 
 /**
- * <p/>
- * The default {@link ViewControllerManager} which uses the {@link DefaultViewControllerNameMapper}
- * to map view-ids to bean names and the {@link ReflectiveViewControllerExecutor} to invoke
- * view controller events on your beans.
- * </p>
+ * A ViewControllerManager which uses the {@link DefaultViewControllerNameMapper}
+ * to map view-ids to bean names and the {@link ReflectiveViewControllerExecutor}
+ * to invoke view controller events on beans.
  *
  * @see ViewControllerManager
  */

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerNameMapper.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerNameMapper.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerNameMapper.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/DefaultViewControllerNameMapper.java
Tue Nov  6 12:43:00 2007
@@ -25,32 +25,97 @@
 import java.util.Set;
 
 /**
- * <p>Map view-ids to bean names.</p>
- * <p/>
+ * Map view-ids to bean names, using a dirSubdirPage style format.
+ * <p>
  * The strategy of this mapper is as follows:
  * <ul>
- * <li>slash ('/') will be removed</li>
- * <li>every character after a slash will be convertert to uppercase, except the first
char</li>
- * <li>everyting after a dot ('.') will be removed</li>
- * <li>reserved words {@link #RESERVED_WORDS} are prefixed with an underscore ('_')</li>
- * <li>result starting with an digit are prefixed too </li>
+ * <li>The first character after every slash (except the first one) is converted to
uppercase;</li>
+ * <li>All slashes ('/') are removed;</li>
+ * <li>All characters following the last dot ('.') are removed;</li>
+ * <li>Reserved words {@link #RESERVED_WORDS} are prefixed with an underscore ('_');</li>
+ * <li>Resulting bean-names starting with a digit are also prefixed with an underscore.</li>
  * </ul>
- * </p>
- * <p/>
+ * <p>
  * Examples:
- * <table border="1">
- * <thead><tr><th>ViewId</th><th>BeanName</th></tr></thead>
- * <tbody>
- * <tr><td>/userInfo.jsp</td><td>userInfo</td></tr>
- * <tr><td>/SecureArea/userPassword.jsp</td><td>secureAreaUserPassword</td></tr>
- * </tbody>
- * </table>
- * </p>
+ * <ul>
+ * <li>"/userInfo.jsp" becomes "userInfo"
+ * <li>"/SecureArea/userPassword.xhtml" becomes "secureAreaUserPassword"
+ * </ul>
+ * <p>
+ * Using a bean naming scheme provides the following benefits:
+ * <ul>
+ * <li>The backing bean code does not need to be aware of the view path;
+ * <li>The backing bean class can be in any package;
+ * <li>Moving the view does not require alteration to the java code;
+ * <li>There is no separate "view mapping" configuration file required with
+ * its own unique format, just normal managed-bean configuration.
+ * <li>It is easy to see from the managed-bean declarations which view a bean is
+ * associated with. This information can be extremely useful when developing
+ * a large application, so a bean naming convention of this type is useful
+ * even when not being used for the purposes of view lifecycle events.
+ * </ul> 
+ * <p>
+ * In particular, the separation between "UI designer" and "coder" remains; the
+ * UI designer can move and rearrange views without touching java code. They do
+ * need to change the bean mapping files, but that is not so significant.
+ * <p>
+ * The following limitations apply to this approach:
+ * <ul>
+ * <li>Only one bean can be mapped to a view. However this can be worked around
+ * by providing a "relay" bean that delegates calls to all of the beans that 
+ * have been injected into it.
+ * <li>When a view is moved, lifecycle events will silently stop occurring if
+ * the bean-name is not been updated.
+ * <li>When a view is moved, the bean-name has to change. If the bean handling
+ * viewcontroller events is also referenced by other expressions in the page,
+ * then all those expressions must also be changed. Dependency-injection
+ * configuration that uses that bean-name must also be updated. However see
+ * below for information on "bean aliasing".
+ * <li>When a view is deeply nested within a directory tree, the bean name
+ * generated from the view name can become long and inconvenient to use within
+ * expressions. This is only an issue if the bean handling lifecycle events
+ * is also the target of expressions in the page, but that is often the case.
+ * </ul>
+ * <p>
+ * Some dependency-injection frameworks allow bean-name "aliases" to be defined,
+ * ie for a single managed-bean to have multiple names. This can be used to define
+ * one name that expressions reference the bean through, and a separate name
+ * that is used only in order to link that bean with the corresponding view. With
+ * this configuration, moving a view simply requires changing the name of the
+ * alias. If appropriate these aliases can be defined in a different configuration
+ * file from the "real" bean definitions (eg for the use of UI Designers). This
+ * approach does increase the number of managed-bean declarations required, so
+ * should only be applied where useful.
+ * <p>
+ * It is possible to define a very simple request-scoped bean for viewcontroller
+ * event handling that just delegates to another bean that is injected into it.
+ * This has the same effect as "bean aliasing" although it is implementable without
+ * "aliasing" support (and particularly, in plain JSF 1.1). This simple bean can be
+ * named after the view it controls, while the "real" backing bean can be named
+ * however it wishes. The same benefits and drawbacks apply as for the "aliases"
+ * approach described above.
+ * <p>
+ * It may be possible to also define aliases within the page definitions. In
+ * particular, for JSF the Apache Myfaces Tomahawk AliasBean can be used to define
+ * a local alias for a bean. If this is done at the top of a file, then when the
+ * view is moved, only that alias entry in the page needs to be altered rather
+ * than all expressions in the page. 
  */
 public class DefaultViewControllerNameMapper implements ViewControllerNameMapper
 {
-	private static Set RESERVED_WORDS = new HashSet(Arrays.asList(
-		new String[]
+	/**
+	 * An unmodifiable set of strings which are not permitted as bean-names.
+	 * <p>
+	 * If the mapping of any viewId to a bean-name results in one of these values,
+	 * then the name-mapper must modify the result.  
+	 * <p>
+	 * TODO: move this list to some shared class. Other ViewControllerNameMapper
+	 * implementations could find this list useful. Note, however, that it is
+	 * servlet-specific. This class is supposed to not assume any particular
+	 * request/response technology.
+	 */
+	private static final Set RESERVED_WORDS = new HashSet(Arrays.asList(
+			new String[]
 			{
 				"applicationScope",
 				"cookie",

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/InterfaceViewControllerExecutor.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/InterfaceViewControllerExecutor.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/InterfaceViewControllerExecutor.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/InterfaceViewControllerExecutor.java
Tue Nov  6 12:43:00 2007
@@ -25,7 +25,17 @@
 package org.apache.myfaces.orchestra.viewController;
 
 /**
- * Invokes ViewController events using the {@link ViewController} interface
+ * Invokes ViewController events using the {@link ViewController} interface.
+ * <p>
+ * This requires that beans implement the ViewController interface in order
+ * to receive view lifecycle events.
+ * <p>
+ * Other implementations are possible that do not require a bean to implement a
+ * specific interface; see ReflectiveViewControllerExecutor for one example.
+ * <p>
+ * Note that each method here returns false if the target bean does not
+ * implement the ViewController interface; this allows this executor to 
+ * be "chained" with others.
  */
 public class InterfaceViewControllerExecutor extends AbstractViewControllerExecutor
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ReflectiveViewControllerExecutor.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ReflectiveViewControllerExecutor.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ReflectiveViewControllerExecutor.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ReflectiveViewControllerExecutor.java
Tue Nov  6 12:43:00 2007
@@ -26,21 +26,22 @@
 import java.lang.reflect.Method;
 
 /**
- * <p>Invokes ViewController events using reflection.</p>
- * <p/>
- * Your beans can optionally provide one of the following methods
+ * Invokes ViewController events using reflection.
+ * <p>
+ * If the target bean has a method with any of the following signatures then it
+ * receives the appropriate callback:
  * <ul>
  * <li>public void initView()</li>
+ * <li>public void preProcess()</li>
  * <li>public void preRenderView()</li>
  * </ul>
- * </p>
+ * <p>
+ * Note that each method here returns false if the target bean does not
+ * have a method with an appropriate signature; this allows this executor to 
+ * be "chained" with others.
  */
 public class ReflectiveViewControllerExecutor extends AbstractViewControllerExecutor
 {
-	/*
-	 * Do not copy this code if you implement new ones, instead have a look
-	 * a few lines below.
-	 */
 	/**
 	 * Helper method to find the method which should get invoked.
 	 */

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=592546&r1=592545&r2=592546&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
Tue Nov  6 12:43:00 2007
@@ -21,11 +21,11 @@
 package org.apache.myfaces.orchestra.viewController;
 
 /**
- * <p>The ViewController interface</p>
- * <p/>
- * Your bean has to implement this interface if you've decided to use the {@link InterfaceViewControllerExecutor}
- * to get notifications
- * </p>
+ * An interface for use with the InterfaceViewControllerExecutor.
+ * <p>
+ * 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.
  */
 public interface ViewController
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerExecutor.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerExecutor.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerExecutor.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerExecutor.java
Tue Nov  6 12:43:00 2007
@@ -22,8 +22,17 @@
 
 
 /**
- * <p>The interface you have to use as basis class for any custom view controller executor.</p>
- * <p>Notice: Do not implement this interface directly, instead use the {@link AbstractViewControllerExecutor}</p>
+ * Find the appropriate method to invoke on a bean for each view lifecycle event.
+ * <p>
+ * Note that each method implementation is expected to return false if no matching
+ * method could be found. This allows ViewControllerExecutor implementations to
+ * be "chained" with others.
+ * <p>
+ * Warning: it is not recommended that code implement this interface directly;
+ * Orchestra reserves the right to change this interface in minor releases. Instead,
+ * subclass the class AbstractViewControllerExecutor.
+ * <p>
+ * @See {@link org.apache.myfaces.orchestra.viewController.AbstractViewControllerManager}
  */
 public interface ViewControllerExecutor
 {

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerNameMapper.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerNameMapper.java?rev=592546&r1=592545&r2=592546&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerNameMapper.java
(original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/ViewControllerNameMapper.java
Tue Nov  6 12:43:00 2007
@@ -21,8 +21,13 @@
 package org.apache.myfaces.orchestra.viewController;
 
 /**
- * <p>The interface for the name mapper.</p>
- * <p>A mapper is responsible for converting a viewId to a managed bean name</p>
+ * Convert the identifier of a view to the name of a bean that should
+ * handle lifecycle events for that view.
+ * <p>
+ * TODO: should this class have the same warning as ViewControllerExecutor,
+ * and an equivalent abstract base class?
+ * 
+ * @See {@link org.apache.myfaces.orchestra.viewController.AbstractViewControllerManager}
  */
 public interface ViewControllerNameMapper
 {



Mime
View raw message