Author: husted Date: Fri Oct 29 03:49:44 2004 New Revision: 55962 Modified: struts/trunk/contrib/struts-shale/src/java/org/apache/shale/ViewController.java Log: Javadoc change only: Minor stylistic changes to help clarify how ViewController integrates with the JSF lifecycle.
Modified: struts/trunk/contrib/struts-shale/src/java/org/apache/shale/ViewController.java ============================================================================== --- struts/trunk/contrib/struts-shale/src/java/org/apache/shale/ViewController.java (original) +++ struts/trunk/contrib/struts-shale/src/java/org/apache/shale/ViewController.java Fri Oct 29 03:49:44 2004 @@ -17,17 +17,22 @@ package org.apache.shale; /** - * <p>[EMAIL PROTECTED] ViewController} is an interface describing a JavaBean that is - * associated with a JavaServer Faces <em>view</em> (typically a JSP page). - * Such a "backing bean" represents a convenient place to retrieve and store + * <p>[EMAIL PROTECTED] ViewController} is a "backing bean" interface which adds several + * extension points to the standard JavaServer Faces lifecycle. The extension + * points help Struts interact with JSF <code>UIComponents</code>. + * </p> + * <p> + * 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 code event handlers triggered by state changes on - * those components. As such, this interface describes an implementation of the + * the view, as well as to code event handlers triggered by state changes on + * those components. A JavaServer Faces <em>view</em> is most often a JSP page, + * but any JSF view rendering system can be used. + * </p> + * <p> + * Essentially, the ViewController is a * <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/ViewHelper.html";> - * View Helper</a> design pattern from - * <a href="http://java.sun.com/blueprints/corej2eepatterns/";>Core J2EE - * Patterns</a>.</p> - * + * View Helper</a> interface for a backing bean and its associated View. + * </p> * <p><strong>NOTE</strong> - 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 @@ -36,15 +41,21 @@ * [EMAIL PROTECTED] org.apache.shale.view.AbstractViewController}) will receive the * benefit of the extra services described by this interface, all of which will be * provided automatically.</p> + * <p> + * To be useful, the ViewController must be plugged into the application + * lifecycle through a custom JSF ViewHandler, like the + * [EMAIL PROTECTED] org.apache.shale.faces.ShaleViewHandler ShaleViewHandler}. + * </p> * - * <h3>Using a [EMAIL PROTECTED] ViewController}</h3> + * <h3>Registering a ViewController backing bean</h3> * - * <p>For each JSF view that you wish to associate with a [EMAIL PROTECTED] ViewController} + * <p>For each JSF view that you wish to associate with a ViewController * backing bean, you must do the following:</p> * <ul> - * <li>As required by the JavaBeans specification, provide a public no-args - * constructor in your backing bean implementation class. Configuration - * of [EMAIL PROTECTED] ViewController} beans is performed using setter injection.</li> + * <li>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.</li> * <li>Register this class as a JSF <code><managed-bean></code>, * using a <code><managed-bean-name></code> that corresponds to * the <code>view identifier</code> of the JSF view. Mapping between @@ -56,16 +67,22 @@ * matches the corresponding view.</li> * <li>Optionally, you may use <code><managed-property></code> * elements within the <code><managed-bean></code> element - * to configure the behavior of your backing bean.</li> + * to configure the behavior of your ViewController bean.</li> * </ul></li> - * <li>Optionally, you may use the <code>binding</code> property of any JSF + * </ul> + * + * <p>Since the ViewController is a backing bean, you have the option of + * establishing other links with the UIComponents, such as:</p> + * + * <ul> + * <li>You may use the <code>binding</code> property of any JSF * <code>UIComponent</code> to establish a linkage between a component * instance in the component tree representing this view, and a propery * (of type <code>UIComponent</code> 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.</li> - * <li>Optionally, you may use the <code>value</code> property of any JSF + * <li>You may use the <code>value</code> property of any JSF * component that implements <code>ValueHolder</code> (for example, any * component based on <code>UIInput</code> or <code>UIOutput</code>) to * establish a linkage between the dynamic value to be rendered or stored, @@ -76,7 +93,7 @@ * implicit registration of a <code>Converter</code>.</li> * </ul> * - * <h3>Services Provided To A [EMAIL PROTECTED] ViewController}</h3> + * <h3>ViewController Lifecycle</h3> * * <p>Once you have configured the use of a [EMAIL PROTECTED] ViewController} backing bean * associated with a JSF view, Struts will provide the following services:</p> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
