public abstract class

BaseCommandController

extends AbstractController
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
Known Direct Subclasses
Known Indirect Subclasses

This class is deprecated.
as of Spring 3.0, in favor of annotated controllers

Class Overview

Controller implementation which creates an object (the command object) on receipt of a request and attempts to populate this object with request parameters.

This controller is the base for all controllers wishing to populate JavaBeans based on request parameters, validate the content of such JavaBeans using Validators and use custom editors (in the form of PropertyEditors) to transform objects into strings and vice versa, for example. Three notions are mentioned here:

Command class:
An instance of the command class will be created for each request and populated with request parameters. A command class can basically be any Java class; the only requirement is a no-arg constructor. The command class should preferably be a JavaBean in order to be able to populate bean properties with request parameters.

Populating using request parameters and PropertyEditors:
Upon receiving a request, any BaseCommandController will attempt to fill the command object using the request parameters. This is done using the typical and well-known JavaBeans property notation. When a request parameter named 'firstName' exists, the framework will attempt to call setFirstName([value]) passing the value of the parameter. Nested properties are of course supported. For instance a parameter named 'address.city' will result in a getAddress().setCity([value]) call on the command class.

It's important to realize that you are not limited to String arguments in your JavaBeans. Using the PropertyEditor-notion as supplied by the java.beans package, you will be able to transform Strings to Objects and the other way around. For instance setLocale(Locale loc) is perfectly possible for a request parameter named locale having a value of en, as long as you register the appropriate PropertyEditor in the Controller (see initBinder() for more information on that matter).

Validators: After the controller has successfully populated the command object with parameters from the request, it will use any configured validators to validate the object. Validation results will be put in a Errors object which can be used in a View to render any input problems.

Workflow (and that defined by superclass):
Since this class is an abstract base class for more specific implementation, it does not override the handleRequestInternal() methods and also has no actual workflow. Implementing classes like AbstractFormController, AbstractCommandController, SimpleFormController and AbstractWizardFormController provide actual functionality and workflow. More information on workflow performed by superclasses can be found here.

Exposed configuration properties (and those defined by superclass):

name default description
commandName command the name to use when binding the instantiated command class to the request
commandClass null the class to use upon receiving a request and which to fill using the request parameters. What object is used and whether or not it should be created is defined by extending classes and their configuration properties and methods.
validators null Array of Validator beans. The validator will be called at appropriate places in the workflow of subclasses (have a look at those for more info) to validate the command object.
validator null Short-form property for setting only one Validator bean (usually passed in using a <ref bean="beanId"/> property.
validateOnBinding true Indicates whether or not to validate the command object after the object has been populated with request parameters.

Thanks to Rainer Schmitz and Nick Lothian for their suggestions!

Summary

Constants
String DEFAULT_COMMAND_NAME
[Expand]
Inherited Fields
From class org.springframework.context.support.ApplicationObjectSupport
Public Constructors
BaseCommandController()
Public Methods
final BindingErrorProcessor getBindingErrorProcessor()
Return the strategy to use for processing binding errors (if any).
final Class getCommandClass()
Return the command class for this controller.
final String getCommandName()
Return the name of the command in the model.
final MessageCodesResolver getMessageCodesResolver()
Return the strategy to use for resolving errors into message codes (if any).
final PropertyEditorRegistrar[] getPropertyEditorRegistrars()
Return the PropertyEditorRegistrars (if any) to be applied to every DataBinder that this controller uses.
final Validator getValidator()
final Validator[] getValidators()
Return the Validators for this controller.
final WebBindingInitializer getWebBindingInitializer()
Return the WebBindingInitializer (if any) which will apply pre-configured configuration to every DataBinder that this controller uses.
final boolean isValidateOnBinding()
Return if the Validator should get applied when binding.
final void setBindingErrorProcessor(BindingErrorProcessor bindingErrorProcessor)
Set the strategy to use for processing binding errors, that is, required field errors and PropertyAccessExceptions.
final void setCommandClass(Class commandClass)
Set the command class for this controller.
final void setCommandName(String commandName)
Set the name of the command in the model.
final void setMessageCodesResolver(MessageCodesResolver messageCodesResolver)
Set the strategy to use for resolving errors into message codes.
final void setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar)
Specify a single PropertyEditorRegistrar to be applied to every DataBinder that this controller uses.
final void setPropertyEditorRegistrars(PropertyEditorRegistrar[] propertyEditorRegistrars)
Specify one or more PropertyEditorRegistrars to be applied to every DataBinder that this controller uses.
final void setValidateOnBinding(boolean validateOnBinding)
Set if the Validator should get applied when binding.
final void setValidator(Validator validator)
Set the primary Validator for this controller.
final void setValidators(Validator[] validators)
Set the Validators for this controller.
final void setWebBindingInitializer(WebBindingInitializer webBindingInitializer)
Specify a WebBindingInitializer which will apply pre-configured configuration to every DataBinder that this controller uses.
Protected Methods
final PortletRequestDataBinder bindAndValidate(PortletRequest request, Object command)
Bind the parameters of the given request to the given command object.
final boolean checkCommand(Object command)
Check if the given command object is a valid for this controller, i.e.
PortletRequestDataBinder createBinder(PortletRequest request, Object command)
Create a new binder instance for the given command and request.
final Object createCommand()
Create a new command instance for the command class of this controller.
Object getCommand(PortletRequest request)
Retrieve a command object for the given request.
final Object getRenderCommand(RenderRequest request)
Get the command object cached for the render phase.
String getRenderCommandSessionAttributeName()
Return the name of the session attribute that holds the render phase command object for this form controller.
final BindException getRenderErrors(RenderRequest request)
Get the bind and validation errors cached for the render phase.
String getRenderErrorsSessionAttributeName()
Return the name of the session attribute that holds the render phase command object for this form controller.
void initApplicationContext()
Subclasses can override this for custom initialization behavior.
void initBinder(PortletRequest request, PortletRequestDataBinder binder)
Initialize the given binder instance, for example with custom editors.
void onBind(PortletRequest request, Object command)
Callback for custom post-processing in terms of binding.
void onBind(PortletRequest request, Object command, BindException errors)
Callback for custom post-processing in terms of binding.
void onBindAndValidate(PortletRequest request, Object command, BindException errors)
Callback for custom post-processing in terms of binding and validation.
final void prepareBinder(PortletRequestDataBinder binder)
Prepare the given binder, applying the specified MessageCodesResolver, BindingErrorProcessor and PropertyEditorRegistrars (if any).
final void setRenderCommandAndErrors(ActionRequest request, Object command, BindException errors)
Set the command object and errors object for the render phase.
boolean suppressBinding(PortletRequest request)
Return whether to suppress binding for the given request.
boolean suppressValidation(PortletRequest request)
Return whether to suppress validation for the given request.
boolean useDirectFieldAccess()
Determine whether to use direct field access instead of bean property access.
[Expand]
Inherited Methods
From class org.springframework.web.portlet.mvc.AbstractController
From class org.springframework.web.portlet.handler.PortletContentGenerator
From class org.springframework.web.portlet.context.PortletApplicationObjectSupport
From class org.springframework.context.support.ApplicationObjectSupport
From class java.lang.Object
From interface org.springframework.context.ApplicationContextAware
From interface org.springframework.web.portlet.context.PortletContextAware
From interface org.springframework.web.portlet.mvc.Controller

