Servlet Fundamentals

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.1.0</version>
    <scope>provided</scope>
</dependency>

curl -sv -d 'title=Dune&tag=sf' http://localhost:18080/g2-servlet/search -o /dev/null

> POST /g2-servlet/search HTTP/1.1
> Host: localhost:18080
> Accept: */*
> Content-Length: 17
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 302

@WebServlet(urlPatterns = "/lifecycle", loadOnStartup = 1,
        initParams = @WebInitParam(name = "greeting", value = "Hello from init"))
public class LifecycleServlet extends HttpServlet {

    private final AtomicInteger hits = new AtomicInteger(); // shared by every request thread
    private String greeting;                                 // written once in init, read-only afterwards

    @Override
    public void init() throws ServletException {
        greeting = getInitParameter("greeting");
        EventLog.of(getServletContext()).add("LifecycleServlet.init, instance " + System.identityHashCode(this));
    }

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        resp.getWriter().printf("%s%ninstance=%d hits=%d thread=%s%n", greeting,
                System.identityHashCode(this), hits.incrementAndGet(), Thread.currentThread().getName());
    }

    @Override
    public void destroy() {
        getServletContext().log("LifecycleServlet.destroy after " + hits.get() + " hits");
    }
}

curl -s http://localhost:18080/g2-servlet/lifecycle
seq 1 60 | xargs -P 20 -I{} curl -s -o /dev/null http://localhost:18080/g2-servlet/lifecycle
curl -s http://localhost:18080/g2-servlet/lifecycle | tail -1

Hello from init
instance=1266317426 hits=2 thread=http-nio-18080-exec-18
instance=1266317426 hits=64 thread=http-nio-18080-exec-17

contextInitialized: 3 books, title=Bookshelf
LifecycleServlet.init, instance 1266317426
...
INFO [Catalina-utility-2] org.apache.catalina.core.ApplicationContext.log LifecycleServlet.destroy after 64 hits

curl -sI  http://localhost:18080/g2-servlet/lifecycle | head -2
curl -si -X POST    http://localhost:18080/g2-servlet/lifecycle | head -1
curl -si -X OPTIONS http://localhost:18080/g2-servlet/lifecycle | grep -i '^allow'
curl -si -X TRACE   http://localhost:18080/g2-servlet/lifecycle | head -1

HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
HTTP/1.1 405
Allow: GET, HEAD, OPTIONS
HTTP/1.1 405

@WebServlet("/search")
public class SearchServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        handle(req, resp);
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        handle(req, resp);
    }

    private void handle(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain");           // the charset comes from web.xml (UTF-8)
        PrintWriter out = resp.getWriter();
        out.println("method=" + req.getMethod() + " query=" + req.getQueryString());
        out.println("request encoding=" + req.getCharacterEncoding() + " type=" + req.getContentType());
        out.println("title=" + req.getParameter("title"));
        out.println("tag=" + Arrays.toString(req.getParameterValues("tag")));
        Map<String, String[]> sorted = new TreeMap<>(req.getParameterMap());
        sorted.forEach((k, v) -> out.println("  param " + k + " -> " + Arrays.toString(v)));
        out.println("Accept-Language=" + req.getHeader("Accept-Language"));
        out.println("locale=" + req.getLocale() + " locales=" + Collections.list(req.getLocales()));
        out.println("Accept (all values)=" + Collections.list(req.getHeaders("Accept")));
        out.println("User-Agent present=" + (req.getHeader("User-Agent") != null));
        out.println("response encoding=" + resp.getCharacterEncoding() + " locale=" + resp.getLocale()
                + " (" + Locale.getDefault() + " default)");
    }
}

curl -s -H 'Accept-Language: es-ES,es;q=0.9,en;q=0.5' \
  'http://localhost:18080/g2-servlet/search?title=%20Dune%20&tag=sf&tag=classic'

method=GET query=title=%20Dune%20&tag=sf&tag=classic
request encoding=UTF-8 type=null
title=Dune
tag=[sf, classic]
  param tag -> [sf, classic]
  param title -> [Dune]
Accept-Language=es-ES,es;q=0.9,en;q=0.5
locale=es_ES locales=[es_ES, es, en]
Accept (all values)=[*/*]
User-Agent present=true
response encoding=UTF-8 locale=en_US (en_US default)

<request-character-encoding>UTF-8</request-character-encoding>
<response-character-encoding>UTF-8</response-character-encoding>

@WebServlet("/search-legacy")
public class LegacyEncodingServlet extends HttpServlet {
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        req.setCharacterEncoding(StandardCharsets.ISO_8859_1);   // Servlet 6.1 overload taking a Charset
        resp.setContentType("text/plain;charset=UTF-8");
        resp.getWriter().println("title=" + req.getParameter("title"));
    }
}

curl -s -d 'title=Ñandú' http://localhost:18080/g2-servlet/search | sed -n 3p
curl -s -d 'title=Ñandú' http://localhost:18080/g2-servlet/search-legacy
curl -s --data-binary 'title=Ñandú' -H 'Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1' \
  http://localhost:18080/g2-servlet/search | sed -n 3p

title=Ñandú
title=Ãandú
title=Ãandú

