Doc: Overriding of default values for HandlerMapping, HandlerAdapter et al. in DispatcherServlet is not obvious [SPR-4086]

[spring-projects-issues]

Chris Lee opened SPR-4086 and commented

DispatcherServlet chooses reasonable defaults for HandlerMapping, HandlerAdapter (and others). For these two specific types, there are multiple defaults listed:

org.springframework.web.servlet.HandlerMapping=org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping,
org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping

org.springframework.web.servlet.HandlerAdapter=org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter,
org.springframework.web.servlet.mvc.SimpleControllerHandlerAdapter,
org.springframework.web.servlet.mvc.throwaway.ThrowawayControllerHandlerAdapter,
org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter

While the JavaDoc for DispatcherServlet does state that any user-added beans of these types override the defaults, there are several challenges with this approach:

1. Users need to be made aware of the implications of overriding the defaults
2. Overriding the defaults breaks forward compatibility (see below)
3. It seems excessive / verbose to re-register defaults to get back core functionality

As an example, an existing Spring 2.0.x application that defined its own HandlerMapping(s) would not be able to use the Spring 2.5.x @RequestMapping functionality without adding DefaultAnnotationHandlerMapping and AnnotationMethodHandlerAdapter beans to their context (after spending time to determine that these were the necessary steps).

There are several use cases to address:

1. Addition of a HandlerMapping (and/or HandlerAdapter) while keeping the existing defaults
2. Removal of a HandlerMapping (and/or HandlerAdapter); it is less clear that this is a valid or common case on its own
3. The combination of 1 & 2, where you want to specify precisely what should be there (remove all defaults and supply your own)

---

Affects: 2.5 RC2

Issue Links:

• @Controller annotated controllers can not co-exist with not annotated ones. [SPR-4088] #8767 @Controller annotated controllers can not co-exist with not annotated ones.

[spring-projects-issues]

Juergen Hoeller commented

Well, arguably forward compatibility is not that big of a deal here. If you want to adopt new functionality like Spring 2.5's @RequestMapping in an existing application, you need to do some effort in the first place - I would argue that caring for proper configuration is not too much to ask for here.

Also, if all you manually defined was a custom HandlerMapping, then you only need to define a DefaultAnnotationHandlerMapping bean. The AnnotationMethodHandlerAdapter would still be registered as implicit default. After all, hardly anybody specifies custom HandlerAdapters...

The main problem here is that custom HandlerMappings / HandlerAdapters may conflict with default ones. A typical case is specifying a custom BeanNameUrlHandlerMapping which implicitly means that the default one should be deactivated; the same applies to a custom DefaultAnnotationHandlerMapping. Doing individual deactivation of specific default strategies is hard here, since in general we don't know where exactly the conflicts would be: You could be using a BeanNameUrlHandlerMapping subclass, or a custom HandlerMapping implementation that adopts the same strategy... Class name based deactivation won't work here.

We could only really do individual deactivation if we required specific bean names for specific strategies (e.g. "beanNameMapping", "annotationMapping"), with custom strategies having to use the exact corresponding bean name in order to override the specific default strategy. That convention wouldn't be immediately obvious either, though.

So I'm afraid there is no obvious 'better' way to handle the defaulting here, in particular taking the problem of conflicting strategies into account. Requiring explicit configuration seems to be the safer strategy to resolve such potential conflicts. That aside, many applications adopt one specific mapping strategy only, so would only have to define one such bean anyway.

I'm open for suggestions, of course...

Juergen

[spring-projects-issues]

Chris Lee commented

I had intended to suggest a custom namespace 'web' - but sobered up and realized that the added complexity of this doesn't address the core issue of user's understanding the plumbing.

Back to basics - improved documentation, specifically:

1. Reference manual - add a note explaining the need to register a DefaultAnnotationHandlerMapping (and perhaps a AnnotationsMethodHandlerAdapter) to section "13.12. Annotation-based controller configuration"
2. JavaDoc - add the same note to @RequestMapping
3. JavaDoc - add a note to DispatcherServlet to make it clear that use of @RequestMapping requires registering DefaultAnnotationHandlerMapping (and perhaps a AnnotationsMethodHandlerAdapter) if defaults are overridden.

[spring-projects-issues]

Juergen Hoeller commented

Done - should make it into the next nightly 2.5 snapshot.

Juergen