Constants

public static final String DEFAULT_COMMAND_NAME

Constant Value: "command"

Public Constructors

public BaseCommandController ()

Public Methods

public final BindingErrorProcessor getBindingErrorProcessor ()

Return the strategy to use for processing binding errors (if any).

public final Class getCommandClass ()

Return the command class for this controller.

public final String getCommandName ()

Return the name of the command in the model.

public final MessageCodesResolver getMessageCodesResolver ()

Return the strategy to use for resolving errors into message codes (if any).

public final PropertyEditorRegistrar[] getPropertyEditorRegistrars ()

Return the PropertyEditorRegistrars (if any) to be applied to every DataBinder that this controller uses.

public final Validator getValidator ()

Returns
  • the primary Validator for this controller.

public final Validator[] getValidators ()

Return the Validators for this controller.

public final WebBindingInitializer getWebBindingInitializer ()

Return the WebBindingInitializer (if any) which will apply pre-configured configuration to every DataBinder that this controller uses.

public final boolean isValidateOnBinding ()

Return if the Validator should get applied when binding.

public final void setBindingErrorProcessor (BindingErrorProcessor bindingErrorProcessor)

Set the strategy to use for processing binding errors, that is, required field errors and PropertyAccessExceptions.

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

See Also

public final void setCommandClass (Class commandClass)

Set the command class for this controller. An instance of this class gets populated and validated on each request.

public final void setCommandName (String commandName)

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

public final void setMessageCodesResolver (MessageCodesResolver messageCodesResolver)

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

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

See Also

public final void setPropertyEditorRegistrar (PropertyEditorRegistrar propertyEditorRegistrar)

Specify a single PropertyEditorRegistrar to be applied to every DataBinder that this controller uses.

Allows for factoring out the registration of PropertyEditors to separate objects, as an alternative to initBinder.

See Also

public final void setPropertyEditorRegistrars (PropertyEditorRegistrar[] propertyEditorRegistrars)

Specify one or more PropertyEditorRegistrars to be applied to every DataBinder that this controller uses.

Allows for factoring out the registration of PropertyEditors to separate objects, as alternative to initBinder.

See Also

public final void setValidateOnBinding (boolean validateOnBinding)

Set if the Validator should get applied when binding.

public final void setValidator (Validator validator)

Set the primary Validator for this controller. 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.

public final void setValidators (Validator[] validators)

Set the Validators for this controller. The Validator must support the specified command class.

public final void setWebBindingInitializer (WebBindingInitializer webBindingInitializer)

