Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
HydraExpress Servlet Development Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

4.8 Define and Map Filters

To configure a filter, a web.xml file first defines the filter instance, then maps one or more URL patterns to the instance. This section describes how to configure a filter within a web.xml file. For a discussion of programming a filter, see Section 6.6.

4.8.1 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 DLL 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 DLL is the name of the library without the platform-specific prefix (if any), without the suffix specified on the HydraExpress command line, 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 Section 6.5. 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 DLL with the base name compressFilters. The container calls the function createCompress to create the servlet instance.

Again, the name of the filter instance need not correspond to the class name. 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:

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 complete program. The exact names and values of the parameters depend on the individual servlet. The example below 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.

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.

4.8.2 Mapping Filters to URLs

The filter-mapping element maps a URL pattern or servlet name to an instance of a filter. The filter-mapping always contains a filter-name element and a url-pattern element.

The filter-name element must match a filter-name defined in a filter element elsewhere in the web.xml file. Since a servlet container may have multiple instances of the same servlet running, the servlet container uses the filter-name to associate a mapping with a filter.

A filter-mapping maps a filter to a URL pattern. Therefore, each filter-mapping contains a single url-pattern element. Notice that the url-pattern for a filter need not exactly match the url-pattern in any particular servlet-mapping.

For example, the web.xml fragment below maps the URL /status/compressed/* to a filter named compressResponse. If the servlet is defined in the examples context of a servlet container at http://example.roguewave.com/, then this element tells the container that the compressResponse filter will process any requests beginning with http://example.roguewave.com/example/status/compressed/.

A single filter instance can be mapped to any number of URL patterns. The fragment below maps the same filter to two different servlets.

Any number of instances within a context may be mapped to the same URL pattern. Filters are added to the filter chain in the order in which the filter-mapping appears in the web.xml file. For example, the web.xml fragment below defines two filters for servlets located at /status/compressed/*:

Both Uncompress and Authenticate appear on the filter chain for servlets located at /status/compressed/*. The Uncompress filter precedes the Authenticate filter in the chain because the Uncompress filter appears before the Authenticate filter in the web.xml file.



Previous fileTop of DocumentContentsIndex pageNext file

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.