AbstractFormController (Spring Framework API 2.1) - Spring Framework 2.1.0 API 文档英文版

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

The Spring Framework

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.springframework.web.portlet.mvc
Class AbstractFormController

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

All Implemented Interfaces:: ApplicationContextAware, PortletContextAware, Controller

Direct Known Subclasses:: AbstractWizardFormController, SimpleFormController

public abstract class AbstractFormController
extends BaseCommandController
extends BaseCommandController

Form controller that auto-populates a form bean from the request. This, either using a new bean instance per request, or using the same bean when the sessionForm property has been set to true.

This class is the base class for both framework subclasses like SimpleFormController and AbstractWizardFormController, and custom form controllers you can provide yourself.

Both form-input-views and after-submission-views have to be provided programmatically. To provide those views using configuration properties, use the SimpleFormController.

Subclasses need to override showForm to prepare the form view, processFormSubmission to handle submit requests, and renderFormSubmission to display the results of the submit. For the latter two methods, binding errors like type mismatches will be reported via the given "errors" holder. For additional custom form validation, a validator (property inherited from BaseCommandController) can be used, reporting via the same "errors" instance.

Comparing this Controller to the Struts notion of the Action shows us that with Spring, you can use any ordinary JavaBeans or database- backed JavaBeans without having to implement a framework-specific class (like Struts' ActionForm). More complex properties of JavaBeans (Dates, Locales, but also your own application-specific or compound types) can be represented and submitted to the controller, by using the notion of a java.beans.PropertyEditors. For more information on that subject, see the workflow of this controller and the explanation of the BaseCommandController.

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. (This is not quite true, the portal can also be told to cache the results of the render for a period of time, but assume it is true for programming purposes.)

Workflow (and that defined by superclass):

The controller receives a request for a new form (typically a Render Request only). The render phase will proceed to display the form as follows.
Call to formBackingObject() which by default, returns an instance of the commandClass that has been configured (see the properties the superclass exposes), but can also be overridden to e.g. retrieve an object from the database (that needs to be modified using the form).
Call to initBinder() which allows you to register custom editors for certain fields (often properties of non- primitive or non-String types) of the command class. This will render appropriate Strings for those property values, e.g. locale-specific date strings.
The PortletRequestDataBinder gets applied to populate the new form object with initial request parameters and the onBindOnNewForm(RenderRequest, Object, BindException) callback method is invoked. (only if bindOnNewForm is set to true) Make sure that the initial parameters do not include the parameter that indicates a form submission has occurred.
Call to showForm to return a View that should be rendered (typically the view that renders the form). This method has to be implemented in subclasses.
The showForm() implementation will call referenceData, which you can implement to provide any relevant reference data you might need when editing a form (e.g. a List of Locale objects you're going to let the user select one from).
Model gets exposed and view gets rendered, to let the user fill in the form.
The controller receives a form submission (typically an Action Request). To use a different way of detecting a form submission, override the isFormSubmission method. The action phase will proceed to process the form submission as follows.
If sessionForm is not set, formBackingObject is called to retrieve a form object. Otherwise, the controller tries to find the command object which is already bound in the session. If it cannot find the object, the action phase does a call to handleInvalidSubmit which - by default - tries to create a new form object and resubmit the form. It then sets a render parameter that will indicate to the render phase that this was an invalid submit.
Still in the action phase of a valid submit, the PortletRequestDataBinder gets applied to populate the form object with current request parameters.
Call to onBind(PortletRequest, Object, Errors) which allows you to do custom processing after binding but before validation (e.g. to manually bind request parameters to bean properties, to be seen by the Validator).
If validateOnBinding is set, a registered Validator will be invoked. The Validator will check the form object properties, and register corresponding errors via the given Errors object.
Call to onBindAndValidate which allows you to do custom processing after binding and validation (e.g. to manually bind request parameters, and to validate them outside a Validator).
Call to processFormSubmission to process the submission, with or without binding errors. This method has to be implemented in subclasses and will be called only once per form submission.
The portal will then call the render phase of processing the form submission. This phase will be called repeatedly by the portal every time the page is refreshed. All processing here should take this into account. Any one-time-only actions (such as modifying a database) must be done in the action phase.
If the action phase indicated this is an invalid submit, the render phase calls renderInvalidSubmit which – also by default – will render the results of the resubmitted form. Be sure to override both handleInvalidSubmit and renderInvalidSubmit if you want to change this overall behavior.
Finally, call renderFormSubmission to render the results of the submission, with or without binding errors. This method has to be implemented in subclasses and will be called repeatedly by the portal.

In session form mode, a submission without an existing form object in the session is considered invalid, like in the case of a resubmit/reload by the browser. The handleInvalidSubmit / renderInvalidSubmit methods are invoked then, by default trying to resubmit. This can be overridden in subclasses to show corresponding messages or to redirect to a new form, in order to avoid duplicate submissions. The form object in the session can be considered a transaction token in that case.

Make sure that any URLs that take you to your form controller are Render URLs, so that it will not try to treat the initial call as a form submission. If you use Action URLs to link to your controller, you will need to override the isFormSubmission method to use a different mechanism for determining whether a form has been submitted. Make sure this method will work for both the ActionRequest and the RenderRequest objects.

Note that views should never retrieve form beans from the session but always from the request, as prepared by the form controller. Remember that some view technologies like Velocity cannot even access a HTTP session.

Exposed configuration properties (and those defined by superclass):

name default description

bindOnNewForm false Indicates whether to bind portlet request parameters when creating a new form. Otherwise, the parameters will only be bound on form submission attempts.

sessionForm false Indicates whether the form object should be kept in the session when a user asks for a new form. This allows you e.g. to retrieve an object from the database, let the user edit it, and then persist it again. Otherwise, a new command object will be created for each request (even when showing the form again after validation errors).

redirectAction false Specifies whether processFormSubmission is expected to call ActionResponse.sendRedirect. This is important because some methods may not be called before ActionResponse.sendRedirect (e.g. ActionResponse.setRenderParameter). Setting this flag will prevent AbstractFormController from setting render parameters that it normally needs for the render phase. If this is set true and sendRedirect is not called, then processFormSubmission must call setFormSubmit. Otherwise, the render phase will not realize the form was submitted and will simply display a new blank form.

renderParameters null An array of parameters that will be passed forward from the action phase to the render phase if the form needs to be displayed again. These can also be passed forward explicitly by calling the passRenderParameters method from any action phase method. Abstract descendants of this controller should follow similar behavior. If there are parameters you need in renderFormSubmission, then you need to pass those forward from processFormSubmission. If you override the default behavior of invalid submits and you set sessionForm to true, then you probably will not need to set this because your parameters are only going to be needed on the first request.

Thanks to Rainer Schmitz and Nick Lothian for their suggestions!

Since:: 2.0
Author:: John A. Lewis, Juergen Hoeller, Alef Arendsen, Rob Harrop
See Also:: showForm(RenderRequest, RenderResponse, BindException), SimpleFormController, AbstractWizardFormController

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

AbstractFormController()
          Create a new AbstractFormController.

Method Summary

protected Object formBackingObject(PortletRequest request)
          Retrieve a backing object for the current form from the given request.

protected Object getCommand(PortletRequest request)
          Return the form object for the given request.

protected BindException getErrorsForNewForm(RenderRequest request)
          Create a BindException instance for a new form.

protected String getFormSessionAttributeName()
          Return the name of the PortletSession attribute that holds the form object for this form controller.

protected String getFormSessionAttributeName(PortletRequest request)
          Return the name of the PortletSession attribute that holds the form object for this form controller.

protected String getFormSubmitParameterName()
          Return the name of the render parameter that indicates this was a form submission.

protected String getInvalidSubmitParameterName()
          Return the name of the render parameter that indicates this was an invalid form submission.

String[] getRenderParameters()
          Returns the list of parameters that will be passed forward from the action phase to the render phase whenever the form is rerendered or when passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse) is called.

protected void handleActionRequestInternal(ActionRequest request, ActionResponse response)
          Handles action phase of two cases: form submissions and showing a new form.

protected void handleInvalidSubmit(ActionRequest request, ActionResponse response)
          Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

protected ModelAndView handleRenderRequestInternal(RenderRequest request, RenderResponse response)
          Handles render phase of two cases: form submissions and showing a new form.

boolean isBindOnNewForm()
          Return if request parameters should be bound in case of a new form.

protected boolean isFormSubmission(PortletRequest request)
          Determine if the given request represents a form submission.

protected boolean isInvalidSubmission(PortletRequest request)
          Determine if the given request represents an invalid form submission.

boolean isRedirectAction()
          Return if ActionResponse.sendRedirect(java.lang.String) is expected to be called in the action phase.

boolean isSessionForm()
          Return if session form mode is activated.

protected void onBindOnNewForm(RenderRequest request, Object command)
          Callback for custom post-processing in terms of binding for a new form.

protected void onBindOnNewForm(RenderRequest request, Object command, BindException errors)
          Callback for custom post-processing in terms of binding for a new form.

protected void passRenderParameters(ActionRequest request, ActionResponse response)
          Pass the specified list of action request parameters to the render phase by putting them into the action response object.

protected abstract void processFormSubmission(ActionRequest request, ActionResponse response, Object command, BindException errors)
          Process action phase of form submission request.

protected Map referenceData(PortletRequest request, Object command, Errors errors)
          Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.

protected abstract ModelAndView renderFormSubmission(RenderRequest request, RenderResponse response, Object command, BindException errors)
          Process render phase of form submission request.

protected ModelAndView renderInvalidSubmit(RenderRequest request, RenderResponse response)
          Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

void setBindOnNewForm(boolean bindOnNewForm)
          Set if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.

protected void setFormSubmit(ActionResponse response)
          Set the action response parameter that indicates this in a form submission.

protected void setInvalidSubmit(ActionResponse response)
          Set the action response parameter that indicates this in an invalid submission.

void setRedirectAction(boolean redirectAction)
          Specify whether the action phase is expected to call ActionResponse.sendRedirect(java.lang.String).

void setRenderParameters(String[] parameters)
          Specify the list of parameters that should be passed forward from the action phase to the render phase whenever the form is rerendered or when passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse) is called.

