After using Tomcat as the preferred Java-Servlet-Container for the last couple of years, I have been using Version 5.0.x built-in clustering support for only a few months now.
Single server servlet programming and deploying was almost always Tomcat independent; one hardly needed to look at Tomcat's source-code and while Tomcat's documentation always sucked, any Servlet.jar file's java-doc was good enough to write programs that would work well inside the container.
If I needed to find out about certain tags in one of the descriptors like server.xml, web.xml, context.xml, etc. there was always
BEA's Web site to look for a helping hand.
With clustering all that changed
Documentation about Tomcat-Clustering is almost none-existent on the Apache site. This
"how-to" is as detailed as it gets there. But no problem, we are talking about
open-source, right? All we have to do is to look at the code and we know what's going on, right?
Well, not exactly. The code in the clustering package is a mess. No documentation in the source files, not a single javadoc tag to be found.
Now, there are open-source projects out there, containing well-written code and documentation;
Jason Hunter's JDOM or
Marc De Scheemaecker Nano-XML come to mind. I had expected so much more when it comes to an established project like Tomcat, hosted on the prestigious Apache site.
Up to a couple of days ago - before I had read in the
Allan Holub's article in the January 2005 issue of the Software Developer Times - I thought it's just me, not being sharp enough to understand the Tomcat code, which for others must be so obvious that it doesn't need documentation - and the code that I considered a mess, in fact was brilliantly written and structured.
Allan Holub, whose opinion I value much for quite some time now, however concludes in his article:
- Tomcat's documentation is virtually unusable. It's a hodgepodge of inadequate .html files.
- The code is a mess. It's poorly structured, poorly documented and poorly written.
- You have to do a lot of work to use an open-source product like Tomcat.
- You have to test new versions rigorously.
