URL Patterns

HydraExpress Servlet Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

4.4 URL Patterns

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.8.2 describes the servlet-mapping element. Section 4.9.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.

4.4.1 URL Pattern Syntax

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:

`http://example.com/examples/status/synopsis`	Matches
`http://example.com/examples/status/complete?date=today`	Matches
`http://example.com/examples/status`	Matches
`http://example.com/examples/server/status`	Does not match

A context located at the path <installdir>/apps/servlets/examples on the Agent at example.com matches the pattern in <url-pattern>*.map</url-pattern> as follows:

`http://example.com/examples/US/Oregon /Portland.map`	Matches
`http://example.com/examples/US/Washington /Seattle.map`	Matches
`http://example.com/examples/Paris.France.map`	Matches
`http://example.com/examples/US/Oregon /Portland.MAP`	Does not match: the extension is uppercase
`http://example.com/examples/interface /description/mail.mapi`	Does not match: the extension is `mapi` rather than `map`

Servlets and filters behave differently if a context defines two or more of them with the same URL mapping. If two servlets have the same URL mapping, it is undetermined which servlet a request will be dispatched to. If two filters have the same URL mapping, both filters will process the request. See the sections on mapping servlets (Section 4.8.2) and filters (Section 4.9.2) for more complete explanations, and examples.

Although two servlets may not have identical URL mappings, they may use overlapping mappings. In this case, the matching procedure determines which servlet the container calls.

4.4.2 Servlet Matching Procedure

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, applied in the order described below:

The container prefers an exact path match over a wildcard path match.

The container prefers to match the longest pattern.

The container prefers path matches over file type matches.

If no valid match is found, the container matches to <url-pattern>/</url-pattern>, the default servlet (see Section 4.4.3).

The container uses case-sensitive string comparisons for matching.

For example, a context web.xml file might 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 if the request URL is http://example.com/servlets/Catalog/search/?word=Grid.

Figure 4: URL pattern matching

Two mappings are valid for this request, the first and third shown. 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

4.4.3 Default Servlet

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.

By explicitly providing a default mapping, you can ensure that requests with malformed URLs find their way to the application rather than simply returning an error. A common practice is to map the default servlet to the application's home page, or you might map to a page with more helpful error handling.

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.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.