How to Use Fragments and Annotations To Configure Your Web Application

posted by mthomas on October 11, 2011 09:10 AM

The Servlet 3 specification - implemented in Apache Tomcat 7 - allows web.xml fragments and annotations to be used to specify configuration information for a web application. This means that, instead of packaging up every configuration centrally in your web.xml file, every JAR can have its own xml fragment containing its own little bit of configuration for whatever classes are in that JAR. This makes it easy to add support for packages with very little effort. For instance, a Spring developer would no longer need to add the Spring application context to the web.xml file, rather they could take advantage of a web fragment in the Spring JAR that would automatically add this configuration information at runtime.

Annotations take this one step further, and allow developers to annotate code that dynamically configures application components such as Servlets and Filters. Java libraries and frameworks have been embracing annotations for some time. In fact, several IDE’s these days use annotations as a default, adding the @WebServlet annotation by default when you create a new Servlet in a dynamic web project.

Performance Impacts

Both annotations and web fragments will impact performance, particularly at application startup. Tomcat has to scan every class in every single jar file to detect if the class has been annotated as a Servlet, a Filter or Listener. This can add substantial time to application start up, which is not so much of a problem for production applications as they should start very infrequently, but it can be pretty problematic during development when you are repetitively restarting.

Tip: If you are not going to be using annotations or web-fragments, you should set your metadata-complete to true in your web.xml file to avoid the longer start up time. (web-app metadata-complete=""true"").

Support Impacts

Another complication is that it forces support staff and administrators to look in more places to answer the same question. For instance, if your administrator wants to know how is a web application going to respond to a request, prior to Servlet 3 they could just into the web.xml file and it would tell them everything they needed to know. Now, fragments and annotations spread configuration information out to several locations, so instead of just checking the Servlet definition in web.xml they may need to check the source code to find the url mapping. It forces support staff to know more about the application itself, and increases time to debug simply by adding more places to look.

Tip: Tomcat can log the equivalent merged web.xml that takes all of the fragments, all of the annotations, and produces you a fully aggregated web.xml file by setting the logEffectiveWebXml attribute on the Context element to true. The easiest way to do this is to set this for all applications by adding this setting to the global defaults in $CATALINA_BASE/conf/context.xml. I recommend taking this output and replacing the production web.xml file with this more complete one. It will help speed problem identification for support, and also when used with the metadata-complete parameter above will improve application start times as well.

Mark Thomas is a Senior Software Engineer for the SpringSource Division of VMware, Inc. (NYSE: VMW). Mark has been using and developing Tomcat for over six years. He first got involved in the development of Tomcat when he needed better control over the SSL configuration than was available at the time. After fixing that first bug, he started working his way through the remaining Tomcat bugs and is still going. Along the way Mark has become a Tomcat committer and PMC member, volunteered to be the Tomcat 4 & 7 release manager, created the Tomcat security pages, become a member of the ASF and joined the Apache Security Committee. He also helps maintain the ASF's Bugzilla instances. Mark has a MEng in Electronic and Electrical Engineering from the University of Birmingham, United Kingdom.