Improve documentation on options for configuring Spring MVC [SPR-8784]

[spring-projects-issues]

Bozhidar Bozhanov opened SPR-8784 and commented

Many occurrences of the built-in namespace handlers are painful to use. That includes <mvc:annotation-driven />, <security:http />, <oauth:xx /> to name a few.

The problem is that once you go outside the standard use-case (and that happens in practically all of the projects I've used that), you have to drop the namespace and define all beans manually, one by one. Which would not be that bad, if it was mentioned anywhere in the documentation how to do that. Now you have to go the the XBeanDefinitionParser, read the code and see what beans are being registered, and what properties they are initialized with. And that code is not the nicest one to read. Plus - this defeats the whole purpose of having a one-tag-to-configure-the-basics. Because it makes you stuck with the basics only, rather than allowing you to built ontop of that. (I know there is at least an issue about mvc:annotation-driven that requests the option to customize a XHandlerAdapter). Another thing is - it is hard to debug once you happen to have a number of beans with names #0 that you haven't registered and don't know anything about (well, I agree you should know where they come from, but you can't override just that particular one - you have to override all). All that leads to questions like this one: http://stackoverflow.com/questions/3693397/howto-get-rid-of-mvcannotation-driven/3694059

How to improve that - I don't know exactly, but something out of the top of my head - allow defining <bean> tags inside the namespace-specific tag. Like:

mvc:annoation-driven
<bean class="...HandlerAdapter"><!-- some custom properties --></bean>
</mvc:annotation-driven>

which will automatically replace the XHandlerAdapter defined by the BeanDefinitionParser with the custom one. I'm reporting the 'issue' in spring-core, because I think that for example AbstractBeanDefinitionParser, or the classes used to register the beans (ParserContext, etc), can be made aware of those inner beans, and use a bean with the same-class-or-subclass, if one is defined with <bean>. I know that sounds vague, but the final idea is to allow customization of just one of the beans defined by the catch-all tag.

(And another thing is documentation. AnnotationDrivenBeanDefinitionParser does a good job showing what beans exactly it defines (except that its javadoc has not been updated from 3.0 to 3.1), but this is not true for many other parsers from portfolio projects. I know the core project can't enforce that, but just mentioning it)

---

No further details from SPR-8784

[spring-projects-issues]

Chris Beams commented

Hi Bozhidar,

This is very much what the new @Enable annotations like @EnableWebMvc are designed to address. Spring's XML namespaces are very useful, and a big improvement on having to do everything with low-level bean definitions, but when you get outside of the typical use cases, extensibility is a real issue. The @Enable family of annotations are designed to be simple for simple cases, but also to accommodate customization smoothly.

I'll let Rossen weigh in further on @EnableWebMvc particularly, including perhaps responding to the linked stackoverflow thread.

[spring-projects-issues]

Rossen Stoyanchev commented

Indeed the more extensive a namespace is, the harder it is to provide a balance between simplicity and flexibility. Probably the best approach to customizing some individual property using an existing mechanism is to define a BeanPostProcessor that modifies a bean after it has been initialized. However it's not an obvious solution and perhaps needs to be mentioned somewhere.

Still there is no easy way to find out the exact beans created by the namespace. We can provide a section in the documentation that describes the process of replacing the namespace with explicit configuration. Probably not down to every detail but at least the bean types registered and the BeanDefinitionParsers.

As for the Java-based config alternative (@Enable*), it does indeed address both concerns of transparency and flexibility. For example with @EnableWebMvc you can see the exact configuration details and beans created in WebMvcConfigurationSupport. Also you can customize the created beans. The javadoc of @EnableWebMvc has a brief overview.

[spring-projects-issues]

Bozhidar Bozhanov commented

Thanks, I didn't know about @Enable*. I've used the PostProcessor option, but I agree it should be mentioned somewhere (I got to it 'the hard way').

So perhaps the issue is more about improving the documentation and tutorials to make them mention all these alternatives.

[spring-projects-issues]

Rossen Stoyanchev commented

I've added a comment under #13426 to that extent.

[spring-projects-issues]

Rossen Stoyanchev commented

The section on configuring Spring MVC in the reference documentation has been revised to include the MVC Java config and the MVC namespace options side-by-side including information on how to make more fine-grained customizations.

The Javadoc of the AnnotationDrivenBeanDefinitionParser was also updated recently to describe what beans are created.

[spring-projects-issues]

Rossen Stoyanchev commented

Modified title to reflect discussion and the actual changes. Was: "Improved namespace handling".