View Controller
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.
Using the Orchestra ViewController gives some very convenenient facilities.
Methods in your code can be invoke when the following events occur:
- initView
This event will be fired after the JSFRESTORE_VIEW
phase. - preProcess
This event will be fired before the JSFINVOKE_APPLICATION
phase. - preRenderView
This event will be fired before the JSFPRE_RENDER
phase.
The ViewController concept is also the base for the core15 annotation
@ConversationRequire
which allows you to issue a redirect if a
conversation times-out during a wizard-style pageflow.
Your view controller bean (the object on which callback methods are invoked) must be configured as a managed bean (eg as a Spring bean).
Installation
There are several parts to managing ViewControllers; the ViewControllerManager handles the following tasks:
- Choosing which object to invoke methods on (ViewControllerNameMapper)
- Choosing which methods to invoke (ViewControllerExecutor)
- Choosing when to invoke them
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.
ViewControllerNameMapper
The default ViewControllerNameMapper maps a viewId to a bean-name as follows:
- Convert each character after a "/" to upper-case
- Remove any occurence of the "/" character
- Stop at the first "." character and remove the rest
- Prefix with a "_" character if the result is a reserved word or an invalid bean name
View-Id | Bean name |
---|---|
mainform.jsp | mainform |
userData/password.jsp | userDataPassword |
requestScope.jsp | _requestScope |
123set.jsp | _123set |
If no bean exists with a name that matches the computed bean-name, then no lifecycle events are invoked for that view.
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.
ViewControllerExecutor
The default ViewControllerExecutor is a CompositeViewControllerExecutor which combines the functionality of the following classes:
- ReflectiveViewControllerExecutor (default)
TheReflectiveViewControllerExecutor
uses reflection to lookup the following public methods: initView, preRenderView, preProcess.
All of the methods are optional. - InterfaceViewControllerExecutor
TheInterfaceViewControllerExecutor
requires you to implement theorg.apache.myfaces.orchestra.viewController.ViewController
interface.
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.
AnnotationsViewControllerNameMapper
To work with the AnnotationsViewController
you have to use the core15
module. Once you added the jar to your classpath and configured the
required import
statement
in your configuration file you are done.
The biggest advantage of AnnotationsViewControllerNameMapper
is that you
do not have to follow any bean-naming scheme. Just annotate your managed-bean with the
@ViewController
annotation.
Example:
@ViewController( viewIds={"/annotations/Page1.jsp", "/annotations/Page2.jsp", "/annotations/Page3.jsp"}) public class MultiViewController
This configuration means that the class MultiViewController
is responsible
for the three configured pages and will receive the lifecycle method callbacks.
AnnotationsViewControllerExecutor
The AnnotationsViewControllerExecutor
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.
The available annotations are:
- @InitView
- @PreProcess
- @PreRenderView
Comparison with the Apache Shale ViewController
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.
The Orchestra implementation currently lacks the ability for f:subview pages to have their own view-controller.