|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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
public class SimpleFormController
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):
processFormSubmission
which inspects
the Errors
object to see if
any errors have occurred during binding and validation.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.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. |
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(PortletRequest request)
Determine whether the given request is a form change request. |
protected void |
onFormChange(ActionRequest request,
ActionResponse response,
Object command)
Simpler onFormChange variant, called by the full version
onFormChange(request, response, command, errors) . |
protected void |
onFormChange(ActionRequest request,
ActionResponse response,
Object command,
BindException errors)
Called during form submission if isFormChangeRequest(PortletRequest)
returns true . |
protected void |
onSubmitAction(ActionRequest request,
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(RenderRequest request,
RenderResponse response,
Object command,
BindException errors)
Submit render phase callback with all parameters. |
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. |
protected Map |
referenceData(PortletRequest request)
Create a reference data map for the given request. |
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 ModelAndView |
renderFormSubmission(RenderRequest request,
RenderResponse response,
Object command,
BindException errors)
This implementation calls showForm in case of errors,
and delegates to onSubmitRender |
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(RenderRequest request,
RenderResponse response,
BindException errors)
This implementation shows the configured form view, delegating to the analogous showForm version with a controlModel argument. |
protected ModelAndView |
showForm(RenderRequest request,
RenderResponse response,
BindException errors,
Map controlModel)
This implementation shows the configured form view. |
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. |
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 |
---|
public 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.
Method Detail |
---|
public final void setFormView(String formView)
public final String getFormView()
public final void setSuccessView(String successView)
public final String getSuccessView()
protected ModelAndView showForm(RenderRequest request, RenderResponse response, BindException errors) throws Exception
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).
showForm
in class AbstractFormController
request
- current render requestresponse
- current render responseerrors
- validation errors holder
Exception
- in case of invalid state or argumentssetFormView(java.lang.String)
,
showForm(RenderRequest, RenderResponse, BindException, Map)
protected ModelAndView showForm(RenderRequest request, RenderResponse response, BindException errors, Map controlModel) throws Exception
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.
request
- current render requesterrors
- validation errors holdercontrolModel
- model map containing controller-specific control data
(e.g. current page in wizard-style controllers or special error message)
Exception
- in case of invalid state or argumentssetFormView(java.lang.String)
protected Map referenceData(PortletRequest request, Object command, Errors errors) throws Exception
Default implementation delegates to referenceData(request). Subclasses can override this to set reference data used in the view.
referenceData
in class AbstractFormController
request
- current portlet requestcommand
- form object with request parameters bound onto iterrors
- validation errors holder
Exception
- in case of invalid state or argumentsModelAndView
protected Map referenceData(PortletRequest request) throws Exception
Default implementation returns null. Subclasses can override this to set reference data used in the view.
request
- current portlet request
Exception
- in case of invalid state or argumentsreferenceData(PortletRequest, Object, Errors)
,
ModelAndView
protected ModelAndView renderFormSubmission(RenderRequest request, RenderResponse response, Object command, BindException errors) throws Exception
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 requestresponse
- current render responsecommand
- form object with request parameters bound onto iterrors
- 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)
protected void processFormSubmission(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
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
.
processFormSubmission
in class AbstractFormController
request
- current action requestresponse
- current action responsecommand
- form object with request parameters bound onto iterrors
- errors holder (subclass can add errors if it wants to)
Exception
- in case of errorsshowForm(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)
protected boolean suppressValidation(PortletRequest request)
isFormChangeRequest
:
A form change request changes the appearance of the form
and should not get validated but just show the new form.
suppressValidation
in class BaseCommandController
request
- current portlet request
isFormChangeRequest(javax.portlet.PortletRequest)
protected boolean isFormChangeRequest(PortletRequest request)
Gets called by suppressValidation and processFormSubmission. Consequently, this single method determines to suppress validation and to show the form view in any case.
request
- current portlet request
suppressValidation(javax.portlet.PortletRequest)
,
processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
protected void onFormChange(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
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)
.
request
- current action requestresponse
- current action responsecommand
- form object with request parameters bound onto iterrors
- validation errors holder, allowing for additional
custom validation
Exception
- in case of errorsisFormChangeRequest(PortletRequest)
,
onFormChange(ActionRequest, ActionResponse, Object)
protected void onFormChange(ActionRequest request, ActionResponse response, Object command) throws Exception
onFormChange
variant, called by the full version
onFormChange(request, response, command, errors)
.
Default implementation is empty.
request
- current action requestresponse
- current action responsecommand
- form object with request parameters bound onto it
Exception
- in case of errorsonFormChange(ActionRequest, ActionResponse, Object, BindException)
protected ModelAndView onSubmitRender(RenderRequest request, RenderResponse response, Object command, BindException errors) throws Exception
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.
request
- current render requestresponse
- current render responsecommand
- form object with request parameters bound onto iterrors
- Errors instance without errors (subclass can add errors if it wants to)
Exception
- in case of errorsonSubmitAction(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()
protected void onSubmitAction(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
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.
request
- current action requestresponse
- current action responsecommand
- form object with request parameters bound onto iterrors
- Errors instance without errors (subclass can add errors if it wants to)
Exception
- in case of errorsonSubmitRender(RenderRequest, RenderResponse, Object, BindException)
,
onSubmitAction(Object, BindException)
,
doSubmitAction(java.lang.Object)
,
Errors
protected ModelAndView onSubmitRender(Object command, BindException errors) throws Exception
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.
command
- form object with request parameters bound onto iterrors
- Errors instance without errors
Exception
- in case of errorsonSubmitRender(RenderRequest, RenderResponse, Object, BindException)
,
onSubmitRender(Object)
,
onSubmitAction(Object, BindException)
,
setSuccessView(java.lang.String)
,
Errors
,
BindException.getModel()
protected void onSubmitAction(Object command, BindException errors) throws Exception
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.
command
- form object with request parameters bound onto iterrors
- Errors instance without errors
Exception
- in case of errorsonSubmitAction(ActionRequest, ActionResponse, Object, BindException)
,
onSubmitAction(Object)
,
onSubmitRender(Object, BindException)
,
Errors
protected ModelAndView onSubmitRender(Object command) throws Exception
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.
command
- form object with request parameters bound onto it
Exception
- in case of errorsonSubmitRender(Object, BindException)
,
onSubmitAction(Object)
,
doSubmitAction(java.lang.Object)
,
setSuccessView(java.lang.String)
protected void onSubmitAction(Object command) throws Exception
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.
command
- form object with request parameters bound onto it
Exception
- in case of errorsonSubmitAction(Object, BindException)
,
onSubmitRender(Object)
,
doSubmitAction(java.lang.Object)
protected void doSubmitAction(Object command) throws Exception
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.
command
- form object with request parameters bound onto it
Exception
- in case of errorsonSubmitAction(Object)
,
onSubmitRender(Object)
,
setSuccessView(java.lang.String)
|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |