The Spring Framework

## org.springframework.web.portlet.mvc
Class SimpleFormController

    java.lang.Object
      org.springframework.context.support.ApplicationObjectSupport
          org.springframework.web.portlet.context.PortletApplicationObjectSupport
              org.springframework.web.portlet.handler.PortletContentGenerator
                  org.springframework.web.portlet.mvc.AbstractController
                      org.springframework.web.portlet.mvc.BaseCommandController
                          org.springframework.web.portlet.mvc.AbstractFormController
                              org.springframework.web.portlet.mvc.SimpleFormController

All Implemented Interfaces:
  ApplicationContextAware, PortletContextAware, 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 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`, `processFormSubmission`, and `renderFormSubmission`: A form view and a success view can be configured declaratively.

This controller is different from it's servlet counterpart in that it must take into account the two phases of a portlet request: the action phase and the render phase. See the JSR-168 spec for more details on these two phases. Be especially aware that the action phase is called only once, but that the render phase will be called repeatedly by the portal -- it does this every time the page containing the portlet is updated, even if the activity is in some other portlet. The main difference in the methods in this class is that the `onSubmit` methods have all been split into `onSubmitAction` and `onSubmitRender` to account for the two phases.

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.portlet.ActionRequest, javax.portlet.ActionResponse, 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 `onSubmitAction` during the action phase and then `onSubmitRender` during the render phase, which in case of the default implementation delegate to `onSubmitAction` and `onSubmitRender` with just the command object. The default implementation of the latter method will return the configured `successView`. Consider just implementing `doSubmitAction` for simply performing a submit action during the action phase and then rendering the success view during the render phase.

The submit behavior can be customized by overriding one of the `onSubmitAction` or `onSubmitRender` 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. You do not have to override both the `onSubmitAction` and `onSubmitRender` methods at a given level unless you truly have custom logic to perform in both.

WARNING: Make sure that any one-time system updates (such as database updates or file writes) are performed in either an `onSubmitAction` method or the `doSubmitAction` method. Logic in the `onSubmitRender` methods may be executed repeatedly by the portal whenever the page containing the portlet is updated.

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 `onSubmitRender()` methods.

Parameters indicated with `setPassRenderParameters` will be preserved if the form has errors or if a form change request occurs. If there are render parameters you need in `onSubmitRender`, then you need to pass those forward from `onSubmitAction`.

Thanks to Rainer Schmitz and Nick Lothian for their suggestions!

Since:
  2.0
Author:
  John A. Lewis, Juergen Hoeller, Rob Harrop

Field Summary

Fields inherited from class org.springframework.web.portlet.mvc.BaseCommandController
`DEFAULT_COMMAND_NAME`

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(javax.portlet.PortletRequest request)` Determine whether the given request is a form change request.
`protected void` `onFormChange(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, Object command)` Simpler `onFormChange` variant, called by the full version `onFormChange(request, response, command, errors)`.
`protected void` `onFormChange(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, Object command, BindException errors)` Called during form submission if `isFormChangeRequest(PortletRequest)` returns `true`.
`protected void` `onSubmitAction(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, Object command, BindException errors)` Submit action phase callback with all parameters.
`protected void` `onSubmitAction(Object command)` Simplest `onSubmitAction` version.
`protected void` `onSubmitAction(Object command, BindException errors)` Simpler `onSubmitAction` version.
`protected ModelAndView` `onSubmitRender(Object command)` Simplest `onSubmitRender` version.
`protected ModelAndView` `onSubmitRender(Object command, BindException errors)` Simpler `onSubmitRender` version.
`protected ModelAndView` `onSubmitRender(javax.portlet.RenderRequest request, javax.portlet.RenderResponse response, Object command, BindException errors)` Submit render phase callback with all parameters.
`protected void` `processFormSubmission(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, Object command, BindException errors)` This implementation does nothing in case of errors, and delegates to `onSubmitAction`'s full version else.
`protected Map` `referenceData(javax.portlet.PortletRequest request)` Create a reference data map for the given request.
`protected Map` `referenceData(javax.portlet.PortletRequest 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.
`protected ModelAndView` `renderFormSubmission(javax.portlet.RenderRequest request, javax.portlet.RenderResponse response, Object command, BindException errors)` This implementation calls `showForm` in case of errors, and delegates to `onSubmitRender`'s full version else.``
`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(javax.portlet.RenderRequest request, javax.portlet.RenderResponse response, BindException errors)` This implementation shows the configured form view, delegating to the analogous showForm version with a controlModel argument.
`protected ModelAndView` `showForm(javax.portlet.RenderRequest request, javax.portlet.RenderResponse response, BindException errors, Map controlModel)` This implementation shows the configured form view.
`protected boolean` `suppressValidation(javax.portlet.PortletRequest request)` This implementation delegates to `isFormChangeRequest(javax.portlet.PortletRequest)`: 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.portlet.mvc.AbstractFormController

`formBackingObject, getCommand, getErrorsForNewForm, getFormSessionAttributeName, getFormSessionAttributeName, getFormSubmitParameterName, getInvalidSubmitParameterName, getRenderParameters, handleActionRequestInternal, handleInvalidSubmit, handleRenderRequestInternal, isBindOnNewForm, isFormSubmission, isInvalidSubmission, isRedirectAction, isSessionForm, onBindOnNewForm, onBindOnNewForm, passRenderParameters, renderInvalidSubmit, setBindOnNewForm, setFormSubmit, setInvalidSubmit, setRedirectAction, setRenderParameters, setSessionForm, showForm, showForm, showNewForm`

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

`bindAndValidate, checkCommand, createBinder, createCommand, getBindingErrorProcessor, getCommandClass, getCommandName, getMessageCodesResolver, getPropertyEditorRegistrars, getRenderCommand, getRenderCommandSessionAttributeName, getRenderErrors, getRenderErrorsSessionAttributeName, getValidator, getValidators, getWebBindingInitializer, initApplicationContext, initBinder, isValidateOnBinding, onBind, onBind, onBindAndValidate, prepareBinder, setBindingErrorProcessor, setCommandClass, setCommandName, setMessageCodesResolver, setPropertyEditorRegistrar, setPropertyEditorRegistrars, setRenderCommandAndErrors, setValidateOnBinding, setValidator, setValidators, setWebBindingInitializer, suppressBinding, useDirectFieldAccess`

Methods inherited from class org.springframework.web.portlet.mvc.AbstractController
`handleActionRequest, handleRenderRequest, isRenderWhenMinimized, isSynchronizeOnSession, setRenderWhenMinimized, setSynchronizeOnSession`

Methods inherited from class org.springframework.web.portlet.handler.PortletContentGenerator
`applyCacheSeconds, cacheForSeconds, check, checkAndPrepare, checkAndPrepare, getCacheSeconds, isRequireSession, preventCaching, setCacheSeconds, setRequireSession`

Methods inherited from class org.springframework.web.portlet.context.PortletApplicationObjectSupport
`getPortletContext, getTempDir, isContextRequired, setPortletContext`

Methods inherited from class org.springframework.context.support.ApplicationObjectSupport
`getApplicationContext, getMessageSourceAccessor, initApplicationContext, 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(Class)`, `BaseCommandController.setCommandName(String)`, `AbstractFormController.setSessionForm(boolean)`, `setFormView(java.lang.String)`, `setSuccessView(java.lang.String)`, `AbstractFormController.formBackingObject(PortletRequest)`

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(javax.portlet.RenderRequest request,
                                    javax.portlet.RenderResponse 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 render request
    `response` - current render 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(RenderRequest, RenderResponse, BindException, Map)`

