Skip to main content
Version: 4.12.x.x LTS

Filter Mapping Concepts

Several nevisAdmin 4 patterns configure filters for nevisProxy. These filters have to be applied to requests and/or responses. For this, you need to configure filter-mapping elements in a nevisProxy web.xml file. This chapter describes how patterns generate the filter-mapping elements, based on examples.

Filter Inheritance

Suppose there is a nevisAdmin 4 project containing the following patterns:

nevisAdmin 4 Test project with patterns

This project sets up a nevisProxy instance with one virtual host serving the domain www.mycompany.com.

By default, the Virtual Host pattern sets up an ErrorFilter to handle HTTP error codes (such as the 404 Not Found code, or the 500 Internal Server Error code). This default error filter ErrorHandler_Default is applied to the root location via the following filter-mapping element:

Root Location Filter Mapping​

<filter-mapping>
 <filter-name>ErrorHandler_Default</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

Because */ matches all paths, the default error filter is applied to all requests and responses: The filter is inherited** to all sub-locations.

Filters are always inherited by default.

Duplicated Filter Problem

Patterns often want to apply filters to specific sub-locations. This can cause the Duplicated Filter Problem. The following sample case illustrates this problem.

Suppose you have the following Web Application pattern:

Sample Web Application pattern

You want to give this application a different error handling: In case of an HTTP 404 Not Found error code, the application will return a nicer page than the default error page. In nevisAdmin 4, you can realize this by configuring a custom HTTP Error Handling pattern and assigning this pattern to the virtual host, via the Additional Settings field of the Virtual Host pattern:

Assigning Error Handling pattern to Virtual Host pattern**The *HTTP Error Handling* pattern Custom 404 in the previous figure generates the following *filter-mapping* element, mapping the custom error filter *ErrorHandler_Custom_404* to */myapp/

:

Sub-location Filter Mapping​

<filter-mapping>
 <filter-name>ErrorHandler_Custom_404</filter-name>
 <url-pattern>/myapp/*</url-pattern>
</filter-mapping>

But: The Virtual Host pattern already maps the default error filter ErrorHandler_Default to */**. This means that error handling would be done twice for requests sent to your application. This is what we call the Duplicated Filter Problem.

Filter Purpose Exclusion Mechanism

To solve the Duplicated Filter Problem, nevisAdmin 4 provides the filter purpose exclusion mechanism: When you declare a purpose for a filter, the nevisProxy generator automatically generates an exclude-url-regex expression for filter-mapping elements.

This algorithm works as follows:

  • When generating a filter F,patterns can set a purpose for this filter.
  • When F is mapped to a parent location P and a sub-location C, a regular expression R for C is generated.
  • R is added to the exclude-url-regex of the filter-mapping for F at P.

Because of this filter purpose exclusion mechanism, the filter-mapping element for the default error filter ErrorHandler_Default of our example changes as follows:

Root Location Filter Mapping​

<filter-mapping>
 <filter-name>ErrorHandler_Default</filter-name>
 <url-pattern>/*</url-pattern>
 <exclude-url-regex>^/myapp/.*$</exclude-url-regex>
</filter-mapping>

As of nevisAdmin 4.6, the filter purpose exclusion mechanism is applied for the following use cases (patterns):

  • HTTP Error Handling
  • Request Validation (ModSecurity)
  • CSRF Protection