Servlet Filter Fundamentals & Lifecycle
Master Servlet Filters in Spring Boot, the Security Checkpoint mental model, request pipeline execution, lifecycle methods, and Spring Boot 3 namespace rules.
Servlet Filter Fundamentals & Lifecycle
A Servlet Filter is an HTTP-level checkpoint positioned around Spring Boot's web container execution. It intercepts incoming HTTP requests before they reach Spring MVC's DispatcherServlet and executes post-processing after downstream handlers return.
1. Mental Model: Building Security Checkpoint
Imagine entering a high-security corporate skyscraper:
BUILDING SECURITY CHECKPOINT ANALOGY:
├── Visitor (Client) ──► Arrives at the building entrance with an HTTP request
├── Building Entrance ──► Tomcat / Embedded Servlet Container
├── Security Checkpoint ──► Servlet Filter (Inspects badge, logs entry time, injects Trace ID)
├── Reception Desk ──► DispatcherServlet (Routes visitor to the right department)
├── Dept Checkpoint ──► HandlerInterceptor (Department-specific inspection)
└── Employee Office ──► Controller / Service (Executes core business logic)Core Architectural Rule: Filter = Servlet Layer Interception (Below Spring MVC; knows HTTP metadata, but does NOT naturally know the target Controller method).
2. Architecture and Request Lifecycle Pipeline
3. Filter Lifecycle Interface (jakarta.servlet.Filter)
A filter implements the standard Servlet API contract. In Spring Boot 3+, use the jakarta.servlet package:
package jakarta.servlet;
import java.io.IOException;
public interface Filter {
// Called once by the Servlet container during startup
default void init(FilterConfig filterConfig) throws ServletException {}
// Executed on EVERY matching incoming HTTP request
void doFilter(
ServletRequest request,
ServletResponse response,
FilterChain chain
) throws IOException, ServletException;
// Called once by the Servlet container during shutdown
default void destroy() {}
}Namespace Migration Rule
Spring Boot 2.x ──► javax.servlet.Filter
Spring Boot 3.x+ ──► jakarta.servlet.Filter4. Cross-Cutting Concerns Taxonomy
Filters handle cross-cutting concerns—infrastructure logic that applies globally across endpoints:
- Request/Response Logging: HTTP method, URI, status codes, elapsed timing
- Correlation / Trace IDs: Injecting
X-Request-IdUUID headers for microservice tracing - Security & Auth Boundaries: Early token validation, blocking invalid requests before Spring MVC
- Character Encoding: Enforcing
UTF-8request/response encoding - Response Headers: Injecting security headers (
X-Content-Type-Options: nosniff)
5. Architectural Matrix: Filter vs Interceptor vs Controller vs Spring Security
| Feature | Servlet Filter | HandlerInterceptor | @RestController | Spring Security |
|---|---|---|---|---|
| Execution Layer | Servlet Container (Below Spring MVC) | Spring MVC Framework | Application Domain | Security Filter Chain |
Executes Before DispatcherServlet? | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| Knows Target Controller Method? | ❌ No | ✅ Yes (Object handler) | ✅ Yes | ❌ No |
| Best For | Request logging, headers, timing, early rejection | Controller pre/post handling | Business logic & REST JSON | Enterprise AuthN/AuthZ |
❓ Knowledge Check
Where does a Servlet Filter execute in relation to Spring MVC's DispatcherServlet?
Which Java package must be imported for Servlet Filters in Spring Boot 3?
Conditional Beans with @Profile & Production Patterns
Master conditional Spring bean registration using @Profile, resolving bean ambiguity, implementation switching, and production configuration anti-patterns.
doFilter Continuation, Blocking & Ordering
Master doFilter execution, chain continuation vs request blocking, HttpServletRequest casting, and filter ordering with @Order.