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 JSF RESTORE_VIEW phase. - preProcess
This event will be fired before the JSF INVOKE_APPLICATION phase. - preRenderView
This event will be fired before the JSF PRE_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)
The ReflectiveViewControllerExecutor uses reflection to lookup the following public methods: initView, preRenderView, preProcess.
All of the methods are optional. - InterfaceViewControllerExecutor
The InterfaceViewControllerExecutor requires you to implement the org.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.