Java tutorial
/* * Copyright 2002-2007 the original author or authors. * * 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.springframework.web.servlet.mvc.generic; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.http.HttpSession; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.ui.ModelMap; import org.springframework.util.Assert; import org.springframework.validation.BindingResult; import org.springframework.web.HttpSessionRequiredException; import org.springframework.web.bind.ServletRequestDataBinder; import org.springframework.web.bind.support.WebBindingInitializer; import org.springframework.web.context.request.ServletWebRequest; import org.springframework.web.servlet.ModelAndView; import org.springframework.web.servlet.mvc.Controller; /** * @author Juergen Hoeller */ public abstract class GenericFormController<T> implements Controller { /** Logger that is available to subclasses */ protected final Log logger = LogFactory.getLog(getClass()); private WebBindingInitializer webBindingInitializer; /** * Specify a WebBindingInitializer which will apply pre-configured * configuration to every DataBinder that this controller uses. * <p>Allows for factoring out the entire binder configuration * to separate objects, as an alternative to {@link #initBinder}. */ public void setWebBindingInitializer(WebBindingInitializer webBindingInitializer) { this.webBindingInitializer = webBindingInitializer; } /** * Handles two cases: form submissions and showing a new form. * Delegates the decision between the two to {@link #isFormSubmission}, * always treating requests without existing form session attribute * as new form when using session form mode. * @see #isFormSubmission * @see #showNewForm * @see #processFormSubmission */ public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) throws Exception { // Form submission or new form to show? if (isFormSubmission(request)) { // Fetch form object from HTTP session, bind, validate, process submission. try { return processFormSubmission(request); } catch (HttpSessionRequiredException ex) { // Cannot submit a session form if no form object is in the session. if (logger.isDebugEnabled()) { logger.debug("Invalid submit detected: " + ex.getMessage()); } return handleInvalidSubmit(request); } } else { // New form to show: render form view. return showNewForm(request); } } /** * Determine if the given request represents a form submission. * <p>The default implementation treats a POST request as form submission. * Note: If the form session attribute doesn't exist when using session form * mode, the request is always treated as new form by handleRequestInternal. * <p>Subclasses can override this to use a custom strategy, e.g. a specific * request parameter (assumably a hidden field or submit button name). * @param request current HTTP request * @return if the request represents a form submission */ protected boolean isFormSubmission(HttpServletRequest request) { return "POST".equals(request.getMethod()); } /** * Return the name of the HttpSession attribute that holds the form object * for this form controller. * <p>Default is an internal name, of no relevance to applications, as the form * session attribute is not usually accessed directly. Can be overridden to use * an application-specific attribute name, which allows other code to access * the session attribute directly. * @param request current HTTP request * @return the name of the form session attribute * @see #getFormSessionAttributeName * @see javax.servlet.http.HttpSession#getAttribute */ protected String getFormSessionAttributeName(HttpServletRequest request) { return getClass().getName() + ".FORM." + getFormObjectName(request); } /** * Show a new form. Prepares a backing object for the current form * and the given request, including checking its validity. * @param request current HTTP request * @return the prepared form view * @throws Exception in case of an invalid new form object */ protected final ModelAndView showNewForm(HttpServletRequest request) throws Exception { logger.debug("Displaying new form"); // Create form-backing object for new form. T formObject = formBackingObject(request); Assert.state(formObject != null, "Form object returned by formBackingObject() must not be null"); // Bind without validation, to allow for prepopulating a form, and for // convenient error evaluation in views (on both first attempt and resubmit). ServletRequestDataBinder binder = createBinder(request, formObject); binder.bind(request); BindingResult bindingResult = binder.getBindingResult(); onBind(request, formObject, bindingResult); return showForm(request, bindingResult); } protected ServletRequestDataBinder createBinder(HttpServletRequest request, T formObject) throws Exception { ServletRequestDataBinder binder = new ServletRequestDataBinder(formObject, getFormObjectName(request)); initBinder(request, binder); return binder; } /** * Initialize the given binder instance, for example with custom editors. * Called by {@link #createBinder}. * <p>This method allows you to register custom editors for certain fields of your * formObject class. For instance, you will be able to transform Date objects into a * String pattern and back, in order to allow your JavaBeans to have Date properties * and still be able to set and display them in an HTML interface. * <p>The default implementation is empty. * @param request current HTTP request * @param binder the new binder instance * @throws Exception in case of invalid state or arguments * @see #createBinder * @see org.springframework.validation.DataBinder#registerCustomEditor * @see org.springframework.beans.propertyeditors.CustomDateEditor */ protected void initBinder(HttpServletRequest request, ServletRequestDataBinder binder) throws Exception { if (this.webBindingInitializer != null) { this.webBindingInitializer.initBinder(binder, new ServletWebRequest(request)); } } /** * Bind the parameters of the given request to the given form object. * @param request current HTTP request * @param formObject the object to bind onto * @throws Exception in case of invalid state or arguments */ protected void onBind(HttpServletRequest request, T formObject, BindingResult bindingResult) throws Exception { } /** * Return the form object for the given request. * <p>Calls {@link #formBackingObject} if not in session form mode. * Else, retrieves the form object from the session. Note that the form object * gets removed from the session, but it will be re-added when showing the * form for resubmission. * @param request current HTTP request * @return object form to bind onto * @throws org.springframework.web.HttpSessionRequiredException * if a session was expected but no active session (or session form object) found * @throws Exception in case of invalid state or arguments * @see #formBackingObject */ protected T currentFormObject(HttpServletRequest request) throws Exception { // Session-form mode: retrieve form object from HTTP session attribute. HttpSession session = request.getSession(false); if (session == null) { throw new HttpSessionRequiredException("Must have session when trying to bind (in session-form mode)"); } String formAttrName = getFormSessionAttributeName(request); T sessionFormObject = (T) session.getAttribute(formAttrName); if (sessionFormObject == null) { throw new HttpSessionRequiredException("Form object not found in session (in session-form mode)"); } // Remove form object from HTTP session: we might finish the form workflow // in this request. If it turns out that we need to show the form view again, // we'll re-bind the form object to the HTTP session. if (logger.isDebugEnabled()) { logger.debug("Removing form session attribute [" + formAttrName + "]"); } session.removeAttribute(formAttrName); return sessionFormObject; } /** * Prepare model and view for the given form, including reference and errors, * adding a controller-specific control model. * <p>In session form mode: Re-puts the form object in the session when returning * to the form, as it has been removed by getCommand. * <p>Can be used in subclasses to redirect back to a specific form page. * @param request current HTTP request * @param bindingResult validation errors holder * @return the prepared form view */ protected final ModelAndView showForm(HttpServletRequest request, BindingResult bindingResult) { // In session form mode, re-expose form object as HTTP session attribute. // Re-binding is necessary for proper state handling in a cluster, // to notify other nodes of changes in the form object. String formAttrName = getFormSessionAttributeName(request); if (logger.isDebugEnabled()) { logger.debug("Setting form session attribute [" + formAttrName + "] to: " + bindingResult.getTarget()); } request.getSession().setAttribute(formAttrName, bindingResult.getTarget()); // Fetch errors model as starting point, containing form object under // "formObjectName", and corresponding Errors instance under internal key. ModelMap model = new ModelMap().addAllAttributes(bindingResult.getModel()); // Merge reference data into model, if any. populateModel(request, model, bindingResult); // Trigger rendering of the specified view, using the final model. return new ModelAndView(getFormView(request), model); } /** * Populate the model map for the given request, consisting of * key-value pairs that will be exposed as model attributes to the view. * <p>The default implementation is empty. * Subclasses can override this to expose reference data used in the view. * @param request current HTTP request * @param model the ModelMap to populate * @param bindingResult validation errors holder * @see ModelAndView */ protected void populateModel(HttpServletRequest request, ModelMap model, BindingResult bindingResult) { } /** * Handle an invalid submit request, e.g. when in session form mode but no form object * was found in the session (like in case of an invalid resubmit by the browser). * <p>The default implementation simply tries to resubmit the form with a new * form object. This should also work if the user hit the back button, changed * some form data, and resubmitted the form. * <p>Note: To avoid duplicate submissions, you need to override this method. * Either show some "invalid submit" message, or call {@link #showNewForm} for * resetting the form (prepopulating it with the current values if "bindOnNewForm" * is true). In this case, the form object in the session serves as transaction token. * <pre> * protected ModelAndView handleInvalidSubmit(HttpServletRequest request) throws Exception { * return showNewForm(request); * }</pre> * You can also show a new form but with special errors registered on it: * <pre class="code"> * protected ModelAndView handleInvalidSubmit(HttpServletRequest request) throws Exception { * BindingResult bindingResult = getErrorsForNewForm(request); * errors.reject("duplicateFormSubmission", "Duplicate form submission"); * return showForm(request, response, bindingResult); * }</pre> * @param request current HTTP request * @return a prepared view, or <code>null</code> if handled directly * @throws Exception in case of errors * @see #showNewForm * @see #showForm */ protected ModelAndView handleInvalidSubmit(HttpServletRequest request) throws Exception { return processFormSubmission(request); } /** * This implementation calls {@link #showForm} in case of errors, * and delegates to {@link #onSubmit}'s variant else. * <p>This can only be overridden to check for an action that should be executed * without respect to binding errors, like a cancel action. To just handle successful * submissions without binding errors, override the {@link #onSubmit} method. * @see #showForm * @see #onSubmit */ protected ModelAndView processFormSubmission(HttpServletRequest request) throws Exception { T formObject = formBackingObject(request); ServletRequestDataBinder binder = createBinder(request, formObject); binder.bind(request); BindingResult bindingResult = binder.getBindingResult(); onBind(request, formObject, bindingResult); return processFormSubmission(request, formObject, bindingResult); } /** * This implementation calls {@link #showForm} in case of errors, * and delegates to {@link #onSubmit}'s variant else. * <p>This can only be overridden to check for an action that should be executed * without respect to binding errors, like a cancel action. To just handle successful * submissions without binding errors, override the {@link #onSubmit} method. * @see #showForm * @see #onSubmit */ protected ModelAndView processFormSubmission(HttpServletRequest request, T formObject, BindingResult bindingResult) throws Exception { if (bindingResult.hasErrors()) { if (logger.isDebugEnabled()) { logger.debug("Data binding errors: " + bindingResult.getErrorCount()); } return showForm(request, bindingResult); } else { logger.debug("No errors -> processing submit"); ModelAndView mav = onSubmit(request, formObject, bindingResult); if (mav != null) { return mav; } else { return showForm(request, bindingResult); } } } /** * Return the name of the form object in the model. * The form object will be included in the model under this name. * @param request current HTTP request * @return the name of the form object */ protected abstract String getFormObjectName(HttpServletRequest request); /** * Return the name of the view that should be used for form display. * @param request current HTTP request * @return the name of the form view */ protected abstract String getFormView(HttpServletRequest request); /** * Retrieve a backing object for the current form from the given request. * <p>The properties of the form object will correspond to the form field values * in your form view. This object will be exposed in the model under the specified * formObject name, to be accessed under that name in the view: for example, with * a "spring:bind" tag. The default formObject name is "formObject". * <p>Note that you need to activate session form mode to reuse the form-backing * object across the entire form workflow. Else, a new instance of the form object * class will be created for each submission attempt, just using this backing * object as template for the initial form. * @param request current HTTP request * @return the backing object * @throws Exception in case of invalid state or arguments */ protected abstract T formBackingObject(HttpServletRequest request) throws Exception; /** * Submit callback with all parameters. Called in case of submit without errors * reported by the registered validator, or on every submit if no validator. * <p>Subclasses can override this to provide custom submission handling like storing * the object to the database. Implementations can also perform custom validation and * call showForm to return to the form. Do <i>not</i> implement multiple onSubmit * methods: In that case, just this method will be called by the controller. * <p>Call <code>errors.getModel()</code> to populate the ModelAndView model * with the form object and the Errors instance, under the specified form object * name, as expected by the "spring:bind" tag. * @param request current servlet request * @param formObject form object with request parameters bound onto it * @param bindingResult Errors instance without errors (subclass can add errors if it wants to) * @return the prepared model and view, or <code>null</code> * @throws Exception in case of errors * @see #onSubmit * @see #showForm * @see org.springframework.validation.Errors * @see org.springframework.validation.BindingResult#getModel() */ protected abstract ModelAndView onSubmit(HttpServletRequest request, T formObject, BindingResult bindingResult) throws Exception; }