| org.springframework.web.servlet.mvc.AbstractController
 org.springframework.web.servlet.mvc.BaseCommandController
org.springframework.web.servlet.mvc.AbstractFormController
All known Subclasses: org.springframework.web.servlet.mvc.SimpleFormController, org.springframework.web.servlet.mvc.AbstractWizardFormController,
| AbstractFormController | | abstract public class AbstractFormController extends BaseCommandController (Code) | | 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 SimpleFormController and
AbstractWizardFormController 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 SimpleFormController .
Subclasses need to override showForm to prepare the form view,
and processFormSubmission to handle submit requests. For the latter,
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.PropertyEditor. For more information on that
subject, see the workflow of this controller and the explanation of the
BaseCommandController BaseCommandController .
Workflow
(and that defined by superclass):
- The controller receives a request for a new form (typically a GET).
- Call to
AbstractFormController.formBackingObject 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
AbstractFormController.initBinder 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.
- Only if
bindOnNewForm is set to true, then
org.springframework.web.bind.ServletRequestDataBinder ServletRequestDataBinder gets applied to populate the new form object with initial request parameters and the
AbstractFormController.onBindOnNewForm(HttpServletRequest,Object,BindException) callback method is
called. Note: any defined Validators are not applied at this point, to allow
partial binding. However be aware that any Binder customizations applied via
initBinder() (such as
org.springframework.validation.DataBinder.setRequiredFields(String[]) will
still apply. As such, if using bindOnNewForm=true and initBinder() customizations are
used to validate fields instead of using Validators, in the case that only some fields
will be populated for the new form, there will potentially be some bind errors for
missing fields in the errors object. Any view (JSP, etc.) that displays binder errors
needs to be intelligent and for this case take into account whether it is displaying the
initial form view or subsequent post results, skipping error display for the former.
- Call to
AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException) 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
AbstractFormController.referenceData 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 a POST).
To use a different way of detecting a form submission, override the
AbstractFormController.isFormSubmission isFormSubmission method.
- If
sessionForm is not set,
AbstractFormController.formBackingObject 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, it does a call to
AbstractFormController.handleInvalidSubmit handleInvalidSubmit which - by default - tries to create a new form object and resubmit the form.
- The
org.springframework.web.bind.ServletRequestDataBinder ServletRequestDataBinder gets applied to populate the form object with current request parameters.
- Call to
AbstractFormController.onBind onBind(HttpServletRequest, 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
org.springframework.validation.Errors Errors object.
- Call to
AbstractFormController.onBindAndValidate 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
AbstractFormController.processFormSubmission(HttpServletRequest,HttpServletResponse,Object,BindException) processFormSubmission() to process the submission, with
or without binding errors. This method has to be implemented in subclasses.
In session form mode, a submission without an existing form object in the
session is considered invalid, like in case of a resubmit/reload by the browser.
The
AbstractFormController.handleInvalidSubmit handleInvalidSubmit method is invoked then,
by default trying to resubmit. It 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.
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 servlet 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). |
author:
Rod Johnson
author:
Juergen Hoeller
author:
Alef Arendsen
author:
Rob Harrop
author:
Colin Sampaleanu
See Also: AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException)
See Also: AbstractFormController.processFormSubmission
See Also: SimpleFormController
See Also: AbstractWizardFormController |
| Method Summary | |
| protected Object | currentFormObject(HttpServletRequest request, Object sessionFormObject)
Return the current form object to use for binding and further processing,
based on the passed-in form object as found in the HttpSession. | | protected Object | formBackingObject(HttpServletRequest request)
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. | | final protected Object | getCommand(HttpServletRequest request)
Return the form object for the given request.
Calls
AbstractFormController.formBackingObject if not in session form mode.
Else, retrieves the form object from the session. | | final protected BindException | getErrorsForNewForm(HttpServletRequest request)
Create a BindException instance for a new form. | | protected String | getFormSessionAttributeName(HttpServletRequest request)
Return the name of the HttpSession attribute that holds the form object
for this form controller. | | protected String | getFormSessionAttributeName()
Return the name of the HttpSession 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. | | protected ModelAndView | handleInvalidSubmit(HttpServletRequest request, HttpServletResponse response)
Handle an invalid submit request, e.g. | | protected ModelAndView | handleRequestInternal(HttpServletRequest request, HttpServletResponse response)
Handles two cases: form submissions and showing a new form. | | final public boolean | isBindOnNewForm()
Return if request parameters should be bound in case of a new form. | | protected boolean | isFormSubmission(HttpServletRequest request)
Determine if the given request represents a form submission.
The default implementation treats a POST request as form submission.
Note: If the form session attribute doesn't exist when using session form
mode, the request is always treated as new form by handleRequestInternal.
Subclasses can override this to use a custom strategy, e.g. | | final public boolean | isSessionForm()
Return if session form mode is activated. | | protected void | onBindOnNewForm(HttpServletRequest request, Object command, BindException errors)
Callback for custom post-processing in terms of binding for a new form. | | protected void | onBindOnNewForm(HttpServletRequest request, Object command)
Callback for custom post-processing in terms of binding for a new form. | | abstract protected ModelAndView | processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors)
Process form submission request. | | protected Map | referenceData(HttpServletRequest 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. | | final public void | setBindOnNewForm(boolean bindOnNewForm)
Set if request parameters should be bound to the form object
in case of a non-submitting request, i.e. | | final public void | setSessionForm(boolean sessionForm)
Activate resp. | | abstract protected ModelAndView | showForm(HttpServletRequest request, HttpServletResponse response, BindException errors)
Prepare the form model and view, including reference and error data. | | final protected ModelAndView | showForm(HttpServletRequest request, BindException errors, String viewName)
Prepare model and view for the given form, including reference and errors. | | final protected ModelAndView | showForm(HttpServletRequest 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.
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 HTTP request
Parameters:
errors - validation errors holder
Parameters:
viewName - name of the form view
Parameters:
controlModel - model map containing controller-specific control data(e.g. | | final protected ModelAndView | showNewForm(HttpServletRequest request, HttpServletResponse response)
Show a new form. |
| currentFormObject | | protected Object currentFormObject(HttpServletRequest request, Object sessionFormObject) throws Exception(Code) | | Return the current form object to use for binding and further processing,
based on the passed-in form object as found in the HttpSession.
The default implementation simply returns the session form object as-is.
Subclasses can override this to post-process the session form object,
for example reattaching it to a persistence manager.
Parameters:
sessionFormObject - the form object retrieved from the HttpSession the form object to use for binding and further processing
throws:
Exception - in case of invalid state or arguments |
| formBackingObject | | protected Object formBackingObject(HttpServletRequest request) throws Exception(Code) | | 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.
The default implementation calls
AbstractFormController.createCommand() ,
creating a new empty instance of the specified command class.
Subclasses can override this to provide a preinitialized backing object.
Parameters:
request - current HTTP request the backing object
throws:
Exception - in case of invalid state or arguments
See Also: AbstractFormController.setCommandName
See Also: AbstractFormController.setCommandClass
See Also: AbstractFormController.createCommand |
| getFormSessionAttributeName | | protected String getFormSessionAttributeName()(Code) | | Return the name of the HttpSession 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.
the name of the form session attribute
See Also: javax.servlet.http.HttpSession.getAttribute |
| handleInvalidSubmit | | protected ModelAndView handleInvalidSubmit(HttpServletRequest request, HttpServletResponse response) throws Exception(Code) | | 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).
The 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
AbstractFormController.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(HttpServletRequest request, HttpServletResponse response) throws Exception {
return showNewForm(request, response);
}
You can also show a new form but with special errors registered on it:
protected ModelAndView handleInvalidSubmit(HttpServletRequest request, HttpServletResponse response) throws Exception {
BindException errors = getErrorsForNewForm(request);
errors.reject("duplicateFormSubmission", "Duplicate form submission");
return showForm(request, response, errors);
}
Parameters:
request - current HTTP request
Parameters:
response - current HTTP response a prepared view, or null if handled directly
throws:
Exception - in case of errors
See Also: AbstractFormController.showNewForm
See Also: AbstractFormController.getErrorsForNewForm
See Also: AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException)
See Also: AbstractFormController.setBindOnNewForm |
| isBindOnNewForm | | final public boolean isBindOnNewForm()(Code) | | Return if request parameters should be bound in case of a new form.
|
| isFormSubmission | | protected boolean isFormSubmission(HttpServletRequest request)(Code) | | Determine if the given request represents a form submission.
The default implementation treats a POST request as form submission.
Note: If the form session attribute doesn't exist when using session form
mode, the request is always treated as new form by handleRequestInternal.
Subclasses can override this to use a custom strategy, e.g. a specific
request parameter (assumably a hidden field or submit button name).
Parameters:
request - current HTTP request if the request represents a form submission |
| isSessionForm | | final public boolean isSessionForm()(Code) | | Return if session form mode is activated.
|
| processFormSubmission | | abstract protected ModelAndView processFormSubmission(HttpServletRequest request, HttpServletResponse response, Object command, BindException errors) throws Exception(Code) | | Process form submission request. Called by
AbstractFormController.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 performing a submit action else.
Subclasses can implement this to provide custom submission handling like
triggering a custom action. They can also provide custom validation and call
AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException) or proceed with the submission accordingly.
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 provided by
AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException) .
Parameters:
request - current servlet request
Parameters:
response - current servlet response
Parameters:
command - form object with request parameters bound onto it
Parameters:
errors - holder without errors (subclass can add errors if it wants to) the prepared model and view, or null
throws:
Exception - in case of errors
See Also: AbstractFormController.handleRequestInternal
See Also: AbstractFormController.isFormSubmission
See Also: AbstractFormController.showForm(HttpServletRequest,HttpServletResponse,BindException)
See Also: org.springframework.validation.Errors
See Also: org.springframework.validation.BindException.getModel |
| referenceData | | protected Map referenceData(HttpServletRequest request, Object command, Errors errors) throws Exception(Code) | | Create a reference data map for the given request, consisting of
bean name/bean instance pairs as expected by ModelAndView.
The default implementation returns null.
Subclasses can override this to set reference data used in the view.
Parameters:
request - current HTTP request
Parameters:
command - form object with request parameters bound onto it
Parameters:
errors - validation errors holder a Map with reference data entries, or null if none
throws:
Exception - in case of invalid state or arguments
See Also: ModelAndView |
| setBindOnNewForm | | final public void setBindOnNewForm(boolean bindOnNewForm)(Code) | | Set if request parameters should be bound to the form object
in case of a non-submitting request, i.e. a new form.
|
| setSessionForm | | final public void setSessionForm(boolean sessionForm)(Code) | | Activate resp. 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.
|
| showForm | | abstract protected ModelAndView showForm(HttpServletRequest request, HttpServletResponse response, BindException errors) throws Exception(Code) | | 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
AbstractFormController.referenceData .
Note: If you decide to have a "formView" property specifying the
view name, consider using SimpleFormController.
Parameters:
request - current HTTP request
Parameters:
response - current HTTP response
Parameters:
errors - validation errors holder the prepared form view, or null if handled directly
throws:
Exception - in case of invalid state or arguments
See Also: AbstractFormController.showForm(HttpServletRequest,BindException,String)
See Also: org.springframework.validation.Errors
See Also: org.springframework.validation.BindException.getModel
See Also: AbstractFormController.referenceData(HttpServletRequest,Object,Errors)
See Also: SimpleFormController.setFormView |
| showForm | | final protected ModelAndView showForm(HttpServletRequest request, BindException errors, String viewName) throws Exception(Code) | | 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 HTTP request
Parameters:
errors - validation errors holder
Parameters:
viewName - name of the form view the prepared form view
throws:
Exception - in case of invalid state or arguments |
| showForm | | final protected ModelAndView showForm(HttpServletRequest request, BindException errors, String viewName, Map controlModel) throws Exception(Code) | | 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 HTTP request
Parameters:
errors - validation errors holder
Parameters:
viewName - name of the form view
Parameters:
controlModel - model map containing controller-specific control data(e.g. current page in wizard-style controllers or special error message) the prepared form view
throws:
Exception - in case of invalid state or arguments |
| Fields inherited from org.springframework.web.servlet.mvc.BaseCommandController | final public static String DEFAULT_COMMAND_NAME(Code)(Java Doc)
|
| Methods inherited from org.springframework.web.servlet.mvc.BaseCommandController | final protected ServletRequestDataBinder bindAndValidate(HttpServletRequest request, Object command) throws Exception(Code)(Java Doc)
final protected boolean checkCommand(Object command)(Code)(Java Doc)
protected ServletRequestDataBinder createBinder(HttpServletRequest request, Object command) throws Exception(Code)(Java Doc)
final protected Object createCommand() throws Exception(Code)(Java Doc)
final public BindingErrorProcessor getBindingErrorProcessor()(Code)(Java Doc)
protected Object getCommand(HttpServletRequest request) throws Exception(Code)(Java Doc)
final public Class getCommandClass()(Code)(Java Doc)
final public String getCommandName()(Code)(Java Doc)
final public MessageCodesResolver getMessageCodesResolver()(Code)(Java Doc)
final public PropertyEditorRegistrar[] getPropertyEditorRegistrars()(Code)(Java Doc)
final public Validator getValidator()(Code)(Java Doc)
final public Validator[] getValidators()(Code)(Java Doc)
protected void initApplicationContext()(Code)(Java Doc)
protected void initBinder(HttpServletRequest request, ServletRequestDataBinder binder) throws Exception(Code)(Java Doc)
final public boolean isValidateOnBinding()(Code)(Java Doc)
protected void onBind(HttpServletRequest request, Object command, BindException errors) throws Exception(Code)(Java Doc)
protected void onBind(HttpServletRequest request, Object command) throws Exception(Code)(Java Doc)
protected void onBindAndValidate(HttpServletRequest request, Object command, BindException errors) throws Exception(Code)(Java Doc)
final protected void prepareBinder(ServletRequestDataBinder binder)(Code)(Java Doc)
final public void setBindingErrorProcessor(BindingErrorProcessor bindingErrorProcessor)(Code)(Java Doc)
final public void setCommandClass(Class commandClass)(Code)(Java Doc)
final public void setCommandName(String commandName)(Code)(Java Doc)
final public void setMessageCodesResolver(MessageCodesResolver messageCodesResolver)(Code)(Java Doc)
final public void setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar)(Code)(Java Doc)
final public void setPropertyEditorRegistrars(PropertyEditorRegistrar[] propertyEditorRegistrars)(Code)(Java Doc)
final public void setValidateOnBinding(boolean validateOnBinding)(Code)(Java Doc)
final public void setValidator(Validator validator)(Code)(Java Doc)
final public void setValidators(Validator[] validators)(Code)(Java Doc)
protected boolean suppressBinding(HttpServletRequest request)(Code)(Java Doc)
protected boolean suppressValidation(HttpServletRequest request, Object command, BindException errors)(Code)(Java Doc)
protected boolean suppressValidation(HttpServletRequest request, Object command)(Code)(Java Doc)
protected boolean suppressValidation(HttpServletRequest request)(Code)(Java Doc)
protected boolean useDirectFieldAccess()(Code)(Java Doc)
|
|
|