The url-pattern element of a servlet-mapping or a filter-mapping associates a filter or servlet with a set of URLs. When a request arrives, the container uses a simple procedure for matching the URL in the request with a url-pattern in the web.xml file. Section 4.7.2 describes the servlet-mapping element. Section 4.8.2 describes the filter-mapping element.
A URL pattern may contain a subset of US-ASCII characters. Other values must be escaped. RFC 2396 describes the legal values for a URL pattern.
Note that HydraExpress matches a URL pattern as a sequence of bytes rather than a sequence of characters. HydraExpress considers URL-escaped and unescaped sequences to be identical. In other words, the URL pattern http://example.com/a/* is identical to the URL pattern http://example.com/%61/*. To represent a character pattern that may have more than one byte sequence, add a mapping for each byte sequence.
URL patterns use an extremely simple syntax. Every character in a pattern must match the corresponding character in the URL path exactly, with two exceptions. At the end of a pattern, /* matches any sequence of characters from that point forward. The pattern *.extension matches any file name ending with extension. No other wildcards are supported, and an asterisk at any other position in the pattern is not a wildcard.
For example, a web.xml file for the examples context on the servlet container at example.com matches the pattern in <url-pattern>/status/*</url-pattern> as follows:
Does not match
A context located at the path /examples on the Agent at example.com matches the pattern in <url-pattern>*.map</url-pattern> as follows:
Does not match, the extension is uppercase
Does not match, the extension is mapi rather than map
Different filters in a single context often use the same url-pattern. In this case, each filter that matches the request may process the request, as described in Section 4.8.2.
In contrast, no two servlet-mapping elements in the same application may use the same url-pattern. If the web.xml file contains two identical mappings to different servlets, the container makes no guarantees about which servlet the container calls for a given request. However, two servlets may use overlapping url-pattern elements. In that case, the matching procedure determines which servlet the container calls.
A request may match more than one servlet-mapping in a given context. The servlet container uses a straightforward matching procedure to determine the best match. The matching procedure has four simple rules. First, the container prefers an exact path match over a wildcard path match. Second, the container prefers to match the longest pattern. Third, the container prefers path matches over filetype matches. Finally, the pattern <url-pattern>/</url-pattern> always matches any request that no other pattern matches (see Section 4.3.3).
For example, a context web.xml file can map the home page for an online catalog to one pattern and the search page for the catalog to a different pattern, as shown below:
<servlet-mapping> <servlet-name>catalogBrowse</servlet-name> <url-pattern>/Catalog/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>catalogSearch</servlet-name> <url-pattern>/Catalog/search/*</url-pattern> </servlet-mapping>
Figure 4 illustrates the matching process for a context. Since the container prefers to match the longest pattern, a URL that includes /Catalog/search/ always matches the mapping for catalogSearch rather than the mapping for catalogBrowse.
A mapping that contains the pattern <url-pattern>/</url-pattern> matches a request if no other pattern matches. This is the default mapping. The servlet mapped to this pattern is called the default servlet.
The default mapping is often directed to the first page of an application. Explicitly providing a default mapping also ensures that malformed URL requests into the application return are handled by the application rather than returning an error.
The servlet-mapping element below maps the Welcome servlet instance to the default mapping.
<servlet-mapping> <servlet-name>Welcome</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping>
For the context that contains this element, any request that is not handled by another mapping is forwarded to the Welcome servlet.
©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.