2011 has been a great year for the Tomcat Expert community. After almost 2 years of operating, the Tomcat Expert has hit its stride, unloading an array of new information, as well as keeping you up to date with the newest releases for Apache Tomcat 6 and Apache Tomcat 7. With the addition of two new Tomcat Expert Contributors, (Channing Benson and Daniel Mikusa), the Tomcat Expert community continues to build on its reputation for being the leading source for fresh perspectives and new information on how to best leverage Apache Tomcat in the enterprise.
My last article for Tomcat Expert described various aspects of the Valve construct of Apache Tomcat: some basics about how to implement and configure a valve and an example of where things could go wrong if you were unaware of the operational details. For those of you who don’t remember (or didn’t read the article in the first place), the key takeaway was that because Tomcat valves are maintained as a chain, the order in which the valves are added to the configuration (typically in conf/server.xml) is significant, and the code that implements the filter must conclude with a call to invoke the next filter in the chain.
This time we’re going to lighten things up a bit with a general survey of what valves are available and how one might put them to use. Given the imminent arrival of the winter holiday season, one might think of it as the Apache Tomcat Valve Gift Catalog. Peruse it and find just the right gift for your favorite Tomcat administrator.
For each valve, I’ll describe its functionality, the most important configuration parameters, and point out any configuration subtleties that might not be apparent from the stock documentation. that can be found at http://tomcat.apache.org/tomcat-7.0-doc/config/valve.html. If there are any less well-known attributes or “secret” parameters associated with the valve, I’ll describe them.
The AccessLogValve can be configured at the context, host, or engine level and will log requests made to that container to a file. Attributes of AccessLogValve control the directory, the filename, and the format of the data to be written, including the ability to write information about headers (incoming and outgoing), cookies, and session or request attributes.
Valves have been an integral feature of Apache Tomcat since version 4 was introduced over seven years ago. As their name suggests, valves provide a way of inserting functionality within a pipeline, in this case, the Tomcat request / response stream. One simply writes a subclass of
org.apache.catalina.valves.ValveBase or a class that implements the
org.apache.catalina.valves.Valve interface and then adds an XML element with the valve’s classname to the appropriate configuration file (in most classes as a sub element of Engine in server.xml). Then, at some point (we’ll come back to that) in the processing of a request, your valve’s invoke method will be called. The invoke method gets passed both the Request and the Response objects, and is free to do whatever it likes with them (though having the power doesn’t mean it’s a good idea to use it).
You may be familiar with this paradigm through servlet filters used by web applications to do application-specific processing of the request / response pipeline. The key distinction between servlet filters and Tomcat Valves is that Valves are applied and controlled through the configuration of the application server. Depending on the container definition where the Valve element appears in the Tomcat configuration, the valve could be configured for all applications on the application server, a subset of applications, or even a single application (by locating the Valve element within a given Context).
This is a simple powerful model that has been written about extensively. A Google search on “tomcat valve” turns up a multitude of descriptions, examples, and “how tos”. The Reference Page on “The Valve Component” that ships with Apache Tomcat 7 documents the mechanism thoroughly along with descriptions of the valve implementations that ship by default. So why yet another article on the subject? What do I hope to add to the canon?
The effort started simply enough: The plan was to demonstrate the configuration and use of the
ThreadDiagnosticsValve that ships with VMware’s vFabric tc Server, a commercial application server based on Apache Tomcat. Additionally I would write and configure a custom Valve, in this case, a valve to exercise tc Server’s
ThreadDiagnosticsValve so that I could demonstrate its use and effects without actually having to have a misbehaving application to trigger it. Not exactly Nobel material, but I thought it would be a useful adjunct to the existing documentation and an interesting exercise.
However, it didn’t go exactly as planned and looking at the reason it didn’t is probably as helpful in understanding Tomcat Valves as the original exercise.