@WebServlet("/buffer")
public class BufferServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        resp.setBufferSize(16 * 1024);                       // a hint: the container may give more, never less
        PrintWriter out = resp.getWriter();
        out.println("bufferSize>=16384: " + (resp.getBufferSize() >= 16 * 1024));
        switch (String.valueOf(req.getParameter("mode"))) {
            case "reset" -> {
                out.println("draft that will be discarded");
                resp.resetBuffer();                            // clears the body, keeps status and headers
                out.println("final body, committed=" + resp.isCommitted());
            }
            case "late-header" -> {
                out.println("first line");
                resp.flushBuffer();                            // commits: status line and headers are on the wire
                resp.setHeader("X-Too-Late", "1");             // silently ignored
                resp.setStatus(500);                           // silently ignored
                out.println("committed=" + resp.isCommitted());
            }
            case "late-error" -> {
                out.println("first line");
                resp.flushBuffer();
                try {
                    resp.sendError(500, "too late");
                } catch (IllegalStateException e) {
                    out.println("sendError after commit -> IllegalStateException");
                }
                try {
                    resp.resetBuffer();
                } catch (IllegalStateException e) {
                    out.println("resetBuffer after commit -> IllegalStateException");
                }
            }
            case "late-session" -> {
                out.println("first line");
                resp.flushBuffer();
                try {
                    req.getSession();                              // would need a Set-Cookie header
                    out.println("session created, id from cookie=" + req.isRequestedSessionIdFromCookie());
                } catch (IllegalStateException e) {
                    out.println("getSession after commit -> IllegalStateException");
                }
            }
            default -> out.println("modes: reset, late-header, late-error, late-session");
        }
    }
}

curl -si 'http://localhost:18080/g2-servlet/buffer?mode=reset'
curl -si 'http://localhost:18080/g2-servlet/buffer?mode=late-header'
curl -si 'http://localhost:18080/g2-servlet/buffer?mode=late-error'
curl -si 'http://localhost:18080/g2-servlet/buffer?mode=late-session'

HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 28

final body, committed=false

HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Transfer-Encoding: chunked

bufferSize>=16384: true
first line
committed=true

bufferSize>=16384: true
first line
sendError after commit -> IllegalStateException
resetBuffer after commit -> IllegalStateException

bufferSize>=16384: true
first line
getSession after commit -> IllegalStateException

@WebServlet("/redirects")
public class RedirectServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        String target = req.getContextPath() + "/books";
        switch (String.valueOf(req.getParameter("mode"))) {
            case "default" -> resp.sendRedirect(target);                                     // 302
            case "relative" -> resp.sendRedirect("books");                                   // relative to this request URI
            case "303" -> resp.sendRedirect(target, HttpServletResponse.SC_SEE_OTHER);       // 6.1: choose the status
            case "308" -> resp.sendRedirect(target, HttpServletResponse.SC_PERMANENT_REDIRECT); // 6.1 constant for 308
            case "keep-body" -> {
                resp.setContentType("text/plain;charset=UTF-8");
                resp.getWriter().print("my own redirect body");
                resp.sendRedirect(target, HttpServletResponse.SC_TEMPORARY_REDIRECT, false);  // 6.1: do not clear the buffer
            }
            case "bad" -> resp.sendRedirect("http://[bad host");                             // not a valid URL
            default -> resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "unknown mode");
        }
    }
}

for m in default relative 303 308 keep-body bad; do
  curl -si "http://localhost:18080/g2-servlet/redirects?mode=$m" | sed -n '1,2p;/^Content-Length/p'
done

HTTP/1.1 302
Location: /g2-servlet/books
Content-Length: 0
HTTP/1.1 302
Location: books
Content-Length: 0
HTTP/1.1 303
Location: /g2-servlet/books
Content-Length: 0
HTTP/1.1 308
Location: /g2-servlet/books
Content-Length: 0
HTTP/1.1 307
Location: /g2-servlet/books
Content-Length: 20
HTTP/1.1 302
Location: http://[bad host
Content-Length: 0

@WebServlet("/scopes")
public class ScopesServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        ServletContext ctx = getServletContext();
        resp.setContentType("text/plain;charset=UTF-8");
        PrintWriter out = resp.getWriter();

        req.setAttribute("who", "request");                          // gone when this request ends
        HttpSession session = req.getSession();                      // creates the session on first use
        AtomicInteger perSession = (AtomicInteger) session.getAttribute("count");
        if (perSession == null) {
            perSession = new AtomicInteger();
            session.setAttribute("count", perSession);               // survives across requests of one client
        }
        int total = ((AtomicInteger) ctx.getAttribute("visits")).incrementAndGet(); // shared by everyone

        out.println("request attribute who=" + req.getAttribute("who"));
        out.println("session count=" + perSession.incrementAndGet() + " (new=" + session.isNew() + ")");
        out.println("application visits=" + total);
        out.println("servlet API " + ctx.getMajorVersion() + "." + ctx.getMinorVersion()
                + ", effective " + ctx.getEffectiveMajorVersion() + "." + ctx.getEffectiveMinorVersion());
        out.println("context path=" + ctx.getContextPath() + " name=" + ctx.getServletContextName());
        out.println("context-param catalogue.title=" + ctx.getInitParameter("catalogue.title"));
        out.println("mime of cover.png=" + ctx.getMimeType("cover.png") + ", of feed.rss=" + ctx.getMimeType("feed.rss"));
        out.println("session timeout (minutes)=" + ctx.getSessionTimeout());
        out.println("request/response encoding=" + ctx.getRequestCharacterEncoding() + "/" + ctx.getResponseCharacterEncoding());
        out.println("resource /WEB-INF/web.xml exists=" + (ctx.getResource("/WEB-INF/web.xml") != null));
        out.println("resource /WEB-INF/../secret exists=" + (ctx.getResourceAsStream("/WEB-INF/../secret") != null));
    }
}

curl -s -c jar -b jar http://localhost:18080/g2-servlet/scopes      # first request of this client
curl -s -c jar -b jar http://localhost:18080/g2-servlet/scopes | sed -n 1,3p
curl -s http://localhost:18080/g2-servlet/scopes | sed -n 1,3p       # another client, no cookie

request attribute who=request
session count=1 (new=true)
application visits=1
servlet API 6.1, effective 6.1
context path=/g2-servlet name=Bookshelf servlet fundamentals
context-param catalogue.title=Bookshelf
mime of cover.png=image/png, of feed.rss=application/rss+xml
session timeout (minutes)=30
request/response encoding=UTF-8/UTF-8
resource /WEB-INF/web.xml exists=true
resource /WEB-INF/../secret exists=false

request attribute who=request
session count=2 (new=false)
application visits=2

request attribute who=request
session count=1 (new=true)
application visits=3

public class Cart implements Serializable, HttpSessionBindingListener {
    private static final long serialVersionUID = 1L;

    private final List<Long> bookIds = new ArrayList<>();

    public synchronized void add(long id) {
        bookIds.add(id);
    }

    public synchronized List<Long> ids() {
        return List.copyOf(bookIds);
    }

    @Override
    public void valueBound(HttpSessionBindingEvent event) {
        EventLog.of(event.getSession().getServletContext()).add("Cart bound as " + event.getName());
    }

    @Override
    public void valueUnbound(HttpSessionBindingEvent event) {
        EventLog.of(event.getSession().getServletContext()).add("Cart unbound from " + event.getName());
    }
}

@WebServlet("/cart")
public class CartServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        HttpSession session = req.getSession();
        Cart cart = (Cart) session.getAttribute("cart");
        resp.setContentType("text/plain;charset=UTF-8");
        PrintWriter out = resp.getWriter();
        out.println("new=" + session.isNew() + " idFromCookie=" + req.isRequestedSessionIdFromCookie()
                + " idFromURL=" + req.isRequestedSessionIdFromURL() + " valid=" + req.isRequestedSessionIdValid());
        out.println("maxInactiveInterval(s)=" + session.getMaxInactiveInterval());
        out.println("cart=" + (cart == null ? "empty" : cart.ids()));
        out.println("encodeURL=" + resp.encodeURL(req.getContextPath() + "/cart"));
        out.println("encodeRedirectURL=" + resp.encodeRedirectURL(req.getContextPath() + "/books"));
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        String action = String.valueOf(req.getParameter("action"));
        HttpSession session = req.getSession();
        switch (action) {
            case "add" -> {
                Cart cart = (Cart) session.getAttribute("cart");
                if (cart == null) {
                    cart = new Cart();
                    session.setAttribute("cart", cart);
                }
                cart.add(Long.parseLong(req.getParameter("book")));
            }
            case "rotate" -> req.changeSessionId();       // new id, same attributes: do it after any privilege change
            case "timeout" -> session.setMaxInactiveInterval(Integer.parseInt(req.getParameter("seconds")));
            case "logout" -> session.invalidate();         // listeners run, attributes are unbound
            default -> {
                resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "unknown action");
                return;
            }
        }
        resp.sendRedirect(req.getContextPath() + "/cart", HttpServletResponse.SC_SEE_OTHER);
    }
}

J=jar; B=http://localhost:18080/g2-servlet
curl -s -c $J -b $J $B/cart
curl -si -c $J -b $J -d 'action=add&book=1' $B/cart | head -3
curl -s -c $J -b $J -d 'action=add&book=3' -L $B/cart | sed -n 3p
curl -s -c $J -b $J -d 'action=rotate' -L $B/cart | sed -n 1,3p
curl -s -c $J -b $J -d 'action=timeout&seconds=120' -L $B/cart | sed -n 2p
curl -s -c $J -b $J -d 'action=logout' -L $B/cart | head -4

new=false idFromCookie=true idFromURL=false valid=true
maxInactiveInterval(s)=1800
cart=empty
encodeURL=/g2-servlet/cart
encodeRedirectURL=/g2-servlet/books
HTTP/1.1 303
Location: /g2-servlet/cart
Content-Length: 0
new=false idFromCookie=true idFromURL=false valid=true
maxInactiveInterval(s)=1800
cart=[1, 3]
new=false idFromCookie=true idFromURL=false valid=true
maxInactiveInterval(s)=1800
cart=[1, 3]
maxInactiveInterval(s)=120
new=true idFromCookie=true idFromURL=false valid=false
maxInactiveInterval(s)=1800
cart=empty
encodeURL=/g2-servlet/cart

