org.springframework.web.servlet.mvc
Class BaseCommandController

java.lang.Object
  org.springframework.context.support.ApplicationObjectSupport
      org.springframework.web.context.support.WebApplicationObjectSupport
          org.springframework.web.servlet.support.WebContentGenerator
              org.springframework.web.servlet.mvc.AbstractController
                  org.springframework.web.servlet.mvc.BaseCommandController

All Implemented Interfaces:

ApplicationContextAware, Controller

Direct Known Subclasses:

AbstractCommandController, AbstractFormController

public abstract class BaseCommandController

extends AbstractController

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:
The command class is the object that will be created filled using the request parameters. What the actual command class is, is customizable in many ways, through extending controllers or overriding methods. Command classes should preferrably be JavaBeans in order to be able to fill instances of the classes using the 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 realise 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 filled the command object with the parameters from the request, it will attempt 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() method 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
validator	null	Validator bean (usually passed in using a <ref bean="beanId"/> property. The validator will be called somewhere in the workflow of implementing classes (have a look at those for more info) to validate the command object
validateOnBinding	true	Indicates whether or not to validate the command object after the object has been filled using the request parameters

Author:

Rod Johnson, Juergen Hoeller

Field Summary

static java.lang.String

DEFAULT_COMMAND_NAME

Fields inherited from class org.springframework.web.servlet.support.WebContentGenerator

HEADER_CACHE_CONTROL, HEADER_EXPIRES, HEADER_PRAGMA, METHOD_GET, METHOD_POST

Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

logger

Constructor Summary

BaseCommandController()

Method Summary

protected ServletRequestDataBinder	bindAndValidate(javax.servlet.http.HttpServletRequest request, java.lang.Object command) Bind the parameters of the given request to the given command object.
protected boolean	checkCommand(java.lang.Object command) Check if the given command object is a valid for this controller, i.e.
protected ServletRequestDataBinder	createBinder(javax.servlet.http.HttpServletRequest request, java.lang.Object command) Create a new binder instance for the given command and request.
protected java.lang.Object	createCommand() Create a new command instance for the command class of this controller.
protected java.lang.Object	getCommand(javax.servlet.http.HttpServletRequest request) Retrieve a command object for the given request.
protected java.lang.Class	getCommandClass() Return the command class for this controller.
protected java.lang.String	getCommandName() Return the name of the command in the model.
protected Validator	getValidator() Return the Validator for this controller.
protected void	initBinder(javax.servlet.http.HttpServletRequest request, ServletRequestDataBinder binder) Initialize the given binder instance, for example with custom editors.
protected boolean	isValidateOnBinding() Return if the Validator should get applied when binding.
protected void	onBind(javax.servlet.http.HttpServletRequest request, java.lang.Object command) Callback for custom post-processing in terms of binding.
protected void	onBindAndValidate(javax.servlet.http.HttpServletRequest request, java.lang.Object command, BindException errors) Callback for custom post-processing in terms of binding and validation.
void	setCommandClass(java.lang.Class commandClass) Set the command class for this controller.
void	setCommandName(java.lang.String commandName) Set the name of the command in the model.
void	setValidateOnBinding(boolean validateOnBinding) Set if the Validator should get applied when binding.
void	setValidator(Validator validator) Set the Validator for this controller (can also be null).

Methods inherited from class org.springframework.web.servlet.mvc.AbstractController

handleRequest, handleRequestInternal, setSynchronizeOnSession

Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator

applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, preventCaching, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseExpiresHeader

Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

getServletContext, getTempDir, getWebApplicationContext, requiredContextClass

Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

getApplicationContext, getMessageSourceAccessor, initApplicationContext, setApplicationContext

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_COMMAND_NAME

public static final java.lang.String DEFAULT_COMMAND_NAME

See Also:

Constant Field Values

Constructor Detail

BaseCommandController

public BaseCommandController()

Method Detail

setCommandName

public final 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.

getCommandName

protected final java.lang.String getCommandName()

Return the name of the command in the model.

setCommandClass

public final void setCommandClass(java.lang.Class commandClass)

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

getCommandClass

protected final java.lang.Class getCommandClass()

Return the command class for this controller.

setValidator

public final void setValidator(Validator validator)

Set the Validator for this controller (can also be null). The Validator must support the specified command class.

getValidator

protected final Validator getValidator()

Return the Validator for this controller.

setValidateOnBinding

public final void setValidateOnBinding(boolean validateOnBinding)

Set if the Validator should get applied when binding.

isValidateOnBinding

protected final boolean isValidateOnBinding()

Return if the Validator should get applied when binding.

getCommand

protected java.lang.Object getCommand(javax.servlet.http.HttpServletRequest request)
                               throws java.lang.Exception

Retrieve a command object for the given request.

Default implementation calls createCommand. Subclasses can override this.

Parameters:

request - current HTTP request

Returns:

object command to bind onto

Throws:

java.lang.Exception

See Also:

createCommand()

createCommand

protected final java.lang.Object createCommand()
                                        throws java.lang.InstantiationException,
                                               java.lang.IllegalAccessException

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

Returns:

the new command instance

Throws:

java.lang.InstantiationException - if the command class could not be instantiated

java.lang.IllegalAccessException - if the class or its constructor is not accessible

checkCommand

protected final boolean checkCommand(java.lang.Object command)

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

Parameters:

command - command object to check

Returns:

if the command object is valid for this controller

bindAndValidate

protected final ServletRequestDataBinder bindAndValidate(javax.servlet.http.HttpServletRequest request,
                                                         java.lang.Object command)
                                                  throws java.lang.Exception

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

Parameters:

request - current HTTP request

command - command to bind onto

Returns:

the ServletRequestDataBinder instance for additional custom validation

Throws:

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

createBinder

protected ServletRequestDataBinder createBinder(javax.servlet.http.HttpServletRequest request,
                                                java.lang.Object command)
                                         throws java.lang.Exception

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

Default implementation creates a standard ServletRequestDataBinder and invokes initBinder. Note that initBinder will not be invoked automatically if you override this method!

Parameters:

command - command to bind onto

request - current request

Returns:

the new binder instance

Throws:

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

See Also:

bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object), initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)

initBinder

protected void initBinder(javax.servlet.http.HttpServletRequest request,
                          ServletRequestDataBinder binder)
                   throws java.lang.Exception

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.

Parameters:

request - current request

binder - new binder instance

Throws:

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

See Also:

createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object), DataBinder.registerCustomEditor(java.lang.Class, java.beans.PropertyEditor), CustomDateEditor

onBind

protected void onBind(javax.servlet.http.HttpServletRequest request,
                      java.lang.Object command)
               throws java.lang.Exception

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

Parameters:

request - current HTTP request

command - command object to perform further binding on

Throws:

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

See Also:

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

onBindAndValidate

protected void onBindAndValidate(javax.servlet.http.HttpServletRequest request,
                                 java.lang.Object command,
                                 BindException errors)
                          throws java.lang.Exception

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

Parameters:

request - current HTTP request

command - 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(javax.servlet.http.HttpServletRequest, java.lang.Object), Errors