SimpleFormController (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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:
    Aware, ApplicationContextAware, ServletContextAware, Controller
  Direct Known Subclasses:
    CancellableFormController

  Deprecated.
  as of Spring 3.0, in favor of annotated controllers

      @Deprecated
      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

      `METHOD_GET, METHOD_HEAD, METHOD_POST`

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

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleFormController()` Deprecated. Create a new SimpleFormController.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `doSubmitAction(Object command)` Deprecated. Template method for submit actions.
    `String` | `getFormView()` Deprecated. Return the name of the view that should be used for form display.
    `String` | `getSuccessView()` Deprecated. Return the name of the view that should be shown on successful submit.
    `protected boolean` | `isFormChangeRequest(HttpServletRequest request)` Deprecated. Simpler `isFormChangeRequest` variant, called by the full variant `isFormChangeRequest(HttpServletRequest, Object)`.
    `protected boolean` | `isFormChangeRequest(HttpServletRequest request, Object command)` Deprecated. Determine whether the given request is a form change request.
    `protected void` | `onFormChange(HttpServletRequest request, HttpServletResponse response, Object command)` Deprecated. Simpler `onFormChange` variant, called by the full variant `onFormChange(HttpServletRequest, HttpServletResponse, Object, BindException)`.
    `protected void` | `onFormChange(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)` Deprecated. Called during form submission if `isFormChangeRequest(javax.servlet.http.HttpServletRequest)` returns `true`.
    `protected ModelAndView` | `onSubmit(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)` Deprecated. Submit callback with all parameters.
    `protected ModelAndView` | `onSubmit(Object command)` Deprecated. Simplest `onSubmit` variant.
    `protected ModelAndView` | `onSubmit(Object command, BindException errors)` Deprecated. Simpler `onSubmit` variant.
    `protected ModelAndView` | `processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)` Deprecated. This implementation calls `showForm(HttpServletRequest, HttpServletResponse, BindException)` in case of errors, and delegates to the full `onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)`'s variant else.
    `protected Map` | `referenceData(HttpServletRequest request)` Deprecated. Create a reference data map for the given request.
    `protected Map` | `referenceData(HttpServletRequest request, Object command, Errors errors)` Deprecated. 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)` Deprecated. Set the name of the view that should be used for form display.
    `void` | `setSuccessView(String successView)` Deprecated. Set the name of the view that should be shown on successful submit.
    `protected ModelAndView` | `showForm(HttpServletRequest request, HttpServletResponse response, BindException errors)` Deprecated. This implementation shows the configured form view, delegating to the analogous `showForm(HttpServletRequest, HttpServletResponse, BindException, Map)` variant with a "controlModel" argument.
    `protected ModelAndView` | `showForm(HttpServletRequest request, HttpServletResponse response, BindException errors, Map controlModel)` Deprecated. This implementation shows the configured form view.
    `protected boolean` | `suppressValidation(HttpServletRequest request, Object command)` Deprecated. This implementation delegates to `isFormChangeRequest(HttpServletRequest, Object)`: 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, getWebBindingInitializer, initApplicationContext, initBinder, isValidateOnBinding, onBind, onBind, onBindAndValidate, prepareBinder, setBindingErrorProcessor, setCommandClass, setCommandName, setMessageCodesResolver, setPropertyEditorRegistrar, setPropertyEditorRegistrars, setValidateOnBinding, setValidator, setValidators, setWebBindingInitializer, suppressBinding, suppressValidation, suppressValidation, useDirectFieldAccess`

    - ### 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, isAlwaysMustRevalidate, isRequireSession, isUseCacheControlHeader, isUseCacheControlNoStore, isUseExpiresHeader, preventCaching, setAlwaysMustRevalidate, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseCacheControlNoStore, setUseExpiresHeader`

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

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### 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()

      Deprecated.
      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)

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

    - #### getFormView

          public final String getFormView()

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

    - #### setSuccessView

          public final void setSuccessView(String successView)

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

    - #### getSuccessView

          public final String getSuccessView()

      Deprecated.
      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

      Deprecated.
      This implementation shows the configured form view, delegating to the analogous `showForm(HttpServletRequest, HttpServletResponse, BindException, Map)` variant with a "controlModel" argument.

      Can be called within `onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)` implementations, to redirect back to the form in case of custom validation errors (errors 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

      Deprecated.
      This implementation shows the configured form view.

      Can be called within `onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)` implementations, to redirect back to the form in case of custom validation errors (errors 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

      Deprecated.
      Create a reference data map for the given request and command, consisting of bean name/bean instance pairs as expected by ModelAndView.

      The default implementation delegates to `referenceData(HttpServletRequest)`. 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

      Deprecated.
      Create a reference data map for the given request. Called by the `referenceData(HttpServletRequest, Object, Errors)` variant with all parameters.

      The 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

      Deprecated.
      This implementation calls `showForm(HttpServletRequest, HttpServletResponse, BindException)` in case of errors, and delegates to the full `onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)`'s variant 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(java.lang.Object)`.

      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,
                                   Object command)

      Deprecated.
      This implementation delegates to `isFormChangeRequest(HttpServletRequest, Object)`: 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
        `command` - the command object to validate
      Returns:
        whether to suppress validation for the given request
      See Also:
        `isFormChangeRequest(javax.servlet.http.HttpServletRequest, java.lang.Object)`

    - #### isFormChangeRequest

          protected boolean isFormChangeRequest(HttpServletRequest request,
                                    Object command)

      Deprecated.
      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(javax.servlet.http.HttpServletRequest, java.lang.Object)` and `processFormSubmission(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException)`. Consequently, this single method determines to suppress validation and to show the form view in any case.

      The default implementation delegates to `isFormChangeRequest(javax.servlet.http.HttpServletRequest)`.

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

    - #### isFormChangeRequest

          protected boolean isFormChangeRequest(HttpServletRequest request)

      Deprecated.
      Simpler `isFormChangeRequest` variant, called by the full variant `isFormChangeRequest(HttpServletRequest, Object)`.

      The default implementation returns `false`.

      Parameters:
        `request` - current HTTP request
      Returns:
        whether the given request is a form change request
      See Also:
        `suppressValidation(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `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

      Deprecated.
      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.

      The default implementation delegates to `onFormChange(HttpServletRequest, HttpServletResponse, Object, BindException)`.

      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

      Deprecated.
      Simpler `onFormChange` variant, called by the full variant `onFormChange(HttpServletRequest, HttpServletResponse, Object, BindException)`.

      The 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

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

      The default implementation delegates to `onSubmit(Object, BindException)`. For simply performing a submit action and rendering the specified success view, consider implementing `doSubmitAction(java.lang.Object)` rather than an `onSubmit` variant.

      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

      Deprecated.
      Simpler `onSubmit` variant. Called by the default implementation of the `onSubmit(HttpServletRequest, HttpServletResponse, Object, BindException)` variant with all parameters.

      The default implementation calls `onSubmit(Object)`, 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

      Deprecated.
      Simplest `onSubmit` variant. Called by the default implementation of the `onSubmit(Object, BindException)` variant.

      This implementation calls `doSubmitAction(Object)` 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(Object, BindException)` or `doSubmitAction(Object)`, 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 (that is, rendering the configured "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

      Deprecated.
      Template method for submit actions. Called by the default implementation of the simplest `onSubmit(Object)` variant.

      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)`