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.
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. (
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.