sessionCreated, active=4
Cart bound as cart
session attribute added: cart
sessionIdChanged (old id ends ...0D4E)
sessionDestroyed, active=3
session attribute removed: count
Cart unbound from cart
session attribute removed: cart

@WebServlet("/prefs")
public class PrefsServlet extends HttpServlet {

    private static final Set<String> THEMES = Set.of("light", "dark");

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        String theme = req.getParameter("theme");
        if (theme != null) {
            if (!THEMES.contains(theme)) {                     // never copy raw input into a cookie value
                resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "unknown theme");
                return;
            }
            Cookie cookie = new Cookie("theme", theme);
            cookie.setPath(req.getContextPath().isEmpty() ? "/" : req.getContextPath());
            cookie.setMaxAge(30 * 24 * 60 * 60);                // seconds; -1 = browser session, 0 = delete
            cookie.setHttpOnly(true);
            cookie.setSecure(req.isSecure());                   // Secure only makes sense over HTTPS
            cookie.setAttribute("SameSite", "Lax");              // Servlet 6.0: generic cookie attributes
            if ("1".equals(req.getParameter("partitioned"))) {
                cookie.setAttribute("Partitioned", "");          // attribute without a value
            }
            resp.addCookie(cookie);
            resp.getWriter().println("theme cookie set to " + theme);
        } else if ("1".equals(req.getParameter("clear"))) {
            Cookie cookie = new Cookie("theme", "");
            cookie.setPath(req.getContextPath().isEmpty() ? "/" : req.getContextPath());
            cookie.setMaxAge(0);                               // same name and path, or the browser keeps the old one
            resp.addCookie(cookie);
            resp.getWriter().println("theme cookie cleared");
        } else {
            Cookie[] cookies = req.getCookies();               // null when the request has no Cookie header
            String current = "none";
            if (cookies != null) {
                for (Cookie c : cookies) {
                    if (c.getName().equals("theme")) {
                        current = c.getValue();
                    }
                }
            }
            resp.getWriter().println("theme=" + current + " (browsers send only name and value back)");
        }
    }
}

curl -si 'http://localhost:18080/g2-servlet/prefs?theme=dark' | grep -i set-cookie
curl -si 'http://localhost:18080/g2-servlet/prefs?theme=dark&partitioned=1' | grep -i set-cookie
curl -s  -H 'Cookie: theme=dark; JSESSIONID=x' http://localhost:18080/g2-servlet/prefs
curl -si 'http://localhost:18080/g2-servlet/prefs?theme=%3Cscript%3E' | head -1
curl -si 'http://localhost:18080/g2-servlet/prefs?clear=1' | grep -i set-cookie

Set-Cookie: theme=dark; Expires=Sat, 07 Nov 2026 10:24:32 GMT; Max-Age=2592000; Path=/g2-servlet; HttpOnly; SameSite=Lax
Set-Cookie: theme=dark; Expires=Sat, 07 Nov 2026 10:24:32 GMT; Max-Age=2592000; Path=/g2-servlet; HttpOnly; SameSite=Lax; Partitioned
theme=dark (browsers send only name and value back)
HTTP/1.1 400
Set-Cookie: theme=; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/g2-servlet

@WebListener
public class AppListener implements ServletContextListener, ServletContextAttributeListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        ServletContext ctx = event.getServletContext();
        EventLog log = new EventLog();
        ctx.setAttribute(EventLog.ATTRIBUTE, log);

        Catalogue catalogue = new Catalogue();
        try (InputStream in = ctx.getResourceAsStream("/WEB-INF/catalogue.csv");
             BufferedReader reader = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8))) {
            reader.lines().skip(1).map(l -> l.split(";")).forEach(
                    f -> catalogue.add(f[0], f[1], Integer.parseInt(f[2])));
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
        ctx.setAttribute(Catalogue.ATTRIBUTE, catalogue);
        ctx.setAttribute("visits", new AtomicInteger());
        ctx.setAttribute("activeSessions", new AtomicInteger());

        // Programmatic registration is allowed here because this listener is annotated (not added programmatically).
        ctx.addServlet("ping", PingServlet.class).addMapping("/ping");
        log.add("initializer found filters: " + ctx.getAttribute("filtersFound"));
        log.add("contextInitialized: " + catalogue.all().size() + " books, title=" + ctx.getInitParameter("catalogue.title"));
    }

    @Override
    public void contextDestroyed(ServletContextEvent event) {
        EventLog.of(event.getServletContext()).add("contextDestroyed");
    }

    @Override
    public void attributeAdded(ServletContextAttributeEvent event) {
        if (!"eventLog".equals(event.getName())) {
            EventLog.of(event.getServletContext()).add("context attribute added: " + event.getName());
        }
    }
}

@WebListener
public class SessionTracker implements HttpSessionListener, HttpSessionAttributeListener, HttpSessionIdListener {

    private static AtomicInteger active(HttpSessionEvent e) {
        return (AtomicInteger) e.getSession().getServletContext().getAttribute("activeSessions");
    }

