BaseCommandController (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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:
    Aware, ApplicationContextAware, ServletContextAware, Controller
  Direct Known Subclasses:
    AbstractCommandController, AbstractFormController

  Deprecated.
  as of Spring 3.0, in favor of annotated controllers

      @Deprecated
      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:
  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 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 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() 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.
  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.

  Author:
    Rod Johnson, Juergen Hoeller

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_COMMAND_NAME` Deprecated. Default command name used for binding command objects: "command"

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

      `METHOD_GET, METHOD_HEAD, METHOD_POST`

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

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BaseCommandController()` Deprecated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected ServletRequestDataBinder` | `bindAndValidate(HttpServletRequest request, Object command)` Deprecated. Bind the parameters of the given request to the given command object.
    `protected boolean` | `checkCommand(Object command)` Deprecated. Check if the given command object is a valid for this controller, i.e.
    `protected ServletRequestDataBinder` | `createBinder(HttpServletRequest request, Object command)` Deprecated. Create a new binder instance for the given command and request.
    `protected Object` | `createCommand()` Deprecated. Create a new command instance for the command class of this controller.
    `BindingErrorProcessor` | `getBindingErrorProcessor()` Deprecated. Return the strategy to use for processing binding errors (if any).
    `protected Object` | `getCommand(HttpServletRequest request)` Deprecated. Retrieve a command object for the given request.
    `Class` | `getCommandClass()` Deprecated. Return the command class for this controller.
    `String` | `getCommandName()` Deprecated. Return the name of the command in the model.
    `MessageCodesResolver` | `getMessageCodesResolver()` Deprecated. Return the strategy to use for resolving errors into message codes (if any).
    `PropertyEditorRegistrar[]` | `getPropertyEditorRegistrars()` Deprecated. Return the PropertyEditorRegistrars (if any) to be applied to every DataBinder that this controller uses.
    `Validator` | `getValidator()` Deprecated. Return the primary Validator for this controller.
    `Validator[]` | `getValidators()` Deprecated. Return the Validators for this controller.
    `WebBindingInitializer` | `getWebBindingInitializer()` Deprecated. Return the WebBindingInitializer (if any) which will apply pre-configured configuration to every DataBinder that this controller uses.
    `protected void` | `initApplicationContext()` Deprecated. Subclasses can override this for custom initialization behavior.
    `protected void` | `initBinder(HttpServletRequest request, ServletRequestDataBinder binder)` Deprecated. Initialize the given binder instance, for example with custom editors.
    `boolean` | `isValidateOnBinding()` Deprecated. Return if the Validator should get applied when binding.
    `protected void` | `onBind(HttpServletRequest request, Object command)` Deprecated. Callback for custom post-processing in terms of binding.
    `protected void` | `onBind(HttpServletRequest request, Object command, BindException errors)` Deprecated. Callback for custom post-processing in terms of binding.
    `protected void` | `onBindAndValidate(HttpServletRequest request, Object command, BindException errors)` Deprecated. Callback for custom post-processing in terms of binding and validation.
    `protected void` | `prepareBinder(ServletRequestDataBinder binder)` Deprecated. Prepare the given binder, applying the specified MessageCodesResolver, BindingErrorProcessor and PropertyEditorRegistrars (if any).
    `void` | `setBindingErrorProcessor(BindingErrorProcessor bindingErrorProcessor)` Deprecated. Set the strategy to use for processing binding errors, that is, required field errors and `PropertyAccessException`s.
    `void` | `setCommandClass(Class commandClass)` Deprecated. Set the command class for this controller.
    `void` | `setCommandName(String commandName)` Deprecated. Set the name of the command in the model.
    `void` | `setMessageCodesResolver(MessageCodesResolver messageCodesResolver)` Deprecated. Set the strategy to use for resolving errors into message codes.
    `void` | `setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar)` Deprecated. Specify a single PropertyEditorRegistrar to be applied to every DataBinder that this controller uses.
    `void` | `setPropertyEditorRegistrars(PropertyEditorRegistrar[] propertyEditorRegistrars)` Deprecated. Specify multiple PropertyEditorRegistrars to be applied to every DataBinder that this controller uses.
    `void` | `setValidateOnBinding(boolean validateOnBinding)` Deprecated. Set if the Validator should get applied when binding.
    `void` | `setValidator(Validator validator)` Deprecated. Set the primary Validator for this controller.
    `void` | `setValidators(Validator[] validators)` Deprecated. Set the Validators for this controller.
    `void` | `setWebBindingInitializer(WebBindingInitializer webBindingInitializer)` Deprecated. Specify a WebBindingInitializer which will apply pre-configured configuration to every DataBinder that this controller uses.
    `protected boolean` | `suppressBinding(HttpServletRequest request)` Deprecated. Return whether to suppress binding for the given request.
    `protected boolean` | `suppressValidation(HttpServletRequest request)` Deprecated. as of Spring 2.0.4, in favor of the `suppressValidation(HttpServletRequest, Object)` variant
    `protected boolean` | `suppressValidation(HttpServletRequest request, Object command)` Deprecated. Return whether to suppress validation for the given request.
    `protected boolean` | `suppressValidation(HttpServletRequest request, Object command, BindException errors)` Deprecated. Return whether to suppress validation for the given request.
    `protected boolean` | `useDirectFieldAccess()` Deprecated. Determine whether to use direct field access instead of bean property access.

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

      `handleRequest, handleRequestInternal, isSynchronizeOnSession, setSynchronizeOnSession`

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

      `applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, checkAndPrepare, getCacheSeconds, getSupportedMethods, isAlwaysMustRevalidate, isRequireSession, isUseCacheControlHeader, isUseCacheControlNoStore, isUseExpiresHeader, preventCaching, setAlwaysMustRevalidate, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseCacheControlNoStore, setUseExpiresHeader`

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

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### 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

    - #### DEFAULT_COMMAND_NAME

          public static final String DEFAULT_COMMAND_NAME

      Deprecated.
      Default command name used for binding command objects: "command"
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BaseCommandController

          public BaseCommandController()

      Deprecated.

  - ### Method Detail

    - #### setCommandName

          public final void setCommandName(String commandName)

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

    - #### getCommandName

          public final String getCommandName()

      Deprecated.
      Return the name of the command in the model.

    - #### setCommandClass

          public final void setCommandClass(Class commandClass)

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

    - #### getCommandClass

          public final Class getCommandClass()

      Deprecated.
      Return the command class for this controller.

    - #### setValidator

          public final void setValidator(Validator validator)

      Deprecated.
      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.

    - #### getValidator

          public final Validator getValidator()

      Deprecated.
      Return the primary Validator for this controller.

    - #### setValidators

          public final void setValidators(Validator[] validators)

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

    - #### getValidators

          public final Validator[] getValidators()

      Deprecated.
      Return the Validators for this controller.

    - #### setValidateOnBinding

          public final void setValidateOnBinding(boolean validateOnBinding)

      Deprecated.
      Set if the Validator should get applied when binding.

    - #### isValidateOnBinding

          public final boolean isValidateOnBinding()

      Deprecated.
      Return if the Validator should get applied when binding.

    - #### setMessageCodesResolver

          public final void setMessageCodesResolver(MessageCodesResolver messageCodesResolver)

      Deprecated.
      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:
        `createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `DataBinder.setMessageCodesResolver(org.springframework.validation.MessageCodesResolver)`

    - #### getMessageCodesResolver

          public final MessageCodesResolver getMessageCodesResolver()

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

    - #### setBindingErrorProcessor

          public final void setBindingErrorProcessor(BindingErrorProcessor bindingErrorProcessor)

      Deprecated.
      Set the strategy to use for processing binding errors, that is, required field errors and `PropertyAccessException`s.

      Default is `null`, that is, using the default strategy of the data binder.

      See Also:
        `createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `DataBinder.setBindingErrorProcessor(org.springframework.validation.BindingErrorProcessor)`

    - #### getBindingErrorProcessor

          public final BindingErrorProcessor getBindingErrorProcessor()

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

    - #### setPropertyEditorRegistrar

          public final void setPropertyEditorRegistrar(PropertyEditorRegistrar propertyEditorRegistrar)

      Deprecated.
      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(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`.

      See Also:
        `initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`

    - #### setPropertyEditorRegistrars

          public final void setPropertyEditorRegistrars(PropertyEditorRegistrar[] propertyEditorRegistrars)

      Deprecated.
      Specify multiple PropertyEditorRegistrars 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(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`.

      See Also:
        `initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`

    - #### getPropertyEditorRegistrars

          public final PropertyEditorRegistrar[] getPropertyEditorRegistrars()

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

    - #### setWebBindingInitializer

          public final void setWebBindingInitializer(WebBindingInitializer webBindingInitializer)

      Deprecated.
      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(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`.

    - #### getWebBindingInitializer

          public final WebBindingInitializer getWebBindingInitializer()

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

    - #### initApplicationContext

          protected void initApplicationContext()

      Deprecated.
      Description copied from class: `ApplicationObjectSupport`
      Subclasses can override this for custom initialization behavior.

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

      Overrides:
        `initApplicationContext` in class `ApplicationObjectSupport`
      See Also:
        `ApplicationObjectSupport.setApplicationContext(org.springframework.context.ApplicationContext)`

    - #### getCommand

          protected Object getCommand(HttpServletRequest request)
                               throws Exception

      Deprecated.
      Retrieve a command object for the given request.

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

      Parameters:
        `request` - current HTTP request
      Returns:
        object command to bind onto
      Throws:
        `Exception` - if the command object could not be obtained
      See Also:
        `createCommand()`

    - #### createCommand

          protected final Object createCommand()
                                        throws Exception

      Deprecated.
      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:
        `BeanUtils.instantiateClass(Class)`

    - #### checkCommand

          protected final boolean checkCommand(Object command)

      Deprecated.
      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

    - #### bindAndValidate

          protected final ServletRequestDataBinder bindAndValidate(HttpServletRequest request,
                                                 Object command)
                                                            throws Exception

      Deprecated.
      Bind the parameters of the given request to the given command object.
      Parameters:
        `request` - current HTTP request
        `command` - the command to bind onto
      Returns:
        the ServletRequestDataBinder instance for additional custom validation
      Throws:
        `Exception` - in case of invalid state or arguments

    - #### suppressBinding

          protected boolean suppressBinding(HttpServletRequest request)

      Deprecated.
      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 HTTP request
      Returns:
        whether to suppress binding for the given request
      See Also:
        `suppressValidation(javax.servlet.http.HttpServletRequest, java.lang.Object, org.springframework.validation.BindException)`

    - #### createBinder

          protected ServletRequestDataBinder createBinder(HttpServletRequest request,
                                              Object command)
                                                   throws Exception

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

      Called by `bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)`. Can be overridden to plug in custom ServletRequestDataBinder instances.

      The default implementation creates a standard ServletRequestDataBinder and invokes `prepareBinder(org.springframework.web.bind.ServletRequestDataBinder)` and `initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`.

      Note that neither `prepareBinder(org.springframework.web.bind.ServletRequestDataBinder)` nor `initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)` will be invoked automatically if you override this method! Call those methods at appropriate points of your overridden method.

      Parameters:
        `request` - current HTTP request
        `command` - the command to bind onto
      Returns:
        the new binder instance
      Throws:
        `Exception` - in case of invalid state or arguments
      See Also:
        `bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `prepareBinder(org.springframework.web.bind.ServletRequestDataBinder)`, `initBinder(javax.servlet.http.HttpServletRequest, org.springframework.web.bind.ServletRequestDataBinder)`

    - #### prepareBinder

          protected final void prepareBinder(ServletRequestDataBinder binder)

      Deprecated.
      Prepare the given binder, applying the specified MessageCodesResolver, BindingErrorProcessor and PropertyEditorRegistrars (if any). Called by `createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object)`.
      Parameters:
        `binder` - the new binder instance
      See Also:
        `createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `setMessageCodesResolver(org.springframework.validation.MessageCodesResolver)`, `setBindingErrorProcessor(org.springframework.validation.BindingErrorProcessor)`

    - #### useDirectFieldAccess

          protected boolean useDirectFieldAccess()

      Deprecated.
      Determine whether to use direct field access instead of bean property access. Applied by `prepareBinder(org.springframework.web.bind.ServletRequestDataBinder)`.

      Default is "false". Can be overridden in subclasses.

      Returns:
        whether to use direct field access (`true`) or bean property access (`false`)
      See Also:
        `prepareBinder(org.springframework.web.bind.ServletRequestDataBinder)`, `DataBinder.initDirectFieldAccess()`

    - #### initBinder

          protected void initBinder(HttpServletRequest request,
                        ServletRequestDataBinder binder)
                             throws Exception

      Deprecated.
      Initialize the given binder instance, for example with custom editors. Called by `createBinder(javax.servlet.http.HttpServletRequest, java.lang.Object)`.

      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 HTTP request
        `binder` - the new binder instance
      Throws:
        `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(HttpServletRequest request,
                    Object command,
                    BindException errors)
                         throws Exception

      Deprecated.
      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(HttpServletRequest, Object)`.

      Parameters:
        `request` - current HTTP 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:
        `bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `onBind(HttpServletRequest, Object)`

    - #### onBind

          protected void onBind(HttpServletRequest request,
                    Object command)
                         throws Exception

      Deprecated.
      Callback for custom post-processing in terms of binding.

      Called by the default implementation of the `onBind(HttpServletRequest, Object, BindException)` variant with all parameters, after standard binding but before validation.

      The default implementation is empty.

      Parameters:
        `request` - current HTTP request
        `command` - the command object to perform further binding on
      Throws:
        `Exception` - in case of invalid state or arguments
      See Also:
        `onBind(HttpServletRequest, Object, BindException)`

    - #### suppressValidation

          protected boolean suppressValidation(HttpServletRequest request,
                                   Object command,
                                   BindException errors)

      Deprecated.
      Return whether to suppress validation for the given request.

      The default implementation delegates to `suppressValidation(HttpServletRequest, Object)`.

      Parameters:
        `request` - current HTTP request
        `command` - the command object to validate
        `errors` - validation errors holder, allowing for additional custom registration of binding errors
      Returns:
        whether to suppress validation for the given request

    - #### suppressValidation

          protected boolean suppressValidation(HttpServletRequest request,
                                   Object command)

      Deprecated.
      Return whether to suppress validation for the given request.

      Called by the default implementation of the `suppressValidation(HttpServletRequest, Object, BindException)` variant with all parameters.

      The default implementation delegates to `suppressValidation(HttpServletRequest)`.

      Parameters:
        `request` - current HTTP request
        `command` - the command object to validate
      Returns:
        whether to suppress validation for the given request

    - #### suppressValidation

          @Deprecated
          protected boolean suppressValidation(HttpServletRequest request)

      Deprecated. as of Spring 2.0.4, in favor of the `suppressValidation(HttpServletRequest, Object)` variant
      Return whether to suppress validation for the given request.

      Called by the default implementation of the `suppressValidation(HttpServletRequest, Object)` variant with all parameters.

      The default implementation is empty.

      Parameters:
        `request` - current HTTP request
      Returns:
        whether to suppress validation for the given request

    - #### onBindAndValidate

          protected void onBindAndValidate(HttpServletRequest request,
                               Object command,
                               BindException errors)
                                    throws Exception

      Deprecated.
      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 HTTP 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:
        `bindAndValidate(javax.servlet.http.HttpServletRequest, java.lang.Object)`, `Errors`