org.apache.shale.view
Interface ViewController

All Known Implementing Classes:

AbstractViewController

public interface ViewController

ViewController is a "backing bean" interface which adds several extension points to the standard JavaServer Faces lifecycle. The extension points help Shale interact with JSF UIComponents.

A "backing bean" represents a convenient place to retrieve and store dynamic values associated with the user interface components that comprise the view, as well as to code event handlers triggered by state changes on those components. A JavaServer Faces view is most often a JSP page, but any JSF view rendering system can be used.

Essentially, the ViewController is a View Helper interface for a backing bean and its associated View.

NOTE - JavaServer Faces imposes no restrictions on the inheritance hierarchy (or interface implementation) for backing beans associated with a view. Therefore, the use of this interface for your own backing beans is entirely optional. That being said, having your backing beans implement this interface (typically by extending AbstractViewController) will receive the benefit of the extra services described by this interface, all of which will be provided automatically.

To be useful, the ViewController must be plugged into the application lifecycle through a custom JSF ViewHandler, like the ViewViewHandler.

Registering a ViewController backing bean

For each JSF view that you wish to associate with a ViewController backing bean, you must do the following:

• First, as required by the JavaBeans specification, be sure to provide a public no-args constructor in your ViewController backing bean implementation class. Configuration of ViewController beans is performed using setter injection, rather than through "rich" constructors.
• In order for Shale to properly locate the ViewController for a particular JSF view, you must register your implementation class in a JSF <managed-bean> element, using a <managed-bean-name> value that can be mapped from the view identifier. The actual mapping is performed by an instance of ViewControllerMapper configured for your application. If no special configuration is done, DefaultViewControllerMapper is used by default. See the Javadocs for that class to see what mapping rules are applied, and examples of correct managed bean names that correspond to particular JSF view identifiers.

  WARNING - if your managed bean name does not match the required mapping rules, it will function as a standard JSF backing bean, but none of the extra ViewController event handling methods will be called.

• Under nearly all circumstances, you will want to register this managed bean to be stored in request scope, so that its lifetime matches the corresponding view.
• Optionally, you may use <managed-property> elements within the <managed-bean> element to configure the behavior of your ViewController bean.

Since the ViewController is a backing bean, you have the option of establishing other links with the UIComponents, such as:

• You may use the binding property of any JSF UIComponent to establish a linkage between a component instance in the component tree representing this view, and a propery (of type UIComponent or an appropriate subclass) in your backing bean. This technique is useful if you need to programmatically manipulate properties of the corresponding component in an event handler in the backing bean.
• You may use the value property of any JSF component that implements ValueHolder (for example, any component based on UIInput or UIOutput) to establish a linkage between the dynamic value to be rendered or stored, and a property (of some appropriate type relevant to the model tier of your application) in your backing bean. This technique is convenient if you are primarily interested in manipulating the values to be rendered or stored, and/or you wish to leverage JSF's support for implicit registration of a Converter.

ViewController Lifecycle

Once you have configured the use of a ViewController backing bean associated with a JSF view, Shale will provide the following services:

• Whenever a JSF view with the appropriate view identifier is created or restored, an appropriate instance of the corresponding ViewController class will be created via the managed beans facility (if such a bean does not already exist), using a key derived from the ViewControllerMapper for this application. As a side effect, property setters wil be called for any <managed-property> configuration you have specified.
• Prior to any other method calls, the following additional property setters will be called:
  • setPostBack() will be called with a flag indicating whether this backing bean was created as result of a "post back" (i.e. to handle an HTTP request submitted by the client) or as a result of navigating to a different page.
• The init() method will be called, allowing the backing bean to acquire data from the model tier as needed to prepare for execution of the JSF request processing lifecycle for this view.
• For a restored view (i.e. where the postBack property was set to true, the preprocess() method will be called after the component tree has been restored by the Restore View phase. This method will not be called for a view that will only be rendered.
• For a restored view, standard JSF processing and event handling occurs for the Apply Request Values through Invoke Application phases of the request processing lifecycle. As a side effect, it is possible that navigation to a different view will have occurred. In this case, the corresponding ViewController for the new view will have been instantiated, and its init() method will have been called, as described above.
• For the ViewController whose view will be rendered, the prerender() method will be called. If your ViewController performed navigation to a different view, this method will NOT be called on the original view; however, it will be called on the ViewController instance for the page that was navigated to.
• The destroy() method will be called, allowing the backing bean to clean up any resources that it has allocated before processing for this HTTP request is completed. In the case where navigation has occurred, this call will take place on both ViewController instances that have been initialized.

$Id: ViewController.java 464373 2006-10-16 04:21:54Z rahul $

Method Summary

void	destroy() Called after the JSF request processing lifecycle has been completed for the current request.
void	init() Called after this ViewController has been instantiated, and after all of the property setters specified above have been called, but before the JSF request processing lifecycle processing and events related to our corresponding view are executed.
boolean	isPostBack() Return a flag indicating whether this request is a "post back" (that is, the view was restored in order to respond to a submit from the client), or a newly created view.
void	preprocess() Called after the component tree has been restored (in Restore View phase), if the current request is a postback.
void	prerender() Called before the Render Response processing for this request is performed, whether or not this is a post back request.
void	setPostBack(boolean postBack) Set a flag indicating whether this request is a "post back" (that is, the view was restored in order to respond to a submit from the client), or a newly created view.

Method Detail

isPostBack

boolean isPostBack()

Return a flag indicating whether this request is a "post back" (that is, the view was restored in order to respond to a submit from the client), or a newly created view. This method must return any value passed to the setPostBack() method.

setPostBack

void setPostBack(boolean postBack)

Set a flag indicating whether this request is a "post back" (that is, the view was restored in order to respond to a submit from the client), or a newly created view.

Parameters:

postBack - true for a post back request, or false for a newly created request

destroy

void destroy()

Called after the JSF request processing lifecycle has been completed for the current request. This allows a ViewController to clean up any resources it has allocated (perhaps during earlier execution of the init() method).

init

void init()

Called after this ViewController has been instantiated, and after all of the property setters specified above have been called, but before the JSF request processing lifecycle processing and events related to our corresponding view are executed. Within this method, you may consult the isPostBack() method to vary the initialization behavior based on whether a post back is being processed or not.

preprocess

void preprocess()

Called after the component tree has been restored (in Restore View phase), if the current request is a postback. If this view is only going to be rendered (because of either direct navigation, or because this view was navigated to from a different view), this method will NOT be called. As such, this method makes a good place to acquire information from your model tier that will be required during the execution of the Apply Request Values through Invoke Application phases of the request processing lifecycle.

prerender

void prerender()

Called before the Render Response processing for this request is performed, whether or not this is a post back request. This method will be called only for the view that will actually be rendered. For example, it will not be called if you have performed navigation to a different view. As such, it makes a good place to acquire information from your model tier that is required to complete this view's presentation.