    @Override
    public void sessionCreated(HttpSessionEvent e) {
        int n = active(e).incrementAndGet();
        EventLog.of(e.getSession().getServletContext()).add("sessionCreated, active=" + n);
    }

    @Override
    public void sessionDestroyed(HttpSessionEvent e) {
        int n = active(e).decrementAndGet();
        EventLog.of(e.getSession().getServletContext()).add("sessionDestroyed, active=" + n);
    }

    @Override
    public void sessionIdChanged(HttpSessionEvent e, String oldSessionId) {
        EventLog.of(e.getSession().getServletContext()).add("sessionIdChanged (old id ends ..."
                + oldSessionId.substring(oldSessionId.length() - 4) + ")");
    }

    @Override
    public void attributeAdded(HttpSessionBindingEvent e) {
        EventLog.of(e.getSession().getServletContext()).add("session attribute added: " + e.getName());
    }

    @Override
    public void attributeRemoved(HttpSessionBindingEvent e) {
        EventLog.of(e.getSession().getServletContext()).add("session attribute removed: " + e.getName());
    }
}

public class PingServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        resp.getWriter().println("pong from " + getServletName());
    }
}

curl -s http://localhost:18080/g2-servlet/log | head -5
curl -s http://localhost:18080/g2-servlet/ping

context attribute added: catalogue
context attribute added: visits
context attribute added: activeSessions
contextInitialized: 3 books, title=Bookshelf
LifecycleServlet.init, instance 1266317426
pong from ping

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_1.xsd"
         version="6.1">

@WebServlet(name = "fragment", urlPatterns = "/fragment/*")
public class FragmentServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        resp.setHeader("X-Ignored", "set-by-fragment");     // ignored when this servlet is being included
        PrintWriter out = resp.getWriter();
        out.println("-- fragment: dispatcher=" + req.getDispatcherType() + " uri=" + req.getRequestURI()
                + " servletPath=" + req.getServletPath() + " pathInfo=" + req.getPathInfo()
                + " query=" + req.getQueryString());
        for (String name : List.of(RequestDispatcher.FORWARD_REQUEST_URI, RequestDispatcher.FORWARD_QUERY_STRING,
                RequestDispatcher.FORWARD_MAPPING, RequestDispatcher.INCLUDE_REQUEST_URI,
                RequestDispatcher.INCLUDE_QUERY_STRING, RequestDispatcher.INCLUDE_SERVLET_PATH)) {
            Object value = req.getAttribute(name);
            out.println("   " + name + " = " + (value instanceof jakarta.servlet.http.HttpServletMapping m
                    ? m.getMappingMatch() + ":" + m.getPattern() : value));
        }
        out.println("   from parameter=" + req.getParameter("from"));
    }
}

@WebServlet("/dispatch")
public class DispatchServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        String mode = String.valueOf(req.getParameter("mode"));
        switch (mode) {
            case "forward" -> {
                resp.getWriter().println("this text is discarded: forward clears the uncommitted buffer");
                req.getRequestDispatcher("/fragment/view?from=forward").forward(req, resp);
            }
            case "include" -> {
                PrintWriter out = resp.getWriter();
                out.println("before include");
                req.getRequestDispatcher("/fragment/view?from=include").include(req, resp);
                out.println("after include, status=" + resp.getStatus() + " header X-Ignored=" + resp.getHeader("X-Ignored"));
            }
            case "named" -> getServletContext().getNamedDispatcher("fragment").forward(req, resp);
            case "forward-after-commit" -> {
                resp.getWriter().println("committed");
                resp.flushBuffer();
                try {
                    req.getRequestDispatcher("/fragment/view").forward(req, resp);
                } catch (IllegalStateException e) {
                    resp.getWriter().println("forward after commit -> IllegalStateException");
                }
            }
            case "missing" -> {
                RequestDispatcher d = req.getRequestDispatcher("/does/not/exist");
                resp.getWriter().println("dispatcher for an unknown path is never null here: " + (d != null));
            }
            default -> resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "modes: forward, include, named, forward-after-commit, missing");
        }
    }
}

B=http://localhost:18080/g2-servlet
curl -s "$B/dispatch?mode=forward&p=1"
curl -s "$B/dispatch?mode=include"
curl -s "$B/dispatch?mode=named&x=1"
curl -s "$B/dispatch?mode=forward-after-commit"

-- fragment: dispatcher=FORWARD uri=/g2-servlet/fragment/view servletPath=/fragment pathInfo=/view query=from=forward
   jakarta.servlet.forward.request_uri = /g2-servlet/dispatch
   jakarta.servlet.forward.query_string = mode=forward&p=1
   jakarta.servlet.forward.mapping = EXACT:/dispatch
   jakarta.servlet.include.request_uri = null
   jakarta.servlet.include.query_string = null
   jakarta.servlet.include.servlet_path = null
   from parameter=forward

before include
-- fragment: dispatcher=INCLUDE uri=/g2-servlet/dispatch servletPath=/dispatch pathInfo=null query=mode=include
   jakarta.servlet.forward.request_uri = null
   jakarta.servlet.forward.query_string = null
   jakarta.servlet.forward.mapping = null
   jakarta.servlet.include.request_uri = /g2-servlet/fragment/view
   jakarta.servlet.include.query_string = from=include
   jakarta.servlet.include.servlet_path = /fragment
   from parameter=include
