com.ervacon.springframework.web.servlet.mvc.webflow
Class SimpleFormAction

java.lang.Object
  com.ervacon.springframework.web.servlet.mvc.webflow.MultiAction
      com.ervacon.springframework.web.servlet.mvc.webflow.SimpleFormAction

All Implemented Interfaces:

Action, org.springframework.beans.factory.InitializingBean

public class SimpleFormAction

extends MultiAction

implements org.springframework.beans.factory.InitializingBean

Multi-action that implements logic that is very similar to that of the SimpleFormController. Two execution methods are provided:

• prepareNewForm(HttpServletRequest, HttpServletResponse, Map) - Prepares a command object for display in a new form. This will initialize the binder so that all custom property editors are available for use in the new form. This action method always returns (signals) the "ok" event.
• bindAndValidate(HttpServletRequest, HttpServletResponse, Map) - Bind all incoming request parameters to the command object and validate the command object using any registered validators. This action method will return (signal) the "ok" event if there are no binding or validation errors, otherwise it will return the "error" event.

Since this is a multi-action, a subclass could add any number of additional action execution methods, e.g. on "onSubmit()".

Using this action, it becomes very easy to implement form preparation and submission logic in your flow:

1. Start of with an action state called "prepareNewForm". This will invoke prepareNewForm to prepare the new form for display.
2. Now show the form using a view state.
3. Go to an action state called "bindAndValidate" when the form is submitted. This will invoke bindAndValidate to bind incoming request data to the command object and validate the command object. If there are binding or validation errors, go back to the previous view state to redisplay the form with error messages.
4. If binding and validation was successful, go to an action state called "onSubmit" (or any other appropriate name). This will invoke an action method called "onSubmit" you must provide on a subclass to process form submission, e.g. interacting with the business logic.
5. If business processing is ok, contine to a view state to display the success view.

Check the "BirthDate" sample application for a usage example of this action.

The most important hook method provided by this class is the method initBinder. This will be called after a new data binder is created by both prepareNewForm and bindAndValidate. It allows you to register any custom property editors required by the form and command object.

Note that this class does not provide "suppressValidation" or "isFormChangeRequest" hook methods like the SimpleFormController. This is not required because in a web flow you have exact control over what happens when certain events are signaled. So a form change request would just use a different event than the submit request.

Exposed configuration properties

name	default	description
commandName	"command"	The name of the command in the model. The command object will be included in the model under this name.
commandClass	null	The command class for this action. An instance of this class will get populated and validated.
reuseCommand	false	Indicates whether or not an existing command object in the flow model should be reused.
requestErrors	false	Indicates whether or not to expose the Errors object resulting from validation in the request instead of the flow model. This is usefull if you want to avoid redisplaying old errors. Defaults to false, so the Errors will be exposed in the model.
validator(s)	empty	The validators for this action. The validators must support the specified command class.
bindOnNewForm	false	Set if request parameters should be bound to the form object during the prepareNewForm action.
validateOnBinding	true	Indicates if the validators should get applied when binding.
messageCodesResolver	null	Set the strategy to use for resolving errors into message codes.

Author:

Erwin Vervaet

See Also:

SimpleFormController

Field Summary

Fields inherited from interface com.ervacon.springframework.web.servlet.mvc.webflow.Action

ERROR, OK

Constructor Summary

SimpleFormAction()

Method Summary

