org.springframework.web.servlet.mvc
Class SimpleFormController

java.lang.Object
  org.springframework.context.support.ApplicationObjectSupport
      org.springframework.web.context.support.WebApplicationObjectSupport
          org.springframework.web.servlet.support.WebContentGenerator
              org.springframework.web.servlet.mvc.AbstractController
                  org.springframework.web.servlet.mvc.BaseCommandController
                      org.springframework.web.servlet.mvc.AbstractFormController
                          org.springframework.web.servlet.mvc.SimpleFormController

All Implemented Interfaces:

ApplicationContextAware, Controller

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 submit behavior can be customized by overriding one of the onSubmit methods. Submit actions can be used as custom validation if necessary (e.g. login), by calling showForm in case of validation errors.

Besides some extra functionality like described above and in the list of exposed configuration properties and the workflow description, this class does the same as the AbstractFormController (hmmm, it also extends it).

Workflow (and that defined by superclass):
The workflow of this Controller does not differ too much from the one described in the AbstractFormController, except for the fact that overriding of the processFormSubmission method and the showForm method is not necessary, since the view for the respective occasions can be configured externally.

1. XXX After validation of the command object and the perscribed call to onBindAndValidate (for more information on that matter, see the AbstractFormController), the following:
2. call to processFormSubmission which inspects the errors object to see if any errors are available (they could be inserted in the bindAndValidate method
3. If errors occured, the controller will return the formView, giving the user the form again (with possible error message render accordingly)
4. If no errors occurred, a call to onSubmit() using all parameters is done which (in case of the default implementation) calls onSubmit() with just the command object. This allows for convenient overriding of custom hooks
5. After that has finished, the successView is returned (which again, is configurable through the exposed configuration properties)

Exposed configuration properties (and those defined by superclass):

name	default	description
formView	null	Indicates what view to use when the user first asks for the form or when validation errors have occurred while submitting the form
successView	null	Indicates what view to use when successful formsubmissions have occurred. This could for instance be a view congrulating the user with his successful submission

Since:

05.05.2003

Author:

Juergen Hoeller

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_POST

Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

logger

Constructor Summary

SimpleFormController()
Create a new SimpleFormController.

Method Summary

protected java.lang.String	getFormView() Return the name of the view that should be used for form display.
protected java.lang.String	getSuccessView() Return the name of the view that should be shown on successful submit.
protected ModelAndView	onSubmit(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) Submit callback with all parameters.
protected ModelAndView	onSubmit(java.lang.Object command) Simple onSubmit version.
protected ModelAndView	processFormSubmission(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Object command, BindException errors) This implementation calls showForm in case of errors, and delegates to onSubmit's full version else.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request) Create a reference data map for the given request.
protected java.util.Map	referenceData(javax.servlet.http.HttpServletRequest request, java.lang.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(java.lang.String formView) Set the name of the view that should be used for form display.
void	setSuccessView(java.lang.String successView) Set the name of the view that should be shown on successful submit.
protected ModelAndView	showForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, BindException errors) This implementation shows the configured form view.

Methods inherited from class org.springframework.web.servlet.mvc.AbstractFormController

formBackingObject, getCommand, getFormSessionAttributeName, handleInvalidSubmit, handleRequestInternal, isBindOnNewForm, isFormSubmission, isSessionForm, setBindOnNewForm, setSessionForm, showForm, showForm, showNewForm

Methods inherited from class org.springframework.web.servlet.mvc.BaseCommandController

bindAndValidate, checkCommand, createBinder, createCommand, getCommandClass, getCommandName, getValidator, initBinder, isValidateOnBinding, onBind, onBindAndValidate, setCommandClass, setCommandName, setValidateOnBinding, setValidator

Methods inherited from class org.springframework.web.servlet.mvc.AbstractController

handleRequest, setSynchronizeOnSession

Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator

applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, preventCaching, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseExpiresHeader

Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

getServletContext, getTempDir, getWebApplicationContext, requiredContextClass

Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

getApplicationContext, getMessageSourceAccessor, initApplicationContext, 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)

Method Detail

setFormView

public final void setFormView(java.lang.String formView)

Set the name of the view that should be used for form display.

getFormView

protected final java.lang.String getFormView()

Return the name of the view that should be used for form display.

setSuccessView

public final void setSuccessView(java.lang.String successView)

Set the name of the view that should be shown on successful submit.

getSuccessView

protected final java.lang.String getSuccessView()

Return the name of the view that should be shown on successful submit.

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request,
                                      java.lang.Object command,
                                      Errors errors)
                               throws java.lang.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:

java.lang.Exception - in case of invalid state or arguments

See Also:

ModelAndView

referenceData

protected java.util.Map referenceData(javax.servlet.http.HttpServletRequest request)
                               throws java.lang.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:

java.lang.Exception - in case of invalid state or arguments

See Also:

referenceData(HttpServletRequest, Object, Errors), ModelAndView

showForm

protected final ModelAndView showForm(javax.servlet.http.HttpServletRequest request,
                                      javax.servlet.http.HttpServletResponse response,
                                      BindException errors)
                               throws java.lang.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).

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:

java.lang.Exception - in case of invalid state or arguments

See Also:

setFormView(java.lang.String)

processFormSubmission

protected ModelAndView processFormSubmission(javax.servlet.http.HttpServletRequest request,
                                             javax.servlet.http.HttpServletResponse response,
                                             java.lang.Object command,
                                             BindException errors)
                                      throws java.lang.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.

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:

java.lang.Exception - in case of errors

See Also:

showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.springframework.validation.BindException), onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)

onSubmit

protected ModelAndView onSubmit(javax.servlet.http.HttpServletRequest request,
                                javax.servlet.http.HttpServletResponse response,
                                java.lang.Object command,
                                BindException errors)
                         throws java.lang.Exception

Submit callback with all parameters. Called in case of submit without errors reported by the registered validator respectively on every submit if no validator.

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

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 both onSubmit template 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 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:

java.lang.Exception - in case of errors

See Also:

onSubmit(Object), showForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.springframework.validation.BindException), Errors

onSubmit

protected ModelAndView onSubmit(java.lang.Object command)
                         throws java.lang.Exception

Simple onSubmit version. Called by the default implementation of the onSubmit version with all parameters.

This implementation returns null, making the calling onSubmit method perform its default rendering of the success view.

Subclasses can override this to provide custom submission handling that just needs the command object.

Parameters:

command - form object with request parameters bound onto it

Returns:

the prepared model and view, or null

Throws:

java.lang.Exception - in case of errors

See Also:

onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)