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.

Author: Robert Watkins

My name is Robert Watkins. I am a software developer and have been for over 20 years now. I currently work for people, but my opinions here are in no way endorsed by them (which is cool; their opinions aren’t endorsed by me either). My main professional interests are in Java development, using Agile methods, with a historical focus on building web based applications. I’m also a Mac-fan and love my iPhone, which I’m currently learning how to code for. I live and work in Brisbane, Australia, but I grew up in the Northern Territory, and still find Brisbane too cold (after 22 years here). I’m married, with two children and one cat. My politics are socialist in tendency, my religious affiliation is atheist (aka “none of the above”), my attitude is condescending and my moral standing is lying down. View all posts by Robert Watkins