void	afterPropertiesSet()
java.lang.String	bindAndValidate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.util.Map model) Bind all incoming request parameters to the command object and validate the command object using any registered validators.
protected org.springframework.web.bind.ServletRequestDataBinder	bindAndValidate(javax.servlet.http.HttpServletRequest request, java.util.Map model, java.lang.Object command) Bind the parameters of the given request to the given command object.
protected org.springframework.web.bind.ServletRequestDataBinder	createBinder(javax.servlet.http.HttpServletRequest request, java.util.Map model, java.lang.Object command) Create a new binder instance for the given command, request and model.
protected java.lang.Object	createCommand() Create a new command instance for the command class of this action.
protected void	exposeCommandAndErrors(javax.servlet.http.HttpServletRequest request, java.util.Map model, java.lang.Object command, org.springframework.validation.BindException errors) Expose the command object and related errors object to the view.
protected java.lang.Object	formBackingObject(javax.servlet.http.HttpServletRequest request, java.util.Map model) Retrieve a backing object for the current form from the given request or flow model.
java.lang.Class	getCommandClass() Return the command class for this action.
java.lang.String	getCommandName() Return the name of the command in the model.
org.springframework.validation.MessageCodesResolver	getMessageCodesResolver() Return the strategy to use for resolving errors into message codes.
org.springframework.validation.Validator	getValidator() Returns the primary validator for this action.
org.springframework.validation.Validator[]	getValidators() Returns all the validators for this action.
protected void	initBinder(javax.servlet.http.HttpServletRequest request, java.util.Map model, org.springframework.web.bind.ServletRequestDataBinder binder) Initialize the given binder instance, for example with custom editors.
boolean	isBindOnNewForm() Returns if request parameters should be bound to the form object during the prepareNewForm(HttpServletRequest, HttpServletResponse, Map) action.
boolean	isRequestErrors() Returns whether or not to expose the Errors object resulting from validation in the request instead of the flow model.
boolean	isReuseCommand() Indicates whether or not an existing command object in the flow model should be reused.
boolean	isValidateOnBinding() Return if the validators should get applied when binding.
protected void	onBind(javax.servlet.http.HttpServletRequest request, java.util.Map model, java.lang.Object command, org.springframework.validation.BindException errors) Callback for custom post-processing in terms of binding.
protected void	onBindAndValidate(javax.servlet.http.HttpServletRequest request, java.util.Map model, java.lang.Object command, org.springframework.validation.BindException errors) Callback for custom post-processing in terms of binding and validation.
java.lang.String	prepareNewForm(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.util.Map model) Prepares a command object for display in a new form.
void	setBindOnNewForm(boolean bindOnNewForm) Set if request parameters should be bound to the form object during the prepareNewForm(HttpServletRequest, HttpServletResponse, Map) action.
void	setCommandClass(java.lang.Class commandClass) Set the command class for this action.
void	setCommandName(java.lang.String commandName) Set the name of the command in the model.
void	setMessageCodesResolver(org.springframework.validation.MessageCodesResolver messageCodesResolver) Set the strategy to use for resolving errors into message codes.
void	setRequestErrors(boolean requestErrors) Set whether or not to expose the Errors object resulting from validation in the request instead of the flow model.
void	setReuseCommand(boolean reuseCommand) Set whether or not an existing command object in the flow model should be reused.
void	setValidateOnBinding(boolean validateOnBinding) Set if the validators should get applied when binding.
void	setValidator(org.springframework.validation.Validator validator) Set the primary validator for this action.
void	setValidators(org.springframework.validation.Validator[] validators) Set the validators for this action.

Methods inherited from class com.ervacon.springframework.web.servlet.mvc.webflow.MultiAction

execute, getCurrentState, getDelegate, getExecuteMethod, getExecuteMethodName, setDelegate

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleFormAction

public SimpleFormAction()

Method Detail

getCommandName

public java.lang.String getCommandName()

Return the name of the command in the model.

setCommandName

public void setCommandName(java.lang.String commandName)

Set the name of the command in the model. The command object will be included in the model under this name.

getCommandClass

public java.lang.Class getCommandClass()

Return the command class for this action.

setCommandClass

public void setCommandClass(java.lang.Class commandClass)

Set the command class for this action. An instance of this class will get populated and validated.

isReuseCommand

public boolean isReuseCommand()

Indicates whether or not an existing command object in the flow model should be reused. Defaults to false, so each call will result in a new command object being created.

setReuseCommand

public void setReuseCommand(boolean reuseCommand)

Set whether or not an existing command object in the flow model should be reused.

isRequestErrors

public boolean isRequestErrors()

Returns whether or not to expose the Errors object resulting from validation in the request instead of the flow model. This is usefull if you want to avoid redisplaying old errors. Defaults to false, so the Errors will be exposed in the model.

setRequestErrors

public void setRequestErrors(boolean requestErrors)

Set whether or not to expose the Errors object resulting from validation in the request instead of the flow model.

getValidators

public org.springframework.validation.Validator[] getValidators()

Returns all the validators for this action.

setValidators

public void setValidators(org.springframework.validation.Validator[] validators)

Set the validators for this action. The validators must support the specified command class.

getValidator

public org.springframework.validation.Validator getValidator()

Returns the primary validator for this action.

setValidator

public void setValidator(org.springframework.validation.Validator validator)

Set the primary validator for this action. The validator must support the specified command class. If there are one or more existing validators set already when this method is called, only the specified validator will be kept. Use setValidators(Validator[]) to set multiple validators.

isBindOnNewForm

public boolean isBindOnNewForm()

Returns if request parameters should be bound to the form object during the prepareNewForm(HttpServletRequest, HttpServletResponse, Map) action. Defaults to false.

setBindOnNewForm

public void setBindOnNewForm(boolean bindOnNewForm)

Set if request parameters should be bound to the form object during the prepareNewForm(HttpServletRequest, HttpServletResponse, Map) action.

isValidateOnBinding

public boolean isValidateOnBinding()

Return if the validators should get applied when binding. Defaults to true.

setValidateOnBinding

public void setValidateOnBinding(boolean validateOnBinding)

Set if the validators should get applied when binding.

getMessageCodesResolver

public org.springframework.validation.MessageCodesResolver getMessageCodesResolver()

Return the strategy to use for resolving errors into message codes.

setMessageCodesResolver

public void setMessageCodesResolver(org.springframework.validation.MessageCodesResolver messageCodesResolver)

Set the strategy to use for resolving errors into message codes. Applies the given strategy to all data binders used by this action.

Default is null, i.e. using the default strategy of the data binder.

See Also:

createBinder(HttpServletRequest, Map, Object), DataBinder.setMessageCodesResolver(org.springframework.validation.MessageCodesResolver)

afterPropertiesSet

public void afterPropertiesSet()
                        throws java.lang.Exception

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Throws:

java.lang.Exception

