When the original servlet API was released back in the late 1990s, writing servlets was the only way of writing server-side web applications in Java. Since then, several standard Java EE and third-party frameworks have been built on top of the Servlet API. Examples of such standard frameworks include JSP and JSF, and third-party frameworks include Struts, Wicket, Spring Web MVC, and several others.

Nowadays, very few (if any) Java web applications are built using the Servlet API directly; instead, the vast majority of projects utilize one of the several available Java web application frameworks. All of these frameworks use the Servlet API "under the covers", therefore setting up an application to use one of these frameworks has always involved making some configuration in the application's web.xml deployment descriptor. In some cases, some applications use more than one framework, but this tends to make the web.xml deployment descriptor fairly large and hard to maintain.

Servlet 3.0 introduced the concept of pluggability. Web application framework developers now have not one, but two ways to avoid having application developers have to modify the web.xml deployment descriptor in order to use their framework. Framework developers can choose to use annotations instead of a web.xml to configure their servlets; after doing this, all that is needed to use the framework is to include the library JAR file(s) provided by the framework developers in the application's WAR file. Alternatively, framework developers may choose to include a web-fragment.xml as part of the JAR file to be included in web applications that use their framework.

web-fragment.xml is almost identical to web.xml, the main difference is that the root element of a web-fragment.xml is <web-fragment> as opposed to <web-app>. The following example illustrates a sample web-fragment.xml:

<?xml version="1.0" encoding="UTF-8"?> 
<web-fragment version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
  http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"> 
  <servlet> 
    <servlet-name>WebFragment</servlet-name> 
    <servlet-class> 
      net.ensode.glassfishbook.webfragment.WebFragmentServlet 
    </servlet-class> 
  </servlet> 
  <servlet-mapping> 
    <servlet-name>WebFragment</servlet-name> 
    <url-pattern>/WebFragment</url-pattern> 
  </servlet-mapping> 
</web-fragment> 

As we can see, web-fragment.xml is almost identical to a typical web.xml. In this simple example, we only use the <servlet> and <servlet-mapping> elements, but all other usual web.xml elements, such as <filter>, <filter-mapping>, and <listener>, are available as well.

As specified in our web-fragment.xml, our servlet can be invoked via its URL pattern, /WebFragment, therefore the URL to execute our servlet once deployed as part of a web application would be http://localhost:8080/webfragmentapp/WebFragment. Of course, the host name, port, and context root must be adjusted as appropriate.

All we need to do for any Java EE-compliant application server to pick up the settings in web-fragment.xml is to place the file in the META-INF folder of the library where we pack our servlet, filter, and/or listener, then place our library's JAR file in the lib folder of the WAR file containing our application.