Specify a WebBindingInitializer which will apply pre-configured configuration to every DataBinder that this controller uses.

Allows for factoring out the entire binder configuration to separate objects, as an alternative to initBinder(PortletRequest, PortletRequestDataBinder).

Protected Methods

protected final PortletRequestDataBinder bindAndValidate (PortletRequest request, Object command)

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

Parameters
request current portlet request
command the command to bind onto
Returns
  • the PortletRequestDataBinder instance for additional custom validation
Throws
Exception in case of invalid state or arguments

protected final boolean checkCommand (Object command)

Check if the given command object is a valid for this controller, i.e. its command class.

Parameters
command the command object to check
Returns
  • if the command object is valid for this controller

protected PortletRequestDataBinder createBinder (PortletRequest request, Object command)

Create a new binder instance for the given command and request.

Called by bindAndValidate. Can be overridden to plug in custom PortletRequestDataBinder instances.

The default implementation creates a standard PortletRequestDataBinder and invokes prepareBinder and initBinder.

Note that neither prepareBinder nor initBinder will be invoked automatically if you override this method! Call those methods at appropriate points of your overridden method.

Parameters
request current portlet request
command the command to bind onto
Returns
  • the new binder instance
Throws
Exception in case of invalid state or arguments
See Also

protected final Object createCommand ()

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

This implementation uses BeanUtils.instantiateClass, so the command needs to have a no-arg constructor (supposed to be public, but not required to).

Returns
  • the new command instance
Throws
Exception if the command object could not be instantiated
See Also

protected Object getCommand (PortletRequest request)

Retrieve a command object for the given request.

The default implementation calls createCommand(). Subclasses can override this.

Parameters
request current portlet request
Returns
  • object command to bind onto
Throws
Exception
See Also

protected final Object getRenderCommand (RenderRequest request)

Get the command object cached for the render phase.

Throws
PortletException
See Also

protected String getRenderCommandSessionAttributeName ()

Return the name of the session attribute that holds the render phase command object for this form controller.

Returns
  • the name of the render phase command object session attribute
See Also
  • javax.portlet.PortletSession#getAttribute

protected final BindException getRenderErrors (RenderRequest request)

Get the bind and validation errors cached for the render phase.

Throws
PortletException
See Also

protected String getRenderErrorsSessionAttributeName ()

Return the name of the session attribute that holds the render phase command object for this form controller.

Returns
  • the name of the render phase command object session attribute
See Also
  • javax.portlet.PortletSession#getAttribute

protected void initApplicationContext ()

Subclasses can override this for custom initialization behavior.

The default implementation is empty. Called by initApplicationContext(org.springframework.context.ApplicationContext).

protected void initBinder (PortletRequest request, PortletRequestDataBinder 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.

The default implementation is empty.

Parameters
request current portlet request
binder new binder instance
Throws
Exception in case of invalid state or arguments
See Also

protected void onBind (PortletRequest request, Object command)

Callback for custom post-processing in terms of binding. Called by the default implementation of the onBind version with all parameters, after standard binding but before validation.

The default implementation is empty.

Parameters
request current portlet request
command the command object to perform further binding on
Throws
Exception in case of invalid state or arguments
See Also

protected void onBind (PortletRequest request, Object command, BindException errors)

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

The default implementation delegates to onBind(request, command).

Parameters
request current portlet request
command the command object to perform further binding on
errors validation errors holder, allowing for additional custom registration of binding errors
Throws
Exception in case of invalid state or arguments
See Also

protected void onBindAndValidate (PortletRequest request, Object command, 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.

The default implementation is empty.

Parameters
request current portlet request
command the command object, still allowing for further binding
errors validation errors holder, allowing for additional custom validation
Throws
Exception in case of invalid state or arguments
See Also

protected final void prepareBinder (PortletRequestDataBinder binder)

Prepare the given binder, applying the specified MessageCodesResolver, BindingErrorProcessor and PropertyEditorRegistrars (if any). Called by createBinder.

Parameters
binder the new binder instance
See Also

protected final void setRenderCommandAndErrors (ActionRequest request, Object command, BindException errors)

Set the command object and errors object for the render phase.

Parameters
request the current action request
command the command object to preserve for the render phase
errors the errors from binding and validation to preserve for the render phase
Throws
Exception
See Also

protected boolean suppressBinding (PortletRequest request)

Return whether to suppress binding for the given request.

The default implementation always returns false. Can be overridden in subclasses to suppress validation: for example, if a special request parameter is set.

Parameters
request current portlet request
Returns
  • whether to suppress binding for the given request
See Also

protected boolean suppressValidation (PortletRequest request)

Return whether to suppress validation for the given request.

The default implementation always returns false. Can be overridden in subclasses to suppress validation: for example, if a special request parameter is set.

Parameters
request current portlet request
Returns
  • whether to suppress validation for the given request

protected boolean useDirectFieldAccess ()

Determine whether to use direct field access instead of bean property access. Applied by prepareBinder.

The default is false. Can be overridden in subclasses.

See Also