org.springframework.web.servlet.mvc
Class SimpleFormController

java.lang.Object
  extended by org.springframework.context.support.ApplicationObjectSupport
      extended by org.springframework.web.context.support.WebApplicationObjectSupport
          extended by org.springframework.web.servlet.support.WebContentGenerator
              extended by org.springframework.web.servlet.mvc.AbstractController
                  extended by org.springframework.web.servlet.mvc.BaseCommandController
                      extended by org.springframework.web.servlet.mvc.AbstractFormController
                          extended by org.springframework.web.servlet.mvc.SimpleFormController
All Implemented Interfaces:
ApplicationContextAware, Controller
Direct Known Subclasses:
CancellableFormController

public class SimpleFormController
extends AbstractFormController

Concrete FormController implementation that provides configurable form and success views, and an onSubmit chain for convenient overriding. Automatically resubmits to the form view in case of validation errors, and renders the success view in case of a valid submission.

The workflow of this Controller does not differ much from the one described in the AbstractFormController. The difference is that you do not need to implement showForm and processFormSubmission: A form view and a success view can be configured declaratively.

Workflow (in addition to the superclass):

  1. Call to processFormSubmission which inspects the Errors object to see if any errors have occurred during binding and validation.
  2. If errors occured, the controller will return the configured formView, showing the form again (possibly rendering according error messages).
  3. If isFormChangeRequest is overridden and returns true for the given request, the controller will return the formView too. In that case, the controller will also suppress validation. Before returning the formView, the controller will invoke onFormChange(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException), giving sub-classes a chance to make modification to the command object. This is intended for requests that change the structure of the form, which should not cause validation and show the form in any case.
  4. If no errors occurred, the controller will call onSubmit using all parameters, which in case of the default implementation delegates to onSubmit with just the command object. The default implementation of the latter method will return the configured successView. Consider implementing doSubmitAction(java.lang.Object) doSubmitAction for simply performing a submit action and rendering the success view.

The submit behavior can be customized by overriding one of the onSubmit methods. Submit actions can also perform custom validation if necessary (typically database-driven checks), calling showForm in case of validation errors to show the form view again.

Exposed configuration properties (and those defined by superclass):

name default description
formView null Indicates what view to use when the user asks for a new form or when validation errors have occurred on form submission.
successView null Indicates what view to use when successful form submissions have occurred. Such a success view could e.g. display a submission summary. More sophisticated actions can be implemented by overriding one of the onSubmit() methods.

Since:
05.05.2003
Author:
Juergen Hoeller, Rob Harrop

Field Summary
 
Fields inherited from class org.springframework.web.servlet.mvc.BaseCommandController
DEFAULT_COMMAND_NAME
 
Fields inherited from class org.springframework.web.servlet.support.WebContentGenerator
HEADER_CACHE_CONTROL, HEADER_EXPIRES, HEADER_PRAGMA, METHOD_GET, METHOD_HEAD, METHOD_POST
 
Fields inherited from class org.springframework.context.support.ApplicationObjectSupport
logger
 
Constructor Summary
SimpleFormController()
          Create a new SimpleFormController.
 
Method Summary
protected  void doSubmitAction(Object command)
          Template method for submit actions.
 String getFormView()
          Return the name of the view that should be used for form display.
 String getSuccessView()
          Return the name of the view that should be shown on successful submit.
protected  boolean isFormChangeRequest(HttpServletRequest request)
          Determine whether the given request is a form change request.
protected  void onFormChange(HttpServletRequest request, HttpServletResponse response, Object command)
          Simpler onFormChange variant, called by the full version onFormChange(request, response, command, errors).
protected  void onFormChange(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)
          Called during form submission if isFormChangeRequest(javax.servlet.http.HttpServletRequest) returns true.
protected  ModelAndView onSubmit(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)
          Submit callback with all parameters.
protected  ModelAndView onSubmit(Object command)
          Simplest onSubmit version.
protected  ModelAndView onSubmit(Object command, BindException errors)
          Simpler onSubmit version.
protected  ModelAndView processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)
          This implementation calls showForm in case of errors, and delegates to onSubmit's full version else.
