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
FilterChainProxywill always delegate
destroy()methods through to the underlaying
Filters if such methods are called against
FilterChainProxyitself. In this case,
FilterChainProxyguarantees to only initialize and destroy each
Filterbean 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 the
targetFilterLifecycleinitialization parameter of
DelegatingFilterProxy. By default this property is
falseand servlet container lifecycle invocations are not delegated through
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.