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

org.springframework.web.servlet.mvc

## Class CancellableFormController

- 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
              - - org.springframework.web.servlet.mvc.CancellableFormController

- All Implemented Interfaces:
    Aware, ApplicationContextAware, ServletContextAware, Controller

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

      @Deprecated
      public class CancellableFormController
      extends SimpleFormController

  Extension of `SimpleFormController` that supports "cancellation" of form processing. By default, this controller looks for a given parameter in the request, identified by the `cancelParamKey`. If this parameter is present, then the controller will return the configured `cancelView`, otherwise processing is passed back to the superclass.

  Workflow (in addition to the superclass):

  1. Call to `processFormSubmission` which calls `isCancelRequest(javax.servlet.http.HttpServletRequest)` to see if the incoming request is to cancel the current form entry. By default, `isCancelRequest(javax.servlet.http.HttpServletRequest)` returns `true` if the configured `cancelParamKey` exists in the request. This behavior can be overridden in subclasses.
  2. If `isCancelRequest(javax.servlet.http.HttpServletRequest)` returns `false`, then the controller will delegate all processing back to `SimpleFormController`, otherwise it will call the `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object)` version with all parameters. By default, that method will delegate to the `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object)` version with just the command object, which will in turn simply return the configured `cancelView`. This behavior can be overridden in subclasses.

  Thanks to Erwin Bolwidt for submitting the original prototype of such a cancellable form controller!

  Since:
    1.2.3
  Author:
    Rob Harrop, Juergen Hoeller
  See Also:
    `setCancelParamKey(java.lang.String)`, `setCancelView(java.lang.String)`, `isCancelRequest(javax.servlet.http.HttpServletRequest)`, `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)`

