Servlet Interceptor

The servlet interceptor is the bridge between the Java Servlet API and Pedestal’s interceptor chain. It is created when an application calls create-server or create-servlet; ultimately, the function service-fn, calls http-interceptor-service-fn, results in the ::http/service-fn context map key; this is a function that accepts the servlet, servlet request and servlet response (as defined by the Servlet API) and executes an interceptor chain, as a chain provider, to handle an incoming HTTP request.

The service function performs the following tasks:

  1. Sets up the context map and request map

  2. Executes the interceptor queue (:enter, then :leave)

  3. Catches any exceptions that aren’t handled by Error Handling within the interceptors

  4. Writes the final response, using the response map

Part of this work is accomplished by adding new keys to the default context map; beyond that, additional interceptors are prepended:

:io.pedestal.http.impl.servlet-interceptor/stylobate

The stylobate interceptor primarily handles otherwise uncaught unhandled exceptions that occur during interceptor chain execution.

:io.pedestal.http.impl.servlet-interceptor/ring-response

Responsible for converting the :response key in the context, when present, into a response delivered to the client; this may include async streaming.

Partial Responses

In very rare cases, different interceptors may provide different parts of response. Ultimately, the response must be a valid Ring response, but different interceptors may provide different parts of the response (the :body or certain values in the :headers map).

If your application requires this, be very careful about early termination.

  1. Put the initial value into the response map in the last :enter function, then use the :leave functions to refine that value.

  2. Put the initial value into the context under a different key and refine that value in either :enter or :leave functions. When the response is complete, transfer the response map to the :response key.