void setSessionForm(boolean sessionForm)
          Activate/deactivate session form mode.

protected ModelAndView showForm(RenderRequest request, BindException errors, String viewName)
          Prepare model and view for the given form, including reference and errors.

protected ModelAndView showForm(RenderRequest request, BindException errors, String viewName, Map controlModel)
          Prepare model and view for the given form, including reference and errors, adding a controller-specific control model.

protected abstract ModelAndView showForm(RenderRequest request, RenderResponse response, BindException errors)
          Prepare the form model and view, including reference and error data.

protected ModelAndView showNewForm(RenderRequest request, RenderResponse response)
          Show a new form.

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, initApplicationContext, initBinder, isValidateOnBinding, onBind, onBind, onBindAndValidate, prepareBinder, setBindingErrorProcessor, setCommandClass, setCommandName, setMessageCodesResolver, setPropertyEditorRegistrar, setPropertyEditorRegistrars, setRenderCommandAndErrors, setValidateOnBinding, setValidator, setValidators, suppressBinding, suppressValidation, 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, requiredContextClass, setApplicationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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
`AbstractFormController()` Create a new AbstractFormController.

Method Summary
`protected Object`	`formBackingObject(PortletRequest request)` Retrieve a backing object for the current form from the given request.
`protected Object`	`getCommand(PortletRequest request)` Return the form object for the given request.
`protected BindException`	`getErrorsForNewForm(RenderRequest request)` Create a BindException instance for a new form.
`protected String`	`getFormSessionAttributeName()` Return the name of the PortletSession attribute that holds the form object for this form controller.
`protected String`	`getFormSessionAttributeName(PortletRequest request)` Return the name of the PortletSession attribute that holds the form object for this form controller.
`protected String`	`getFormSubmitParameterName()` Return the name of the render parameter that indicates this was a form submission.
`protected String`	`getInvalidSubmitParameterName()` Return the name of the render parameter that indicates this was an invalid form submission.
`String[]`	`getRenderParameters()` Returns the list of parameters that will be passed forward from the action phase to the render phase whenever the form is rerendered or when `passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse)` is called.
`protected void`	`handleActionRequestInternal(ActionRequest request, ActionResponse response)` Handles action phase of two cases: form submissions and showing a new form.
`protected void`	`handleInvalidSubmit(ActionRequest request, ActionResponse response)` Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).
`protected ModelAndView`	`handleRenderRequestInternal(RenderRequest request, RenderResponse response)` Handles render phase of two cases: form submissions and showing a new form.
`boolean`	`isBindOnNewForm()` Return if request parameters should be bound in case of a new form.
`protected boolean`	`isFormSubmission(PortletRequest request)` Determine if the given request represents a form submission.
`protected boolean`	`isInvalidSubmission(PortletRequest request)` Determine if the given request represents an invalid form submission.
`boolean`	`isRedirectAction()` Return if `ActionResponse.sendRedirect(java.lang.String)` is expected to be called in the action phase.
`boolean`	`isSessionForm()` Return if session form mode is activated.
`protected void`	`onBindOnNewForm(RenderRequest request, Object command)` Callback for custom post-processing in terms of binding for a new form.
`protected void`	`onBindOnNewForm(RenderRequest request, Object command, BindException errors)` Callback for custom post-processing in terms of binding for a new form.
`protected void`	`passRenderParameters(ActionRequest request, ActionResponse response)` Pass the specified list of action request parameters to the render phase by putting them into the action response object.
`protected abstract void`	`processFormSubmission(ActionRequest request, ActionResponse response, Object command, BindException errors)` Process action phase of form submission request.
`protected Map`	`referenceData(PortletRequest request, Object command, Errors errors)` Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView.
`protected abstract ModelAndView`	`renderFormSubmission(RenderRequest request, RenderResponse response, Object command, BindException errors)` Process render phase of form submission request.
`protected ModelAndView`	`renderInvalidSubmit(RenderRequest request, RenderResponse response)` Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).
`void`	`setBindOnNewForm(boolean bindOnNewForm)` Set if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.
`protected void`	`setFormSubmit(ActionResponse response)` Set the action response parameter that indicates this in a form submission.
`protected void`	`setInvalidSubmit(ActionResponse response)` Set the action response parameter that indicates this in an invalid submission.
`void`	`setRedirectAction(boolean redirectAction)` Specify whether the action phase is expected to call `ActionResponse.sendRedirect(java.lang.String)`.
`void`	`setRenderParameters(String[] parameters)` Specify the list of parameters that should be passed forward from the action phase to the render phase whenever the form is rerendered or when `passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse)` is called.
`void`	`setSessionForm(boolean sessionForm)` Activate/deactivate session form mode.
`protected ModelAndView`	`showForm(RenderRequest request, BindException errors, String viewName)` Prepare model and view for the given form, including reference and errors.
`protected ModelAndView`	`showForm(RenderRequest request, BindException errors, String viewName, Map controlModel)` Prepare model and view for the given form, including reference and errors, adding a controller-specific control model.
`protected abstract ModelAndView`	`showForm(RenderRequest request, RenderResponse response, BindException errors)` Prepare the form model and view, including reference and error data.
`protected ModelAndView`	`showNewForm(RenderRequest request, RenderResponse response)` Show a new form.

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, initApplicationContext, initBinder, isValidateOnBinding, onBind, onBind, onBindAndValidate, prepareBinder, setBindingErrorProcessor, setCommandClass, setCommandName, setMessageCodesResolver, setPropertyEditorRegistrar, setPropertyEditorRegistrars, setRenderCommandAndErrors, setValidateOnBinding, setValidator, setValidators, suppressBinding, suppressValidation, 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, requiredContextClass, setApplicationContext`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

AbstractFormController

public AbstractFormController()

Create a new AbstractFormController.

Subclasses should set the following properties, either in the constructor or via a BeanFactory: commandName, commandClass, bindOnNewForm, sessionForm. Note that commandClass doesn't need to be set when overriding formBackingObject, as the latter determines the class anyway.

"cacheSeconds" is by default set to 0 (-> no caching for all form controllers).

See Also:: BaseCommandController.setCommandName(java.lang.String), BaseCommandController.setCommandClass(java.lang.Class), setBindOnNewForm(boolean), setSessionForm(boolean), formBackingObject(javax.portlet.PortletRequest)

Method Detail

setBindOnNewForm

public final void setBindOnNewForm(boolean bindOnNewForm)

Set if request parameters should be bound to the form object in case of a non-submitting request, i.e. a new form.

isBindOnNewForm

public final boolean isBindOnNewForm()

Return if request parameters should be bound in case of a new form.

setSessionForm

public final void setSessionForm(boolean sessionForm)

Activate/deactivate session form mode. In session form mode, the form is stored in the session to keep the form object instance between requests, instead of creating a new one on each request.

This is necessary for either wizard-style controllers that populate a single form object from multiple pages, or forms that populate a persistent object that needs to be identical to allow for tracking changes.

isSessionForm

public final boolean isSessionForm()

Return if session form mode is activated.

setRedirectAction

public void setRedirectAction(boolean redirectAction)

Specify whether the action phase is expected to call ActionResponse.sendRedirect(java.lang.String). This information is important because some methods may not be called before ActionResponse.sendRedirect(java.lang.String), e.g. ActionResponse.setRenderParameter(java.lang.String, java.lang.String) and ActionResponse.setRenderParameters(java.util.Map).

Parameters:: redirectAction - true if ActionResponse#sendRedirect is expected to be called
See Also:: ActionResponse.sendRedirect(java.lang.String)

isRedirectAction

public boolean isRedirectAction()

Return if ActionResponse.sendRedirect(java.lang.String) is expected to be called in the action phase.

setRenderParameters

public void setRenderParameters(String[] parameters)

Specify the list of parameters that should be passed forward from the action phase to the render phase whenever the form is rerendered or when passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse) is called.

See Also:: passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse)

getRenderParameters

public String[] getRenderParameters()

Returns the list of parameters that will be passed forward from the action phase to the render phase whenever the form is rerendered or when passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse) is called.

Returns:: the list of parameters
See Also:: passRenderParameters(javax.portlet.ActionRequest, javax.portlet.ActionResponse)

handleActionRequestInternal

protected void handleActionRequestInternal(ActionRequest request,
                                           ActionResponse response)
                                    throws Exception

Handles action phase of two cases: form submissions and showing a new form. Delegates the decision between the two to isFormSubmission, always treating requests without existing form session attribute as new form when using session form mode.

Overrides:: handleActionRequestInternal in class AbstractController

Throws:: Exception
See Also:: isFormSubmission(javax.portlet.PortletRequest), processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException), handleRenderRequestInternal(javax.portlet.RenderRequest, javax.portlet.RenderResponse)

handleRenderRequestInternal

protected ModelAndView handleRenderRequestInternal(RenderRequest request,
                                                   RenderResponse response)
                                            throws Exception

Handles render phase of two cases: form submissions and showing a new form. Delegates the decision between the two to isFormSubmission, always treating requests without existing form session attribute as new form when using session form mode.

Overrides:: handleRenderRequestInternal in class AbstractController

Throws:: Exception
See Also:: isFormSubmission(javax.portlet.PortletRequest), showNewForm(javax.portlet.RenderRequest, javax.portlet.RenderResponse), processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException), handleActionRequestInternal(javax.portlet.ActionRequest, javax.portlet.ActionResponse)

isFormSubmission

protected boolean isFormSubmission(PortletRequest request)

Determine if the given request represents a form submission.

Default implementation checks to see if this is an ActionRequest and treats all action requests as form submission. During the action phase it will pass forward a render parameter to indicate to the render phase that this is a form submission. This method can check both kinds of requests and indicate if this is a form submission.

Subclasses can override this to use a custom strategy, e.g. a specific request parameter (assumably a hidden field or submit button name). Make sure that the override can handle both ActionRequest and RenderRequest objects properly.

Parameters:: request - current request
Returns:: if the request represents a form submission

isInvalidSubmission

protected boolean isInvalidSubmission(PortletRequest request)

Determine if the given request represents an invalid form submission.

getFormSubmitParameterName

protected String getFormSubmitParameterName()

Return the name of the render parameter that indicates this was a form submission.

Returns:: the name of the render parameter
See Also:: PortletRequest.getParameter(java.lang.String)

getInvalidSubmitParameterName

protected String getInvalidSubmitParameterName()

Return the name of the render parameter that indicates this was an invalid form submission.

Returns:: the name of the render parameter
See Also:: PortletRequest.getParameter(java.lang.String)

setFormSubmit

protected final void setFormSubmit(ActionResponse response)

Set the action response parameter that indicates this in a form submission.

Parameters:: response - the current action response
See Also:: getFormSubmitParameterName()

setInvalidSubmit

protected final void setInvalidSubmit(ActionResponse response)

Set the action response parameter that indicates this in an invalid submission.

Parameters:: response - the current action response
See Also:: getInvalidSubmitParameterName()

getFormSessionAttributeName

protected String getFormSessionAttributeName(PortletRequest request)

Return the name of the PortletSession attribute that holds the form object for this form controller.

Default implementation delegates to the getFormSessionAttributeName version without arguments.

Parameters:: request - current HTTP request
Returns:: the name of the form session attribute, or null if not in session form mode
See Also:: getFormSessionAttributeName(javax.portlet.PortletRequest), PortletSession.getAttribute(java.lang.String)

getFormSessionAttributeName

protected String getFormSessionAttributeName()

Return the name of the PortletSession attribute that holds the form object for this form controller.

Default is an internal name, of no relevance to applications, as the form session attribute is not usually accessed directly. Can be overridden to use an application-specific attribute name, which allows other code to access the session attribute directly.

Returns:: the name of the form session attribute
See Also:: PortletSession.getAttribute(java.lang.String)

passRenderParameters

protected void passRenderParameters(ActionRequest request,
                                    ActionResponse response)

Pass the specified list of action request parameters to the render phase by putting them into the action response object. This may not be called when the action will call will call sendRedirect.

Parameters:: request - the current action request; response - the current action response
See Also:: ActionResponse.setRenderParameter(java.lang.String, java.lang.String)

showNewForm

protected final ModelAndView showNewForm(RenderRequest request,
                                         RenderResponse response)
                                  throws Exception

Show a new form. Prepares a backing object for the current form and the given request, including checking its validity.

Parameters:: request - current render request; response - current render response
Returns:: the prepared form view
Throws:: Exception - in case of an invalid new form object
See Also:: getErrorsForNewForm(javax.portlet.RenderRequest)

getErrorsForNewForm

protected final BindException getErrorsForNewForm(RenderRequest request)
                                           throws Exception

Create a BindException instance for a new form. Called by showNewForm.

Can be used directly when intending to show a new form but with special errors registered on it (for example, on invalid submit). Usually, the resulting BindException will be passed to showForm, after registering the errors on it.

Parameters:: request - current render request
Returns:: the BindException instance
Throws:: Exception - in case of an invalid new form object

onBindOnNewForm

protected void onBindOnNewForm(RenderRequest request,
                               Object command,
                               BindException errors)
                        throws Exception

Callback for custom post-processing in terms of binding for a new form. Called when preparing a new form if bindOnNewForm is true.

Default implementation delegates to onBindOnNewForm(request, command).

Parameters:: request - current render request; command - the command object to perform further binding on; errors - validation errors holder, allowing for additional custom registration of binding errors
Throws:: Exception - in case of invalid state or arguments
See Also:: onBindOnNewForm(RenderRequest, Object), setBindOnNewForm(boolean)

onBindOnNewForm

protected void onBindOnNewForm(RenderRequest request,
                               Object command)
                        throws Exception

Callback for custom post-processing in terms of binding for a new form. Called by the default implementation of the onBindOnNewForm version with all parameters, after standard binding when displaying the form view. Only called if bindOnNewForm is set to true.

Default implementation is empty.

Parameters:: request - current render request; command - the command object to perform further binding on
Throws:: Exception - in case of invalid state or arguments
See Also:: onBindOnNewForm(RenderRequest, Object, BindException), setBindOnNewForm(boolean)

getCommand

protected final Object getCommand(PortletRequest request)
                           throws Exception

Return the form object for the given request.

Calls formBackingObject if the object is not in the session

Overrides:: getCommand in class BaseCommandController

Parameters:: request - current request
Returns:: object form to bind onto
Throws:: Exception
See Also:: formBackingObject(javax.portlet.PortletRequest)

formBackingObject

protected Object formBackingObject(PortletRequest request)
                            throws Exception

Retrieve a backing object for the current form from the given request.

The properties of the form object will correspond to the form field values in your form view. This object will be exposed in the model under the specified command name, to be accessed under that name in the view: for example, with a "spring:bind" tag. The default command name is "command".

Note that you need to activate session form mode to reuse the form-backing object across the entire form workflow. Else, a new instance of the command class will be created for each submission attempt, just using this backing object as template for the initial form.

Default implementation calls BaseCommandController.createCommand, creating a new empty instance of the command class. Subclasses can override this to provide a preinitialized backing object.

Parameters:: request - current portlet request
Returns:: the backing object
Throws:: Exception - in case of invalid state or arguments
See Also:: BaseCommandController.setCommandName(java.lang.String), BaseCommandController.setCommandClass(java.lang.Class), BaseCommandController.createCommand()

showForm

protected abstract ModelAndView showForm(RenderRequest request,
                                         RenderResponse response,
                                         BindException errors)
                                  throws Exception

Prepare the form model and view, including reference and error data. Can show a configured form page, or generate a form view programmatically.

A typical implementation will call showForm(request, errors, "myView") to prepare the form view for a specific view name, returning the ModelAndView provided there.

For building a custom ModelAndView, 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. You also need to include the model returned by referenceData.

Note: If you decide to have a "formView" property specifying the view name, consider using SimpleFormController.

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:: showForm(RenderRequest, BindException, String), Errors, BindException.getModel(), referenceData(PortletRequest, Object, Errors), SimpleFormController.setFormView(java.lang.String)

showForm

protected final ModelAndView showForm(RenderRequest request,
                                      BindException errors,
                                      String viewName)
                               throws Exception

Prepare model and view for the given form, including reference and errors.

In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by getCommand.

Can be used in subclasses to redirect back to a specific form page.

Parameters:: request - current render request; errors - validation errors holder; viewName - name of the form view
Returns:: the prepared form view
Throws:: Exception - in case of invalid state or arguments
See Also:: showForm(RenderRequest, BindException, String, Map), showForm(RenderRequest, RenderResponse, BindException)

showForm

protected final ModelAndView showForm(RenderRequest request,
                                      BindException errors,
                                      String viewName,
                                      Map controlModel)
                               throws Exception

Prepare model and view for the given form, including reference and errors, adding a controller-specific control model.

In session form mode: Re-puts the form object in the session when returning to the form, as it has been removed by getCommand.

Can be used in subclasses to redirect back to a specific form page.

Parameters:: request - current render request; errors - validation errors holder; viewName - name of the form view; 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:: showForm(RenderRequest, BindException, String), showForm(RenderRequest, RenderResponse, BindException)

referenceData

protected Map referenceData(PortletRequest request,
                            Object command,
                            Errors errors)
                     throws Exception

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

Default implementation returns null. Subclasses can override this to set reference data used in the view.

Parameters:: request - current render 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

renderFormSubmission

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

Process render phase of form submission request. Called by handleRequestInternal in case of a form submission, with or without binding errors. Implementations need to proceed properly, typically showing a form view in case of binding errors or rendering the result of a submit action else.

For a success view, 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. For a form view, simply return the ModelAndView object privded by showForm.

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:: handleRenderRequestInternal(javax.portlet.RenderRequest, javax.portlet.RenderResponse), processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException), isFormSubmission(javax.portlet.PortletRequest), showForm(RenderRequest, RenderResponse, BindException), Errors, BindException.getModel()

processFormSubmission

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

Process action phase of form submission request. Called by handleRequestInternal in case of a form submission, with or without binding errors. Implementations need to proceed properly, typically performing a submit action if there are no binding errors.

Subclasses can implement this to provide custom submission handling like triggering a custom action. They can also provide custom validation or proceed with the submission accordingly.

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:: handleActionRequestInternal(javax.portlet.ActionRequest, javax.portlet.ActionResponse), renderFormSubmission(javax.portlet.RenderRequest, javax.portlet.RenderResponse, java.lang.Object, org.springframework.validation.BindException), isFormSubmission(javax.portlet.PortletRequest), Errors

renderInvalidSubmit

protected ModelAndView renderInvalidSubmit(RenderRequest request,
                                           RenderResponse response)
                                    throws Exception

Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

Default implementation simply tries to resubmit the form with a new form object. This should also work if the user hit the back button, changed some form data, and resubmitted the form.

Note: To avoid duplicate submissions, you need to override this method. Either show some "invalid submit" message, or call showNewForm for resetting the form (prepopulating it with the current values if "bindOnNewForm" is true). In this case, the form object in the session serves as transaction token.

 protected ModelAndView handleInvalidSubmit(RenderRequest request, RenderResponse response) throws Exception {
   return showNewForm(request, response);
 }

You can also show a new form but with special errors registered on it:

 protected ModelAndView handleInvalidSubmit(RenderRequest request, RenderResponse response) throws Exception {
   BindException errors = getErrorsForNewForm(request);
   errors.reject("duplicateFormSubmission", "Duplicate form submission");
   return showForm(request, response, errors);
 }

WARNING: If you override this method, be sure to also override the action phase version of this method so that it will not attempt to perform the resubmit action by default.

Parameters:: request - current render request; response - current render response
Returns:: a prepared view, or null if handled directly
Throws:: Exception - in case of errors
See Also:: handleInvalidSubmit(javax.portlet.ActionRequest, javax.portlet.ActionResponse)

handleInvalidSubmit

protected void handleInvalidSubmit(ActionRequest request,
                                   ActionResponse response)
                            throws Exception

Handle an invalid submit request, e.g. when in session form mode but no form object was found in the session (like in case of an invalid resubmit by the browser).

Default implementation simply tries to resubmit the form with a new form object. This should also work if the user hit the back button, changed some form data, and resubmitted the form.

Note: To avoid duplicate submissions, you need to override this method. Most likely you will simply want it to do nothing here in the action phase and diplay an appropriate error and a new form in the render phase.

 protected void handleInvalidSubmit(ActionRequest request, ActionResponse response) throws Exception {
 }

If you override this method but you do need a command object and bind errors in the render phase, be sure to call setRenderCommandAndErrors from here.

Parameters:: request - current action request; response - current action response
Throws:: Exception - in case of errors
See Also:: renderInvalidSubmit(javax.portlet.RenderRequest, javax.portlet.RenderResponse), BaseCommandController.setRenderCommandAndErrors(javax.portlet.ActionRequest, java.lang.Object, org.springframework.validation.BindException)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

The Spring Framework

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

name	default	description
bindOnNewForm	false	Indicates whether to bind portlet request parameters when creating a new form. Otherwise, the parameters will only be bound on form submission attempts.
sessionForm	false	Indicates whether the form object should be kept in the session when a user asks for a new form. This allows you e.g. to retrieve an object from the database, let the user edit it, and then persist it again. Otherwise, a new command object will be created for each request (even when showing the form again after validation errors).
redirectAction	false	Specifies whether `processFormSubmission` is expected to call `ActionResponse.sendRedirect`. This is important because some methods may not be called before `ActionResponse.sendRedirect` (e.g. `ActionResponse.setRenderParameter`). Setting this flag will prevent AbstractFormController from setting render parameters that it normally needs for the render phase. If this is set true and `sendRedirect` is not called, then `processFormSubmission` must call `setFormSubmit`. Otherwise, the render phase will not realize the form was submitted and will simply display a new blank form.
renderParameters	null	An array of parameters that will be passed forward from the action phase to the render phase if the form needs to be displayed again. These can also be passed forward explicitly by calling the `passRenderParameters` method from any action phase method. Abstract descendants of this controller should follow similar behavior. If there are parameters you need in `renderFormSubmission`, then you need to pass those forward from `processFormSubmission`. If you override the default behavior of invalid submits and you set sessionForm to true, then you probably will not need to set this because your parameters are only going to be needed on the first request.

AbstractFormController (Spring Framework API 2.1) - Spring Framework 2.1.0 API 文档英文版

org.springframework.web.portlet.mvc Class AbstractFormController

AbstractFormController

setBindOnNewForm

isBindOnNewForm

setSessionForm

isSessionForm

setRedirectAction

isRedirectAction

setRenderParameters

getRenderParameters

handleActionRequestInternal

handleRenderRequestInternal

isFormSubmission

isInvalidSubmission

getFormSubmitParameterName

getInvalidSubmitParameterName

setFormSubmit

setInvalidSubmit

getFormSessionAttributeName

getFormSessionAttributeName

passRenderParameters

showNewForm

getErrorsForNewForm

onBindOnNewForm

onBindOnNewForm

getCommand

formBackingObject

showForm

showForm

showForm

referenceData

renderFormSubmission

processFormSubmission

renderInvalidSubmit

handleInvalidSubmit

org.springframework.web.portlet.mvc
Class AbstractFormController