Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Configuration

web.xml, Defaults and URL Mapping

Understand the global conf/web.xml and your app's WEB-INF/web.xml, the DefaultServlet and JspServlet, url-pattern matching rules, welcome files, error pages and session timeout.

Every web application inherits a deployment descriptor from the server (conf/web.xml) and adds its own (WEB-INF/web.xml, plus annotations). The merged result decides how URLs map to servlets, which file types are served, how long sessions live and which error pages appear. When a URL "goes to the wrong place", the cause is almost always in the mapping rules, so it is worth learning them exactly.

This lesson explains the two files, the built-in servlets, the four kinds of URL pattern and the precedence between them, and then implements the matching algorithm in Java so you can try patterns yourself.

Two levels of web.xml

  1. conf/web.xml (global): applies to every app on every host. It declares the default servlet (serves static files), the jsp servlet (compiles JSPs), MIME type mappings, the welcome-file list, session-timeout of 30 minutes and more.
  2. WEB-INF/web.xml (per app): adds or overrides settings for one application. With Servlet 3.0 and later, annotations (@WebServlet, @WebFilter, @WebListener) and web-fragment.xml files inside library JARs contribute as well.

Settings in the app's file override the global file. Edit the global one rarely; it is easier to override per app so upgrades of conf/web.xml do not conflict with your changes.

The default servlet and the JSP servlet

The global file contains, in simplified form:

XML
<servlet>
  <servlet-name>default</servlet-name>
  <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
  <init-param><param-name>debug</param-name><param-value>0</param-value></init-param>
  <init-param><param-name>listings</param-name><param-value>false</param-value></init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet>
  <servlet-name>jsp</servlet-name>
  <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
  <load-on-startup>3</load-on-startup>
</servlet>

<servlet-mapping><servlet-name>default</servlet-name><url-pattern>/</url-pattern></servlet-mapping>
<servlet-mapping><servlet-name>jsp</servlet-name><url-pattern>*.jsp</url-pattern><url-pattern>*.jspx</url-pattern></servlet-mapping>

<session-config><session-timeout>30</session-timeout></session-config>
<welcome-file-list>
  <welcome-file>index.html</welcome-file>
  <welcome-file>index.htm</welcome-file>
  <welcome-file>index.jsp</welcome-file>
</welcome-file-list>
  • default is mapped to /, so any URL that matches no other servlet is treated as a static file lookup. This is how style.css is served. It also produces the 404. Its listings parameter is false: set it to true and directories without a welcome file show a file list (a common information leak).
  • jsp compiles and runs .jsp pages.

URL pattern types

Exact /cart
Path prefix /api/*
Extension *.jsp
Default /

Exact beats prefix beats extension beats default.

1 / 2

The matching rules

For a request path inside the context, the container tries in this order and stops at the first match:

  1. Exact match on a pattern with no wildcard (/cart). Query strings are ignored.
  2. Longest path-prefix match on patterns ending in /* (/api/* matches /api, /api/ and /api/orders/5; between /api/* and /api/v2/*, the longer one wins).
  3. Extension match on *.ext patterns (*.jsp), applied to the last path segment.
  4. Default servlet (pattern /).

Special patterns: /* is the shortest path-prefix pattern and swallows everything, including .jsp and static files, so avoid it unless a single servlet must handle all requests (it also hides the default servlet, so your servlet must serve static files itself). An empty pattern "" matches exactly the context root. Patterns like /*.do are invalid: a pattern cannot be both prefix and extension.

Also remember getServletPath() and getPathInfo(): for pattern /api/* and request /api/orders/5, the servlet path is /api and the path info /orders/5.

Java URL pattern matching (stand-in for the mapper)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Note that /cart/ (with trailing slash) does not match the exact /cart pattern and falls through to the default servlet, and /cartoon does not match /cart either. Spring MVC's DispatcherServlet is usually mapped to / (or /*) and then does its own, more flexible matching.

Reading a web.xml

Tools and tests often need to list mappings of a given descriptor. This program parses a small descriptor with the DOM API and prints servlet names with their patterns, plus the session timeout and welcome files, using the Jakarta EE namespace.

Java Read servlet mappings from a descriptor (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Other useful settings

  • Session timeout (<session-config>): minutes of inactivity (30 by default). A negative or zero value means never expire, a memory risk.
  • Welcome files: tried in order for a directory request.
  • Error pages: <error-page> by error-code (404) or exception-type. They replace Tomcat's default error report (which also reveals the version; hide it with ErrorReportValve showServerInfo="false" and showReport="false").
  • MIME mappings: <mime-mapping> maps extensions to content types. Add types the default list lacks, for example .webmanifest.
  • Filters: <filter> and <filter-mapping> control order by their position in the file; annotations give no order guarantees.
  • metadata-complete="true" on <web-app> tells Tomcat to skip annotation scanning, which speeds up startup for large WARs.
  • <absolute-ordering> and web-fragment.xml decide the order in which library fragments are processed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which pattern type has the highest priority when several match?

    Order: exact, longest path prefix, extension, then the default servlet.
  2. 2. Request: /api/orders/5, mapping /api/*. What are getServletPath() and getPathInfo()?

    The servlet path is the part matching the pattern prefix; the path info is the rest.
  3. 3. What is a risk of mapping a servlet to /* ?

    /* is a path-prefix pattern, so it beats extension patterns and the default servlet; your servlet then receives every request.
  4. 4. Which DefaultServlet parameter, if set to true, can leak the contents of directories?

    listings=true shows an index of files for directories without a welcome file.

Summary

  • conf/web.xml provides global defaults (default servlet, JSP servlet, MIME types, timeouts); WEB-INF/web.xml and annotations add application settings.
  • URL patterns match in the order exact, longest prefix, extension, default.
  • / is the default servlet; /* captures everything and should be used with care.
  • Welcome files, error pages, session timeout and filters are configured in the same descriptor.
  • Keep listings off and hide server details in error pages.

Next: JNDI resources and data sources