Defining the Filter Instance
The filter element of a web.xml file defines a filter instance. The filter element always contains a filter-name element and a filter-class element, and may contain initialization parameters.
The filter-name element declares a name for this particular filter instance. Each filter instance in a context must have a unique name. However, the name is only used to associate URL mappings with this instance. Therefore, the name need not correspond to the name of the filter class. The name is completely arbitrary.
The filter-class element tells the servlet container how to load the filter. There are two components to this element. The element contains the base name of the shared library (.dll or .so) that contains the servlet, and the name of the function that the container uses to load the servlet. The components of the element are separated by a single period. For example, the value compressFilters.createCompress contains the base name compressFilters and the function name createCompress.
The base name of a shared library is the name of the library without the platform-specific prefix (if any), without the
12d or
15d suffix, and without the platform-specific extension. See
Appendix C for information on library name mappings for each platform that HydraExpress supports.
The function name in the
filter-class element must match the function name defined in the filter implementation. The
RWSF_DEFINE_FILTER macro in the implementation source code defines the function name, as described in
Defining Filters, Servlets, and Listeners . Note that the name of this function must be a legal C++ identifier.
The filter element below defines a filter named compressResponse. The compiled filter is in a shared library with the base name compressFilters. The container calls the function createCompress to create the filter instance. Notice that the name of the filter instance does not need to correspond to the class name.
<filter>
<filter-name>compressResponse</filter-name>
<filter-class>compressFilters.createCompress</filter-class>
</filter>
To add another instance of the same filter class to the container, use another filter element with a different filter-name. The example below shows a fragment of a web.xml file that defines two different instances of the same filter class:
<filter>
<filter-name>compressResponse</filter-name>
<filter-class>compressFilters.createCompress</filter-class>
</filter>
<filter>
<filter-name>compressUpload</filter-name>
<filter-class>compressFilters.createCompress</filter-class>
</filter>
Each filter element may contain any number of init-param elements. The container passes the parameters to the filter in much the same way that command line parameters are passed to a program. The exact names and values of the parameters depend on the individual servlet. (See below for an example of the corresponding servlet code.)
This example shows a fragment of a web.xml file that defines two different instances of the same filter class. The container starts each instance with different parameters.
<filter>
<filter-name>compressResponse</filter-name>
<filter-class>compressFilters.createCompress</filter-class>
<init-param>
<param-name>prefer</param-name>
<param-value>speed</param-value>
</init-param>
</filter>
<filter>
<filter-name>compressUpload</filter-name>
<filter-class>status.createStatusServlet</filter-class>
<init-param>
<param-name>prefer</param-name>
<param-value>space</param-value>
</init-param>
</filter>
Here is an example of the servlet code that might retrieve the initiation parameter.
virtual void init(const rwsf::FilterConfig& filterConfig)
{
std::string compressionType = filterConfig.getInitParameter("prefer");
}
Notice that a filter element only defines an instance of a filter. For the container to forward requests to the filter, the filter must be mapped to one or more URLs or one or more servlets.
