Source Code vs Documentation…

In any battle between the source code and the documentation, the documentation always loses. Note that this is not the same thing as the source code winning.

I was doing some work with Spring Security over the last couple of days, and I wanted to get the filter chain to initialise using the FilterConfig. According to the doco for the version I’m using (3.0.6), it should work. Straight from the manual:

In relation to lifecycle issues, the FilterChainProxy will always delegate init(FilterConfig) and destroy() methods through to the underlaying Filters if such methods are called against FilterChainProxy itself. In this case,FilterChainProxy guarantees to only initialize and destroy each Filter bean once, no matter how many times it is declared in the filter chain(s). You control the overall choice as to whether these methods are called or not via thetargetFilterLifecycle initialization parameter of DelegatingFilterProxy. By default this property is false and servlet container lifecycle invocations are not delegated through DelegatingFilterProxy.

However, it doesn’t. Reading through the code, this becomes very clear. In fact, that feature never made it to the 3.0.0 release – it got removed between the 3.0.0-M1 release and the 3.0.0-M2 release. But the doco didn’t get updated.

(Well, not for the 3.0.x line – it’s updated in the 3.1.x version, which is the current release)

The lesson here is that the documentation can never be trusted. If you see odd behaviour in code that contradicts what the documentation says, you need to assume the documentation is incorrect until proven otherwise.