Web container allows the web applications to contain both the annotations and metadata in the XML files named
web fragments. If there is no web deployment descriptor file web.xml or the meta-complete attribute is set to false, then web container is obliged to search the plain old JAR files placed in the WEB-INF/lib directory for the pluggable Servlet annotations. The container is also obliged to search the JAR special named files named web fragments in the folder META-INF/, which match web-fragment.xml. The contents of web.xml and web-fragment.xml are almost the same.
Web fragments are descriptors that introduce pluggability into the Servlet specification. It can be seen as a weak form of modularity without enforcement of the class boundaries. Fragments allow different JAR files from other projects, which maybe separate, to be brought together, and assemble into a WAR file, and hence a web application.
Let's suppose we have a fictional example of an integrated library implemented as web fragment. We have an ACME electronic commerce, and the web development team in the organization packaged a library as a two event listener, namely an HTTP session listener and a Servlet context listener. They have also given us a Servlet filter to handle user security.
A possible web-fragment.xml file for this situation is as follows:
<web-fragment>
<listener>
<listener-class>
acme.LoginUserServletContextListener
</listener-class>
</listener>
<listener>
<listener-class>
acme.LoginUserSessionContextListener
</listener-class>
</listener>
<filter>
<filter-name>userSecurityFilter</filter-name>
<filter-class>acme.UserSecurityFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>userSecurityFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<web-fragment>This file could be part of an acme-user-security.jar file and placed in the WEB-INF/lib directory.
You may be wondering what can happen if I have more than one web fragment inside an application. How do we go about establishing an order of registration?
There are two ways to achieve the ordering in the modular web fragments. In the deployment descriptor file web.xml, we can use a special XML element named <absolute-ordering>. In any web fragment file web-fragment.xml, we can use another XML element named <ordering>.
Let's see an example:
<web-app>
...
<absolute-ordering>
<name>Fragment1</name>
<others/>
<name>Fragment2</name>
<absolute-ordering>
</web-app>The XML element <absolute-ordering> lists other web fragments by the name from the subelement <name> and the order is the first listed, the first initialized. Note the special <others> XML element in there, which is a placeholder for all other web fragments that may or may not exist in the web application. The reading of this ordering, then, is Fragment1, any other web fragments, and then Fragment2.
Web fragments can also contain ordering themselves. An example of this ordering named Fragment3 is as follows:
<web-fragment>
<name>Fragment3</name>
...
<ordering>
<before>
<others/>
</before>
<after>
<name>SalesFragement</name>
<name>Fragment2</name>
</after>
</ordering>
</web-fragment> First of all, a web fragment can have given a name. The child of the root element named <name> specifies the name of the preceding web fragment.
In a web fragment, the XML element <ordering> defines the order. A web fragment can specify the registration to appear before or after other fragments, as you saw in the previous example. There, Fragment3 is initialized before other fragments, and also after particular fragments SalesFragment and Fragment2 have been successfully initialized. So we see that these orderings are metadata and declarative instructions for the Servlet 3.0 or better container to observe in a web application.
It is instructive to inspect the reverse of this ordering as follows:
<web-fragment>
<name>Fragment4</name>
...
<ordering>
<before>
<name>SalesFragement</name>
<name>Fragment3</name>
</before>
<after>
<others/>
</after>
</ordering>
</web-fragment> In the previous example, Fragment4 is initialized after all other web fragments, but before SalesFragment and the previous Fragment3.
Ordering cannot be achieved currently with the annotations at least with the Java Servlet 3.1 specification, so they must be applied with the XML configuration files. However, as we have seen before, these XML deployment descriptors, and the fragment files can be more or less empty save the ordering, and still the annotations on the Java classes will work.
Of course, the Servlet web container will disable scanning for and processing the annotations when the attribute metadata-complete is set to true in either <web-fragment> or a <webapp> root XML element.