after include, status=200 header X-Ignored=null

-- fragment: dispatcher=FORWARD uri=/g2-servlet/dispatch servletPath=/dispatch pathInfo=null query=mode=named&x=1
   jakarta.servlet.forward.request_uri = null
   ...
   from parameter=null

committed
forward after commit -> IllegalStateException

forward:  outer before REQUEST /g2-servlet/dispatch
          inner before REQUEST /g2-servlet/dispatch
          DispatchTrace saw REQUEST /g2-servlet/dispatch
          DispatchTrace saw FORWARD /g2-servlet/fragment/view
          by-servlet-name before FORWARD /g2-servlet/fragment/view
          by-servlet-name after (188 us)
          inner after (399 us)
          outer after (414 us)
include:  outer before REQUEST /g2-servlet/dispatch
          inner before REQUEST /g2-servlet/dispatch
          DispatchTrace saw REQUEST /g2-servlet/dispatch
          DispatchTrace saw INCLUDE /g2-servlet/dispatch
          inner after (1336 us)
          outer after (1362 us)

public class MappingServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        HttpServletMapping m = req.getHttpServletMapping();
        resp.setContentType("text/plain;charset=UTF-8");
        PrintWriter out = resp.getWriter();
        out.println("servlet=" + getServletName() + " instance=" + System.identityHashCode(this));
        out.println("match=" + m.getMappingMatch() + " pattern='" + m.getPattern() + "' matchValue='" + m.getMatchValue() + "'");
        out.println("requestURI=" + req.getRequestURI());
        out.println("contextPath='" + req.getContextPath() + "' servletPath='" + req.getServletPath()
                + "' pathInfo=" + req.getPathInfo());
    }
}

<servlet>
  <servlet-name>mapping-exact</servlet-name>
  <servlet-class>org.example.bookshelf.MappingServlet</servlet-class>
</servlet>
<servlet>
  <servlet-name>mapping-prefix</servlet-name>
  <servlet-class>org.example.bookshelf.MappingServlet</servlet-class>
</servlet>
<servlet>
  <servlet-name>mapping-extension</servlet-name>
  <servlet-class>org.example.bookshelf.MappingServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>mapping-exact</servlet-name>
  <url-pattern>/map/exact</url-pattern>
</servlet-mapping>

B=http://localhost:18080/g2-servlet
curl -s $B/map/exact ; curl -s $B/map/a/b ; curl -s $B/reports/q1.report

servlet=mapping-exact instance=223862864
match=EXACT pattern='/map/exact' matchValue='map/exact'
requestURI=/g2-servlet/map/exact
contextPath='/g2-servlet' servletPath='/map/exact' pathInfo=null
servlet=mapping-prefix instance=1832380977
match=PATH pattern='/map/*' matchValue='a/b'
requestURI=/g2-servlet/map/a/b
contextPath='/g2-servlet' servletPath='/map' pathInfo=/a/b
servlet=mapping-extension instance=2010951165
match=EXTENSION pattern='*.report' matchValue='reports/q1'
requestURI=/g2-servlet/reports/q1.report
contextPath='/g2-servlet' servletPath='/reports/q1.report' pathInfo=null

/                                  public: served as static files or mapped to servlets
├── hello.jsp                        a JSP in the public tree (reachable, implicit *.jsp mapping)
├── docs/index.html                  a directory with a welcome file
├── errors/readme.txt                a plain static file
├── META-INF/MANIFEST.MF
└── WEB-INF/                         never served to a client
    ├── web.xml                      the deployment descriptor
    ├── catalogue.csv                private data read with getResourceAsStream
    ├── views/books.jsp              JSP views, reachable only through a dispatcher
    ├── views/book.jsp
    ├── views/about.jsp
    ├── classes/org/example/bookshelf/*.class
    ├── classes/META-INF/services/jakarta.servlet.ServletContainerInitializer
    └── lib/jakarta.servlet.jsp.jstl-api-3.0.2.jar, jakarta.servlet.jsp.jstl-3.0.1.jar

B=http://localhost:18080/g2-servlet
curl -s -o /dev/null -w '%{http_code}\n' $B/WEB-INF/web.xml
curl -s -o /dev/null -w '%{http_code}\n' $B/WEB-INF/views/books.jsp
curl -si $B/docs | head -2
curl -s $B/docs/

404
404
HTTP/1.1 302
Location: /g2-servlet/docs/
<!DOCTYPE html>
<html><body><h1>Docs welcome page</h1></body></html>

<welcome-file-list>
  <welcome-file>index.html</welcome-file>
  <welcome-file>default.jsp</welcome-file>
</welcome-file-list>

<error-page>
  <error-code>404</error-code>
  <location>/errors/generic</location>
</error-page>
<error-page>
  <exception-type>java.sql.SQLException</exception-type>
  <location>/errors/database</location>
</error-page>
<error-page>
  <location>/errors/generic</location>
</error-page>

@WebServlet(name = "errors", urlPatterns = {"/errors/generic", "/errors/database"})
public class ErrorServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        Integer status = (Integer) req.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        resp.setContentType("text/plain;charset=UTF-8");
        if (status != null) {
            resp.setStatus(status);                         // an error page keeps the original status unless you set it
        }
        PrintWriter out = resp.getWriter();
        out.println("error page " + req.getServletPath() + " dispatcher=" + req.getDispatcherType()
                + " handled-as=" + req.getMethod());
        out.println("status=" + status);
        out.println("message=" + req.getAttribute(RequestDispatcher.ERROR_MESSAGE));
        out.println("exception_type=" + req.getAttribute(RequestDispatcher.ERROR_EXCEPTION_TYPE));
        out.println("exception=" + req.getAttribute(RequestDispatcher.ERROR_EXCEPTION));
        out.println("request_uri=" + req.getAttribute(RequestDispatcher.ERROR_REQUEST_URI));
        out.println("query_string=" + req.getAttribute(RequestDispatcher.ERROR_QUERY_STRING));
        out.println("servlet_name=" + req.getAttribute(RequestDispatcher.ERROR_SERVLET_NAME));
        out.println("original method=" + req.getAttribute(RequestDispatcher.ERROR_METHOD));
    }
}

@WebServlet("/boom")
public class BoomServlet extends HttpServlet {
    @Override
    protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        switch (String.valueOf(req.getParameter("kind"))) {
            case "status" -> resp.sendError(HttpServletResponse.SC_FORBIDDEN, "no entry");
            case "runtime" -> throw new IllegalStateException("catalogue exploded");
            case "wrapped" -> throw new ServletException("lookup failed", new SQLException("db down"));
            case "committed" -> {
                resp.getWriter().println("partial page");
                resp.flushBuffer();
                throw new IllegalStateException("too late for an error page");
            }
            default -> resp.getWriter().println("kinds: status, runtime, wrapped, committed");
        }
    }
}

B=http://localhost:18080/g2-servlet
for k in status runtime wrapped committed; do curl -si -X POST "$B/boom?kind=$k"; done
curl -si $B/nothing/here

HTTP/1.1 403
error page /errors/generic dispatcher=ERROR handled-as=GET
status=403
message=no entry
exception_type=null
exception=null
request_uri=/g2-servlet/boom
query_string=kind=status
servlet_name=org.example.bookshelf.BoomServlet
original method=POST

HTTP/1.1 500
error page /errors/generic dispatcher=ERROR handled-as=GET
status=500
message=
exception_type=null
exception=java.lang.IllegalStateException: catalogue exploded
request_uri=/g2-servlet/boom
query_string=kind=runtime
servlet_name=org.example.bookshelf.BoomServlet
original method=POST

HTTP/1.1 500
error page /errors/database dispatcher=ERROR handled-as=GET
status=500
message=lookup failed
exception_type=class java.sql.SQLException
exception=java.sql.SQLException: db down
request_uri=/g2-servlet/boom
query_string=kind=wrapped
servlet_name=org.example.bookshelf.BoomServlet
original method=POST

HTTP/1.1 200
Transfer-Encoding: chunked

partial page
curl: (18) transfer closed with outstanding read data remaining

HTTP/1.1 404
error page /errors/generic dispatcher=ERROR handled-as=GET
status=404
message=The requested resource [/g2-servlet/nothing/here] is not available
exception_type=null
exception=null
request_uri=/g2-servlet/nothing/here
query_string=null
servlet_name=default
original method=GET

@WebServlet("/upload")
@MultipartConfig(location = "", fileSizeThreshold = 8 * 1024, maxFileSize = 64 * 1024, maxRequestSize = 128 * 1024)
public class UploadServlet extends HttpServlet {

    private static final Set<String> TYPES = Set.of("image/png", "image/jpeg");

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        String contentType = req.getContentType();
        if (contentType == null || !contentType.toLowerCase().startsWith("multipart/form-data")) {
            resp.sendError(HttpServletResponse.SC_UNSUPPORTED_MEDIA_TYPE, "multipart/form-data expected");
            return;
        }
        Part cover;
        String title;
        try {
            title = req.getParameter("title");               // text fields arrive as ordinary parameters
            cover = req.getPart("cover");
        } catch (IllegalStateException e) {                  // size limits exceeded
            resp.setStatus(HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE);
            resp.getWriter().println("upload rejected: too large");
            return;
        }
        if (cover == null || cover.getSize() == 0 || !TYPES.contains(cover.getContentType())) {
            resp.sendError(HttpServletResponse.SC_UNSUPPORTED_MEDIA_TYPE, "send a PNG or JPEG in the cover part");
            return;
        }
        String submitted = cover.getSubmittedFileName();     // the client's name: display only, never a file path
        String display = submitted == null ? "" : Paths.get(submitted.replace('\\', '/')).getFileName().toString();
        File dir = (File) getServletContext().getAttribute("jakarta.servlet.context.tempdir");
        Path target = dir.toPath().resolve(UUID.randomUUID() + ".png");     // the server picks the stored name
        try (InputStream in = cover.getInputStream()) {
            Files.copy(in, target);
        }
        resp.getWriter().println("title=" + title + " cover=" + display + " type=" + cover.getContentType()
                + " bytes=" + cover.getSize() + " stored=" + Files.exists(target));
        Files.delete(target);
    }
}

B=http://localhost:18080/g2-servlet
curl -si -F title=Dune -F 'cover=@cover.png;type=image/png;filename=../../etc/dune cover.png' $B/upload
curl -si -F title=Dune -F 'cover=@note.txt;type=text/plain' $B/upload | head -1
curl -si -F title=Dune -F 'cover=@big.png;type=image/png' $B/upload | sed -n '1p;/^$/,$p'
curl -si -d title=x $B/upload | head -1

HTTP/1.1 200
...
title=Dune cover=dune cover.png type=image/png bytes=69 stored=true
HTTP/1.1 415
HTTP/1.1 413

upload rejected: too large
HTTP/1.1 415

@WebServlet(urlPatterns = "/async", asyncSupported = true)
public class AsyncServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        String requestThread = Thread.currentThread().getName();
        AsyncContext async = req.startAsync();               // the container thread is released when doGet returns
        async.setTimeout(5_000);
        async.start(() -> {
            try {
                Thread.sleep(200);                            // stands in for a slow remote call
                resp.setContentType("text/plain;charset=UTF-8");
                resp.getWriter().println("request thread=" + requestThread + ", worker thread="
                        + Thread.currentThread().getName());
            } catch (IOException | InterruptedException e) {
                Thread.currentThread().interrupt();
            } finally {
                async.complete();                             // always complete, or the request hangs until timeout
            }
        });
    }
}

curl -s http://localhost:18080/g2-servlet/async

request thread=http-nio-18080-exec-37, worker thread=http-nio-18080-exec-30

B=http://localhost:18080/g2-servlet; J=jar
curl -si -c $J -b $J -H 'X-Trace: 1' $B/books | sed -n 1,3p
T=$(curl -s -c $J -b $J $B/books | grep -o 'name="csrf" value="[^"]*"' | sed 's/.*value="//;s/"//')
curl -si -c $J -b $J -d "csrf=$T&title=Hyperion&author=Dan+Simmons&year=1989" $B/books | sed -n 1,3p
curl -s -b $J $B/books/4 | sed -n 4,6p
curl -si -b $J -d 'title=X&author=Y&year=2000' $B/books | sed -n 1p
curl -si -c $J -b $J -d "csrf=$T&title=&author=Y&year=2000" $B/books | sed -n 1p
curl -s -H 'Accept: application/json' $B/books | tail -c 150

HTTP/1.1 200
Set-Cookie: JSESSIONID=38A8141E...; Path=/g2-servlet; HttpOnly; SameSite=Lax
Vary: Accept
HTTP/1.1 303
Location: /g2-servlet/books/4
Content-Length: 0
<h1>Hyperion</h1>
<p>by Dan Simmons, 1989</p>
<p><a href="/g2-servlet/books">Back to the shelf</a></p>
HTTP/1.1 403
HTTP/1.1 400
,{"id":3,"title":"The Left Hand of Darkness","author":"Ursula K. Le Guin","year":1969},{"id":4,"title":"Hyperion","author":"Dan Simmons","year":1989}]

outer before REQUEST /g2-servlet/books
inner before REQUEST /g2-servlet/books
sessionCreated, active=4
session attribute added: csrf
inner after (1009 us)
outer after (1301 us)

    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        HttpSession session = req.getSession(false);
        String expected = session == null ? null : (String) session.getAttribute("csrf");
        String actual = req.getParameter("csrf");
        if (expected == null || actual == null
                || !MessageDigest.isEqual(expected.getBytes(), actual.getBytes())) {
            resp.sendError(HttpServletResponse.SC_FORBIDDEN, "Missing or invalid CSRF token");
            return;
        }
        String title = req.getParameter("title");
        String author = req.getParameter("author");
        int year;
        try {
            year = Integer.parseInt(req.getParameter("year"));
        } catch (NumberFormatException e) {
            year = -1;
        }
        if (title == null || title.isBlank() || author == null || author.isBlank() || year < 1450) {
            resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "title, author and a year >= 1450 are required");
            return;
        }
        Book created = Catalogue.of(getServletContext()).add(title.strip(), author.strip(), year);
        // Post/Redirect/Get: 303 tells the client to follow with a GET, so a refresh never re-posts the form.
        resp.sendRedirect(req.getContextPath() + "/books/" + created.id(), HttpServletResponse.SC_SEE_OTHER);
    }

<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %>
<%@ taglib prefix="c" uri="jakarta.tags.core" %>
<!DOCTYPE html>
<html>
<body>
<h1>${initParam['catalogue.title']}</h1>
<ul>
<c:forEach var="b" items="${books}">
  <li><a href="${pageContext.request.contextPath}/books/${b.id}"><c:out value="${b.title}"/></a>
      by <c:out value="${b.author}"/> (${b.year})</li>
</c:forEach>
</ul>
<form method="post" action="${pageContext.request.contextPath}/books">
  <input type="hidden" name="csrf" value="<c:out value='${csrf}'/>">
  <input name="title"> <input name="author"> <input name="year" size="4">
  <button>Add</button>
</form>
</body>
</html>