Servlet 3.0 web-fragment.xml

Servlet 3.0 web-fragment.xml

By Shing Wai Chan on May 07, 2009

In
JSR 315: Java Servlet 3.0 Specification, web-fragment.xml is introduced for pluggability of library jars which are packaged under WEB-INF/lib. The content of web.xml and web-fragment.xml are almost the same. One can define servlets, filters and listeners there. One can also specify metadata-complete=true in a given web-fragment.xml. In the latter case, the annotation processing of classes in that jar would be skipped. With web-fragment.xml, library jars can be self-contained and provide web related metadata information.
The basic differences of web.xml and web-fragment.xml are summarized in the following table:

	web.xml	web-fragment.xml
Location	WEB-INF of the war file	META-INF directory of JAR file inside WAR file's WEB-INF/lib
Ordering related element	<absolute-ordering>	<ordering>

Ordering of web fragments

If there are more than one web-fragment jars, then one may like to specify the order of processing web-fragment.xml and annotations. This is important. For instance, filters will be executed in the order specified in web.xml. Similary for listeners. In Servlet 3.0, <absolute-ordering> is introduced in web.xml and <ordering> is introduced in web-fragment.xml. The ordering of web-fragments is specified in the following priority:

from <absolute-ordering> in web.xml if it exists

from <ordering> for each web-fragment.xml if it exists

otherwise unspecified

absolute-ordering in web.xml

The <absolute-ordering> in web.xml provides a way to specify the ordering of loading web-fragment.xml and annotation processing of web fragment. For instance,

<web-app>

...

<absolute-ordering>

<name>A</name>

<others/>

<name>B</name>

<absolute-ordering>

</web-app>
In the above example, the web fragment A would be processed first and web fragment B would be processed last. Note the name A and B are specified in name element of web-fragment.xml (see examples below).

ordering in web-fragment.xml

If there is no <absolute-ordering> in web.xml, then one would look at <ordering> in web-fragment.xml. The details are described in section 8.2.3 of Servlet 3.0 spec. Let us look at some examples.

There is only one jar having <ordering> in web-fragment.xml.

<web-fragment>

<name>A</name>

...

<ordering>

<before>

<others/>

</before>

</ordering>

</web-fragment>
In this case, web-fragment A would be processed first.

There are two jars having <ordering> in web-fragment.xml, namely
web-fragment A:

<web-fragment>

<name>A</name>

...

<ordering>

<before>

<others/>

</before>

</ordering>

</web-fragment>
web-fragment B:

<web-fragment>

<name>B</name>

...

<ordering>

<before>

<others/>

</before>

</ordering>

</web-fragment>
Both web-fragment A and B would like to be processed first. In this case, one only guarantee that both A and B are processed before other web-fragments. But the ordering of A and B are not determined, that is arbitrary in this case.

There are two jars having <ordering> in web-fragment.xml, namely
web-fragment A:

<web-fragment>

<name>A</name>

...

<ordering>

<before>

<others/>

</before>

</ordering>

</web-fragment>
web-fragment B:

<web-fragment>

<name>B</name>

...

<ordering>

<after>

<name>A</name>

</after>

<before>

<others/>

</before>

</ordering>

</web-fragment>
In this case, A would be processed first, then followed by B, and then other web-fragments.

If one would like to have a deterministic ordering, then I would recommend to use absolute-ordering in web.xml.