|
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.AbstractWizardFormController
public abstract class AbstractWizardFormController
Form controller for typical wizard-style workflows.
In contrast to classic forms, wizards have more than one form view page. Therefore, there are various actions instead of one single submit action:
Finish and cancel actions can be triggered by request parameters, named PARAM_FINISH ("_finish") and PARAM_CANCEL ("_cancel"), ignoring parameter values to allow for HTML buttons. The target page for page changes can be specified by PARAM_TARGET, appending the page number to the parameter name (e.g. "_target1"). The action parameters are recognized when triggered by image buttons too (via "_finish.x", "_abort.x", or "_target1.x").
The current page number will be stored in the session. It can also be specified as request parameter PARAM_PAGE, to properly handle usage of the back button in a browser: In this case, a submission always contains the correct page number, even if the user submitted from an old view.
The page can only be changed if it validates correctly, except if a "dirty back" or "dirty forward" is allowed. At finish, all pages get validated again to guarantee a consistent state.
Note that a validator's default validate method is not executed when using
this class! Rather, the validatePage
implementation should call
special validateXXX
methods that the validator needs to provide,
validating certain pieces of the object. These can be combined to validate
the elements of individual pages.
Note: Page numbering starts with 0, to be able to pass an array consisting of the corresponding view names to the "pages" bean property.
Parameters indicated with setPassRenderParameters
will be present
for each page. If there are render parameters you need in renderFinish
or renderCancel
, then you need to pass those forward from the
processFinish
or processCancel
methods, respectively.
setPages(java.lang.String[])
,
validatePage(java.lang.Object, org.springframework.validation.Errors, int, boolean)
,
processFinish(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
,
processCancel(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
Field Summary | |
---|---|
static String |
PARAM_CANCEL
Parameter triggering the cancel action. |
static String |
PARAM_FINISH
Parameter triggering the finish action. |
static String |
PARAM_PAGE
Parameter specifying the current page as value. |
static String |
PARAM_TARGET
Parameter specifying the target page, appending the page number to the name. |
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 | |
---|---|
AbstractWizardFormController()
Create a new AbstractWizardFormController. |
Method Summary | |
---|---|
protected int |
getCurrentPage(PortletRequest request)
Return the current page number. |
protected int |
getInitialPage(PortletRequest request)
Return the initial page of the wizard, i.e. the page shown at wizard startup. |
protected int |
getInitialPage(PortletRequest request,
Object command)
Return the initial page of the wizard, i.e. the page shown at wizard startup. |
String |
getPageAttribute()
Return the name of the page attribute in the model. |
protected int |
getPageCount()
Return the number of wizard pages. |
protected int |
getPageCount(PortletRequest request,
Object command)
Return the page count for this wizard form controller. |
String[] |
getPages()
Return the wizard pages, i.e. the view names for the pages. |
protected String |
getPageSessionAttributeName()
Return the name of the PortletSession attribute that holds the page object for this wizard form controller. |
protected String |
getPageSessionAttributeName(PortletRequest request)
Return the name of the PortletSession attribute that holds the page object for this wizard form controller. |
protected int |
getTargetPage(PortletRequest request,
int currentPage)
Return the target page specified in the request. |
protected int |
getTargetPage(PortletRequest request,
Object command,
Errors errors,
int currentPage)
Return the target page specified in the request. |
protected String |
getViewName(PortletRequest request,
Object command,
int page)
Return the name of the view for the specified page of this wizard form controller. |
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). |
boolean |
isAllowDirtyBack()
Return whether "dirty back" is allowed. |
boolean |
isAllowDirtyForward()
Return whether "dirty forward" is allowed. |
protected boolean |
isCancelRequest(PortletRequest request)
Determine whether the incoming request is a request to cancel the processing of the current form. |
protected boolean |
isFinishRequest(PortletRequest request)
Determine whether the incoming request is a request to finish the processing of the current form. |
protected boolean |
isFormSubmission(PortletRequest request)
Consider an explicit finish or cancel request as a form submission too. |
protected void |
onBindAndValidate(PortletRequest request,
Object command,
BindException errors)
Calls page-specific onBindAndValidate method. |
protected void |
onBindAndValidate(PortletRequest request,
Object command,
BindException errors,
int page)
Callback for custom post-processing in terms of binding and validation. |
protected void |
postProcessPage(ActionRequest request,
Object command,
Errors errors,
int page)
Post-process the given page after binding and validation, potentially updating its command object. |
protected void |
processCancel(ActionRequest request,
ActionResponse response,
Object command,
BindException errors)
Template method for the action phase of the cancel action of this wizard. |
protected void |
processFinish(ActionRequest request,
ActionResponse response,
Object command,
BindException errors)
Template method for the action phase of the finish action of this wizard. |
protected void |
processFormSubmission(ActionRequest request,
ActionResponse response,
Object command,
BindException errors)
Apply wizard workflow: finish, cancel, page change. |
protected Map |
referenceData(PortletRequest request,
int page)
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView. |
protected Map |
referenceData(PortletRequest request,
Object command,
Errors errors)
Calls page-specific referenceData method. |
protected Map |
referenceData(PortletRequest request,
Object command,
Errors errors,
int page)
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView. |
protected ModelAndView |
renderCancel(RenderRequest request,
RenderResponse response,
Object command,
BindException errors)
Template method for the render phase of the cancel action of this wizard. |
protected ModelAndView |
renderFinish(RenderRequest request,
RenderResponse response,
Object command,
BindException errors)
Template method for the render phase of the finish action of this wizard. |
protected ModelAndView |
renderFormSubmission(RenderRequest request,
RenderResponse response,
Object command,
BindException errors)
Apply wizard workflow: finish, cancel, page change. |
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 |
setAllowDirtyBack(boolean allowDirtyBack)
Set if "dirty back" is allowed, i.e. if moving to a former wizard page is allowed in case of validation errors for the current page. |
void |
setAllowDirtyForward(boolean allowDirtyForward)
Set if "dirty forward" is allowed, i.e. if moving to a later wizard page is allowed in case of validation errors for the current page. |
protected void |
setCancelRenderParameter(ActionRequest request,
ActionResponse response)
Pass the the parameter that indicates a cancel request forward to the render phase. |
protected void |
setFinishRenderParameter(ActionRequest request,
ActionResponse response)
Pass the the parameter that indicates a finish request forward to the render phase. |
void |
setPageAttribute(String pageAttribute)
Set the name of the page attribute in the model, containing an Integer with the current page number. |
protected void |
setPageRenderParameter(ActionResponse response,
int page)
Pass the page number to the render phase by setting a render parameter. |
void |
setPages(String[] pages)
Set the wizard pages, i.e. the view names for the pages. |
protected void |
setTargetRenderParameter(ActionRequest request,
ActionResponse response)
Pass the the parameter that indicates the target page of the request forward to the render phase. |
protected ModelAndView |
showForm(RenderRequest request,
RenderResponse response,
BindException errors)
Show first page as form view. |
protected ModelAndView |
showPage(RenderRequest request,
BindException errors,
int page)
Prepare the form model and view, including reference and error data, for the given page. |
protected void |
validatePage(Object command,
Errors errors,
int page)
Template method for custom validation logic for individual pages. |
protected void |
validatePage(Object command,
Errors errors,
int page,
boolean finish)
Template method for custom validation logic for individual pages. |
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 |
Field Detail |
---|
public static final String PARAM_FINISH
public static final String PARAM_CANCEL
public static final String PARAM_TARGET
public static final String PARAM_PAGE
Constructor Detail |
---|
public AbstractWizardFormController()
"sessionForm" is automatically turned on, "validateOnBinding" turned off, and "cacheSeconds" set to 0 by the base class (-> no caching for all form controllers).
Method Detail |
---|
public final void setPages(String[] pages)
pages
- view names for the pagespublic final String[] getPages()
Note that a concrete wizard form controller might override
getViewName(PortletRequest, Object, int)
to
determine the view name for each page dynamically.
protected final int getPageCount()
Note that a concrete wizard form controller might override
getPageCount(PortletRequest, Object)
to determine
the page count dynamically.
getPageCount(PortletRequest, Object)
public final void setPageAttribute(String pageAttribute)
This will be necessary for single views rendering multiple view pages. It also allows for specifying the optional "_page" parameter.
pageAttribute
- name of the page attributePARAM_PAGE
public final String getPageAttribute()
public final void setAllowDirtyBack(boolean allowDirtyBack)
allowDirtyBack
- if "dirty back" is allowedpublic final boolean isAllowDirtyBack()
public final void setAllowDirtyForward(boolean allowDirtyForward)
allowDirtyForward
- if "dirty forward" is allowedpublic final boolean isAllowDirtyForward()
protected final void onBindAndValidate(PortletRequest request, Object command, BindException errors) throws Exception
onBindAndValidate
in class BaseCommandController
request
- current portlet requestcommand
- the command object, still allowing for further bindingerrors
- validation errors holder, allowing for additional
custom validation
Exception
- in case of invalid state or argumentsBaseCommandController.bindAndValidate(javax.portlet.PortletRequest, java.lang.Object)
,
Errors
protected void onBindAndValidate(PortletRequest request, Object command, BindException errors, int page) throws Exception
Note: AbstractWizardFormController does not perform standard validation on binding but rather applies page-specific validation on processing the form submission.
request
- current portlet requestcommand
- bound commanderrors
- Errors instance for additional custom validationpage
- current wizard page
Exception
- in case of invalid state or argumentsBaseCommandController.bindAndValidate(javax.portlet.PortletRequest, java.lang.Object)
,
processFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
,
Errors
protected boolean isFormSubmission(PortletRequest request)
isFormSubmission
in class AbstractFormController
request
- current request
isFinishRequest(PortletRequest)
,
isCancelRequest(PortletRequest)
protected final Map referenceData(PortletRequest request, Object command, Errors errors) throws Exception
referenceData
in class AbstractFormController
request
- current render 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, Object command, Errors errors, int page) throws Exception
Default implementation delegates to referenceData(HttpServletRequest, int). Subclasses can override this to set reference data used in the view.
request
- current portlet requestcommand
- form object with request parameters bound onto iterrors
- validation errors holderpage
- current wizard page
Exception
- in case of invalid state or argumentsreferenceData(PortletRequest, int)
,
ModelAndView
protected Map referenceData(PortletRequest request, int page) throws Exception
Default implementation returns null. Subclasses can override this to set reference data used in the view.
request
- current portlet requestpage
- current wizard page
Exception
- in case of invalid state or argumentsModelAndView
protected final ModelAndView showForm(RenderRequest request, RenderResponse response, BindException errors) throws Exception
showForm
in class AbstractFormController
request
- current render requestresponse
- current render responseerrors
- validation errors holder
Exception
- in case of invalid state or argumentsAbstractFormController.showForm(RenderRequest, BindException, String)
,
Errors
,
BindException.getModel()
,
AbstractFormController.referenceData(PortletRequest, Object, Errors)
,
SimpleFormController.setFormView(java.lang.String)
protected final ModelAndView showPage(RenderRequest request, BindException errors, int page) throws Exception
processFinish
implementations,
to show the corresponding page in case of validation errors.
request
- current portlet render requesterrors
- validation errors holderpage
- number of page to show
Exception
- in case of invalid state or argumentsprotected int getPageCount(PortletRequest request, Object command)
getPageCount()
.
Can be overridden to dynamically adapt the page count.
request
- current portlet requestcommand
- the command object as returned by formBackingObject
getPageCount()
protected String getViewName(PortletRequest request, Object command, int page)
getPages()
array.
Can be overridden to dynamically switch the page view or to return view names for dynamically defined pages.
request
- current portlet requestcommand
- the command object as returned by formBackingObject
getPageCount()
protected int getInitialPage(PortletRequest request, Object command)
getInitialPage(PortletRequest)
.
request
- current portlet requestcommand
- the command object as returned by formBackingObject
getInitialPage(PortletRequest)
,
AbstractFormController.formBackingObject(javax.portlet.PortletRequest)
protected int getInitialPage(PortletRequest request)
request
- current portlet request
protected String getPageSessionAttributeName(PortletRequest request)
Default implementation delegates to the getPageSessionAttributeName
version without arguments.
request
- current portlet request
getPageSessionAttributeName(javax.portlet.PortletRequest)
,
AbstractFormController.getFormSessionAttributeName(javax.portlet.PortletRequest)
,
PortletSession.getAttribute(java.lang.String)
protected String getPageSessionAttributeName()
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.
AbstractFormController.getFormSessionAttributeName(javax.portlet.PortletRequest)
,
PortletSession.getAttribute(java.lang.String)
protected void setPageRenderParameter(ActionResponse response, int page)
ActionResponse.sendRedirect(String)
.
response
- the current action responsepage
- the page numberActionResponse.setRenderParameter(java.lang.String, java.lang.String)
protected void setTargetRenderParameter(ActionRequest request, ActionResponse response)
getTargetPage method
was overridden, this may need to be overriden as well.
- Parameters:
request
- the current action requestresponse
- the current action response- See Also:
PARAM_TARGET
,
getTargetPage(PortletRequest, int)
,
getTargetPage(PortletRequest, Object, Errors, int)
,
ActionResponse.setRenderParameter(java.lang.String, java.lang.String)
protected void setFinishRenderParameter(ActionRequest request, ActionResponse response)
isFinishRequest
method
was overridden, this may need to be overriden as well.
request
- the current action requestresponse
- the current action responsePARAM_FINISH
,
isFinishRequest(javax.portlet.PortletRequest)
,
ActionResponse.setRenderParameter(java.lang.String, java.lang.String)
protected void setCancelRenderParameter(ActionRequest request, ActionResponse response)
isCancelRequest
method
was overridden, this may need to be overriden as well.
request
- the current action requestresponse
- the current action responsePARAM_CANCEL
,
isCancelRequest(javax.portlet.PortletRequest)
,
ActionResponse.setRenderParameter(java.lang.String, java.lang.String)
protected ModelAndView renderInvalidSubmit(RenderRequest request, RenderResponse response) throws Exception
Default implementation for wizard form controllers simply shows the initial page of a new wizard form. If you want to show some "invalid submit" message, you need to override this method.
renderInvalidSubmit
in class AbstractFormController
request
- current portlet render requestresponse
- current portlet render response
Exception
- in case of errorsAbstractFormController.showNewForm(javax.portlet.RenderRequest, javax.portlet.RenderResponse)
,
AbstractFormController.setBindOnNewForm(boolean)
,
handleInvalidSubmit(javax.portlet.ActionRequest, javax.portlet.ActionResponse)
protected void handleInvalidSubmit(ActionRequest request, ActionResponse response) throws Exception
Default implementation for wizard form controllers simply shows the initial page of a new wizard form, so here in the action phase this method does nothing. If you want to take some action on an invalid submit, you need to override this method.
handleInvalidSubmit
in class AbstractFormController
request
- current portlet action requestresponse
- current portlet action response
Exception
- in case of errorsrenderInvalidSubmit(javax.portlet.RenderRequest, javax.portlet.RenderResponse)
protected final ModelAndView renderFormSubmission(RenderRequest request, RenderResponse response, Object command, BindException errors) throws Exception
renderFormSubmission
in class AbstractFormController
request
- current render requestresponse
- current render responsecommand
- form object with request parameters bound onto iterrors
- errors holder
Exception
- in case of errorsprocessFormSubmission(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
protected final void processFormSubmission(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
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 errorsrenderFormSubmission(javax.portlet.RenderRequest, javax.portlet.RenderResponse, java.lang.Object, org.springframework.validation.BindException)
protected int getCurrentPage(PortletRequest request)
The default implementation checks the page session attribute. Subclasses can override this for customized page determination.
protected boolean isFinishRequest(PortletRequest request)
By default, this method returns true
if a parameter
matching the "_finish" key is present in the request, otherwise it
returns false
. Subclasses may override this method
to provide custom logic to detect a finish request.
The parameter is recognized both when sent as a plain parameter ("_finish") or when triggered by an image button ("_finish.x").
request
- current portlet requestPARAM_FINISH
protected boolean isCancelRequest(PortletRequest request)
By default, this method returns true
if a parameter
matching the "_cancel" key is present in the request, otherwise it
returns false
. Subclasses may override this method
to provide custom logic to detect a cancel request.
The parameter is recognized both when sent as a plain parameter ("_cancel") or when triggered by an image button ("_cancel.x").
request
- current portlet requestPARAM_CANCEL
protected int getTargetPage(PortletRequest request, Object command, Errors errors, int currentPage)
Default implementation delegates to
getTargetPage(PortletRequest, int)
.
Subclasses can override this for customized target page determination.
request
- current portlet requestcommand
- form object with request parameters bound onto iterrors
- validation errors holdercurrentPage
- the current page, to be returned as fallback
if no target page specified
getTargetPage(PortletRequest, int)
protected int getTargetPage(PortletRequest request, int currentPage)
Default implementation examines "_target" parameter (e.g. "_target1"). Subclasses can override this for customized target page determination.
request
- current portlet requestcurrentPage
- the current page, to be returned as fallback
if no target page specified
PARAM_TARGET
protected void validatePage(Object command, Errors errors, int page, boolean finish)
validatePage(command, errors, page)
.
Implementations will typically call fine-granular validateXXX
methods of this instance's Validator, combining them to validation of the
corresponding pages. The Validator's default validate
method
will not be called by a wizard form controller!
command
- form object with the current wizard stateerrors
- validation errors holderpage
- number of page to validatefinish
- whether this method is called during final revalidation on finish
(else, it is called for validating the current page)validatePage(Object, Errors, int)
,
Validator.validate(java.lang.Object, org.springframework.validation.Errors)
protected void validatePage(Object command, Errors errors, int page)
Implementations will typically call fine-granular validateXXX methods of this
instance's validator, combining them to validation of the corresponding pages.
The validator's default validate
method will not be called by a
wizard form controller!
command
- form object with the current wizard stateerrors
- validation errors holderpage
- number of page to validateValidator.validate(java.lang.Object, org.springframework.validation.Errors)
protected void postProcessPage(ActionRequest request, Object command, Errors errors, int page) throws Exception
Only invoked when displaying another page or the same page again, not when finishing or cancelling.
request
- current action requestcommand
- form object with request parameters bound onto iterrors
- validation errors holderpage
- number of page to post-process
Exception
- in case of invalid state or argumentsprotected ModelAndView renderFinish(RenderRequest request, RenderResponse response, Object command, BindException errors) throws Exception
Default implementation throws a PortletException, saying that a finish render request is not supported by this controller. Thus, you do not need to implement this template method if you do not need to render after a finish.
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 portlet render requestresponse
- current portlet render responsecommand
- form object with the current wizard stateerrors
- validation errors holder
Exception
- in case of invalid state or argumentsprocessFinish(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
,
Errors
,
BindException.getModel()
protected void processFinish(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
Default implementation throws a PortletException, saying that a finish action request is not supported by this controller. You will almost certainly need to override this method.
request
- current portlet action requestresponse
- current portlet action responsecommand
- form object with the current wizard stateerrors
- validation errors holder
Exception
- in case of invalid state or argumentsrenderFinish(javax.portlet.RenderRequest, javax.portlet.RenderResponse, java.lang.Object, org.springframework.validation.BindException)
,
Errors
protected ModelAndView renderCancel(RenderRequest request, RenderResponse response, Object command, BindException errors) throws Exception
Default implementation throws a PortletException, saying that a cancel render request is not supported by this controller. Thus, you do not need to implement this template method if you do not support a cancel operation.
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 portlet render requestresponse
- current portlet render responsecommand
- form object with the current wizard stateerrors
- Errors instance containing errors
Exception
- in case of invalid state or argumentsprocessCancel(javax.portlet.ActionRequest, javax.portlet.ActionResponse, java.lang.Object, org.springframework.validation.BindException)
,
Errors
,
BindException.getModel()
protected void processCancel(ActionRequest request, ActionResponse response, Object command, BindException errors) throws Exception
Default implementation throws a PortletException, saying that a cancel action request is not supported by this controller. Thus, you do not need to implement this template method if you do not support a cancel operation.
request
- current portlet action requestresponse
- current portlet action responsecommand
- form object with the current wizard stateerrors
- Errors instance containing errors
Exception
- in case of invalid state or argumentsrenderCancel(javax.portlet.RenderRequest, javax.portlet.RenderResponse, java.lang.Object, org.springframework.validation.BindException)
,
Errors
|
The Spring Framework | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |