API Summary

Routes: get, post, put, patch, delete, head, options, each also as (path, description, handler), and path(prefix, group → …​); patterns and matching order in Routing

Introspection: routes() reports every registered route as Route(method, path, description), in registration order. guards() reports the filters and error handlers beside them as Guard.BeforeRequest(path), Guard.BeforeRoute(path), Guard.AfterRoute(path), Guard.Error(status), and Guard.ResponseFilter(). spider-silk-openapi turns the route list into an OpenAPI 3.1 document

Filters: beforeRequest(filter) / beforeRequest(path, filter) before routing, beforeRoute(filter) / beforeRoute(path, filter), same for afterRoute, and responseFilter(filter) for every response, the ones no after-filter sees included

Logging: requestLogger((request, completion) → …​), with the servlet status, elapsed time, response definition, transmission failure, and the exception the request was answered for in RequestCompletion; see Request Logging

Errors: exception(Type, handler), where the most specific registered type wins and an HttpException reaches only a handler for its own type or a subtype, error(HttpStatus, handler)

Response-wide concerns: cors(Cors), gzip() / gzip(Gzip), securityHeaders() / securityHeaders(SecurityHeaders). Each is off until named, and applies to every answer including static files and errors, which is why they are not filters; see CORS, Compression, and Security

Rendering and assets: templates(renderer), staticFiles(classpathRoot), staticFiles(StaticFiles…​). jte over classpath:/jte and classpath:/public at the root are the defaults, so neither has to be called. StaticFiles.directory(path) serves a directory on disk instead of the classpath, several roots given at once are read in order, and precompressed() answers with a .br or .gz sibling where a build left one. FreeMarkerTemplates, HandlebarsTemplates, and ThymeleafTemplates are TemplateRenderer implementations in modules of their own

Server: start() / start(port), stop(), join(), port(), server(factory). Registration closes while an AppServlet serves the application, however it was started: a route, filter, or setting added then throws IllegalStateException, and stop() opens it again. Cors, Gzip, SecurityHeaders, and StaticFiles are copied when they are registered

Request info: method(), path(), header(name), headers(name) for a repeated header, headers() for all of them, contentType(), queryString(), isSecure(), scheme(), host(), remoteAddress(), and raw() for the servlet request itself. host() carries the port when it is not the scheme’s default, so scheme(), host(), and path() rebuild the absolute URL

The matched route: route(), the Route that answered, with its pattern and description; null before routing and where no route matched, see Route Introspection

Path variables: pathParam, pathParamLong, pathParamEnum, and pathParam(name, parser) for any other type. A name the pattern never declared throws IllegalStateException, not a 400. A \{name*} tail binds the rest of the path with its slashes, and "" when it matched nothing

Parameters: param (400 when missing), paramOrNull (null when missing), paramLong, paramBoolean (true or false only), paramEnum, each with a (…​, default) form for optional parameters; params(name) for repeated values

Any other type: param(name, parser) and param(name, parser, default), where the parser is a Function<String, T> such as UUID::fromString or LocalDate::parse. A parser that throws IllegalArgumentException or DateTimeException answers 400 naming the parameter

One source only: queryParam(name) and formParam(name) require a value and answer 400 when absent. queryParamOrNull(name) and formParamOrNull(name) return null when absent. Parser overloads are required unless a (…​, parser, default) supplies a default

Query vs. form: queryParam, queryParams, formParam, formParams

Content negotiation: accepts(types…​) answers with the type the caller prefers out of the ones offered, 406 when it will take none of them; acceptedTypes() for the parsed Accept header

Cookies the client sent: cookie(name), cookies()

Body: body(), bodyJson(), bodyJson(reader) (400 on a body the reader rejects). The text is read once and kept, so every call answers the whole body

Multipart uploads: file(name) (400 when absent), fileOrNull(name) (null when absent), files(name) for a field that carries several. UploadedFile answers fileName(), contentType(), size(), bytes(), asText(), inputStream(), and writeTo(path)

Body, unread: bodyStream() and bodyReader() hand it over for a parser from another library, and neither mixes with the kept text: whichever goes second throws IllegalStateException. bodyNdjson(reader) reads newline-delimited JSON lazily, and answers 400 naming the line; see Large JSON and NDJSON and External JSON Binding

Session: sessionAttr(key, Class<T>) reads under a named type and fails on that line naming the key and both types, sessionAttr(key) leaves the cast to the call site, setSessionAttr(key, value) writes, removeSessionAttr(key) removes one, and invalidateSession() ends the session

Flash: flash(key, value), read exactly once with flashed(key) on the request after a redirect, and a null value removes the key as it does for a session attribute

Errors: errorMessage() inside an error(status, handler) handler

Bodies: html, text, json(raw), json(JsonValue), json(value, writer), bytes(contentType, data), template(name), template(name, model), stream(contentType, out → …​), file(path), sse(stream → …​), raw((req, res) → …​)

file(path) reads the content type from the name and the length from the file. A path that is not a readable regular file throws UncheckedIOException, so a 404 for a missing file is the handler’s line to write

Bodies written a value at a time: jsonArray(sink → …​) for an array too big to hold, and ndjson(sink → …​) for one value per line. Both are a stream body underneath, and the writer runs outside handler exception handling

Statuses: empty(), empty(HttpStatus), noContent(), redirect(location), redirect(location, HttpStatus)

Building on: status, header, withoutHeader(name), contentType, vary(field), attachment, body, cookie(name, value), cookie(name, value, maxAge), cookie(Cookie), removeCookie

Reading back: status(), header(name), headers(), cookies(), body(). Header names compare without regard to case, and one field holds one value however many spellings set it. A header that must be sent twice is written through raw; see Headers