Filter and Servlet configuration
Loading filters and servlets
For the nevisProxy servlet container to load a filter, the following sample configuration definition has to be included in the web.xml of a web application:
<filter>
<filter-name>TestFilter</filter-name>
<filter-class>ch::nevis::navajo::servlet::example::TestFilter</filter-class>
<filter-lib>libTestServlet.so.1</filter-lib>
<init-param>
<param-name>SomeName</param-name>
<param-value>some-value</param-value>
<description>some configuration for the test filter</description>
</init-param>
</filter>
The description of the above tags:
- filter-name: It specifies a logical name for the filter. This is the name that is used for the mapping of the respective filter.
- filter-class: It specifies the class name that is used for loading the filter, i.e., the class name of the filter in the sense of C++.
- filter-lib: The tags filter-lib and servlet-lib are the only extensions made to the web-app_2_3.dtd. It specifies the library containing the filter. The library is searched in the subdirectory 'WEB-INF/lib' of the configured docBase directory.
- init-param: It may occur several times, and is used for the configuration of the filter. It consist of the following:
The configuration of servlets is similar:
<servlet>
<servlet-name>TestServlet</servlet-name>
<servlet-class>ch::nevis::navajo::servlet::example::TestServlet</servlet-class>
<servlet-lib>libTestServlet.so.1</servlet-lib>
<init-param>
<param-name>SomeName</param-name>
<param-value>some-value</param-value>
<description>some configuration for the test servlet</description>
</init-param>
</servlet>
If a filter or servlet cannot be loaded, the servlet container writes a detailed error message in the log about why it could not load the configuration, and continues processing.
Context Parameters
There is some configuration data that has to be shared with different filters or servlets of a web application. This data is configured in the context-param tag, as shown in the example:
<context-param>
<param-name>application-id</param-name>
<param-value>MobileApplication</param-value>
</context-param>
As for the filter/servlet configuration, the value of param-name must be unique. The following context parameters can be configured:
| Name | Type | Description |
|---|---|---|
| application-id | string | Needed by the MySQLSessionStoreServlet. For more information, see the Limitations chapter in MySQLSessionStoreServlet. |
| SectokenVerifierCert | newline separated string of filenames contains the verifier certificate | Needed by the IdentityCreationFilter and SecurityRoleFilter. The files (in pem format) containing the certificates to verify the signature of the sectoken. If a file contains multiple certificates then each of them will be loaded. |
Mapping filters and servlets
The mapping of a servlet into a URL namespace looks as follows:
<filter-mapping>
<filter-name>TestFilter</filter-name>
<url-pattern>/test/*</url-pattern>
<exclude-url-regex>/test/foo/.*</exclude-url-regex>
</filter-mapping>
Additionally to the servlet-mappings, it is possible to define exceptions based on a regular expression or IP using the following tags:
- exclude-url-regex: If the defined regular expression matches on the URL, the specified filter is not called.
- ip: A newline, spaces, or comma separated list of IP addresses (CIDR format) for which the filter has to match.
- exclude-ip: A newline, spaces, or comma separated list of IP-addresses (CIDR format) for which the filter should not match.
A filter is considered to match, if the following conditions are all true:
- the url-pattern matches
- if one or more ip is set: at least one of them matches
- if one or more exclude-ip is set: none of them match
- if one or more exclude-url-regex is set: none of them match
It is also possible to define the mapping of a filter directly on a servlet, by using the servlet-name tag. Such a filter is called each time the specified servlet is called:
<filter-mapping>
<filter-name>TestFilter</filter-name>
<servlet-name>ServletName</servlet-name>
</filter-mapping>
Constructing the filter chain
The filter chain is an assembly of filter mappings. Every filter mapping with a URL pattern that matches the beginning of the path is added to the filter chain. The filter chain order matches the ordering of the filter mapping configuration in the web.xml.
Example
Let us assume that the context path of a web application is store, and that there are several filters and servlets configured with the following mappings:
| URL Pattern | Servlet Name | Filter Name(s) |
|---|---|---|
| /test/* | TestServlet1 | TestFilter1 |
| /test/foo/* | TestServlet2 | TestFilter1, TestFilter2 |
| /test/bar/* | TestServlet2 |
This results in the following URL mapping:
| Request URL | Invoked Servlet | Invoked Filter Chain |
|---|---|---|
| /store/test/ | TestServlet1 | TestFilter1 |
| /store/test | ||
| /store/test/egal* | TestServlet1 | TestFilter1 |
| /store/test/foo/doit | TestServlet2 | TestFilter1, TestFilter1, TestFilter2 |
| /store/test/bar/egal | TestServlet2 | TestFilter1 |
Error Mapping
In the web.xml file, a mapping between the HTTP status code and a configured file can be specified. As an example:
<error-page>
<error-code>500</error-code>
<location>/errorpages/server_error.html</location>
</error-page>
In this case, if a 500 status code is generated on the backend side, the error is overwritten and the client receives the /errorpages/server_error.html error page. The files are searched in the specified docBase directory. For a more fine-grained error mapping, see the chapter ErrorFilter.
Static Content
As described above, the attribute docBase configures the path where the WEB-INF directory of the web application is searched. All files in that directory and any subdirectory, except the WEB-INF directory are loaded at startup. The Content-Type of a file is given by its suffix and the respective mime-mapping in the web.xml. The default nevisProxy installation comes with a handful of mime-mappings in the web.xml, for example:
<mime-mapping>
<extension>txt</extension>
<mime-type>text/plain</mime-type>
</mime-mapping>
After startup of the server, none of these files must be added or removed. If there is no matching servlet mapping found for a request, an attempt is made to find a file that matches it exactly. The filter chain is only constructed and invoked if there is a matching file. See also the chapter FileReaderServlet for serving static content.