Java Doc for SimpleFormController.java in  » J2EE » spring-framework-2.0.6 » org » springframework » web » portlet » mvc » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 AbstractFormController . The difference is that you do not need to implement SimpleFormController.showForm showForm , SimpleFormController.processFormSubmission processFormSubmission , and SimpleFormController.renderFormSubmission 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 SimpleFormController.processFormSubmission processFormSubmission which inspects the org.springframework.validation.Errors 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 SimpleFormController.isFormChangeRequest 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 SimpleFormController.onFormChange , 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 SimpleFormController.onSubmitAction(ActionRequest,ActionResponse,Object,BindException) onSubmitAction during the action phase and then SimpleFormController.onSubmitRender(RenderRequest,RenderResponse,Object,BindException) onSubmitRender during the render phase, which in case of the default implementation delegate to SimpleFormController.onSubmitAction(Object,BindException)onSubmitAction and SimpleFormController.onSubmitRender(Object,BindException) onSubmitRender with just the command object. The default implementation of the latter method will return the configured successView. Consider just implementing SimpleFormController.doSubmitAction 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 SimpleFormController.onSubmitAction onSubmitAction or SimpleFormController.onSubmitRender onSubmitRender methods. Submit actions can also perform custom validation if necessary (typically database-driven checks), calling SimpleFormController.showForm(RenderRequest,RenderResponse,BindException) 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 SimpleFormController.onSubmitAction onSubmitAction method or the SimpleFormController.doSubmitAction doSubmitAction method. Logic in the SimpleFormController.onSubmitRender 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 SimpleFormController.onSubmitRender(Object) 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!
author:
   John A. Lewis
author:
   Juergen Hoeller
author:
   Rob Harrop
since:
   2.0

Constructor Summary
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.

Method Summary
protected  void	doSubmitAction(Object command)      Template method for submit actions.
final public  String	getFormView()      Return the name of the view that should be used for form display.
final public  String	getSuccessView()      Return the name of the view that should be shown on successful submit.
protected  boolean	isFormChangeRequest(PortletRequest request)      Determine whether the given request is a form change request.
protected  void	onFormChange(ActionRequest request, ActionResponse response, Object command, BindException errors)      Called during form submission if SimpleFormController.isFormChangeRequest(PortletRequest) returns true.
protected  void	onFormChange(ActionRequest request, ActionResponse response, Object command)      Simpler onFormChange variant, called by the full version onFormChange(request, response, command, errors).
protected  void	onSubmitAction(ActionRequest request, ActionResponse response, Object command, BindException errors)      Submit action phase callback with all parameters.
protected  void	onSubmitAction(Object command, BindException errors)      Simpler onSubmitAction version.
protected  void	onSubmitAction(Object command)      Simplest onSubmitAction version.
protected  ModelAndView	onSubmitRender(RenderRequest request, RenderResponse response, Object command, BindException errors)      Submit render phase callback with all parameters.
protected  ModelAndView	onSubmitRender(Object command, BindException errors)      Simpler onSubmitRender version.
protected  ModelAndView	onSubmitRender(Object command)      Simplest onSubmitRender version.
protected  void	processFormSubmission(ActionRequest request, ActionResponse response, Object command, BindException errors)      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.
protected  Map	referenceData(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  Map	referenceData(PortletRequest request)      Create a reference data map for the given request.
protected  ModelAndView	renderFormSubmission(RenderRequest request, RenderResponse response, Object command, BindException errors)      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.
final public  void	setFormView(String formView)      Set the name of the view that should be used for form display.
final public  void	setSuccessView(String successView)      Set the name of the view that should be shown on successful submit.
protected  ModelAndView	showForm(RenderRequest request, RenderResponse response, BindException errors)      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.
protected  ModelAndView	showForm(RenderRequest request, RenderResponse response, BindException errors, Map controlModel)      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.
protected  boolean	suppressValidation(PortletRequest request)      This implementation delegates to isFormChangeRequest: A form change request changes the appearance of the form and should not get validated but just show the new form.

Constructor Detail

SimpleFormController
public SimpleFormController()(Code)
	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:   SimpleFormController.setCommandClass(Class) See Also:   SimpleFormController.setCommandName(String) See Also:   SimpleFormController.setSessionForm(boolean) See Also:   SimpleFormController.setFormView See Also:   SimpleFormController.setSuccessView See Also:   SimpleFormController.formBackingObject(PortletRequest)