metadata-complete="true" is implicitly set and @WebFilter does not work when the version of web.xml is 2.3 or 2.4 in JBoss EAP 6

Environment

• Red Hat JBoss Enterprise Application Platform (EAP) 6.x

Issue

I add a new library jar which contains a servlet filter using @WebFilter to our legacy web application which web.xml version is specified as 2.4. But it does not work. The servlet filter is never invoked.

Resolution

Apply JBoss EAP 6.4 Cumulative Patch (CP) 6 or later

As workaround, please modify your web.xml and set to the version to 2.5 or 3.0:

<web-app 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-app_2_5.xsd"
         version="2.5">

or

<web-app 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-app_3_0.xsd"
         version="3.0">

Root Cause

As per Servlet 3.0 specification¹, annotation must be scanned regardless of the version of web.xml unless metadata-complete is explicitly set to true in web.xml. The issue is caused by:

This content is not included.BZ-1235627 - annotation must be scanned regardless of the version of web.xml unless metadata-complete is explicitly set to true

In Servlet 2.5, metadata-complete only affected the scanning of annotations at
deployment time. The notion of web-fragments did not exist in servlet 2.5. However
in servlet 3.0 metadata-complete affects scanning of all annotations and web-
fragments at deployment time. The version of the descriptor MUST not affect which
annotations you scan for in a web application. An implementation of a particular
version of the specification MUST scan for all annotations supported in that
configuration, unless metadata-complete is specified.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.