|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.springframework.webflow.action.AbstractAction
org.springframework.webflow.action.MultiAction
org.springframework.webflow.action.FormAction
public class FormAction
Multi-action that implements common logic dealing with input forms. This class uses the Spring Web data binding code to do binding and validation.
Several action execution methods are provided:
setupForm(RequestContext)
- Prepares the form object for display on a form,
creating it
and an associated errors
if necessary, then
caching them in the configured form object scope
and
form errors scope
, respectively. Also
installs
any custom property editors for formatting form
object field values. This action method will return the "success" event unless an exception is thrown. bindAndValidate(RequestContext)
- Binds all incoming request parameters to the form object and then
validates the form object using a registered validator
. This action method will
return the "success" event if there are no binding or validation errors, otherwise it will return the "error" event.
bind(RequestContext)
- Binds all incoming request parameters to the form object. No additional
validation is performed. This action method will return the "success" event if there are no binding errors, otherwise
it will return the "error" event. validate(RequestContext)
- Validates the form object using a registered validator. No data binding is
performed. This action method will return the "success" event if there are no validation errors, otherwise it will
return the "error" event. resetForm(RequestContext)
- Resets the form by reloading the backing form object and reinstalling any
custom property editors. Returns "success" on completion, an exception is thrown when a failure occurs. Since this is a multi-action a subclass could add any number of additional action execution methods, e.g. "setupReferenceData(RequestContext)", or "processSubmit(RequestContext)".
Using this action, it becomes very easy to implement form preparation and submission logic in your flow. One way to do this follows:
setupForm
to prepare the new form for display. bindAndValidate
to bind incoming request parameters to the form object and
validate the form object. Here is an example implementation of such a form flow:
<view-state id="displayCriteria"> <on-render> <evaluate expression="formAction.setupForm"/> </on-render> <transition on="search" to="executeSearch"> <evaluate expression="formAction.bindAndValidate"/> </transition> </view-state>
When you need additional flexibility consider splitting the view state above acting as a single logical form state into multiple states. For example, you could have one action state handle form setup, a view state trigger form display, another action state handle data binding and validation, and another process form submission. This would be a bit more verbose but would also give you more control over how you respond to specific results of fine-grained actions that occur within the flow.
Subclassing hooks:
createFormObject
. You may override this to
customize where the backing form object instance comes from (e.g instantiated transiently in memory or loaded from a
database).initBinder
.
This is called after a new data binder is created.
registerPropertyEditors(PropertyEditorRegistry)
. By overriding it you
can register any required property editors for your form. Instead of overriding this method, consider setting an
explicit PropertyEditorRegistrar
strategy as a more reusable way to encapsulate
custom PropertyEditor installation logic.validationEnabled(RequestContext)
to dynamically decide whether or not to do validation based
on data available in the request context.
Note that this action does not provide a referenceData() hook method similar to that of Spring MVC's
SimpleFormController
. If you wish to expose reference data to populate form drop downs you can define
a custom action method in your FormAction subclass that does just that. Simply invoke it as either a chained action
as part of the setupForm state, or as a fine grained state definition itself.
For example, you might create this method in your subclass:
public Event setupReferenceData(RequestContext context) throws Exception { MutableAttributeMap requestScope = context.getRequestScope(); requestScope.put("refData", lookupService.getSupportingFormData()); return success(); }... and then invoke it like this:
<view-state id="displayCriteria"> <on-render> <evaluate expression="formAction.setupForm"/> <evaluate expression="formAction.setupReferenceData"/> </on-render> ... </view-state>This style of calling multiple action methods in a chain (Chain of Responsibility) is preferred to overriding a single action method. In general, action method overriding is discouraged.
When it comes to validating submitted input data using a registered Validator
,
this class offers the following options:
bind(RequestContext)
instead of
bindAndValidate(RequestContext)
or don't register a validator.bindAndValidate(RequestContext)
or
validate(RequestContext)
and specify a validatorMethod
action execution
attribute. This will invoke the identified custom validator method on the validator. The validator method signature
should follow the following pattern:
public void ${validateMethodName}(${formObjectClass}, Errors)For instance, having a action definition like this:
<evaluate expression="formAction.bindAndValidate"> <attribute name="validatorMethod" value="validateSearchCriteria"/> </evaluate>Would result in the public void validateSearchCriteria(SearchCriteria, Errors) method of the registered validator being called if the form object class would be
SearchCriteria
.validate
method of the registered validator, call bindAndValidate(RequestContext)
or
validate(RequestContext)
without specifying a "validatorMethod" action execution attribute.
FormAction configurable properties
name | default | description |
formObjectName | formObject | The name of the form object. The form object will be set in the configured scope using this name. |
formObjectClass | null | The form object class for this action. An instance of this class will get populated and validated. Required when using a validator. |
formObjectScope | flow |
The scope in which the form object will be put. If put in flow scope the object will be cached and reused over the life of the flow, preserving previous values. Request scope will cause a new fresh form object instance to be created on each request into the flow execution. |
formErrorsScope | flash |
The scope in which the form object errors instance will be put. If put in flash scope form errors will be cached until the next user event is signaled. |
propertyEditorRegistrar | null | The strategy used to register custom property editors with the data binder. This is an alternative to overriding
the registerPropertyEditors(PropertyEditorRegistry) hook method. |
validator | null | The validator for this action. The validator must support the specified form object class. |
messageCodesResolver | null | Set the strategy to use for resolving errors into message codes. |
PropertyEditorRegistrar
,
DataBinder
,
ScopeType
Nested Class Summary |
---|
Nested classes/interfaces inherited from class org.springframework.webflow.action.MultiAction |
---|
MultiAction.MethodResolver |
Field Summary | |
---|---|
static String |
DEFAULT_FORM_OBJECT_NAME
The default form object name ("formObject"). |
static String |
VALIDATOR_METHOD_ATTRIBUTE
Optional attribute that identifies the method that should be invoked on the configured validator instance, to support piecemeal wizard page validation ("validatorMethod"). |
Constructor Summary | |
---|---|
FormAction()
Bean-style default constructor; creates a initially unconfigured FormAction instance relying on default property values. |
|
FormAction(Class formObjectClass)
Creates a new form action that manages instance(s) of the specified form object class. |
Method Summary | |
---|---|
Event |
bind(RequestContext context)
Bind incoming request parameters to allowed fields of the form object. |
Event |
bindAndValidate(RequestContext context)
Bind incoming request parameters to allowed fields of the form object and then validate the bound form object if a validator is configured. |
ScopeType |
getFormErrorsScope()
Get the scope in which the Errors object will be placed. |
Class |
getFormObjectClass()
Return the form object class for this action. |
String |
getFormObjectName()
Return the name of the form object in the configured scope. |
ScopeType |
getFormObjectScope()
Get the scope in which the form object will be placed. |
org.springframework.validation.MessageCodesResolver |
getMessageCodesResolver()
Return the strategy to use for resolving errors into message codes. |
org.springframework.beans.PropertyEditorRegistrar |
getPropertyEditorRegistrar()
Get the property editor registration strategy for this action's data binders. |
org.springframework.validation.Validator |
getValidator()
Returns the validator for this action. |
Event |
resetForm(RequestContext context)
Resets the form by clearing out the form object in the specified scope and recreating it. |
void |
setFormErrorsScope(ScopeType errorsScope)
Set the scope in which the Errors object will be placed. |
void |
setFormObjectClass(Class formObjectClass)
Set the form object class for this action. |
void |
setFormObjectName(String formObjectName)
Set the name of the form object in the configured scope. |
void |
setFormObjectScope(ScopeType scopeType)
Set the scope in which the form object will be placed. |
void |
setMessageCodesResolver(org.springframework.validation.MessageCodesResolver messageCodesResolver)
Set the strategy to use for resolving errors into message codes. |
void |
setPropertyEditorRegistrar(org.springframework.beans.PropertyEditorRegistrar propertyEditorRegistrar)
Set a property editor registration strategy for this action's data binders. |
Event |
setupForm(RequestContext context)
Prepares a form object for display in a new form, creating it and caching it in the getFormObjectScope()
if necessary. |
void |
setValidator(org.springframework.validation.Validator validator)
Set the validator for this action. |
String |
toString()
|
Event |
validate(RequestContext context)
Validate the form object by invoking the validator if configured. |
Methods inherited from class org.springframework.webflow.action.MultiAction |
---|
getMethodResolver, setMethodResolver |
Methods inherited from class org.springframework.webflow.action.AbstractAction |
---|
afterPropertiesSet, execute, getEventFactorySupport |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface org.springframework.beans.factory.InitializingBean |
---|
afterPropertiesSet |
Field Detail |
---|
public static final String DEFAULT_FORM_OBJECT_NAME
public static final String VALIDATOR_METHOD_ATTRIBUTE
Constructor Detail |
---|
public FormAction()
createFormObject(RequestContext)
.
setFormObjectClass(Class)
public FormAction(Class formObjectClass)
formObjectClass
- the class of the form object (must be instantiable)Method Detail |
---|
public String getFormObjectName()
public void setFormObjectName(String formObjectName)
public Class getFormObjectClass()
public void setFormObjectClass(Class formObjectClass)
setValidator(Validator)
)!
If no form object name is set at the moment this method is called, a form object name will be automatically
generated based on the provided form object class using
ClassUtils.getShortNameAsProperty(java.lang.Class)
.
public ScopeType getFormObjectScope()
public void setFormObjectScope(ScopeType scopeType)
flow scope
.
public ScopeType getFormErrorsScope()
public void setFormErrorsScope(ScopeType errorsScope)
flash scope
.
public org.springframework.beans.PropertyEditorRegistrar getPropertyEditorRegistrar()
public void setPropertyEditorRegistrar(org.springframework.beans.PropertyEditorRegistrar propertyEditorRegistrar)
registerPropertyEditors(PropertyEditorRegistry)
method.
public org.springframework.validation.Validator getValidator()
public void setValidator(org.springframework.validation.Validator validator)
form object class
. The validator must support the specified form object
class.
public org.springframework.validation.MessageCodesResolver getMessageCodesResolver()
public void setMessageCodesResolver(org.springframework.validation.MessageCodesResolver messageCodesResolver)
Default is null, i.e. using the default strategy of the data binder.
createBinder(RequestContext, Object)
,
DataBinder.setMessageCodesResolver(org.springframework.validation.MessageCodesResolver)
public Event setupForm(RequestContext context) throws Exception
getFormObjectScope()
if necessary. Also installs custom property editors for formatting form object values in UI controls such as text
fields.
A new form object instance will only be created (or more generally acquired) with a call to
createFormObject(RequestContext)
, if the form object does not yet exist in the configured
scope
. If you want to reset the form handling machinery, including creation or
loading of a fresh form object instance, call resetForm(RequestContext)
instead.
NOTE: This action method is not designed to be overridden and might become final
in a future
version of Spring Web Flow. If you need to execute custom form setup logic have your flow call this method along
with your own custom methods as part of a single action chain.
context
- the action execution context, for accessing and setting data in "flow scope" or "request scope"
Exception
- an unrecoverable exception occurs, either checked or uncheckedcreateFormObject(RequestContext)
public Event bindAndValidate(RequestContext context) throws Exception
NOTE: This action method is not designed to be overridden and might become final
in a future
version of Spring Web Flow. If you need to execute custom bind and validate logic have your flow call this method
along with your own custom methods as part of a single action chain. Alternatively, override the
doBind(RequestContext, DataBinder)
or doValidate(RequestContext, Object, Errors)
hooks.
context
- the action execution context, for accessing and setting data in "flow scope" or "request scope"
Exception
- an unrecoverable exception occurred, either checked or uncheckedpublic Event bind(RequestContext context) throws Exception
NOTE: This action method is not designed to be overridden and might become final
in a future
version of Spring Web Flow. If you need to execute custom data binding logic have your flow call this method
along with your own custom methods as part of a single action chain. Alternatively, override the
doBind(RequestContext, DataBinder)
hook.
context
- the action execution context, for accessing and setting data in "flow scope" or "request scope"
Exception
- an unrecoverable exception occured, either checked or uncheckedpublic Event validate(RequestContext context) throws Exception
NOTE: This action method is not designed to be overridden and might become final
in a future
version of Spring Web Flow. If you need to execute custom validation logic have your flow call this method along
with your own custom methods as part of a single action chain. Alternatively, override the
doValidate(RequestContext, Object, Errors)
hook.
context
- the action execution context, for accessing and setting data in "flow scope" or "request scope"
Exception
- an unrecoverable exception occured, either checked or uncheckedgetValidator()
public Event resetForm(RequestContext context) throws Exception
NOTE: This action method is not designed to be overridden and might become final
in a future
version of Spring Web Flow. If you need to execute custom reset logic have your flow call this method along with
your own custom methods as part of a single action chain.
context
- the request context
Exception
- if an exception occuredcreateFormObject(RequestContext)
public String toString()
toString
in class Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |