Author: craigmcc Date: Fri Jul 29 23:24:50 2005 New Revision: 226477 URL: http://svn.apache.org/viewcvs?rev=226477&view=rev Log: Implement some now-or-never refactorings that are required. Principally: * org.apache.shale.ViewController --> org.apache.shale.view.ViewController * org.apache.shale.ViewControllerMapper --> org.apache.shale.view.ViewControllerMapper * org.apache.shale.view.DefaultViewControllerMapper --> org.apache.shale.view.impl.DefaultViewControllerMapper
These changes isolate all of the "view controller" related APIs supported by Shale into the "org.apache.shale.view" package. Added: struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewController.java struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewControllerMapper.java struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/ struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/DefaultViewControllerMapper.java Removed: struts/shale/trunk/core-library/src/java/org/apache/shale/ViewController.java struts/shale/trunk/core-library/src/java/org/apache/shale/ViewControllerMapper.java struts/shale/trunk/core-library/src/java/org/apache/shale/view/DefaultViewControllerMapper.java Modified: struts/shale/trunk/clay-plugin/src/java/org/apache/shale/clay/faces/ClayViewHandler.java struts/shale/trunk/core-library/src/java/org/apache/shale/component/Subview.java struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleApplicationFilter.java struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleConstants.java struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShalePhaseListener.java struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleViewHandler.java struts/shale/trunk/core-library/src/java/org/apache/shale/package.html struts/shale/trunk/core-library/src/java/org/apache/shale/view/AbstractViewController.java struts/shale/trunk/core-library/src/java/org/apache/shale/view/package.html Modified: struts/shale/trunk/clay-plugin/src/java/org/apache/shale/clay/faces/ClayViewHandler.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/clay-plugin/src/java/org/apache/shale/clay/faces/ClayViewHandler.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/clay-plugin/src/java/org/apache/shale/clay/faces/ClayViewHandler.java (original) +++ struts/shale/trunk/clay-plugin/src/java/org/apache/shale/clay/faces/ClayViewHandler.java Fri Jul 29 23:24:50 2005 @@ -32,12 +32,12 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.apache.shale.ViewController; -import org.apache.shale.ViewControllerMapper; import org.apache.shale.clay.component.Clay; import org.apache.shale.clay.config.Globals; import org.apache.shale.faces.ShaleConstants; -import org.apache.shale.view.DefaultViewControllerMapper; +import org.apache.shale.view.ViewController; +import org.apache.shale.view.ViewControllerMapper; +import org.apache.shale.view.impl.DefaultViewControllerMapper; /** * <p>This <code>ViewHandler</code> will handle full HTML template views using the Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/component/Subview.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/component/Subview.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/component/Subview.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/component/Subview.java Fri Jul 29 23:24:50 2005 @@ -27,7 +27,7 @@ import javax.faces.event.PhaseId; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.apache.shale.ViewController; +import org.apache.shale.view.ViewController; import org.apache.shale.faces.ShaleConstants; import org.apache.shale.faces.ShalePhaseListener; import org.apache.shale.faces.ShaleViewHandler; Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleApplicationFilter.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleApplicationFilter.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleApplicationFilter.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleApplicationFilter.java Fri Jul 29 23:24:50 2005 @@ -41,7 +41,7 @@ import org.apache.commons.chain.web.servlet.ServletWebContext; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.apache.shale.ViewControllerMapper; +import org.apache.shale.view.ViewControllerMapper; import org.apache.shale.util.Messages; @@ -379,7 +379,7 @@ String className = context.getInitParameter(VIEW_CONTROLLER_MAPPER); if (className == null) { - className = "org.apache.shale.view.DefaultViewControllerMapper"; + className = "org.apache.shale.view.impl.DefaultViewControllerMapper"; } ClassLoader cl = Thread.currentThread().getContextClassLoader(); if (cl == null) { Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleConstants.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleConstants.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleConstants.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleConstants.java Fri Jul 29 23:24:50 2005 @@ -16,8 +16,8 @@ package org.apache.shale.faces; -import org.apache.shale.ViewController; -import org.apache.shale.ViewControllerMapper; +import org.apache.shale.view.ViewController; +import org.apache.shale.view.ViewControllerMapper; import org.apache.shale.util.TokenProcessor; Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShalePhaseListener.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShalePhaseListener.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShalePhaseListener.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShalePhaseListener.java Fri Jul 29 23:24:50 2005 @@ -18,7 +18,7 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.apache.shale.ViewController; +import org.apache.shale.view.ViewController; import javax.faces.event.PhaseEvent; import javax.faces.event.PhaseId; Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleViewHandler.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleViewHandler.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleViewHandler.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/faces/ShaleViewHandler.java Fri Jul 29 23:24:50 2005 @@ -18,8 +18,8 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -import org.apache.shale.ViewController; -import org.apache.shale.ViewControllerMapper; +import org.apache.shale.view.ViewController; +import org.apache.shale.view.ViewControllerMapper; import javax.faces.FacesException; import javax.faces.application.ViewHandler; Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/package.html URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/package.html?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/package.html (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/package.html Fri Jul 29 23:24:50 2005 @@ -18,7 +18,7 @@ <body> -<p>This package defines the fundamental interfaces and manifest constants -for the overall controller architecture.</p> +<p>This package defines the localizable resources +for the overall Shale architecture.</p> </body> Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/view/AbstractViewController.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/AbstractViewController.java?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/view/AbstractViewController.java (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/view/AbstractViewController.java Fri Jul 29 23:24:50 2005 @@ -16,7 +16,7 @@ package org.apache.shale.view; -import org.apache.shale.ViewController; +import org.apache.shale.view.ViewController; /** * <p>[EMAIL PROTECTED] AbstractViewController} is a convenience base implementation of Added: struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewController.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewController.java?rev=226477&view=auto ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewController.java (added) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewController.java Fri Jul 29 23:24:50 2005 @@ -0,0 +1,222 @@ +/* + * Copyright 2004-2005 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.shale.view; + +/** + * <p>[EMAIL PROTECTED] 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 <code>UIComponent</code>s. + * </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 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> 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 + * backing beans is entirely optional. That being said, having your + * backing beans implement this interface (typically by extending + * [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>Registering a ViewController backing bean</h3> + * + * <p>For each JSF view that you wish to associate with a ViewController + * backing bean, you must do the following:</p> + * <ul> + * <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 + * <code>view id</code> and managed bean names will be performed by + * a [EMAIL PROTECTED] ViewControllerMapper} configured for this application. + * <ul> + * <li>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.</li> + * <li>Optionally, you may use <code><managed-property></code> + * elements within the <code><managed-bean></code> element + * to configure the behavior of your ViewController bean.</li> + * </ul></li> + * </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>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, + * 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 <em>values</em> to + * be rendered or stored, and/or you wish to leverage JSF's support for + * implicit registration of a <code>Converter</code>.</li> + * </ul> + * + * <h3>ViewController Lifecycle</h3> + * + * <p>Once you have configured the use of a [EMAIL PROTECTED] ViewController} backing bean + * associated with a JSF view, Shale will provide the following services:</p> + * <ul> + * <li>Whenever a JSF view with the appropriate <code>view identifier</code> + * is created or restored, an appropriate instance of the corresponding + * [EMAIL PROTECTED] ViewController} class will be created via the managed beans + * facility (if such a bean does not already exist), using a key derived + * from the [EMAIL PROTECTED] ViewControllerMapper} for this application. As a + * side effect, property setters wil be called for any + * <code><managed-property></code> configuration you have + * specified.</li> + * <li>Prior to any other method calls, the following additional property + * setters will be called: + * <ul> + * <li><code>setPostBack()</code> 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.</li> + * </ul></li> + * <li>The <code>init()</code> 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.</li> + * <li>For a restored view (i.e. where the <code>postBack</code> property + * was set to <code>true</code>, the <code>preprocess()</code> method will + * be called after the component tree has been restored by the + * <em>Restore View</em> phase. This method will <strong>not</strong> + * be called for a view that will only be rendered.</p> + * <li>For a restored view, standard JSF processing and event handling occurs + * for the <em>Apply Request Values</em> through <em>Invoke Application</em> + * 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 <code>ViewController</code> for the new + * view will have been instantiated, and its <code>init()</code> method + * will have been called, as described above.</li> + * <li>For the <code>ViewController</code> whose view will be rendered, the + * <code>preprocess()</code> method will be called. If your + * <code>ViewController</code> performed navigation to a different view, + * this method will <strong>NOT</strong> be called on the original view; + * however, it will be called on the <code>ViewController</code> instance + * for the page that was navigated to.</li> + * <li>The <code>destroy()</code> 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 <code>ViewController</code> + * instances that have been initialized.</li> + * </ul> + * + * $Id$ + */ + +public interface ViewController { + + + // -------------------------------------------------------------- Properties + + + /** + * <p>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 <code>setPostBack()</code> method.</p> + */ + public boolean isPostBack(); + + + /** + * <p>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.</p> + * + * @param postBack <code>true</code> for a post back request, or + * <code>false</code> for a newly created request + */ + public void setPostBack(boolean postBack); + + + // ---------------------------------------------------------- Public Methods + + + /** + * <p>Called after the JSF request processing lifecycle has been completed + * for the current request. This allows a [EMAIL PROTECTED] ViewController} to clean + * up any resources it has allocated (perhaps during earlier execution of + * the <code>init()</code> method).</p> + */ + public void destroy(); + + + /** + * <p>Called after this [EMAIL PROTECTED] 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 <code>isPostBack()</code> method to vary the initialization + * behavior based on whether a post back is being processed or not.</p> + */ + public void init(); + + + /** + * <p>Called after the component tree has been restored (in <em>Restore + * View</em> 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 <strong>NOT</strong> 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 <em>Apply Request Values</em> through + * <em>Invoke Application</em> phases of the request processing lifecycle. + * </p> + */ + public void preprocess(); + + + /** + * <p>Called before the <em>Render Response</em> 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.</p> + */ + public void prerender(); + + +} Added: struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewControllerMapper.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewControllerMapper.java?rev=226477&view=auto ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewControllerMapper.java (added) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/view/ViewControllerMapper.java Fri Jul 29 23:24:50 2005 @@ -0,0 +1,42 @@ +/* + * Copyright 2004-2005 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.shale.view; + +/** + * <p>[EMAIL PROTECTED] ViewControllerMapper} is an interface describing a pluggable + * mechanism to map between a JavaServer Faces <em>view identifier</em> + * and the name of a corresponding <em>managed bean</em> that serves as + * the backing bean for this view. If the managed bean class implements + * [EMAIL PROTECTED] ViewController}, the services described in that interface will + * be provided by Struts.</p> + * + * $Id$ + */ + +public interface ViewControllerMapper { + + /** + * <p>Return the name of the managed bean that serves as the backing + * bean for the specified <code>view identifier</code>. If no such + * managed bean name can be determined, return <code>null</code>.</p> + * + * @param viewId View identifier for which to identify a backing bean + */ + public String mapViewId(String viewId); + + +} Added: struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/DefaultViewControllerMapper.java URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/DefaultViewControllerMapper.java?rev=226477&view=auto ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/DefaultViewControllerMapper.java (added) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/view/impl/DefaultViewControllerMapper.java Fri Jul 29 23:24:50 2005 @@ -0,0 +1,93 @@ +/* + * Copyright 2004-2005 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.shale.view.impl; + +import java.util.HashSet; +import java.util.Set; +import org.apache.shale.view.ViewControllerMapper; + +/** + * <p>[EMAIL PROTECTED] DefaultViewControllerMapper} is a default implementation of [EMAIL PROTECTED] ViewControllerMapper}. The following + * algorithm is implemented:</p> + * <ul> + * <li>Strip any leading slash ("/") character.</li> + * <li>Strip any traling extension (".xxx"), as long as it occurs + * after any remaining slash ("/") character.</li> + * <li>Convert each instance of a slash ("/") + * character into a dollar sign ("$") character.</li> + * <li>If the resulting name matches one of the reserved names recognized + * by the default <code>VariableResolver</code>, prefix it with an + * underscore character ("_"), to avoid problems loading managed beans.</li> + * </ul> + * + * $Id$ + */ + +public class DefaultViewControllerMapper implements ViewControllerMapper { + + + // -------------------------------------------------------- Static Variables + + + /** + * <p>Reserved variable names.</p> + */ + private static Set reserved = new HashSet(); + + static { + reserved.add("applicationScope"); + reserved.add("cookies"); + reserved.add("facesContext"); + reserved.add("header"); + reserved.add("headerValues"); + reserved.add("initParam"); + reserved.add("param"); + reserved.add("paramValues"); + reserved.add("requestScope"); + reserved.add("sessionScope"); + reserved.add("view"); + } + + + // ---------------------------------------------------------- Public Methods + + + // Specified by ViewControllerMapper + public String mapViewId(String viewId) { + + if (viewId == null) { + return null; + } + if (viewId.startsWith("/")) { + viewId = viewId.substring(1); + } + int slash = viewId.lastIndexOf("/"); + int period = viewId.lastIndexOf("."); + if ((period >= 0) && (period > slash)) { + viewId = viewId.substring(0, period); + } + viewId = viewId.replace('/', '$'); + if (reserved.contains(viewId)) { + return "_" + viewId; + } else { + return viewId; + } + + } + + +} Modified: struts/shale/trunk/core-library/src/java/org/apache/shale/view/package.html URL: http://svn.apache.org/viewcvs/struts/shale/trunk/core-library/src/java/org/apache/shale/view/package.html?rev=226477&r1=226476&r2=226477&view=diff ============================================================================== --- struts/shale/trunk/core-library/src/java/org/apache/shale/view/package.html (original) +++ struts/shale/trunk/core-library/src/java/org/apache/shale/view/package.html Fri Jul 29 23:24:50 2005 @@ -18,7 +18,7 @@ <body> -<p>This package defines base classes and implementations related to the -ViewController functionality provided by Shale.</p> +<p>This package defines fundamental interfaces and convenience base classes +related to the ViewController functionality provided by Shale.</p> </body> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]