### showForm

    protected ModelAndView showForm(javax.portlet.RenderRequest request,
                                    javax.portlet.RenderResponse 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 render 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(javax.portlet.PortletRequest 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 portlet 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(javax.portlet.PortletRequest 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 portlet request
  Returns:
    a Map with reference data entries, or null if none
  Throws:
    `Exception` - in case of invalid state or arguments
  See Also:
    `referenceData(PortletRequest, Object, Errors)`, `ModelAndView`

### renderFormSubmission

    protected ModelAndView renderFormSubmission(javax.portlet.RenderRequest request,
                                                javax.portlet.RenderResponse response,
                                                Object command,
                                                BindException errors)
                                         throws Exception

  This implementation calls `showForm` in case of errors, and delegates to `onSubmitRender`'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 `onSubmitRender` methods.

  ``
  Specified by:
    `renderFormSubmission` in class `AbstractFormController`
  Parameters:
    `request` - current render request
    `response` - current render response
    `command` - form object with request parameters bound onto it
    `errors` - errors holder
  Returns:
    the prepared model and view, or null
  Throws:
    `Exception` - in case of errors
  See Also:
    `showForm(RenderRequest, RenderResponse, BindException)`, `onSubmitRender(RenderRequest, RenderResponse, Object, BindException)`, `onSubmitRender(Object, BindException)`, `onSubmitRender(Object)`, `processFormSubmission(ActionRequest, ActionResponse, Object, BindException)`

### processFormSubmission

    protected void processFormSubmission(javax.portlet.ActionRequest request,
                                         javax.portlet.ActionResponse response,
                                         Object command,
                                         BindException errors)
                                  throws Exception

  This implementation does nothing in case of errors, and delegates to `onSubmitAction`'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 `onSubmitAction` methods or `doSubmitAction`.

  Specified by:
    `processFormSubmission` in class `AbstractFormController`
  Parameters:
    `request` - current action request
    `response` - current action response
    `command` - form object with request parameters bound onto it
    `errors` - errors holder (subclass can add errors if it wants to)
  Throws:
    `Exception` - in case of errors
  See Also:
    `showForm(javax.portlet.RenderRequest, javax.portlet.RenderResponse, org.springframework.validation.BindException)`, `onSubmitAction(ActionRequest, ActionResponse, Object, BindException)`, `onSubmitAction(Object, BindException)`, `onSubmitAction(Object)`, `doSubmitAction(Object)`, `renderFormSubmission(RenderRequest, RenderResponse, Object, BindException)`

### suppressValidation

    protected boolean suppressValidation(javax.portlet.PortletRequest request)

  This implementation delegates to `isFormChangeRequest(javax.portlet.PortletRequest)`: 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 portlet request
  Returns:
    whether to suppress validation for the given request
  See Also:
    `isFormChangeRequest(javax.portlet.PortletRequest)`

### isFormChangeRequest

    protected boolean isFormChangeRequest(javax.portlet.PortletRequest 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(javax.portlet.PortletRequest)` and `processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, 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 returns `false</code. <P>`

  Parameters:
    `request` - current portlet request
  Returns:
    whether the given request is a form change request
  See Also:
    `suppressValidation(javax.portlet.PortletRequest)`, `processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)`

### onFormChange

    protected void onFormChange(javax.portlet.ActionRequest request,
                                javax.portlet.ActionResponse response,
                                Object command,
                                BindException errors)
                         throws Exception

  Called during form submission if `isFormChangeRequest(PortletRequest)` 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 action request
    `response` - current action 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(PortletRequest)`, `onFormChange(ActionRequest, ActionResponse, Object)`

### onFormChange

    protected void onFormChange(javax.portlet.ActionRequest request,
                                javax.portlet.ActionResponse 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 action request
    `response` - current action response
    `command` - form object with request parameters bound onto it
  Throws:
    `Exception` - in case of errors
  See Also:
    `onFormChange(ActionRequest, ActionResponse, Object, BindException)`

### onSubmitRender

    protected ModelAndView onSubmitRender(javax.portlet.RenderRequest request,
                                          javax.portlet.RenderResponse response,
                                          Object command,
                                          BindException errors)
                                   throws Exception

  Submit render phase 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 `onSubmitRender(Object, BindException)`. For simply performing a submit action and rendering the specified success view, do not implement an `onSubmitRender` at all.

  Subclasses can override this to provide custom rendering to display results of the action phase. Implementations can also call `showForm` to return to the form if the `onSubmitAction` failed custom validation. Do not implement multiple `onSubmitRender` 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 render request
    `response` - current render 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
  Throws:
    `Exception` - in case of errors
  See Also:
    `onSubmitAction(ActionRequest, ActionResponse, Object, BindException)`, `onSubmitRender(Object, BindException)`, `doSubmitAction(java.lang.Object)`, `showForm(javax.portlet.RenderRequest, javax.portlet.RenderResponse, org.springframework.validation.BindException)`, `Errors`, `BindException.getModel()`

### onSubmitAction

    protected void onSubmitAction(javax.portlet.ActionRequest request,
                                  javax.portlet.ActionResponse response,
                                  Object command,
                                  BindException errors)
                           throws Exception

  Submit action phase 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 delegates to `onSubmitAction(Object, BindException)`. For simply performing a submit action consider implementing `doSubmitAction` rather than an `onSubmitAction` version.

  Subclasses can override this to provide custom submission handling like storing the object to the database. Implementations can also perform custom validation and signal the render phase to call `showForm` to return to the form. Do not implement multiple `onSubmitAction` methods: In that case, just this method will be called by the controller.

  Parameters:
    `request` - current action request
    `response` - current action response
    `command` - form object with request parameters bound onto it
    `errors` - Errors instance without errors (subclass can add errors if it wants to)
  Throws:
    `Exception` - in case of errors
  See Also:
    `onSubmitRender(RenderRequest, RenderResponse, Object, BindException)`, `onSubmitAction(Object, BindException)`, `doSubmitAction(java.lang.Object)`, `Errors`

### onSubmitRender

    protected ModelAndView onSubmitRender(Object command,
                                          BindException errors)
                                   throws Exception

  Simpler `onSubmitRender` version. Called by the default implementation of the `onSubmitRender` version with all parameters.

  Default implementation calls `onSubmitRender(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, or null
  Throws:
    `Exception` - in case of errors
  See Also:
    `onSubmitRender(RenderRequest, RenderResponse, Object, BindException)`, `onSubmitRender(Object)`, `onSubmitAction(Object, BindException)`, `setSuccessView(java.lang.String)`, `Errors`, `BindException.getModel()`

### onSubmitAction

    protected void onSubmitAction(Object command,
                                  BindException errors)
                           throws Exception

  Simpler `onSubmitAction` version. Called by the default implementation of the `onSubmitAction` version with all parameters.

  Default implementation calls `onSubmitAction(command)`.

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

  Parameters:
    `command` - form object with request parameters bound onto it
    `errors` - Errors instance without errors
  Throws:
    `Exception` - in case of errors
  See Also:
    `onSubmitAction(ActionRequest, ActionResponse, Object, BindException)`, `onSubmitAction(Object)`, `onSubmitRender(Object, BindException)`, `Errors`

### onSubmitRender

    protected ModelAndView onSubmitRender(Object command)
                                   throws Exception

  Simplest `onSubmitRender` version. Called by the default implementation of the `onSubmitRender` version with command and BindException parameters.

  This implementation returns null as ModelAndView, making the calling onSubmitRender 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.

  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:
    `onSubmitRender(Object, BindException)`, `onSubmitAction(Object)`, `doSubmitAction(java.lang.Object)`, `setSuccessView(java.lang.String)`

### onSubmitAction

    protected void onSubmitAction(Object command)
                           throws Exception

  Simplest `onSubmitAction` version. Called by the default implementation of the `onSubmitAction` version with command and BindException parameters.

  This implementation calls `doSubmitAction`.

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

  Parameters:
    `command` - form object with request parameters bound onto it
  Throws:
    `Exception` - in case of errors
  See Also:
    `onSubmitAction(Object, BindException)`, `onSubmitRender(Object)`, `doSubmitAction(java.lang.Object)`

### doSubmitAction

    protected void doSubmitAction(Object command)
                           throws Exception

  Template method for submit actions. Called by the default implementation of the simplest onSubmitAction 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.

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

The Spring Framework

Copyright © 2002-2008 The Spring Framework.