- - ### 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
    `CancellableFormController()` Deprecated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getCancelParamKey()` Deprecated. Return the key of the request parameter used to identify a cancel request.
    `String` | `getCancelView()` Deprecated. Gets the name of the cancel view.
    `protected boolean` | `isCancelRequest(HttpServletRequest request)` Deprecated. Determine whether the incoming request is a request to cancel the processing of the current form.
    `protected boolean` | `isFormSubmission(HttpServletRequest request)` Deprecated. Consider an explicit cancel request as a form submission too.
    `protected ModelAndView` | `onCancel(HttpServletRequest request, HttpServletResponse response, Object command)` Deprecated. Callback method for handling a cancel request.
    `protected ModelAndView` | `onCancel(Object command)` Deprecated. Simple `onCancel` version.
    `protected ModelAndView` | `processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)` Deprecated. This implementation first checks to see if the incoming is a cancel request, through a call to `isCancelRequest(javax.servlet.http.HttpServletRequest)`.
    `void` | `setCancelParamKey(String cancelParamKey)` Deprecated. Set the key of the request parameter used to identify a cancel request.
    `void` | `setCancelView(String cancelView)` Deprecated. Sets the name of the cancel view.
    `protected boolean` | `suppressValidation(HttpServletRequest request, Object command)` Deprecated. Suppress validation for an explicit cancel request too.

    - ### Methods inherited from class org.springframework.web.servlet.mvc.SimpleFormController

      `doSubmitAction, getFormView, getSuccessView, isFormChangeRequest, isFormChangeRequest, onFormChange, onFormChange, onSubmit, onSubmit, onSubmit, referenceData, referenceData, setFormView, setSuccessView, showForm, showForm`

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

      `currentFormObject, formBackingObject, getCommand, getErrorsForNewForm, getFormSessionAttributeName, getFormSessionAttributeName, handleInvalidSubmit, handleRequestInternal, isBindOnNewForm, 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

    - #### CancellableFormController

          public CancellableFormController()

      Deprecated.

  - ### Method Detail

    - #### setCancelParamKey

          public final void setCancelParamKey(String cancelParamKey)

      Deprecated.
      Set the key of the request parameter used to identify a cancel request. Default is "_cancel".

      The parameter is recognized both when sent as a plain parameter ("_cancel") or when triggered by an image button ("_cancel.x").

    - #### getCancelParamKey

          public final String getCancelParamKey()

      Deprecated.
      Return the key of the request parameter used to identify a cancel request.

    - #### setCancelView

          public final void setCancelView(String cancelView)

      Deprecated.
      Sets the name of the cancel view.

    - #### getCancelView

          public final String getCancelView()

      Deprecated.
      Gets the name of the cancel view.

    - #### isFormSubmission

          protected boolean isFormSubmission(HttpServletRequest request)

      Deprecated.
      Consider an explicit cancel request as a form submission too.
      Overrides:
        `isFormSubmission` in class `AbstractFormController`
      Parameters:
        `request` - current HTTP request
      Returns:
        if the request represents a form submission
      See Also:
        `isCancelRequest(javax.servlet.http.HttpServletRequest)`

    - #### suppressValidation

          protected boolean suppressValidation(HttpServletRequest request,
                                   Object command)

      Deprecated.
      Suppress validation for an explicit cancel request too.
      Overrides:
        `suppressValidation` in class `SimpleFormController`
      Parameters:
        `request` - current HTTP request
        `command` - the command object to validate
      Returns:
        whether to suppress validation for the given request
      See Also:
        `isCancelRequest(javax.servlet.http.HttpServletRequest)`

    - #### processFormSubmission

          protected ModelAndView processFormSubmission(HttpServletRequest request,
                                           HttpServletResponse response,
                                           Object command,
                                           BindException errors)
                                                throws Exception

      Deprecated.
      This implementation first checks to see if the incoming is a cancel request, through a call to `isCancelRequest(javax.servlet.http.HttpServletRequest)`. If so, control is passed to `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object)`; otherwise, control is passed up to `SimpleFormController.processFormSubmission(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException)`.
      Overrides:
        `processFormSubmission` in class `SimpleFormController`
      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:
        `isCancelRequest(javax.servlet.http.HttpServletRequest)`, `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)`, `SimpleFormController.processFormSubmission(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Object, org.springframework.validation.BindException)`

    - #### isCancelRequest

          protected boolean isCancelRequest(HttpServletRequest request)

      Deprecated.
      Determine whether the incoming request is a request to cancel the processing of the current form.

      By default, this method returns `true` if a parameter matching the configured `cancelParamKey` is present in the request, otherwise it returns `false`. Subclasses may override this method to provide custom logic to detect a cancel request.

      The parameter is recognized both when sent as a plain parameter ("_cancel") or when triggered by an image button ("_cancel.x").

      Parameters:
        `request` - current HTTP request
      See Also:
        `setCancelParamKey(java.lang.String)`, `PARAM_CANCEL`

    - #### onCancel

          protected ModelAndView onCancel(HttpServletRequest request,
                              HttpServletResponse response,
                              Object command)
                                   throws Exception

      Deprecated.
      Callback method for handling a cancel request. Called if `isCancelRequest(javax.servlet.http.HttpServletRequest)` returns `true`.

      Default implementation delegates to `onCancel(Object)` to return the configured `cancelView`. Subclasses may override either of the two methods to build a custom `ModelAndView` that may contain model parameters used in the cancel view.

      If you simply want to move the user to a new view and you don't want to add additional model parameters, use `setCancelView(String)` rather than overriding an `onCancel` method.

      Parameters:
        `request` - current servlet request
        `response` - current servlet response
        `command` - form object with request parameters bound onto it
      Returns:
        the prepared model and view, or `null`
      Throws:
        `Exception` - in case of errors
      See Also:
        `isCancelRequest(javax.servlet.http.HttpServletRequest)`, `onCancel(Object)`, `setCancelView(java.lang.String)`

    - #### onCancel

          protected ModelAndView onCancel(Object command)
                                   throws Exception

      Deprecated.
      Simple `onCancel` version. Called by the default implementation of the `onCancel` version with all parameters.

      Default implementation returns eturns the configured `cancelView`. Subclasses may override this method to build a custom `ModelAndView` that may contain model parameters used in the cancel view.

      If you simply want to move the user to a new view and you don't want to add additional model parameters, use `setCancelView(String)` rather than overriding an `onCancel` method.

      Parameters:
        `command` - form object with request parameters bound onto it
      Returns:
        the prepared model and view, or `null`
      Throws:
        `Exception` - in case of errors
      See Also:
        `onCancel(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, Object)`, `setCancelView(java.lang.String)`