prepareNewForm

public java.lang.String prepareNewForm(javax.servlet.http.HttpServletRequest request,
                                       javax.servlet.http.HttpServletResponse response,
                                       java.util.Map model)

Prepares a command object for display in a new form. This will initialize the binder so that all custom property editors are available for use in the new form.

If the "bindOnNewForm" property is set, a bind and validate step will be done to pre-populate the new form with incoming request parameters.

Parameters:

request - current HTTP request

response - current HTTP response

model - model of the flow

Returns:

"ok"

See Also:

AbstractFormController.showNewForm(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

bindAndValidate

public java.lang.String bindAndValidate(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response,
                                        java.util.Map model)

Bind all incoming request parameters to the command object and validate the command object using any registered validators.

Parameters:

request - current HTTP request

response - current HTTP response

model - model of the flow

Returns:

"ok" when binding and validation is successful, "error" otherwise

See Also:

BaseCommandController.bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)

formBackingObject

protected java.lang.Object formBackingObject(javax.servlet.http.HttpServletRequest request,
                                             java.util.Map model)

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

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 "reuseCommand" 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 createCommand(), creating a new empty instance of the command class. Subclasses can override this to provide a preinitialized backing object.

Parameters:

request - current HTTP request

model - model of the flow

Returns:

the backing object

See Also:

setCommandName(String), setCommandClass(Class), createCommand()

createCommand

protected java.lang.Object createCommand()

Create a new command instance for the command class of this action.

Returns:

the new command instance

bindAndValidate

protected org.springframework.web.bind.ServletRequestDataBinder bindAndValidate(javax.servlet.http.HttpServletRequest request,
                                                                                java.util.Map model,
                                                                                java.lang.Object command)

Bind the parameters of the given request to the given command object.

Parameters:

request - current HTTP request

model - model of the flow

command - the command to bind onto

Returns:

the ServletRequestDataBinder instance for additional custom validation

createBinder

protected org.springframework.web.bind.ServletRequestDataBinder createBinder(javax.servlet.http.HttpServletRequest request,
                                                                             java.util.Map model,
                                                                             java.lang.Object command)

Create a new binder instance for the given command, request and model. Called by bindAndValidate(). Can be overridden to plug in custom ServletRequestDataBinder subclasses.

Default implementation creates a standard ServletRequestDataBinder, sets the specified MessageCodesResolver (if any), and invokes initBinder(). Note that initBinder() will not be invoked if you override this method!

Parameters:

request - current HTTP request

model - model of the flow

command - the command to bind onto

Returns:

the new binder instance

See Also:

bindAndValidate(HttpServletRequest, Map, Object), initBinder(HttpServletRequest, Map, ServletRequestDataBinder), setMessageCodesResolver(MessageCodesResolver)

exposeCommandAndErrors

protected void exposeCommandAndErrors(javax.servlet.http.HttpServletRequest request,
                                      java.util.Map model,
                                      java.lang.Object command,
                                      org.springframework.validation.BindException errors)

Expose the command object and related errors object to the view. The command object will always be put in the flow model. If the "requestErrors" property is set, the errors will be exposed in the request. If not set, they will also be exposed in the flow model.

Parameters:

request - current HTTP request

model - model of the flow

command - the command object

errors - the errors object

onBind

protected void onBind(javax.servlet.http.HttpServletRequest request,
                      java.util.Map model,
                      java.lang.Object command,
                      org.springframework.validation.BindException errors)

Callback for custom post-processing in terms of binding. Called on each submit, after standard binding but before validation.

Default implementation is empty.

Parameters:

request - current HTTP request

model - model of the flow

command - the command object to perform further binding on

errors - validation errors holder, allowing for additional custom registration of binding errors

See Also:

bindAndValidate(HttpServletRequest, Map, Object)

onBindAndValidate

protected void onBindAndValidate(javax.servlet.http.HttpServletRequest request,
                                 java.util.Map model,
                                 java.lang.Object command,
                                 org.springframework.validation.BindException errors)

Callback for custom post-processing in terms of binding and validation. Called on each submit, after standard binding and validation, but before error evaluation.

Default implementation is empty.

Parameters:

request - current HTTP request

model - model of the flow

command - the command object, still allowing for further binding

errors - validation errors holder, allowing for additional custom validation

Throws:

java.lang.Exception - in case of invalid state or arguments

See Also:

bindAndValidate(HttpServletRequest, Map, Object), Errors

initBinder

protected void initBinder(javax.servlet.http.HttpServletRequest request,
                          java.util.Map model,
                          org.springframework.web.bind.ServletRequestDataBinder binder)

Initialize the given binder instance, for example with custom editors. Called by createBinder().

This method allows you to register custom editors for certain fields of your command class. For instance, you will be able to transform Date objects into a String pattern and back, in order to allow your JavaBeans to have Date properties and still be able to set and display them in an HTML interface.

Default implementation is empty.

Parameters:

request - current HTTP request

model - model of the flow

binder - new binder instance

See Also:

createBinder(HttpServletRequest, Map, Object), DataBinder.registerCustomEditor(java.lang.Class, java.beans.PropertyEditor)