protected  Map referenceData(HttpServletRequest request)
          Create a reference data map for the given request.
protected  Map referenceData(HttpServletRequest request, Object command, Errors errors)
          Create a reference data map for the given request and command, consisting of bean name/bean instance pairs as expected by ModelAndView.
 void setFormView(String formView)
          Set the name of the view that should be used for form display.
 void setSuccessView(String successView)
          Set the name of the view that should be shown on successful submit.
protected  ModelAndView showForm(HttpServletRequest request, HttpServletResponse response, BindException errors)
          This implementation shows the configured form view, delegating to the analogous showForm version with a controlModel argument.
protected  ModelAndView showForm(HttpServletRequest request, HttpServletResponse response, BindException errors, Map controlModel)
          This implementation shows the configured form view.
protected  boolean suppressValidation(HttpServletRequest request)
          This implementation delegates to isFormChangeRequest: A form change request changes the appearance of the form and should not get validated but just show the new form.
 
Methods inherited from class org.springframework.web.servlet.mvc.AbstractFormController
currentFormObject, formBackingObject, getCommand, getErrorsForNewForm, getFormSessionAttributeName, getFormSessionAttributeName, handleInvalidSubmit, handleRequestInternal, isBindOnNewForm, isFormSubmission, isSessionForm, onBindOnNewForm, onBindOnNewForm, setBindOnNewForm, setSessionForm, showForm, showForm, showNewForm
 
Methods inherited from class org.springframework.web.servlet.mvc.BaseCommandController
bindAndValidate, checkCommand, createBinder, createCommand, getBindingErrorProcessor, getCommandClass, getCommandName, getMessageCodesResolver, getPropertyEditorRegistrars, getValidator, getValidators, initApplicationContext, initBinder, isValidateOnBinding, onBind, onBind, onBindAndValidate, setBindingErrorProcessor, setCommandClass, setCommandName, setMessageCodesResolver, setPropertyEditorRegistrar, setPropertyEditorRegistrars, setValidateOnBinding, setValidator, setValidators, suppressBinding
 
Methods inherited from class org.springframework.web.servlet.mvc.AbstractController
handleRequest, isSynchronizeOnSession, setSynchronizeOnSession
 
Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator
applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, checkAndPrepare, getCacheSeconds, getSupportedMethods, isRequireSession, isUseCacheControlHeader, isUseExpiresHeader, preventCaching, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseExpiresHeader
 
Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport
getServletContext, getTempDir, getWebApplicationContext, isContextRequired
 
Methods inherited from class org.springframework.context.support.ApplicationObjectSupport
getApplicationContext, getMessageSourceAccessor, requiredContextClass, setApplicationContext
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SimpleFormController

public SimpleFormController()
Create a new SimpleFormController.

Subclasses should set the following properties, either in the constructor or via a BeanFactory: commandName, commandClass, sessionForm, formView, successView. Note that commandClass doesn't need to be set when overriding formBackingObject, as this determines the class anyway.

See Also:
BaseCommandController.setCommandClass(java.lang.Class), BaseCommandController.setCommandName(java.lang.String), AbstractFormController.setSessionForm(boolean), setFormView(java.lang.String), setSuccessView(java.lang.String), AbstractFormController.formBackingObject(javax.servlet.http.HttpServletRequest)
Method Detail

setFormView

public final void setFormView(String formView)
Set the name of the view that should be used for form display.


getFormView

public final String getFormView()
Return the name of the view that should be used for form display.


setSuccessView

public final void setSuccessView(String successView)
Set the name of the view that should be shown on successful submit.


getSuccessView

public final String getSuccessView()
Return the name of the view that should be shown on successful submit.


showForm

protected ModelAndView showForm(HttpServletRequest request,
                                HttpServletResponse response,
                                BindException errors)
                         throws Exception
This implementation shows the configured form view, delegating to the analogous showForm version with a controlModel argument.

Can be called within onSubmit implementations, to redirect back to the form in case of custom validation errors (i.e. not determined by the validator).

Can be overridden in subclasses to show a custom view, writing directly to the response or preparing the response before rendering a view.

If calling showForm with a custom control model in subclasses, it's preferable to override the analogous showForm version with a controlModel argument (which will handle both standard form showing and custom form showing then).

Specified by:
showForm in class AbstractFormController
Parameters:
request - current HTTP request
response - current HTTP response
errors - validation errors holder
Returns:
the prepared form view, or null if handled directly
Throws:
Exception - in case of invalid state or arguments
See Also:
setFormView(java.lang.String), showForm(HttpServletRequest, HttpServletResponse, BindException, Map)

showForm

protected ModelAndView showForm(HttpServletRequest request,
                                HttpServletResponse response,
                                BindException errors,
                                Map controlModel)
                         throws Exception
This implementation shows the configured form view.

Can be called within onSubmit implementations, to redirect back to the form in case of custom validation errors (i.e. not determined by the validator).

Can be overridden in subclasses to show a custom view, writing directly to the response or preparing the response before rendering a view.

Parameters:
request - current HTTP request
errors - validation errors holder
controlModel - model map containing controller-specific control data (e.g. current page in wizard-style controllers or special error message)
Returns:
the prepared form view
Throws:
Exception - in case of invalid state or arguments
See Also:
setFormView(java.lang.String)

referenceData

protected Map referenceData(HttpServletRequest request,
                            Object command,
                            Errors errors)
                     throws Exception
Create a reference data map for the given request and command, consisting of bean name/bean instance pairs as expected by ModelAndView.

Default implementation delegates to referenceData(request). Subclasses can override this to set reference data used in the view.

Overrides:
referenceData in class AbstractFormController
Parameters:
request - current HTTP request
command - form object with request parameters bound onto it
errors - validation errors holder
Returns:
a Map with reference data entries, or null if none
Throws:
Exception - in case of invalid state or arguments
See Also:
ModelAndView

referenceData

protected Map referenceData(HttpServletRequest request)
                     throws Exception
Create a reference data map for the given request. Called by referenceData version with all parameters.

Default implementation returns null. Subclasses can override this to set reference data used in the view.

Parameters:
request - current HTTP request
Returns:
a Map with reference data entries, or null if none
Throws:
Exception - in case of invalid state or arguments
See Also:
referenceData(HttpServletRequest, Object, Errors), ModelAndView

processFormSubmission

protected ModelAndView processFormSubmission(HttpServletRequest request,
                                             HttpServletResponse response,
                                             Object command,
                                             BindException errors)
                                      throws Exception
This implementation calls showForm in case of errors, and delegates to onSubmit's full version else.

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 one of the onSubmit methods or doSubmitAction.

Specified by:
processFormSubmission in class AbstractFormController
Parameters:
request - current servlet request
response - current servlet response
command - form object with request parameters bound onto it
errors - holder without errors (subclass can add errors if it wants to)
Returns:
the prepared model and view, or null
Throws:
Exception - in case of errors
See Also:
showForm(HttpServletRequest, HttpServletResponse, BindException), onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException), onSubmit(Object, BindException), onSubmit(Object), doSubmitAction(Object)

suppressValidation

protected boolean suppressValidation(HttpServletRequest request)
This implementation delegates to isFormChangeRequest: A form change request changes the appearance of the form and should not get validated but just show the new form.

Overrides:
suppressValidation in class BaseCommandController
Parameters:
request - current HTTP request
Returns:
whether to suppress validation for the given request
See Also:
isFormChangeRequest(javax.servlet.http.HttpServletRequest)

isFormChangeRequest

protected boolean isFormChangeRequest(HttpServletRequest request)
Determine whether the given request is a form change request. A form change request changes the appearance of the form and should always show the new form, without validation.

Gets called by suppressValidation and processFormSubmission. Consequently, this single method determines to suppress validation and to show the form view in any case.

Parameters:
request - current HTTP request
Returns:
whether the given request is a form change request
See Also:
suppressValidation(javax.servlet.http.HttpServletRequest), processFormSubmission(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException)

onFormChange

protected void onFormChange(HttpServletRequest request,
                            HttpServletResponse response,
                            Object command,
                            BindException errors)
                     throws Exception
Called during form submission if isFormChangeRequest(javax.servlet.http.HttpServletRequest) returns true. Allows subclasses to implement custom logic to modify the command object to directly modify data in the form.

Default implementation delegates to onFormChange(request, response, command).

Parameters:
request - current servlet request
response - current servlet response
command - form object with request parameters bound onto it
errors - validation errors holder, allowing for additional custom validation
Throws:
Exception - in case of errors
See Also:
isFormChangeRequest(HttpServletRequest), onFormChange(HttpServletRequest, HttpServletResponse, Object)

onFormChange

protected void onFormChange(HttpServletRequest request,
                            HttpServletResponse response,
                            Object command)
                     throws Exception
Simpler onFormChange variant, called by the full version onFormChange(request, response, command, errors).

Default implementation is empty.

Parameters:
request - current servlet request
response - current servlet response
command - form object with request parameters bound onto it
Throws:
Exception - in case of errors
See Also:
onFormChange(HttpServletRequest, HttpServletResponse, Object, BindException)

onSubmit

protected ModelAndView onSubmit(HttpServletRequest request,
                                HttpServletResponse response,
                                Object command,
                                BindException errors)
                         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.

Default implementation delegates to onSubmit(Object, BindException). For simply performing a submit action and rendering the specified success view, consider implementing doSubmitAction rather than an onSubmit version.

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 not implement multiple onSubmit methods: In that case, just this method will be called by the controller.

Call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified command name, as expected by the "spring:bind" tag.

Parameters:
request - current servlet request
response - current servlet response
command - form object with request parameters bound onto it
errors - Errors instance without errors (subclass can add errors if it wants to)
Returns:
the prepared model and view, or null
Throws:
Exception - in case of errors
See Also:
onSubmit(Object, BindException), doSubmitAction(java.lang.Object), showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.springframework.validation.BindException), Errors, BindException.getModel()

onSubmit

protected ModelAndView onSubmit(Object command,
                                BindException errors)
                         throws Exception
Simpler onSubmit version. Called by the default implementation of the onSubmit version with all parameters.

Default implementation calls onSubmit(command), using the returned ModelAndView if actually implemented in a subclass. Else, the default behavior will apply: rendering the success view with the command and Errors instance as model.

Subclasses can override this to provide custom submission handling that does not need request and response.

Call errors.getModel() to populate the ModelAndView model with the command and the Errors instance, under the specified command name, as expected by the "spring:bind" tag.

Parameters:
command - form object with request parameters bound onto it
errors - Errors instance without errors
Returns:
the prepared model and view
Throws:
Exception - in case of errors
See Also:
onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException), onSubmit(Object), setSuccessView(java.lang.String), Errors, BindException.getModel()

onSubmit

protected ModelAndView onSubmit(Object command)
                         throws Exception
Simplest onSubmit version. Called by the default implementation of the onSubmit version with command and BindException parameters.

This implementation calls doSubmitAction and returns null as ModelAndView, making the calling onSubmit method perform its default rendering of the success view.

Subclasses can override this to provide custom submission handling that just depends on the command object. It's preferable to use either onSubmit(command, errors) or doSubmitAction(command), though: Use the former when you want to build your own ModelAndView; use the latter when you want to perform an action and forward to the successView.

Parameters:
command - form object with request parameters bound onto it
Returns:
the prepared model and view, or null for default (i.e. successView)
Throws:
Exception - in case of errors
See Also:
onSubmit(Object, BindException), doSubmitAction(java.lang.Object), setSuccessView(java.lang.String)

doSubmitAction

protected void doSubmitAction(Object command)
                       throws Exception
Template method for submit actions. Called by the default implementation of the simplest onSubmit version.

This is the preferred submit callback to implement if you want to perform an action (like storing changes to the database) and then render the success view with the command and Errors instance as model. You don't need to care about the success ModelAndView here.

Parameters:
command - form object with request parameters bound onto it
Throws:
Exception - in case of errors
See Also:
onSubmit(Object), setSuccessView(java.lang.String)


Copyright (c) 2002-2006 The Spring Framework Project.