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 2008/02/27 14:20:36 UTC
svn commit: r631584 -
/myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
Author: skitching
Date: Wed Feb 27 05:20:35 2008
New Revision: 631584
URL: http://svn.apache.org/viewvc?rev=631584&view=rev
Log:
Tidy up ViewController documentation
Modified:
myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml?rev=631584&r1=631583&r2=631584&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml Wed Feb 27 05:20:35 2008
@@ -26,88 +26,63 @@
<body>
<section name="View Controller">
-
<p>
- The ViewController is just a concept which binds a specific bean to a web-page.
- In JSF this means, you have a managed bean configured which directly matches to a view-id.
+ The ViewController is just a concept which binds a specific bean to a web-page.
+ In JSF this means, you have a managed bean associated with each view.
+ Note however that the ViewController is not limited to JSF; any framework can take
+ advantage of it to cause lifecycle method callbacks to occur for each page.
</p>
<p>
- If you follow this concept you'll gain some very comfortable things. They are:
- <br />
- Notifications:
- <ul>
- <li>initView
- <br />
- This event will be fired after the JSF <code>RESTORE_VIEW</code> phase.
- </li>
- <li>preProcess
+ Using the Orchestra ViewController gives some very convenenient facilities.
+ </p>
+ <p>
+ Methods in your code can be invoke when the following events occur:
+ <ul>
+ <li>initView
+ <br />
+ This event will be fired after the JSF <code>RESTORE_VIEW</code> phase.
+ </li>
+ <li>preProcess
<br />
This event will be fired before the JSF <code>INVOKE_APPLICATION</code> phase.
</li>
- <li>preRenderView
+ <li>preRenderView
<br />
This event will be fired before the JSF <code>PRE_RENDER</code> phase.
- </li>
- </ul>
- The ViewController concept is also the base for the core15 annotation
- <code>@ConversationRequire</code> which allows you to issue a redirect if a
- conversations timed-out in the mid of a e.g. wizzard style pageflow.
- <br />
- <br />
- <b>Notice:</b> Your view controller bean has to be configured inside the spring-configuration file.
-
+ </li>
+ </ul>
+ </p>
+ <p>
+ The ViewController concept is also the base for the core15 annotation
+ <code>@ConversationRequire</code> which allows you to issue a redirect if a
+ conversation times-out during a wizard-style pageflow.
+ </p>
+ <p>
+ Your view controller bean (the object on which callback methods are invoked) must
+ be configured as a managed bean (eg as a Spring bean).
</p>
<subsection name="Installation">
-
<p>
- In a JSF environment Orchestra already configures the JSF system in a way which allows
- you to start using this concept.
- This has been done by installing the PhaseListener
- <code>org.apache.myfaces.orchestra.viewController.jsf.ViewControllerPhaseListener</code>.
- <br/>
- However, there is a way which allows you to adjust the configuration as required.
- </p>
- <p>
- To make the ViewController work you need to have two things:
- <ul>
- <li>A NameMapper (org.apache.myfaces.orchestra.viewController.ViewControllerNameMapper)
- <br/>
- The NameMapper is responsible to build a managed-bean name out of the view-id.
- </li>
- <li>An Executor (org.apache.myfaces.orchestra.viewController.AbstractViewControllerExecutor)
- <br/>
- The Executor finally will invoke some methods on this managed-bean then
- (if there is a bean with the mapped name).
- </li>
- </ul>
-
- Both things will be used by the
- <code>ViewControllerManager</code>. Now, if you are in need
- of a custom name mapping scheme, just create jour own
- <code>ViewControllerManager</code> by inheriting from the
- <code>org.apache.myfaces.orchestra.viewController.AbstractViewControllerManager</code>
- class. Two methods you have to implement allow you to provide custom implementations for the
- <code>>NameMapper</code> and the <code>Executor</code>.
- <br/>
- Finally you have to configure your implementation by adding an bean definition with the name
- <code>org.apache.myfaces.orchestra.viewController.ViewControllerManager</code>. For example:
- <pre>
-<bean
- name="org.apache.myfaces.orchestra.viewController.ViewControllerManager"
- class="your.package.YourViewController"
- scope="singleton">
-
-</bean>
- </pre>
-
+ There are several parts to managing ViewControllers; the ViewControllerManager handles
+ the following tasks:
+ <ul>
+ <li>Choosing which object to invoke methods on (ViewControllerNameMapper)</li>
+ <li>Choosing which methods to invoke (ViewControllerExecutor)</li>
+ <li>Choosing when to invoke them</li>
+ </ul>
+ </p>
+ <p>
+ In a JSF environment, the default ViewControllerManager is set up with behaviour that
+ should suit most users. However this can be customised if the defaults do not suit.
+ See the javadoc documentation for the ViewControllerManager and related classes
+ for details on how to customise configuration.
</p>
-
</subsection>
- <subsection name="DefaultViewControllerNameMapper">
- There is a default NameMapper which will be used if you do not provide your own.
- The mapping will be as follows:
+ <subsection name="ViewControllerNameMapper">
+ <p>
+ The default ViewControllerNameMapper maps a viewId to a bean-name as follows:
<ul>
<li>Convert each character after a "/" to upper-case</li>
<li>Remove any occurence of the "/" character</li>
@@ -137,63 +112,99 @@
<td>_123set</td>
</tr>
</table>
+ </p>
+ <p>
+ If no bean exists with a name that matches the computed bean-name, then no lifecycle
+ events are invoked for that view.
+ </p>
+ <p>
+ When the Orchestra core15 module is in the classpath, then annotations can also
+ be used to specify that a bean is a ViewController for a specific view. See the
+ section on the AnnotationsViewControllerNameMapper for details.
+ </p>
</subsection>
- <subsection name="ViewControllerExecutor (AbstractViewControllerExecutor)">
- The ViewControllerExecutor is responsible to invoke the notification methods on your
- managed-bean.<br />
- Currently the Orchestra standard provides the following methods:
+ <subsection name="ViewControllerExecutor">
+ <p>
+ The default ViewControllerExecutor is a CompositeViewControllerExecutor which combines
+ the functionality of the following classes:
<ul>
<li>ReflectiveViewControllerExecutor (default)
- <br />
+ <br />
The <code>ReflectiveViewControllerExecutor</code> uses reflection to lookup the
following public methods: initView, preRenderView, preProcess. <br />
All of the methods are optional.
</li>
<li>InterfaceViewControllerExecutor
- <br />
+ <br />
The <code>InterfaceViewControllerExecutor</code> requires you to implement the
<code>org.apache.myfaces.orchestra.viewController.ViewController</code> interface.
</li>
- <li>AnnotationsViewControllerExecutor (core15)
- <br />
- The <code>AnnotationsViewControllerExecutor</code> might be the most powerful one.
- It allows you to configure a managed bean as view controller without following any
- naming scheme. Not for the bean name nor for the method name.<br />
- This is a feature of the core15 module.
- </li>
</ul>
- Again, you have to configure a custom <code>ViewControllerManager</code> if you
- do not want the default <code>ReflectiveViewControllerExecutor</code>.<br />
+ </p>
+ <p>
+ When the Orchestra core15 module is in the classpath, then annotations can also
+ be used to specify which methods on a bean should be invoked to handle lifecycle
+ events. See the section on the AnnotationsViewControllerExecutor for details.
+ </p>
</subsection>
- <subsection name="AnnotationsViewController">
+ <subsection name="AnnotationsViewControllerNameMapper">
+ <p>
To work with the <code>AnnotationsViewController</code> you have to use the core15
module. Once you added the jar to your classpath and configured the
<a href="installation.html">required import</a> statement
in your configuration file you are done.
- <br />
- The biggest advantage the <code>AnnotationsViewController</code> provides is, that you do
- not have to follow any naming scheme. Just annotate your managed-bean with the
+ </p>
+ <p>
+ The biggest advantage of <code>AnnotationsViewControllerNameMapper</code> is that you
+ do not have to follow any bean-naming scheme. Just annotate your managed-bean with the
<code>@ViewController</code> annotation.
- <br />
+ </p>
+ <p>
Example:
<pre>
@ViewController(
viewIds={"/annotations/Page1.jsp", "/annotations/Page2.jsp", "/annotations/Page3.jsp"})
public class MultiViewController
-{
- </pre>
- Which means the class <code>MultiViewController</code> is responsible for the three
- configured pages and will receive the notification to the methods annotated with the
+ </pre>
+ </p>
+ <p>
+ This configuration means that the class <code>MultiViewController</code> is responsible
+ for the three configured pages and will receive the lifecycle method callbacks.
+ </p>
+ </subsection>
+
+ <subsection name="AnnotationsViewControllerExecutor">
+ <p>
+ The <code>AnnotationsViewControllerExecutor</code> allows the methods to be
+ invoked to be marked via annotations. The methods can then have any name, and
+ the bean on which they exist does not need to implement any specific interface.
+ This is a feature of the core15 module, and is automatically enabled if the
+ Orchestra core15 library is in the classpath.
+ </p>
+ <p>
+ The available annotations are:
<ul>
<li>@InitView</li>
<li>@PreProcess</li>
<li>@PreRenderView</li>
</ul>
- annotation.
+ </p>
</subsection>
+ <subsection name="Comparison with the Apache Shale ViewController">
+ <p>
+ The ViewController concept in Orchestra was inspired by the Apache Shale ViewController,
+ and is very similar. Unfortunately the Shale version could not be used directly in
+ Orchestra; it is hoped that at some time in the future the two implementations can
+ be unified in some manner.
+ </p>
+ <p>
+ The Orchestra implementation currently lacks the ability for f:subview pages to have
+ their own view-controller.
+ </p>
+ </subsection>
</section>
</body>
</document>