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/11/06 21:43:01 UTC
svn commit: r592546 -
/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/viewController/
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
{