The Spring Framework

## 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:
  ApplicationContextAware, ServletContextAware, Controller

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

Method Summary
`String` `getCancelParamKey()` Return the key of the request parameter used to identify a cancel request.
`String` `getCancelView()` Gets the name of the cancel view.
`protected boolean` `isCancelRequest(HttpServletRequest request)` Determine whether the incoming request is a request to cancel the processing of the current form.
`protected boolean` `isFormSubmission(HttpServletRequest request)` Consider an explicit cancel request as a form submission too.
`protected ModelAndView` `onCancel(HttpServletRequest request, HttpServletResponse response, Object command)` Callback method for handling a cancel request.
`protected ModelAndView` `onCancel(Object command)` Simple `onCancel` version.
`protected ModelAndView` `processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)` 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)` Set the key of the request parameter used to identify a cancel request.
`void` `setCancelView(String cancelView)` Sets the name of the cancel view.
`protected boolean` `suppressValidation(HttpServletRequest request, Object command)` 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, isRequireSession, isUseCacheControlHeader, isUseCacheControlNoStore, isUseExpiresHeader, preventCaching, 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()

Method Detail

### setCancelParamKey

    public final void setCancelParamKey(String cancelParamKey)

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

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

### setCancelView

    public final void setCancelView(String cancelView)

  Sets the name of the cancel view.

### getCancelView

    public final String getCancelView()

  Gets the name of the cancel view.

### isFormSubmission

    protected boolean isFormSubmission(HttpServletRequest request)

  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)

  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

  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)

  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

  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

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

The Spring Framework

Copyright © 2002-2008 The Spring Framework.