DEV Community: Ankit Verma

Filters vs Interceptors vs AOP — when each

Ankit Verma — Sat, 19 Sep 2026 08:54:38 +0000

🧠 The big idea in one line

Filters, interceptors, and aspects are three places to run code around a request — at three different depths of the stack.

Every web app has work that isn't the "real" job of any single endpoint: logging, timing, auth checks, adding headers, collecting metrics.
Copying that work into every controller method is a mess. You repeat it everywhere, and you forget it somewhere.
A cross-cutting concern is a job that applies to many requests or many methods — it cuts across your normal code instead of belonging to one spot.
Spring gives you three tools to handle these in one place. They differ by where in the request's journey they sit, and how much they can see.
You meet this the first time you need "run this before every request" — and immediately hit the real question: which of the three?

🛣️ First, the journey of one request

Before comparing the tools, you need to see the path a request takes. It does not land on your controller directly.

Servlet container (Tomcat, Jetty): the web server that speaks HTTP and hands your app a raw HttpServletRequest.
DispatcherServlet: Spring's single front-door servlet. It reads the URL, picks the right controller method, calls it, and turns the return value into a response.
Handler: the specific controller method chosen to serve this request.

Here is where each tool sits, from outside in:

HTTP request
  │
  ▼
▓ Servlet Filter            ← outermost · raw HTTP · no idea which controller
  │
  ▼
  ▓ Handler Interceptor     ← inside Spring MVC · knows the handler
    │
    ▼
    ▓ Controller method
      │  (calls a service bean)
      ▼
      ▓ AOP Aspect          ← wraps any bean method · fires for non-web calls too

The order is the whole insight: filters sit outermost, interceptors sit inside the DispatcherServlet, aspects sit deepest — around your bean methods.
As you move inward, each layer sees more Spring detail and less raw HTTP.

🧱 Layer 1 — Servlet Filters (the outer wall)

A Filter is part of the Servlet spec — plain Jakarta/Java EE, not Spring. It wraps the request before Spring even runs.
It sees the raw HttpServletRequest and HttpServletResponse, and nothing about which controller will run.

@Component
public class TimingFilter implements Filter {
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        long start = System.currentTimeMillis();
        chain.doFilter(req, res);   // hand off to the next filter, then the app
        long took = System.currentTimeMillis() - start;
        System.out.println("Request took " + took + "ms");
    }
}

chain.doFilter(...) is the pivot. Everything before it runs on the way in; everything after it runs on the way out.
If you never call chain.doFilter, the request stops right here. That is how a filter blocks a request entirely — for example, rejecting a missing API key before any Spring code runs.
It holds both the request and the response, so it can even wrap or replace the response body.

Filters are good at:

Work that must happen for every HTTP request — controller-bound or not (static files, error paths).
Reading or modifying the raw request/response (compression, CORS headers, caching the request body).
Security gates that should run before Spring. Spring Security itself is built as one big filter.

🧭 Layer 2 — HandlerInterceptors (inside Spring MVC)

A HandlerInterceptor runs inside the DispatcherServlet, after Spring has already decided which handler will serve the request.
So it knows the handler — a filter never does.

It gives you three hooks around the controller call:

Hook	When it runs	Typical use
`preHandle`	before the controller method	auth check; start a timer; return `false` to block
`postHandle`	after the controller, before the view renders	tweak the model or response
`afterCompletion`	after everything, even when the handler threw	cleanup; stop a timer; log the exception

@Component
public class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
        if (req.getHeader("X-User") == null) {
            res.setStatus(401);
            return false;          // stop: the controller never runs
        }
        return true;               // continue to the controller
    }
}

Returning false from preHandle stops the request — the same idea as a filter that skips chain.doFilter, except you are already inside Spring.
You register it against URL patterns, and the handler argument lets you read the target method's annotations:

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new AuthInterceptor()).addPathPatterns("/api/**");
    }
}

Interceptors are good at:

Web concerns that need to know the controller or endpoint (per-route auth, request logging that names the method).
Anything tied to the MVC lifecycle, like touching the model before the view renders.

🎯 Layer 3 — AOP / Aspects (around any bean method)

The first two tools only see web requests. But cross-cutting work often lives deeper — inside services that are called from web endpoints and from scheduled jobs and from message listeners.

AOP (Aspect-Oriented Programming) lets you run code around any Spring bean method call, web or not.
How does it reach inside a method call? Spring wraps your bean in a proxy — a stand-in object that looks identical to your bean but runs extra code before and after the real method.

caller ──▶ [ Proxy ] ──▶ your real bean method
               │
               └─ runs "advice" before & after the real call

Two terms fall out of that picture:

Advice: the extra code the aspect runs (before, after, or around the method).
Pointcut: the rule that picks which methods to wrap — e.g. "every method in the service package".

@Aspect
@Component
public class LoggingAspect {
    @Around("execution(* com.example.service..*(..))")
    public Object logTime(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = pjp.proceed();      // call the real method
        long took = System.currentTimeMillis() - start;
        System.out.println(pjp.getSignature() + " took " + took + "ms");
        return result;
    }
}

pjp.proceed() is the AOP version of chain.doFilter — it runs the real method. Same in-and-out shape as a filter, but wrapped around a plain Java method instead of an HTTP request.
The pointcut execution(* com.example.service..*(..)) targets every method under the service package.

Aspects are good at:

Business-level cross-cutting: @Transactional, @Cacheable, retries, method-level security, a custom @Audited annotation.
Work that is not about HTTP at all — it fires no matter who called the method.

⚠️ Easy to confuse — the proxy gotcha (self-invocation)

Because AOP works through a proxy, calling one method of a bean from another method of the same bean skips the proxy — the advice does not run.
The reason: this.otherMethod() goes straight to the real object and never touches the wrapper.
This is the classic "@Transactional did nothing" bug: an internal call bypassed the proxy that would have opened the transaction.

🧩 Bad vs good: picking the wrong layer

❌ Putting per-endpoint auth in a Filter

A filter cannot see which controller method will run, so you end up re-parsing the URL by hand to decide the rule. Fragile, and it duplicates Spring's own routing.

✅ Use an interceptor (or method security) instead

It already knows the handler and its annotations, so the rule lives next to where the endpoint is defined.

❌ Using AOP to set an HTTP response header

Your service method has no HttpServletResponse — you would have to smuggle one in. Wrong layer.

✅ Use a filter or interceptor

They hold the raw response and can set headers directly.

⚠️ Easy to confuse — quick separations

Filter vs Interceptor: both wrap web requests. A filter is at the servlet level, has no idea which controller runs, and fires even for non-Spring requests. An interceptor is inside Spring MVC, knows the handler, and only fires for requests the DispatcherServlet routes.
Interceptor vs Aspect: an interceptor is web-only and lifecycle-based (pre/post/after). An aspect targets any method by pointcut and fires for non-web calls too.
The "continue" call in each: chain.doFilter(), return true, and pjp.proceed() all mean "go on to the next thing." Skip any of them and the flow stops there.

📊 Quick summary

	Filter	Interceptor	Aspect (AOP)
Level	Servlet container	Spring MVC (DispatcherServlet)	Any Spring bean method
Spec	Servlet (Jakarta)	Spring MVC	Spring AOP
Sees	raw request/response	handler + request/response	method args + return value
Knows the controller?	❌ no	✅ yes	it is a bean method
Fires for non-web calls?	❌ no	❌ no	✅ yes
"Continue" call	`chain.doFilter()`	`return true`	`pjp.proceed()`
Typical use	CORS, compression, security gate	per-endpoint auth, MVC logging	`@Transactional`, caching, audit

🎯 Decision rule

Need it for every HTTP request — even errors and static files — or must it run before Spring? → Filter.
Need to know which controller/endpoint runs, or hook the MVC lifecycle? → Interceptor.
Need it around service/business methods, or for non-web calls too? → Aspect (AOP).
Rough guide: outer = HTTP plumbing, inner = business logic. Pick the outermost layer that still has everything you need.

💡 Remember this

Three layers, outer to inner: Filter → Interceptor → Aspect. Each sees less raw HTTP and more Spring/business detail.
The "continue" step is the heart of all three: chain.doFilter / return true / proceed(). Skip it to stop the flow.
Only the filter runs without Spring MVC; only the aspect fires for non-web method calls.
AOP works through a proxy, so a self-invocation inside the same bean silently skips the advice.

Exception handling: @ExceptionHandler / @ControllerAdvice / ProblemDetail

Ankit Verma — Fri, 18 Sep 2026 09:07:41 +0000

🧠 The big idea in one line

When your controller code throws, something has to turn that exception into an HTTP response — a status code and a body — instead of leaking a stack trace.
Spring gives you a small set of hooks to say "when this exception happens, send back this status and this body."

Why this exists:

A REST endpoint can't just crash. The caller is a program that needs a clear status code (404, 400, 409…) and a predictable error body to react to.
Without a plan, every controller writes its own try/catch, and error responses come out inconsistent.

When you meet it:

The moment you build a real API. As soon as "the user wasn't found" or "that input was invalid" needs to become a proper HTTP response.

🌊 What Spring does when you do nothing

Before adding any error handling, it helps to see the default path.

In Spring MVC, one servlet receives every incoming request and routes it to the right controller method. That single entry point is the DispatcherServlet — think of it as the front door that dispatches each request to a handler.
If your controller method throws and nothing catches it, the exception travels back up to that front door.

HTTP request
   │
   ▼
DispatcherServlet ──► your @Controller method  ──► throws RuntimeException
   │                                                    │
   │   ◄────────────── exception bubbles back up ───────┘
   ▼
Exception resolvers  ──►  default: "Whitelabel Error Page" / generic 500 JSON

The DispatcherServlet hands the exception to a chain of exception resolvers — objects whose job is to convert an exception into a response.
With no configuration, the default resolver produces a generic 500 Internal Server Error (the plain "Whitelabel Error Page" in a browser, or a bare JSON error).

The problem:

A 500 is wrong for most errors. "User not found" should be 404; "bad input" should be 400.
The body is generic. Your API client gets nothing useful to branch on.

So the whole topic is really: how do I plug into that resolver step and return the right status and body?

🎯 Tool 1 — `@ExceptionHandler` on a controller

The first hook lives right inside a controller. You write a method and mark it as the handler for a given exception type.

Suppose a lookup fails and you throw a custom UserNotFoundException.

@RestController
class UserController {

    @GetMapping("/users/{id}")
    User getUser(@PathVariable String id) {
        return repo.findById(id)
                   .orElseThrow(() -> new UserNotFoundException(id));
    }

    @ExceptionHandler(UserNotFoundException.class)
    ResponseEntity<String> handleNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(404).body(ex.getMessage());
    }
}

What happened here:

@ExceptionHandler(UserNotFoundException.class) marks a method as the catch point for that exception within this controller.
When any method in UserController throws UserNotFoundException, Spring skips the normal return path and calls handleNotFound instead.
The method returns a ResponseEntity — a full HTTP response: status line, headers, and body, all under your control. Here: status 404, body = the message.
The exception object is passed in, so you can read its details to build the response.

⚠️ Easy to confuse: throwing vs. returning. The controller method throws; the handler method returns. The handler is not in the call stack of the failing method — Spring catches the exception and invokes the handler separately.

A shortcut for simple cases: `@ResponseStatus`

If all you want is "this exception means this status code," you can skip the handler method entirely.

@ResponseStatus(HttpStatus.NOT_FOUND) // 404
class UserNotFoundException extends RuntimeException {
    UserNotFoundException(String id) {
        super("No user with id " + id);
    }
}

@ResponseStatus on the exception class tells Spring: whenever this exception reaches the resolver, respond with this status.
No handler method needed. Good for simple, body-less cases.

✅ Use @ResponseStatus when the status is the whole response.

❌ Avoid it when you need a structured body or to add headers — reach for a handler method instead.

🌍 Tool 2 — `@ControllerAdvice` for the whole app

@ExceptionHandler inside one controller only helps that controller. Real apps have many controllers that throw the same errors. Copying handlers everywhere is the duplication we wanted to avoid.

The fix is a class that holds handlers shared by every controller. In Spring, a class of cross-cutting controller logic is called an advice.

@RestControllerAdvice
class GlobalErrorHandler {

    @ExceptionHandler(UserNotFoundException.class)
    ResponseEntity<String> handleNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(404).body(ex.getMessage());
    }

    @ExceptionHandler(IllegalArgumentException.class)
    ResponseEntity<String> handleBadInput(IllegalArgumentException ex) {
        return ResponseEntity.badRequest().body(ex.getMessage()); // 400
    }
}

Walking through it:

@ControllerAdvice marks a class whose @ExceptionHandler methods apply to all controllers, not just one.
@RestControllerAdvice is the same thing plus @ResponseBody behavior baked in — the returned object becomes the JSON body directly. Use it for REST APIs.
One class now owns the mapping from exception → response for the entire application.

⚠️ Easy to confuse — the two advice annotations.

Annotation	Applies to all controllers?	Return value becomes response body?
`@ControllerAdvice`	Yes	Only if you add `@ResponseBody`
`@RestControllerAdvice`	Yes	Yes, automatically

For JSON APIs, @RestControllerAdvice is almost always what you want.

How Spring picks which handler runs

With handlers in both a controller and a global advice, Spring needs a rule.

Exception thrown
      │
      ▼
1. Look in the SAME controller for a matching @ExceptionHandler  ──► found? use it
      │ (none)
      ▼
2. Look in @ControllerAdvice classes                            ──► found? use it
      │ (none)
      ▼
3. Fall back to default resolver (generic 500)

Controller-local handlers win over global ones. A controller can override the app-wide behavior for its own errors.
Among matching handlers, Spring prefers the one whose exception type is most specific (closest in the class hierarchy). A handler for UserNotFoundException beats a handler for RuntimeException when a UserNotFoundException is thrown.

This "most specific wins" rule is why a broad @ExceptionHandler(Exception.class) is a safe catch-all and not a trap — narrower handlers still take priority.

📦 Tool 3 — `ProblemDetail` for a standard error body

Returning a bare string works, but every endpoint can shape its errors differently, and clients hate guessing. There is a standard for this.

ProblemDetail is Spring's built-in model for RFC 9457 ("Problem Details for HTTP APIs") — an agreed-upon JSON shape for errors, sent with the media type application/problem+json. (Available from Spring Framework 6 / Spring Boot 3.)

The standard fields:

Field	Meaning
`type`	URI identifying the error kind (a stable id, optionally a doc link)
`title`	Short human-readable summary of the error kind
`status`	The HTTP status code, repeated in the body
`detail`	Human-readable explanation of this occurrence
`instance`	URI for this specific occurrence (e.g. the request path)

Here is a handler that returns one:

@ExceptionHandler(UserNotFoundException.class)
ProblemDetail handleNotFound(UserNotFoundException ex) {
    ProblemDetail pd =
        ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    pd.setTitle("User not found");
    pd.setType(URI.create("https://api.example.com/errors/user-not-found"));
    pd.setProperty("userId", ex.getUserId()); // custom extension field
    return pd;
}

What each line does:

ProblemDetail.forStatusAndDetail(...) builds the object with the status and the per-occurrence detail message set.
setTitle / setType fill in the stable, error-kind fields.
setProperty adds a custom field beyond the standard ones — the spec allows these extensions, so you can attach domain data like userId.
Returning a ProblemDetail from a @RestControllerAdvice makes Spring serialize it as application/problem+json.

The response body looks like this:

{
  "type": "https://api.example.com/errors/user-not-found",
  "title": "User not found",
  "status": 404,
  "detail": "No user with id 42",
  "instance": "/users/42",
  "userId": "42"
}

Why this is worth it:

Every error across the API has the same shape, so clients write one parser.
It's a public standard, so tools and other teams already understand it.

Handling Spring's own errors: `ResponseEntityExceptionHandler`

Not every exception is yours. Spring MVC itself throws for things like a malformed body or a missing parameter — and by default those become plain responses that don't match your ProblemDetail style.

Extend ResponseEntityExceptionHandler in your advice. It already has @ExceptionHandler methods for the built-in MVC exceptions (bad JSON, unsupported media type, validation failures, and more), and in Spring 6 it returns ProblemDetail bodies too.

@RestControllerAdvice
class GlobalErrorHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    ProblemDetail handleNotFound(UserNotFoundException ex) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    }
    // framework exceptions are handled by the parent class, as ProblemDetail
}

Your custom handlers sit alongside the inherited ones.
Now both your errors and Spring's framework errors come back in the same standard format. One consistent contract for the whole API.

🚧 Gotchas the mechanism creates

These follow directly from how the resolver works.

Errors before the controller are invisible here. Requests pass through filters (a layer that runs before the DispatcherServlet) for things like authentication. An exception thrown in a filter never reaches @ControllerAdvice — the request hasn't entered the dispatch machinery yet. Security errors (401/403) are usually handled by a separate mechanism, not your advice.

request ─► Filters ─► DispatcherServlet ─► Controller
             ▲                │
       throws here            └─ throws here → @ControllerAdvice CAN handle
       → advice CANNOT

An advice can't handle an exception thrown by another advice. If your handler method itself throws, that new exception is not re-fed into the resolver chain — you'll fall back to a generic 500. Keep handler methods simple and safe.
Order among advices isn't guaranteed unless you set it. If two @ControllerAdvice classes both match an exception, use @Order to make the winner explicit rather than relying on chance.
Don't over-catch. A handler for Exception.class will also swallow bugs you'd rather see as a loud 500. Handle the exceptions you understand; let truly unexpected ones fall through to a generic 500 (or a deliberate catch-all that still logs the stack trace).
A returned status beats the annotation. If a handler returns a ResponseEntity with an explicit status, that status is used — the @ResponseStatus on the exception class is ignored for that path. Pick one source of truth per exception.

📊 Quick summary

Tool	Scope	Use it for
`@ResponseStatus` on exception	That exception, everywhere	Status-only errors, no body
`@ExceptionHandler` in a controller	One controller	Errors special to that controller
`@ControllerAdvice` / `@RestControllerAdvice`	All controllers	App-wide error mapping (the default home)
`ProblemDetail`	The response body	A standard, consistent error shape
`ResponseEntityExceptionHandler`	Spring's own MVC errors	Making framework errors match your style

Selection order Spring uses: controller-local handler → global advice → default 500, and within each, most specific exception type wins.

🎯 Decision rule

Just need a status code, no body → @ResponseStatus on the exception.
Need a custom body or headers → an @ExceptionHandler method.
The same error appears across many controllers → move the handler into @RestControllerAdvice.
Building a real API clients depend on → return ProblemDetail so every error has one shape.
Want Spring's built-in errors to match → extend ResponseEntityExceptionHandler.
Error looks like it's being ignored → check whether it's thrown in a filter (before dispatch) rather than a controller.

💡 Remember this

Every uncaught controller exception flows to the DispatcherServlet, which asks exception resolvers to turn it into a response — the default is a generic 500.
@ExceptionHandler maps an exception type to a response; put it in a @RestControllerAdvice to share it across the whole app.
Controller-local beats global, and most-specific exception type beats broader ones.
ProblemDetail (RFC 9457) gives every error one standard JSON shape; extend ResponseEntityExceptionHandler so Spring's own errors match it too.
The chain only covers exceptions thrown inside dispatch — anything from a filter needs handling elsewhere.

Bean Validation (@Valid) + binding errors

Ankit Verma — Thu, 17 Sep 2026 09:35:27 +0000

🧠 The big idea in one line

Bean Validation lets you declare the rules your incoming data must obey right on the data object, and Spring checks them for you at the edge of your app — so bad input is rejected before it ever reaches your logic.

Why it exists: every web app receives junk — empty names, negative ages, malformed emails. Checking all of that by hand, in every controller method, is repetitive and easy to get wrong.
The shift: instead of writing checks, you attach rules to the fields, and something else runs them.
When you meet it: the moment a request carries a body or form — a signup, an order, a search filter — and you want to trust the fields before you use them.

🩹 The problem: hand-written checks everywhere

Imagine a controller that creates a user. Without any help, you check each field yourself:

@PostMapping("/users")
public User create(@RequestBody UserRequest req) {
    if (req.getName() == null || req.getName().isBlank())
        throw new IllegalArgumentException("name required");
    if (req.getAge() < 18)
        throw new IllegalArgumentException("must be 18+");
    // ... and on, and on
    return service.save(req);
}

The rules are buried in the method, mixed with real work.
The same checks get copy-pasted into every endpoint that touches a user.
The error you throw is a raw exception — no clean list of what was wrong.
Change a rule and you must hunt down every copy.

The rules really belong to the data, not to one method. That is the idea Bean Validation makes real.

🏷️ Step 1 — Rules become annotations (constraints)

A constraint is a single rule attached to a field, written as an annotation. "This must not be blank." "This must be at least 18." You put the rule on the field it governs:

public class UserRequest {

    @NotBlank
    private String name;

    @Min(18)
    private int age;

    @Email
    private String email;

    // getters / setters
}

@NotBlank, @Min, @Email are constraint annotations — each names one rule.
The rules now live with the data, readable at a glance, defined once.
These annotations come from the Jakarta Bean Validation standard (the specification; Hibernate Validator is the usual implementation that actually enforces them). It is a Java standard, not a Spring invention — Spring just plugs into it.

A quick tour of the everyday constraints:

Constraint	Passes when…	Note
`@NotNull`	value is not null	says nothing about emptiness
`@NotEmpty`	not null and length/size > 0	for String, Collection, Map, array
`@NotBlank`	not null and has non-whitespace text	String only
`@Min` / `@Max`	number ≥ / ≤ a bound	on numeric types
`@Size(min, max)`	length/size in range	String or collection
`@Email`	looks like an email	format check only
`@Pattern(regexp)`	matches a regex	your own format rule

⚠️ Easy to confuse: the three "not empty" checks are different.

@NotNull → only rejects null. An empty string passes.

@NotEmpty → rejects null and "", but " " (spaces) passes.

@NotBlank → rejects null, "", and " ". For user-typed strings, this is almost always the one you want.

⚙️ Step 2 — Who actually runs the rules?

Declaring a rule does nothing on its own — something has to read the annotations and check the object. That something is a validator: an object that takes your populated data object, runs every constraint on it, and reports back the failures.

Spring Boot, when the validation library is on the classpath, builds a validator and wires it in automatically — you don't create one by hand.
You get that library through the starter:

// build.gradle
implementation 'org.springframework.boot:spring-boot-starter-validation'

Without this dependency the annotations are just silently ignored — a classic "why isn't my validation running?" trap.

So now we have rules on the object and a validator ready to run them. The last piece is telling Spring to actually run it on a request.

🎯 Step 3 — `@Valid` triggers the check at the boundary

Spring reads a JSON body or form into your object automatically — this mapping of request data onto object fields is called binding. You mark the bound parameter with @Valid to say: after binding, run the validator on it.

@PostMapping("/users")
public User create(@Valid @RequestBody UserRequest req) {
    // reached ONLY if every constraint passed
    return service.save(req);
}

@RequestBody binds the JSON into req.
@Valid tells Spring to validate req right after binding, before your code runs.
If everything passes, the method body runs with data you can trust.
If anything fails, the method body never runs — Spring stops at the boundary.

The failures collected during binding and validation are called binding errors. The next question is: where do they go?

📥 Step 4 — Where the errors live, and the two paths

Every failure lands in an Errors object (its common subtype is BindingResult) — a container holding each thing that went wrong. What Spring does with it depends on whether you ask for that container as a parameter.

Path A — Spring throws. No BindingResult parameter:

@PostMapping("/users")
public User create(@Valid @RequestBody UserRequest req) { ... }

Validation fails → Spring raises an exception and your method is skipped.
With no handler, the client gets an automatic 400 Bad Request.
This is the common, clean choice: let it throw, handle it in one place (see Step 6).

Path B — you inspect it yourself. Add a BindingResult parameter:

@PostMapping("/users")
public ResponseEntity<?> create(@Valid @RequestBody UserRequest req,
                                BindingResult result) {
    if (result.hasErrors()) {
        return ResponseEntity.badRequest().body(result.getAllErrors());
    }
    return ResponseEntity.ok(service.save(req));
}

The BindingResult catches the errors instead of letting them throw.
Now the method does run, and you decide what to do with the failures. > ⚠️ The parameter order is a hard rule. The BindingResult must come immediately after the object it validates. Put anything between them and Spring goes back to Path A and throws — a subtle, much-hit bug.

JSON/form  ──►  bind to object  ──►  @Valid runs validator
                                         │
                       ┌─────────────────┴─────────────────┐
                       ▼                                     ▼
             BindingResult param?                    no such param
                       │                                     │
               inspect result yourself             Spring throws → 400

🧩 Step 5 — The failure looks different for JSON vs forms

The exception Spring throws is not the same depending on how the data arrived. Both carry a BindingResult inside, but they have different types — which matters when you write a handler.

Input style	Parameter	Exception on failure
JSON body	`@Valid @RequestBody`	`MethodArgumentNotValidException`
Form / query params	`@Valid @ModelAttribute`	`BindException`

For a REST API sending JSON, you will almost always be handling MethodArgumentNotValidException.
Both expose the same getBindingResult(), so once you have the result the handling code looks the same.

📤 Step 6 — Turning binding errors into a clean response

You rarely want the raw exception page. You catch it in one place and shape a tidy reply. Spring gives a standard error body type, ProblemDetail (RFC 9457), so responses look consistent:

@RestControllerAdvice
class ValidationAdvice {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    ProblemDetail handle(MethodArgumentNotValidException ex) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setTitle("Validation failed");
        pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
            .collect(Collectors.toMap(FieldError::getField,
                                      FieldError::getDefaultMessage)));
        return pd;
    }
}

getFieldErrors() gives one entry per field that failed.
Each FieldError knows the field name and a message (getDefaultMessage()).
The result is a 400 with a clean { field: message } map — the client learns exactly what to fix.
Wiring these handlers in one advice class is its own topic; here just note that a thrown validation error becomes a friendly response in a single spot.

You can control the message per constraint:

@NotBlank(message = "Name is required")
private String name;

Field errors are tied to one field (name was blank).
Global errors (also called object errors) are about the whole object — e.g. "password and confirmation must match," a rule that spans two fields.

🪆 Step 7 — Nested objects and collections

Validation does not automatically dive into nested objects. You must mark the nested field with @Valid too, or its constraints are skipped.

public class OrderRequest {

    @NotNull
    private String product;

    @Valid                       // <-- without this, Address rules are ignored
    private Address address;

    @Valid                       // <-- validates every Item in the list
    private List<Item> items;
}

@Valid on address tells the validator to descend into the Address object and run its constraints.
@Valid on a List validates each element.
Forget the inner @Valid and the nested rules quietly never run — another silent trap.

🔀 Step 8 — `@Validated`: groups and validating single params

@Valid is the plain standard annotation. Spring adds its own @Validated, which does two extra things.

1. Validation groups — apply different rules in different situations.

A field might be required on update but not on create. You tag constraints with a group (a marker interface) and activate the group you want.

public class UserRequest {
    @NotNull(groups = Update.class)   // required only when updating
    private Long id;

    @NotBlank(groups = {Create.class, Update.class})
    private String name;
}

// activate a group for this endpoint:
public User update(@Validated(Update.class) @RequestBody UserRequest req) { ... }

@Valid cannot select a group; @Validated(Group.class) can.

2. Validating loose method parameters — not a whole object.

To validate a bare @RequestParam or @PathVariable, you put @Validated on the class, then constraints directly on the parameters:

@RestController
@Validated                              // <-- enables param-level checks
class SearchController {

    @GetMapping("/search")
    List<Hit> search(@RequestParam @Min(1) int page,
                     @RequestParam @Size(max = 50) String q) { ... }
}

Here the failure is a third exception type: ConstraintViolationException (not the two from Step 5), because there is no object and no BindingResult — just individual parameters. > ⚠️ Easy to confuse: @Valid and @Validated are not the same annotation. > - @Valid → the Java standard annotation. Validates a whole object, cascades into nested @Valid fields. No groups. > - @Validated → Spring's annotation. Supports groups, and on a class enables validating single @RequestParam / @PathVariable values. > - Rule of thumb: use @Valid on the body object; use @Validated when you need groups or method-parameter checks.

🛠️ Step 9 — Writing your own constraint (briefly)

When no built-in rule fits, you can define one. A custom constraint is two pieces: an annotation and a validator class that holds the logic.

@Constraint(validatedBy = NotReservedValidator.class)
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NotReserved {
    String message() default "value is reserved";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

class NotReservedValidator implements ConstraintValidator<NotReserved, String> {
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        return value == null || !value.equalsIgnoreCase("admin");
    }
}

The annotation points to its validator with validatedBy.
isValid returns true or false; the three members (message, groups, payload) are required boilerplate the spec expects.
Now @NotReserved behaves like any built-in constraint — reusable across your whole app.

⚠️ Step 10 — Traps the mechanism creates

Missing dependency, silent no-op. Without spring-boot-starter-validation on the classpath the annotations are simply ignored. Validation "works on my machine" but not after a slimmed-down build.
Misplaced result container. The BindingResult must sit immediately after the validated parameter, or Spring throws instead of handing it to you.
Forgotten nested cascade. Inner objects and list elements are only validated when their field carries @Valid.
Wrong emptiness check. A blank string sails past @NotNull. Pick the constraint (@NotNull, @NotEmpty, @NotBlank) that matches what "empty" means for that field.
Groups without the right annotation. Groups only fire under @Validated; using plain @Valid silently applies the default group and skips your group-specific rules.
Three exception types, one habit. JSON gives MethodArgumentNotValidException, forms give BindException, loose params give ConstraintViolationException. A handler written for one will not catch the others.

📊 Quick summary

Piece	Role
Constraint (`@NotBlank`, `@Min`, …)	one rule, declared on the field
Validator	runs the rules on the object (auto-wired by Boot)
`@Valid`	trigger validation after binding; cascades into nested `@Valid`
`@Validated`	Spring's variant: groups + single-parameter validation
`BindingResult` / `Errors`	holds the failures
`MethodArgumentNotValidException`	thrown for a failed `@RequestBody`
`BindException`	thrown for a failed form / `@ModelAttribute`
`ConstraintViolationException`	thrown for failed loose `@RequestParam` / `@PathVariable`
`@ExceptionHandler` • `ProblemDetail`	turn the failure into a clean 400

🎯 Decision rule

Validating a request body or form object? → put @Valid on the parameter.
Want to inspect errors inline? → add a BindingResult right after it. Otherwise let it throw and handle centrally.
Need rules that differ by create/update, or to validate a bare param? → reach for @Validated (with a group, or on the class).
Validation not running at all? → check the spring-boot-starter-validation dependency first.
Nested object or list not being checked? → add @Valid on that field.

💡 Remember this

Rules live on the data as annotations; Spring runs them for you at the boundary. That is the whole point — no hand-written checks scattered through controllers.
The trigger, then the container. @Valid runs the check; the errors land in a BindingResult — ask for that parameter to inspect them, or let Spring throw a 400.
Two annotations, two jobs. Use @Valid for whole objects and @Validated for groups and single parameters — and the exception type depends on how the data arrived.
Silence usually means a missing piece: the starter dependency, a misplaced BindingResult, or a forgotten nested @Valid.

Content negotiation & message converters (Jackson)

Ankit Verma — Wed, 16 Sep 2026 09:25:29 +0000

🧠 The big idea in one line

Your controller returns a plain Java object, and Spring quietly turns it into JSON (or reads JSON back into an object) — content negotiation is how Spring decides which format, and a message converter is the thing that actually does the translation.

Why this topic exists:

A browser, a mobile app, and a curl script can all call the same endpoint but want the body in different shapes: JSON, XML, plain text, a PDF.
You do not want to write if (wantsJson) ... else if (wantsXml) ... in every method.
Spring pushes that decision to the edge of the request, so your method stays about business logic and returns one object.

When you meet it:

The moment you write @RestController and return an object instead of a view name.
The first time a client gets a 406 or 415 error and you have no idea why.
The first time a date serializes as 1699999999000 instead of 2026-09-16 and you go hunting.

🎯 The starting point: a method that returns an object

In classic Spring MVC, a controller method returned a view name — a string like "userProfile" — and Spring rendered an HTML template.
For an API you do not want HTML. You want the object itself, as data, in the response body.

Here is the shape almost every API method has:

@RestController
@RequestMapping("/users")
class UserController {

    @GetMapping("/{id}")
    User getUser(@PathVariable Long id) {
        return userService.find(id); // just a Java object
    }
}

The method returns a User. No JSON anywhere in sight.
Something between your method and the network socket has to turn that User into bytes on the wire.
That "something" is a message converter, and picking the right one is content negotiation. Let's build both up.

🔌 What a message converter is

A message converter is an object that knows how to translate between a Java type and one HTTP body format.
It works in both directions:
- Write: Java object → bytes in the response body (serialization).
- Read: bytes in the request body → Java object (deserialization).

Spring models this with one interface, HttpMessageConverter. The important part is these four questions it can answer:

boolean canRead(Class<?> type, MediaType mediaType);   // can I turn this body into that type?
boolean canWrite(Class<?> type, MediaType mediaType);  // can I turn that type into this body?
Object  read(Class<?> type, HttpInputMessage in);      // do the reading
void    write(Object value, MediaType type, HttpOutputMessage out); // do the writing

A MediaType is just a content type like application/json or text/plain — the label that says what a body is.
Each converter is tied to one or a few media types. For example:
- MappingJackson2HttpMessageConverter handles application/json using the Jackson library.
- StringHttpMessageConverter handles text/plain.
- ByteArrayHttpMessageConverter handles raw application/octet-stream bytes.

So Spring holds a list of converters, and for any request it asks each one, "can you handle this type and this media type?" The first that says yes wins.

🧭 Content negotiation: which format does the client want?

On the response side, Spring has your User object and a list of converters. It still needs to know which format the client wants back.
Deciding that format is content negotiation.

The client states its preference with the Accept header:

GET /users/42
Accept: application/json

Accept: application/json means "send me JSON."
Accept: application/xml means "send me XML."
Accept: */* (what curl sends by default) means "I'll take anything."

The flow on the way out looks like this:

controller returns User
        │
        ▼
read Accept header  ──►  application/json
        │
        ▼
find a converter where canWrite(User, application/json) == true
        │
        ▼
MappingJackson2HttpMessageConverter.write(user, ...)
        │
        ▼
{"id":42,"name":"Ada"}  ──►  response body

Spring intersects two lists: the media types the client will accept, and the media types the converters can produce.
It picks the best match and hands the object to that converter.

The other strategies (and why Accept is the default)

The Accept header is the default and preferred way to negotiate. But Spring supports a few other strategies, each managed by a ContentNegotiationStrategy:

Strategy	How the client asks	Status today
Header	`Accept: application/json`	✅ Default, recommended
Parameter	`GET /users/42?format=json`	Off by default; opt in
Path extension	`GET /users/42.json`	❌ Deprecated (security risks), off by default

⚠️ Easy to confuse — Accept vs Content-Type:
- Accept is on the request and describes the body the client wants back. It drives the response converter.
- Content-Type describes the body that is actually attached right now. On a request it labels what the client sent; on a response it labels what the server sent.
- Same idea (a media type), opposite direction. Mixing them up is the classic content-negotiation bug.

You can turn the parameter strategy on with a small config bean:

@Configuration
class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer c) {
        c.favorParameter(true)       // enable ?format=...
         .parameterName("format")
         .defaultContentType(MediaType.APPLICATION_JSON); // fallback when Accept is silent
    }
}

defaultContentType matters: if a client sends no Accept header at all, this is what they get.

📥 The request side: reading a body in

Everything so far was the response. Reading a request body works with the same converters, but the trigger and the header are different.
You mark a parameter with @RequestBody to say "fill this from the request body."

@PostMapping("/users")
User create(@RequestBody User newUser) {
    return userService.save(newUser);
}

Here the client sends a JSON body, and Spring must turn it into a User.
Now the header that matters is Content-Type, because it describes the body the client actually sent:

POST /users
Content-Type: application/json

{"name":"Ada"}

Spring asks each converter canRead(User, application/json). Jackson's converter says yes and deserializes the body into a User.

So the two sides mirror each other:

Direction	Trigger	Header read	Converter method
Response out	`@ResponseBody` / `@RestController`	`Accept`	`canWrite` → `write`
Request in	`@RequestBody`	`Content-Type`	`canRead` → `read`

Note: @RestController is just @Controller + @ResponseBody on every method, which is why returning an object "just works" without writing @ResponseBody each time.

🚦 When negotiation fails: 406 and 415

Two HTTP errors come straight out of this machinery, and knowing which is which saves real debugging time.
406 Not Acceptable → a response problem.
- The client's Accept header asks for a format no converter can produce.
- Example: Accept: application/xml but you only have Jackson (JSON) on the classpath.
415 Unsupported Media Type → a request problem.
- The client's Content-Type labels a body no converter can read.
- Example: client posts Content-Type: text/yaml and nothing can parse YAML.
⚠️ Easy to confuse — 406 vs 415:
- 406 = "I can't give you what you'll accept" (about Accept, the way out).
- 415 = "I can't read what you sent me" (about Content-Type, the way in).

You can also constrain endpoints explicitly with produces and consumes:

@PostMapping(
    path = "/users",
    consumes = MediaType.APPLICATION_JSON_VALUE,  // only accept JSON bodies
    produces = MediaType.APPLICATION_JSON_VALUE)  // only ever return JSON
User create(@RequestBody User u) { ... }

consumes narrows what the endpoint will read → a mismatch gives 415.
produces narrows what the endpoint will return → a mismatch with Accept gives 406.
These also help Spring route: two methods on the same path can differ only by produces, one for JSON and one for XML.

🧩 Jackson: the converter that does the JSON work

For JSON, the converter is MappingJackson2HttpMessageConverter, and inside it sits a single ObjectMapper — Jackson's core engine that maps between objects and JSON.
Spring Boot auto-configures this ObjectMapper for you, so you rarely create one by hand. But you do need to steer it.

The date trap

By default, plain Jackson serializes a java.time date as a number (epoch or an array), which almost nobody wants:

❌  "createdAt": 1726444800.000
✅  "createdAt": "2026-09-16T10:00:00"

The fix has two parts, and Boot handles both automatically:
- Register the JavaTimeModule so Jackson understands LocalDate, Instant, and friends.
- Turn off WRITE_DATES_AS_TIMESTAMPS so they render as ISO-8601 strings.
If you build an ObjectMapper yourself, you must add these — forgetting the module is the single most common Jackson bug.

Steering serialization with annotations

You control the JSON shape field by field, right on the class:

class User {
    @JsonProperty("user_name")   // rename the JSON key
    String name;

    @JsonIgnore                  // never serialize this
    String passwordHash;

    @JsonInclude(JsonInclude.Include.NON_NULL) // drop nulls from output
    String nickname;
}

@JsonProperty bridges a Java name and a different JSON name.
@JsonIgnore keeps secrets out of the body.
@JsonInclude(NON_NULL) trims empty fields so responses stay small.

The unknown-property trap

By default Jackson fails when the incoming JSON has a field your class does not declare.
That is strict and often surprising when a client sends an extra field.

❌  Strict (default): unknown field  →  deserialization throws  →  400
✅  Lenient: ignore unknown fields, bind the rest

Boot flips this to lenient for you by default (FAIL_ON_UNKNOWN_PROPERTIES=false), but know the switch exists — it decides whether an extra field is a hard error or quietly ignored.

⚙️ Customizing converters the right way

You will eventually need to change global behavior. There is a clean order of preference, from least to most invasive.
1. Properties first. Most tuning needs no code:

spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.default-property-inclusion=non_null
spring.jackson.deserialization.fail-on-unknown-properties=false

2. A builder-customizer bean when properties are not enough. This adjusts Boot's ObjectMapper without replacing it:

@Bean
Jackson2ObjectMapperBuilderCustomizer json() {
    return builder -> builder.simpleDateFormat("yyyy-MM-dd")
                             .modulesToInstall(new MyModule());
}

3. configureMessageConverters / extendMessageConverters when you need to touch the converter list itself:
extendMessageConverters — adjust the list Boot already built (the safe choice).
configureMessageConverters — replace the whole list (you now own every converter, including the defaults you just dropped).
❌ Don't create a bare new ObjectMapper() bean just to tweak one setting — you throw away all of Boot's sensible defaults (the JavaTimeModule, the lenient reading) and reintroduce the date trap.
✅ Do start at properties, then a customizer, and only reach for the converter list when you are adding a genuinely new format.

📊 Quick summary

Concept	What it does	Header it reads
Message converter	Translates Java object ↔ body bytes	—
Content negotiation	Picks the response format	`Accept`
`@RequestBody`	Reads request body into an object	`Content-Type`
`@ResponseBody`	Writes returned object to the body	`Accept`
`produces`	Restricts formats the endpoint returns	`Accept` (mismatch → 406)
`consumes`	Restricts formats the endpoint reads	`Content-Type` (mismatch → 415)
Jackson `ObjectMapper`	The engine doing the JSON mapping	—

🎯 Decision rule

Getting a 406? The client's Accept asks for a format you can't produce. Add the converter (e.g. XML) or fix the client's Accept.
Getting a 415? The client's Content-Type names a body you can't read. Fix the header or add a converter.
Dates look like numbers? You're missing the JavaTimeModule or write-dates-as-timestamps is still on — you likely built your own ObjectMapper.
Need to change JSON globally? Try spring.jackson.* → then a Jackson2ObjectMapperBuilderCustomizer → then the converter list, in that order.
Need per-field control? Use @JsonProperty, @JsonIgnore, @JsonInclude on the class.

💡 Remember this

Your controller returns an object; a message converter turns it into bytes, and content negotiation picks the format.
Accept drives the response (out); Content-Type drives the request body (in). Keep the two straight and 406 vs 415 becomes obvious.
Jackson's ObjectMapper is the JSON engine — let Boot configure it, and tune it through properties or a customizer, never by replacing it wholesale.
@JsonProperty, @JsonIgnore, and @JsonInclude shape the JSON per field; the JavaTimeModule keeps your dates readable.

Request lifecycle: HandlerMapping HandlerAdapter resolvers

Ankit Verma — Tue, 15 Sep 2026 22:08:02 +0000

🧠 The big idea in one line

Spring finds the handler, prepares its arguments, calls it, and handles the result.

Why this exists — an HTTP request contains paths, headers, and bytes. Your Java method needs typed arguments.
Spring bridges that gap using the parameter and return types it supports.
When you meet it — a route fails, a parameter cannot be converted, or you want to supply a custom method argument.
What you already have — one servlet catches every request, and @GetMapping marks a method. This lesson is everything that happens in between.

🗺️ Three questions, asked in order

The DispatcherServlet does not contain your logic and does not know your URLs. On each request it asks three questions and hands each one to a different object:

Which method should run? — answered by an object whose only job is matching a request to a method. That object is a handler mapping.
How do I actually call that method? — answered by an object that knows one calling style. That is a handler adapter.
What value goes in each parameter? — answered by small single-purpose objects called argument resolvers.

request
      |
      v
+------------------+
| DispatcherServlet|
+------------------+
      |
      |  1. "who owns /users/42?"
      +---------------------------> HandlerMapping  --> HandlerMethod
      |
      |  2. "who can call that?"
      +---------------------------> HandlerAdapter
      |
      |  3. adapter fills the args
      |        @PathVariable Long id  <-- ArgumentResolver
      |        @RequestBody  User u   <-- ArgumentResolver
      |
      v
   your method runs

Each answer is looked up, never hard-coded. That is what makes the whole thing extensible.

📇 The lookup table is built at startup

Matching a URL by scanning every controller on every request would be slow. So Spring does the scanning once, at startup.

At boot, Spring walks every bean marked @Controller or @RestController.
For each annotated method it reads the mapping annotations and builds a RequestMappingInfo — a small object holding everything that must match: path, HTTP method, params, headers, consumes, produces.
It pairs that with a HandlerMethod — just the controller bean plus a java.lang.reflect.Method handle. That pair is "the handler".
Both go into one map, the mapping registry, held by RequestMappingHandlerMapping.

So this method:

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping(path = "/{id}", produces = "application/json")
    public User getUser(@PathVariable Long id) { ... }
}

becomes, at startup, roughly one registry entry:

RequestMappingInfo{ GET /users/{id}, produces=application/json }
        ->  HandlerMethod{ userController, getUser(Long) }

What this means in practice:

Lookup at request time is a map read plus a little matching — fast.
Creating an object with new does not register a new route.
The registry is not frozen. Spring exposes registerMapping() and unregisterMapping() for deliberate runtime changes.
Ordinary applications let Spring discover their routes at startup.

🔍 Step 1 — the handler mapping picks the method

The DispatcherServlet holds an ordered list of handler mappings, not just one. It asks each in turn and takes the first non-null answer.

// Conceptually, inside DispatcherServlet
for (HandlerMapping mapping : this.handlerMappings) {
    HandlerExecutionChain chain = mapping.getHandler(request);
    if (chain != null) return chain;   // first one to claim it wins
}
return null;                            // nobody claimed it -> 404

In the usual Spring MVC configuration, annotated controllers are checked before static resources by RequestMappingHandlerMapping.
Other mappings and custom ordering can change this list.
Static resources (/style.css) are checked by a later mapping in the list.
That ordering matters — a controller mapped to a very broad path answers first, and the static file is never reached.

What comes back is not the method alone. It is a HandlerExecutionChain — the handler plus the list of interceptors that should run around it. We'll use those at the end.

How a match is actually decided

A route must satisfy its path and mapping conditions.
If no full match exists, Spring checks partial matches to explain common failures.
These are typical default responses for mapping failures. Other processing stages can produce the same codes.

Stage	Checks	If nothing matches
Path	URL against the patterns	404 — no handler at all
HTTP method	GET vs POST vs …	405 Method Not Allowed
`consumes`	request `Content-Type`	415 Unsupported Media Type
`produces`	request `Accept` header	406 Not Acceptable
`params`	required request-parameter conditions	400 Bad Request

A failed headers mapping condition does not automatically mean 400. It can leave the request without a matching controller.
A 404 can mean no route matched, a static file was missing, or application code returned 404.
A 415 can come from consumes matching or from a body converter later.
Check the exception or logs along with the status code.
If several mappings match, Spring compares specificity. An exact path usually beats a variable pattern.
If the best matches remain equally specific, Spring reports an ambiguous match.

🔌 Step 2 — the handler adapter, and why there is a middleman

The mapping returns a handler typed as plain Object.
It might represent an annotated method, a static-resource handler, or a function-based route.
The DispatcherServlet needs a different calling strategy for each kind.

❌ The obvious design that fails

// If DispatcherServlet called handlers directly:
if (handler instanceof HandlerMethod hm) { ... }
else if (handler instanceof ResourceHttpRequestHandler r) { ... }
else if (handler instanceof HandlerFunction f) { ... }
// every new handler style = editing DispatcherServlet

Every new kind of handler forces a change to the core class.
Third parties could never add a handler style at all.

✅ What Spring does instead

A handler adapter knows how to call one kind of handler. Its two main operations are shown here:

public interface HandlerAdapter {
    boolean supports(Object handler);
    ModelAndView handle(HttpServletRequest req,
                        HttpServletResponse res,
                        Object handler) throws Exception;
}

The DispatcherServlet walks its adapter list and takes the first one whose supports() returns true.
For your @GetMapping methods that is RequestMappingHandlerAdapter.
The DispatcherServlet stays completely unaware of annotations, reflection, or JSON.

The adapter returns a ModelAndView — a small holder for the data plus the name of a page to render. It may also be null. Hold that thought — it matters in step 4.

🧩 Step 3 — argument resolvers fill the parameters

Now the adapter has to call getUser(Long id). It has an HttpServletRequest; it needs a Long. This is where the real work happens.

An argument resolver supplies values for the parameter types or annotations it supports. Here is a simplified outline of its two operations:

public interface HandlerMethodArgumentResolver {
    boolean supportsParameter(MethodParameter parameter);
    Object resolveArgument(MethodParameter parameter, ...) throws Exception;
}

The adapter loops over the method's parameters. For each one:

Walk the resolver list and find the first whose supportsParameter() says yes.
Call its resolveArgument() to produce the value.
Put the value in the argument array.

What happens on later requests:

Spring caches which resolver supports each parameter. It does not repeat that search on every request.
It still resolves fresh argument values for each request.
Text values also need type conversion: "42" becomes a Long; "abc" cannot.
A missing required value or failed conversion normally produces 400 before your method runs.
An unannotated simple parameter is normally treated as a request parameter.
A complex parameter can instead be built from form or query fields. This is model-attribute binding, also requested explicitly with @ModelAttribute. It does not parse a JSON body.

Once every slot is filled, the adapter invokes the method by reflection. This signature:

public User update(@PathVariable Long id,
                   @RequestBody UserDto body,
                   @RequestHeader("X-Trace") String trace) { ... }

is not one magic step. It is three independent resolvers, each filling one slot:

Parameter	Resolver responsible	Where the value comes from
`@PathVariable`	`PathVariableMethodArgumentResolver`	URL template variables
`@RequestParam`	`RequestParamMethodArgumentResolver`	query string or form fields
`@RequestBody`	`RequestResponseBodyMethodProcessor`	request body, via message converters
`@RequestHeader`	`RequestHeaderMethodArgumentResolver`	a named header
`HttpServletRequest`, `Principal`, `Locale`	`ServletRequestMethodArgumentResolver`	the request itself

That @RequestBody row is a boundary worth naming. The resolver does not parse JSON itself — it hands the body stream to a message converter, which is the thing that knows JSON. The next lesson takes converters apart; here it is enough that the resolver delegates.

Adding your own resolver

Because the list is just a list, you can extend it. Say every request carries a tenant header and you are tired of reading it by hand.

public class TenantResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter p) {
        return p.hasParameterAnnotation(CurrentTenant.class);
    }

    @Override
    public Object resolveArgument(MethodParameter p, ModelAndViewContainer m,
                                  NativeWebRequest req, WebDataBinderFactory b) {
        return new Tenant(req.getHeader("X-Tenant-Id"));
    }
}

CurrentTenant is a custom parameter annotation retained at runtime.
Tenant is your value type with a constructor accepting the ID.
Register the resolver through WebMvcConfigurer, Spring MVC's configuration extension interface:

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new TenantResolver());
    }
}

Your controller can then ask for that value:

@GetMapping("/orders")
public List<Order> list(@CurrentTenant Tenant tenant) { ... }

supportsParameter is the filter: only parameters marked @CurrentTenant.
resolveArgument is the factory: build the value from the request.
Controllers no longer repeat the header lookup.
This small example omits missing-header checks. Reject a missing or invalid ID before using it.
A client-supplied tenant ID is input, not proof of access. Verify access against the authenticated user.

📤 Step 4 — return value handlers deal with what comes back

Arguments have a mirror image. A return value handler decides what to do with whatever your method returned. Same two-method shape: does it support this return type, and how should it be handled.

The common return-value paths:

Return type	Handler	Result
`@ResponseBody` value	`RequestResponseBodyMethodProcessor`	serialized straight into the response body
`ResponseEntity`	`HttpEntityMethodProcessor`	body plus status and headers
plain `String` on `@Controller`	`ViewNameMethodReturnValueHandler`	treated as a view name to render

Here is the mechanism that connects this back to the DispatcherServlet:

When a return-value handler handles the response body, it marks the request as handled.
That flag means no view is needed. It does not promise that network delivery has finished.
The adapter then returns null instead of a ModelAndView.
The DispatcherServlet sees null and skips view resolution entirely.
@RestController includes @ResponseBody behavior for its methods.
A method in a plain @Controller can also use @ResponseBody, or return ResponseEntity.
Both controller styles use the same pipeline. Annotations and return types determine how the result is handled.

🔗 Interceptors wrap the whole thing

Remember the chain carried interceptors alongside the handler. They run at three fixed points:

preHandle       -> before the adapter is called
   [ handler runs, response may be written ]
postHandle      -> after the handler, before any view is rendered
   [ view rendering, if any ]
afterCompletion -> cleanup for interceptors whose preHandle returned true

preHandle returning false stops the request there — the handler never runs.
postHandle is skipped if the handler threw an exception.
Cleanup runs only for interceptors whose preHandle completed and returned true.
If your own preHandle returns false or throws, release anything it acquired there.
preHandle runs in list order. postHandle and afterCompletion run in reverse order.
This diagram shows a synchronous request. Async processing defers completion and may dispatch again.
If processing throws, the DispatcherServlet asks exception resolvers to handle the failure.
A resolver may produce an error response or view. An unresolved exception propagates to the servlet container.
Exception handling gets its own lesson later in this module.

⚠️ Easy to confuse

Handler mapping vs handler adapter — the mapping answers which method; the adapter answers how to call it. A mapping failure means no method was chosen at all. By the time an adapter is involved, your method has already been picked.
Argument resolver vs message converter — the resolver decides which part of the request a parameter comes from. The converter turns bytes into an object. Only body-related parameters involve a converter at all.
HandlerMethod vs handler — "handler" is the general word for whatever answers a request. HandlerMethod is the specific kind that wraps one annotated controller method.
404 vs 405 — a default routing 404 means no matching handler was found. A mapping-stage 405 means a path matched but the HTTP method did not. Application code can also return these statuses.

🕳️ Traps this design creates

Do not consume the body before Spring reads it. A filter that drains the stream can leave @RequestBody with no bytes.
For logging, ContentCachingRequestWrapper records bytes as downstream code reads them. Read its cache after the filter chain returns.
That wrapper does not automatically make the input stream replayable. Reading the body first requires a wrapper that actually supplies a fresh stream.
Changing the model in postHandle will not change a JSON response. Body handling already ran inside the adapter.
Use ResponseBodyAdvice, a hook that can adjust the body before a message converter writes it.
The first supporting resolver wins. Resolvers added through addArgumentResolvers() sit after many standard resolvers, but before fallback resolvers.
An explicit @RequestParam is normally claimed by its standard resolver first. Use a dedicated annotation for a custom value.
A broad controller path can claim static-file requests. In the usual ordering, a root mapping like /{path} can match /favicon.ico before the resource handler sees it.
Creating a controller object does not register its routes. Dynamic registration is possible through the mapping registry's API. It must be deliberate.

📊 Quick summary

Stage	Component	Question it answers	Produces
Startup	mapping registry	what routes exist?	RequestMappingInfo → HandlerMethod
1	HandlerMapping	which method owns this request?	HandlerExecutionChain
2	HandlerAdapter	how do I call this handler?	calls the handler and returns ModelAndView or null
3	Argument resolvers	what goes in each parameter?	the argument array
4	Return value handlers	what do I do with the result?	a written body, or a view name

🎯 Decision rule

Use the code as a clue, then check the exception and logs:

404 → check mappings, class-level prefixes, and static-resource lookup. Also check whether application code returned it.
405 → check the request method against the mapped methods.
415 → check Content-Type, consumes, and whether a converter can read the body.
406 → check Accept, produces, and whether a converter can write the result.
400 with a missing-parameter message → step 3, a resolver could not find a required value.
Parameter is null but the request looks right → step 3, check that the resolver you expect is actually the first one claiming that parameter.

To inject a value of your own, add an argument resolver with your own annotation — never fight the built-in ones.

💡 Remember this

The DispatcherServlet orchestrates and delegates. It asks which method, how to call it, and what to pass — three questions, three replaceable answers.
Spring discovers ordinary routes at startup. Creating an object later does not add a route, but explicit runtime registration is possible.
Status codes help locate a failure. They do not uniquely identify its stage; read the exception too.
A method signature is filled one parameter at a time by independent resolvers, and the return value is handled by their mirror image. Both lists are open — that is the extension point.

@Controller vs @RestController, request mapping

Ankit Verma — Tue, 15 Sep 2026 09:32:20 +0000

Where this fits

When a browser or another service sends an HTTP request to your Spring application, something has to catch that request, run your code, and send a reply. In Spring, the class that does the catching is called a controller. It is the front door of a web application — the layer where "a GET request just arrived for /users/42" turns into "run this Java method and return this result."

You meet controllers the moment you build anything that answers HTTP: a JSON API, a server-rendered web page, a webhook receiver. This article is about the two annotations that declare one — @Controller and @RestController — and about how Spring decides which method handles which request. That second part is called request mapping, and it is where most of the everyday work happens.

A controller is just a managed object

One idea has to be in place before the rest makes sense. Spring runs a container: an object created at startup that builds your objects, wires them together, and manages how long they live. Any object the container owns is called a bean. You almost never write new for a controller — you describe the class, and the container builds one instance and holds onto it.

To tell the container "this class is one of yours," you put an annotation on it. At startup Spring scans your packages, finds those annotations, and registers a bean for each match. @Controller is one of those annotations.

So the first thing @Controller does is ordinary: it marks the class as a bean for the container to create. But it does a second thing, and that second thing is the entire point.

What @Controller actually signals

@Controller is a stereotype — a specialized "this is a bean" marker that also tells Spring what kind of bean it is. It says: this bean handles web requests, so inspect its methods for request mappings.

Here is the smallest useful one.

@Controller
public class PageController {

    @GetMapping("/hello")
    public String hello() {
        return "welcome";
    }
}

The @GetMapping("/hello") line says this method handles GET requests for the path /hello. The method runs and returns the string "welcome".

Now the part that surprises everyone the first time. With a plain @Controller, that returned string is not the response body. It is a view name — the name of a template file (a welcome.html, say) that Spring should find, render, and send back as a full HTML page.

That default exists for a reason. @Controller was born for server-side web pages, back when a request usually meant "give me a rendered page." So its baked-in assumption is: the String you return names a page to render, not the text to send.

Telling Spring "that's the body, not a view name"

Often you do not want a rendered page. You want to send data straight back — plain text, or JSON. To flip the meaning of the return value, you add @ResponseBody.

@Controller
public class ApiController {

    @GetMapping("/hello")
    @ResponseBody
    public String hello() {
        return "welcome";
    }
}

With @ResponseBody present, the return value is written directly into the HTTP response body. The client now receives the literal text welcome, with no template lookup at all.

The same rule covers objects, and this is where it earns its keep. Return a User object from a @ResponseBody method and Spring serializes it — to JSON by default — and writes that JSON to the response. This is how a Java method becomes a REST endpoint.

@GetMapping("/users/42")
@ResponseBody
public User getUser() {
    return new User(42, "Ada");
}
// client receives:  {"id":42,"name":"Ada"}

So the whole difference between "web page" and "API" is that one annotation. But repeating @ResponseBody on every method in an API class gets tedious fast.

@RestController: the shortcut you almost always want

@RestController is that repetition, removed.

@RestController
public class ApiController {

    @GetMapping("/hello")
    public String hello() {
        return "welcome";   // sent as the body, not a view name
    }
}

@RestController is a meta-annotation: an annotation built out of other annotations. It bundles @Controller and @ResponseBody together, and the @ResponseBody applies to every method in the class. Nothing more, nothing less.

That gives a clean rule of thumb:

@RestController — for APIs that return data (JSON, XML, plain text).
@Controller — for endpoints that render server-side pages, or a class where some methods render pages and only some return data.

And it explains a classic bug. Someone builds a JSON API with @Controller, forgets @ResponseBody, and every endpoint returns a String. Spring dutifully treats each return value as a view name and tries to find a template called welcome — so instead of JSON, they get a confusing 500 error about a missing view. The fix is almost always "switch to @RestController."

Request mapping: matching a request to a method

Declaring a controller is half the job. The other half is telling Spring which requests each method should handle. That wiring is request mapping.

The general-purpose annotation is @RequestMapping, which takes the path and the HTTP method explicitly:

@RequestMapping(path = "/hello", method = RequestMethod.GET)

Because "map this path to this one HTTP verb" is so common, Spring ships a shortcut for each verb. These two lines mean exactly the same thing:

@RequestMapping(path = "/hello", method = RequestMethod.GET)
@GetMapping("/hello")

The full set of shortcuts mirrors the HTTP verbs you already know: @GetMapping, @PostMapping, @PutMapping, @PatchMapping, @DeleteMapping. Reach for these by default; fall back to the long @RequestMapping form only when you need something they do not express.

Composing paths, and reading the request

You can put @RequestMapping on the class too, to set a common prefix. Spring joins the class-level path and the method-level path together.

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.find(id);
    }

    @GetMapping
    public List<User> list(@RequestParam(defaultValue = "0") int page) {
        return userService.page(page);
    }
}

The class prefix /users plus the method path /{id} gives the full mapping /users/{id}. The second method has no method-level path, so it maps to /users itself.

Two small helpers appear here, and both pull pieces of the request into method parameters:

@PathVariable grabs a value out of the path. In /users/{id}, a request to /users/42 binds id = 42. The {id} in the mapping and the parameter name line up.
@RequestParam grabs a value from the query string. For /users?page=2, it binds page = 2; the defaultValue supplies 0 when the parameter is absent.

That covers the normal case end to end: mark the class, map the path and verb, pull what you need out of the request.

Narrowing a mapping further

Path and verb are the usual filters, but @RequestMapping (and the shortcuts) can narrow a match on more than that. The common two:

consumes — only match if the request's Content-Type fits, e.g. consumes = "application/json".
produces — only match if the client will accept what you emit, e.g. produces = "application/json".

@PostMapping(path = "/users", consumes = "application/json")
public User create(@RequestBody User user) {
    return userService.save(user);
}

Here @RequestBody is the mirror image of @ResponseBody: it takes the incoming JSON body and deserializes it into a User for you. And consumes means this method is only chosen when the caller actually sent JSON — a request with a different content type is turned away before your code runs.

When two mappings could both match

Because you can map broadly (a /{id} pattern) and narrowly (an exact /me path) in the same class, two methods can both look like valid matches for one request. Spring resolves this by specificity: a more exact mapping wins over a more general one. An exact path like /users/me beats the variable pattern /users/{id}, even though me would also satisfy {id}.

If two mappings are genuinely equally specific — a real tie Spring cannot break — it does not guess. You get an exception at request time complaining that the mapping is ambiguous. That is a signal to make one of the two more specific, not something to work around.

Putting it together

A controller is a bean that handles HTTP. @Controller marks it, and by default treats a returned String as a page to render. @ResponseBody flips that method to write its return value straight into the response, serializing objects to JSON on the way out. @RestController is simply @Controller with @ResponseBody on every method — the right default for a data API.

Request mapping is the matching layer: @RequestMapping and its per-verb shortcuts bind a path and an HTTP method to a method, class-level and method-level paths compose, and @PathVariable and @RequestParam hand you the pieces of the request you asked for. When several mappings could match, the most specific one wins. Get these two ideas — declare the controller, map the request — and the rest of Spring MVC is detail layered on top.

Servlet model & DispatcherServlet flow

Ankit Verma — Mon, 14 Sep 2026 10:03:04 +0000

Every Spring web request goes through one door

When you build a web app with Spring, you write small methods that handle URLs — one for /users, another for /orders, and so on. It feels like each method is wired straight to the network. It isn't.

Behind the scenes, every incoming request for your app is first handed to a single Java object. That object reads the request, works out which of your methods should answer it, calls that method, and turns whatever it returns into a response. That one object is the DispatcherServlet, and it sits at the center of everything Spring MVC does.

To see why it exists — and what it actually does on each request — we have to start one level below Spring, with the plain Java technology it is built on.

The Servlet: Java's original web building block

Long before Spring, Java already had a standard way to answer web requests: the Servlet. A servlet is just a Java class that receives an HTTP request and writes an HTTP response. That is the whole idea.

Here is the shape of one:

public class HelloServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws IOException {
        resp.setContentType("text/plain");
        resp.getWriter().write("Hello, world");
    }
}

doGet runs when a GET request arrives. The req object hands you everything about the incoming request — the path, the headers, the query parameters. The resp object is where you write what goes back. That is genuinely all a servlet is.

But a servlet cannot run on its own. Something has to listen on the network port, accept the raw bytes of a connection, parse them into that tidy HttpServletRequest, and then decide which servlet to hand it to. That something is the servlet container — a program (Tomcat is the usual one) that owns the HTTP socket, manages a pool of threads, and controls the lifecycle of your servlets. You write servlets; the container runs them and feeds them requests.

How the container knows which servlet to call

A container can hold many servlets, so it needs a rule for matching a URL to one of them. That rule is a servlet mapping — a pattern that says "requests to this path go to that servlet."

@WebServlet("/hello")
public class HelloServlet extends HttpServlet { /* ... */ }

Here the mapping is /hello. A request to /hello lands in this servlet's doGet; a request to /goodbye does not. The container keeps a little table of these patterns and consults it for every request.

This works, and for one or two endpoints it is fine. The trouble starts when the app grows.

Why raw servlets stop scaling

Picture a real application: users, orders, invoices, search, each with several operations. With plain servlets, every distinct piece of behavior tends to become its own servlet with its own mapping. You accumulate dozens of them.

Worse, each one repeats the same chores. Read the request body and parse the JSON. Validate the fields. Catch exceptions and turn them into a sensible error response. Set the right content type. None of that is your actual business logic, yet it gets copied into servlet after servlet.

And the routing is rigid. The mapping table lives in the container's configuration, wired up before your logic ever runs. There is no single place where a request first lands — no natural spot to add a behavior that should apply to every request, like logging or a security check.

What you really want is one servlet that catches everything, does the shared chores once, and then routes each request to the right small piece of your code. That idea has a name.

The front controller idea

A front controller is a single entry point that receives every request for an application, performs the common work in one place, and then delegates to whichever component actually handles that specific request.

Instead of the container knowing about your /users and /orders logic directly, it knows about exactly one servlet. That servlet becomes the front door. Everything comes through it, and it decides where each request goes next.

This is not a Spring invention — it is a classic pattern. But Spring MVC's entire design rests on it, and Spring ships a ready-made front controller so you never write one yourself.

DispatcherServlet: Spring's front controller

The DispatcherServlet is that front controller, implemented as an ordinary servlet. When you use Spring MVC, Spring registers this one servlet with the container and maps it to a broad pattern — typically /, meaning "send me everything."

You do not write it or wire it up by hand. In a Spring Boot app it is registered automatically at startup. The mapping looks, conceptually, like this:

// You never write this — Spring Boot does it for you at startup.
// One servlet, mapped to "/", catches every request into the app.
registration.addServlet("dispatcherServlet", new DispatcherServlet(context));
registration.addMapping("/");

The important shift: the servlet container now has essentially one servlet to think about. Every request funnels into the DispatcherServlet, and from there Spring — not the container — decides what happens.

But if there is only one servlet, how does a request to /users reach a different method than a request to /orders? That routing has moved inside Spring, and it needs a few helpers to do the job.

The pieces the DispatcherServlet delegates to

The DispatcherServlet does not contain your endpoint logic, and it does not hard-code the routing rules either. It orchestrates. To do that, it leans on a small set of collaborators, each with one responsibility:

A handler is the specific piece of your code that answers one kind of request — in practice, one of your controller methods. "Handler" is just the general word for "the thing that handles this request."
A handler mapping answers the question "given this request, which handler should run?" It holds the routing knowledge that used to live in the container's config.
A handler adapter knows how to actually invoke a given handler — how to call it and collect its result. Different styles of handler need different adapters, so this indirection keeps the DispatcherServlet from caring about the details.
A view resolver comes in when a handler returns the name of a page to render rather than raw data; it turns that name into something that can produce the final HTML.

Each of these is a Spring bean — an object Spring creates and manages inside its application context — so the DispatcherServlet simply asks the context for them. Hold these four names loosely for now; the next lessons take the mapping and adapter apart in detail. Here we just need to watch them cooperate.

Walking one request through the DispatcherServlet

Now we can trace what happens the moment a request arrives. Say a browser sends GET /users/42.

First, the container hands it over. Tomcat accepts the connection, parses the bytes into an HttpServletRequest, sees that /users/42 matches the / mapping, and calls the DispatcherServlet — exactly like calling doGet on any servlet.

Second, the DispatcherServlet asks: who handles this? It walks through its handler mappings, passing them the request, until one reports a match:

// Conceptually, inside the DispatcherServlet:
HandlerExecutionChain chain = null;
for (HandlerMapping mapping : this.handlerMappings) {
    chain = mapping.getHandler(request);   // "do you own /users/42?"
    if (chain != null) break;              // first match wins
}

The result is the handler for /users/42 — your controller method — bundled with any interceptors that should run around it. If no mapping claims the request, this is the exact point where you get the familiar 404.

Third, it finds the right way to call that handler. The DispatcherServlet does not call your method directly. It looks for a handler adapter that understands this handler type:

// Pick the adapter that knows how to invoke this particular handler.
HandlerAdapter adapter = getHandlerAdapter(chain.getHandler());

Fourth, the adapter invokes your code. The adapter reads the request, prepares whatever your method needs as arguments, calls it, and captures what it returns. Your controller method finally runs here — this is the one moment your own logic executes.

Fifth, the DispatcherServlet handles the result. What comes back is normalized into a single result object the DispatcherServlet knows how to process:

ModelAndView mv = adapter.handle(request, response, chain.getHandler());

If your handler produced data to send straight back (the typical REST case), the response has effectively already been written and the DispatcherServlet is nearly done. If instead it returned the name of a page, the DispatcherServlet calls a view resolver to turn that name into a renderable view and asks it to write the HTML into the response.

Finally, the response goes back down. The finished HttpServletResponse returns to the container, which serializes it onto the socket and back to the browser. The DispatcherServlet's work for this request is over — until the next one arrives and the whole cycle repeats.

Why this shape is worth the indirection

Notice what the single front door buys you. Because every request passes through the DispatcherServlet before reaching any handler, there is now one obvious place to attach behavior that should apply to all of them — request logging, timing, security checks. You add it once, not in fifty servlets.

And because the DispatcherServlet only orchestrates — delegating the "which handler" question to mappings and the "how to call it" question to adapters — your controller code stays clean. You write a method that takes an id and returns a user. You never touch the socket, the thread, the parsing, or the routing table. All of that lives in machinery you did not have to build.

A couple of traps the design creates

The single-servlet setup has sharp edges worth knowing.

The first is a mapping surprise. Because the DispatcherServlet is mapped to /, it wants to handle everything, including requests for static files like /style.css. Spring has sensible defaults for serving static resources, but when a URL unexpectedly returns a 404 or the wrong content, the cause is often a collision between your handler mappings and static-resource handling — both living under that one broad mapping.

The second is about threads. The container runs each request on a thread from its pool, and the same DispatcherServlet instance serves them all at once. That is fine, because the DispatcherServlet holds no per-request state. But it means anything you hang onto across a request — a field on a shared bean, a ThreadLocal you forget to clear — is shared across concurrent requests too. The front controller is a single object handling many requests in parallel, and code downstream of it has to respect that.

Where this leaves us

So the picture is this: the servlet container owns the network and hands each request to one servlet. That servlet is the DispatcherServlet — Spring's front controller — and it does not answer requests itself. It asks a handler mapping which piece of your code should run, asks a handler adapter how to run it, lets your controller method do the real work, and then turns the result into a response.

We deliberately kept the mapping and the adapter at arm's length here, treating them as helpers that just "know" the answer. That is exactly where the next step goes: how a handler mapping actually decides that /users/42 belongs to your method, and how the adapter builds the arguments to call it — the request lifecycle, one stage at a time.

Recap — M2 Boot

Ankit Verma — Sun, 13 Sep 2026 09:40:22 +0000

What this module was really about

Plain Spring hands you a powerful toolbox and then asks you to assemble the workshop yourself. You pick the libraries, wire the objects together, point them at a database, choose a web server, and write the glue that starts it all. It works, but the first hour of any new project is spent on plumbing you've written a dozen times before.

Spring Boot is the layer that does that plumbing for you. It looks at what libraries you've added, guesses a sensible setup, and steps aside the moment you want to decide something yourself. Everything in module M2 was a different angle on that one promise. This recap ties the ten topics back into the single story they were always telling.

The one sentence that holds it all together

Here is the mental model to keep:

What's on your classpath, plus the settings you provide, flows through a set of conditions that decide which pre-written configuration Boot applies — and you can override any of it.

Read that again, because every topic in this module is one clause of it. Starters put things on the classpath. Externalized config supplies the settings. Conditional annotations are the conditions. Auto-configuration is the pre-written configuration. SpringApplication.run is what sets the whole flow in motion. Actuator lets you watch the result. The jar is how you ship it.

Let's walk that sentence from left to right.

Starters: how things get onto the classpath

A starter is a dependency that pulls in other dependencies. It contains almost no code of its own — it's a curated shopping list. Adding one line:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

quietly brings in Spring MVC, an embedded Tomcat, and the Jackson JSON library, all at versions known to work together. You asked for "web" and got a matched set instead of hunting down five compatible version numbers yourself.

The key thing to remember: a starter's real job is to change what's on your classpath. That matters because the classpath is the signal everything downstream reads. Which brings us to the next clause.

Conditional annotations: the "if" behind every decision

Boot ships hundreds of small configuration classes, but it doesn't blindly apply them. Each one is guarded by a condition — a rule that says "only do this if something is true."

@Configuration
@ConditionalOnClass(DataSource.class)
@ConditionalOnMissingBean(DataSource.class)
public class DataSourceAutoConfiguration {
    // configure a connection pool — but only if the conditions pass
}

Read the two guards in plain English. @ConditionalOnClass means "only if the DataSource type is on the classpath" — i.e. only if you added a database starter. @ConditionalOnMissingBean means "only if you haven't already defined a DataSource yourself."

Those two annotations together are the whole personality of Boot. It configures things because a starter put the class there, and it backs off the instant you take over. That is what people mean when they call Boot "opinionated but polite." Hold onto this — it explains the next clause completely.

Auto-configuration: the pre-written setup that reads those conditions

Auto-configuration is the pile of guarded @Configuration classes we just met. At startup Boot gathers a long list of them and offers each one to the conditions. The ones whose conditions pass contribute beans; the rest silently do nothing.

Where does the list come from? Boot reads a plain text file baked into the library jars:

```plain text
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports





Each line is the name of one auto-configuration class. (Older Boot used `spring.factories` for the same job — same idea, different filename.) There's no magic scanning of your code and no reflection guesswork: it's a list in a file, filtered by conditions.


**The key thing to remember:** auto-configuration is not "Boot being clever." It's a fixed list of candidate configs, each one asking "do my conditions hold?" If you ever wonder _why_ a bean appeared, the honest answer is always "a class on that list had all its conditions satisfied."


## Externalized config: the settings that feed the machine


Auto-configuration still needs values — a port, a database URL, a pool size. Those live _outside_ your compiled code, in **externalized configuration**: `application.properties` or `application.yml`, environment variables, command-line arguments, and more.


The important part is **order**. When the same key is set in two places, the higher-precedence source wins. Roughly, from strongest to weakest:

- Command-line arguments (`--server.port=9000`)
- OS environment variables
- `application.properties` inside your jar

So a value baked into your jar is a _default_, and an environment variable at deploy time quietly overrides it — no rebuild required. That single rule is why the same jar can run unchanged on a laptop and in production.


## Binding: turning flat keys into real objects


Loose key–value pairs are awkward to use in code, so Boot **binds** them onto Java objects. There are two ways in.


**`@Value`** injects one key into one field:




```java
@Value("${server.port}")
private int port;

Fine for a stray value, clumsy once you have a dozen related settings.

@ConfigurationProperties binds a whole group onto a typed object:

@ConfigurationProperties(prefix = "app.mail")
public class MailProperties {
    private String host;
    private int port;
    // getters and setters
}

Now every app.mail.* key lands on a field automatically. And because of relaxed binding, Boot treats app.mail.host, APP_MAIL_HOST, and app.mail.HOST as the same property — so a kebab-case file and an UPPER_SNAKE environment variable both fill the same field. That's the quiet reason your properties file and your Docker environment variables agree without you doing anything.

Remember it as: @Value for one loose value, @ConfigurationProperties for a family of related ones.

Profiles: swapping settings per environment

You rarely want one set of settings everywhere. A profile is a named bundle of configuration that's only active when you switch it on.

Put shared settings in application.properties, and environment-specific ones in application-dev.properties or application-prod.properties. Activate one with a property:

```plain text
spring.profiles.active=prod





Boot layers the profile-specific file on top of the base file. You can also gate a whole bean on a profile:




```java
@Bean
@Profile("prod")
public MeterRegistry realMetrics() { ... }

The key thing to remember: profiles are how one build carries every environment's config and picks the right slice at launch — the natural partner to the precedence order from earlier.

Starting it all: the run() method

Everything above is potential energy until one line fires it:

@SpringBootApplication
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

@SpringBootApplication is three annotations in one: it enables component scanning, marks the class as a config source, and — crucially — switches on auto-configuration. Then run does the work in order: it reads your externalized config, creates the application context (the container that holds your beans), lets auto-configuration and your own components populate it, and — for a web app — starts an embedded Tomcat inside the same process.

That embedded server is the mental shift from old Spring. There's no external server to install and deploy into; the web server is just another bean Boot started for you. Your application is the server.

Actuator: watching the thing once it runs

A running app you can't see inside is a liability. Actuator is a starter that adds ready-made HTTP endpoints reporting on the live application.

```plain text
GET /actuator/health -> {"status":"UP"}
GET /actuator/metrics -> memory, request timings, pool usage
GET /actuator/info -> build version, git commit, whatever you add





`/health` is what a load balancer or Kubernetes probe pings to decide if traffic should reach you. `/metrics` is what a monitoring system scrapes. Notice the pattern holding again: you _added a starter_, a _condition_ saw Actuator on the classpath, and _auto-configuration_ wired the endpoints. Same story, one more time.


## Packaging: the fat jar, the layered jar, and DevTools


Finally you ship it. Boot builds a **fat jar** (also called an uber jar): a single `.jar` containing your code, every dependency, _and_ the embedded server. One file runs anywhere a JVM exists:




```bash
java -jar app.jar

No server to pre-install, no unpacking — the artifact is the whole application.

A layered jar is that same fat jar organized into layers by how often they change — dependencies in one layer, your code in another. Docker caches unchanged layers, so rebuilding after a one-line code change re-ships only your thin top layer instead of hundreds of megabytes of libraries.

And DevTools is a development-only helper that restarts the app automatically when it sees a class change, so you skip the manual stop-and-start loop. It disables itself in production, so it never ships with the fat jar.

Putting the whole sentence back together

Trace one request through the story and the module clicks into a single line:

A starter puts classes on the classpath.
Conditional annotations read that classpath — and your existing beans — and decide what applies.
Auto-configuration contributes the beans whose conditions passed.
Externalized config, bound by @ConfigurationProperties and sliced by profiles, supplies the settings those beans need.
SpringApplication.run builds the context and starts embedded Tomcat.
Actuator reports on the running result.
A fat or layered jar ships it, with DevTools smoothing the ride while you build.

If you remember nothing else from M2, remember this: Boot is a chain of sensible defaults, each one guarded by a condition and open to your override. Once that clicks, none of its behavior looks like magic — it looks like a list being filtered by what you asked for. That is exactly the footing you want before stepping into the web layer next.

Fat jar vs layered jar; DevTools

Ankit Verma — Sat, 12 Sep 2026 08:45:30 +0000

Why your Spring Boot app is one runnable file

You finish a Spring Boot service, run a single command, and a full web server starts up:

java -jar app.jar

No Tomcat to install first. No classpath to spell out by hand. No WEB-INF folder dropped into a separate application server. One file, one command, a running app that answers HTTP on a port.

That single file is what this article is about. We will open it up and see what is inside, understand why it is built that way, and then look at the two packaging choices that decide how it runs and how quickly it ships: the fat jar and the layered jar. At the end we meet DevTools, the piece that keeps the write-code-and-see-it loop fast while you are still building.

Start with a plain question: why can't an ordinary jar already do this?

The problem: a jar cannot hold other jars

A normal Java application is not one jar. It is your code plus every library it depends on — often dozens of jars. To run it, you list all of them on the classpath:

java -cp app.jar:lib/jackson.jar:lib/tomcat.jar:... com.example.App

That is fragile. You have to ship a folder of jars alongside your own, and get the whole list right every time.

The obvious wish is to put everything into one jar. But standard Java has a hard limit here: the classpath cannot see a jar nested inside another jar. Java's built-in class loading knows how to read .class files from inside a jar, and it knows how to read a jar sitting on the filesystem — but it does not know how to reach into app.jar, find jackson.jar inside it, and load classes out of that. Nested jars are invisible to it.

So "just one file" is not something plain Java hands you. Something has to make it work. That something is the Spring Boot build plugin.

Inside the fat jar

When you run mvn package (or the Gradle equivalent), the Spring Boot plugin does an extra step called repackaging. It takes the plain jar your compiler produced and rebuilds it into an executable jar — the thing people casually call a fat jar, because it is fat with all its dependencies inside.

Peek inside one and the layout is deliberate:

```plain text
app.jar
├── META-INF/
│ └── MANIFEST.MF
├── org/springframework/boot/loader/ ← Spring's own loader classes
├── BOOT-INF/
│ ├── classes/ ← your compiled code
│ └── lib/ ← every dependency, as nested jars





Three things share the file. Your own classes live under **`BOOT-INF/classes`**. Every library you depend on sits as an untouched jar under **`BOOT-INF/lib`**. And at the root sits a small set of Spring's own classes — the loader.


Notice what Spring did _not_ do. It did not melt all the libraries down and pour their `.class` files into one flat pile. The older "uber jar" approach did exactly that, and it caused real pain: two libraries shipping a file at the same path would silently overwrite each other, and once unpacked you could no longer tell which library a class came from. Spring keeps each dependency as its own intact jar. Cleaner — but now we are back to the nested-jar problem Java can't solve on its own. That is what the loader classes are for.


## The launcher that boots the jar


Open the manifest and you see the trick:




```plain text
Main-Class:  org.springframework.boot.loader.launch.JarLauncher
Start-Class: com.example.MyApplication

When you type java -jar app.jar, the JVM runs whatever Main-Class names. That is not your application. It is Spring's JarLauncher, the entry point that knows how to handle the nested layout.

The launcher does two jobs. First it installs a custom classloader — a small piece of Spring code that does know how to read a jar-inside-a-jar, reaching into BOOT-INF/lib to load classes straight out of those nested jars. Then it reads Start-Class from the manifest, which points at your real application, and hands control over to your main method — now running with a classloader that can see everything.

So the boot sequence is: JVM starts the launcher → launcher builds a classloader that can read nested jars → launcher calls your main. From your code's point of view, every dependency is simply on the classpath and life is normal. The launcher quietly bridged the gap that plain Java left open.

That is the whole fat jar story. It is a brilliant way to run an app. The trouble starts when you want to ship one.

Why one big jar is slow to ship

Most Spring Boot apps run in a Docker image these days. A Docker image is built in layers — stacked, read-only slices of a filesystem. The reason layers exist is caching: when you rebuild an image, Docker reuses any layer whose inputs did not change and only rebuilds the ones that did. Unchanged layers are also skipped when pushing and pulling, so a rebuild that touches one small layer ships almost nothing.

Now picture the naive Dockerfile:

FROM eclipse-temurin:21-jre
COPY app.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

The whole fat jar is copied in as a single layer. And here is the sting: your 30 MB of dependencies and your 200 KB of code are fused into that one file. Change a single line in a controller, rebuild, and because the file's bytes changed, Docker throws away the cached layer and re-ships the entire 30 MB — even though the dependencies did not move an inch.

The costs are lopsided. Dependencies are large and rarely change. Your code is tiny and changes constantly. Baking them into one layer means every code change pays the full weight of the dependencies. We want the opposite: the things that rarely change in their own layer, and the things that change often in another.

The layered jar

This is exactly what a layered jar gives you. Since Spring Boot 2.3, the repackaged jar can carry an index file, BOOT-INF/layers.idx, that sorts its contents into named layers, ordered from least likely to change to most likely:

```plain text

dependencies ← released third-party libraries
spring-boot-loader ← Spring's loader classes
snapshot-dependencies ← -SNAPSHOT libraries (change more often)
application ← your classes and resources ```

The ordering is the whole point. Your dependencies almost never change between builds, so that layer stays cached for weeks. Your application code changes every commit, so only that thin layer is rebuilt and re-shipped.

To use the layers you first pull them out of the jar. The jar can unpack itself:

java -Djarmode=layertools -jar app.jar extract

That produces one folder per layer — dependencies/, spring-boot-loader/, snapshot-dependencies/, application/ — each holding just its slice of the original jar.

A Dockerfile that respects the layers

Now the layers map cleanly onto Docker's caching. The trick is a multi-stage build: one stage extracts the layers, and a second stage copies them in — one COPY per layer, in change-frequency order.

# Stage 1: extract the layers from the fat jar
FROM eclipse-temurin:21-jre AS builder
WORKDIR /app
COPY app.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract

# Stage 2: assemble the image, layer by layer
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /app/dependencies/ ./
COPY --from=builder /app/spring-boot-loader/ ./
COPY --from=builder /app/snapshot-dependencies/ ./
COPY --from=builder /app/application/ ./
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

Each COPY becomes its own Docker layer. Because dependencies is copied before application, a code-only change invalidates only the last COPY — Docker reuses the cached dependency layer and rebuilds just the tiny application layer. The 30 MB stays put; only your 200 KB moves.

Notice the entry point is JarLauncher again — the same launcher from the fat jar. Even unpacked across folders, Spring still uses its loader to start your app. The layered jar did not change how the app runs; it only reorganised how it is stored so Docker can cache it well.

That covers building and shipping. The last piece is the loop you live in while writing the code in the first place.

DevTools: a faster inner loop

Restarting an app by hand after every change is the slow tax of development: save a file, stop the app, run it again, wait for Spring to start, click back to where you were. The dependency spring-boot-devtools exists to shrink that loop.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-devtools</artifactId>
  <optional>true</optional>
</dependency>

With DevTools on the classpath, Spring watches your project's files. The moment your IDE recompiles a class, DevTools notices and automatically restarts the application. You save; a second later the running app already reflects the change. No manual stop-and-start.

The natural worry is: isn't restarting the whole app still slow? It would be — if DevTools did a cold restart. It does not, and the reason is clever.

Two classloaders make the restart quick

DevTools splits your app's classes across two classloaders. The base classloader loads the things that do not change while you work — the third-party libraries from your dependencies. The restart classloader loads the code you are actively editing — your own project classes.

When a file changes, DevTools throws away only the restart classloader and builds a fresh one, reloading just your classes. The base classloader — holding all the heavy libraries — is left untouched, and the JVM itself never stops.

That is why a DevTools restart feels near-instant while a cold start takes several seconds. A cold start reloads everything: the JVM boots, every library class is read and verified again from scratch. DevTools reloads only the small, changing half and keeps the expensive, stable half warm in memory. Same fresh application state, a fraction of the work.

The rest of the loop: caches off, browser refresh

DevTools smooths two more rough edges.

By default it overrides caching properties that make sense in production but get in your way during development. Template engines like Thymeleaf normally cache compiled templates; DevTools switches that caching off so a tweak to an HTML template shows up on the next request without even a restart.

It also runs a LiveReload server. Paired with a small browser extension, it refreshes the page in your browser automatically the instant the app restarts — so you are not even reaching for the reload button.

Why none of this reaches production

All of that convenience raises an obvious flag: you would never want auto-restart or disabled caches on a live server. DevTools handles this for you, on two levels.

First, it disables itself when it detects the app is running as a fully packaged jar — the java -jar app.jar path a real deployment uses. DevTools is active when you run from your IDE or the build tool, and dormant when it sees it is running from a packaged archive.

Second, the repackaging step strips DevTools out of the fat jar entirely, because you declared it optional. So the dependency is present while you develop and simply absent from the artifact you ship. The fast inner loop is a development-only tool, by design.

The one connected picture

Three ideas, one line of reasoning. The fat jar solves running: Spring's launcher and its custom classloader let a single file carry every nested dependency, so java -jar just works. The layered jar solves shipping: the same jar is sorted into layers by how often each part changes, so Docker caches the heavy, stable dependencies and re-ships only your thin, fast-moving code. And DevTools solves developing: two classloaders keep restarts near-instant, caches step out of your way, and the whole thing removes itself before it ever reaches production.

Build fat so it runs anywhere; layer it so it ships cheaply; lean on DevTools so getting there is quick.

Actuator: health / metrics / info

Ankit Verma — Fri, 11 Sep 2026 09:01:53 +0000

A running app is a black box

Once your Spring Boot app leaves your laptop and lands on a server, it becomes a process you can't see into. From the outside, you can't tell whether it's healthy, how much memory it's burning, or even which build of the code is actually running. Then something breaks at 3 a.m., someone needs answers fast, and SSH-ing onto the box to poke around is slow and risky.

Spring Boot Actuator is the module that fixes this. It bolts a set of ready-made operational features onto your app — standard ways to inspect and monitor it while it runs — and serves them over HTTP so that tools and humans can ask the app about itself. You write none of it. You add one dependency, and the features appear.

You meet Actuator the day your app goes to production: the load balancer needs a health check, the dashboards need metrics, and the on-call engineer needs to know what version is live. This article walks the three endpoints you'll reach for first — health, metrics, and info — and finishes with how to expose them without handing the world a window into your app.

Turning it on

Everything starts with one starter dependency:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Boot's auto-configuration notices the starter on the classpath and wires everything up for you — no @Bean definitions, no config class. Each operational feature it registers is called an endpoint: a small, named unit of functionality (like health or metrics) that you can reach at a URL under a common base path, /actuator.

Two separate switches govern every endpoint, and mixing them up is a classic source of confusion. An endpoint is enabled (it exists and does its work) and, separately, exposed (it's reachable over HTTP). Most endpoints are enabled by default, but for safety Boot only exposes health over HTTP out of the box. We'll open up the others deliberately at the end.

With the starter added, hit the base path and the app lists what's on offer:

GET /actuator

Now let's walk the three you'll use daily.

Health: is the app OK?

The health endpoint answers the single most-asked question in operations: is this thing working?

GET /actuator/health

{ "status": "UP" }

That UP is not a guess. Actuator ships small probes called health indicators, and it auto-registers one for each piece of infrastructure it detects — a datasource, a message broker, disk space, and so on. Each indicator checks its own dependency and reports UP or DOWN. A database indicator, for example, runs a trivial validation query; if the query fails, that indicator goes DOWN.

The endpoint then aggregates all indicators into the one top-level status, and the rule is simple: the worst status wins. One DOWN indicator drags the whole app to DOWN, which is exactly what a load balancer wants — a mostly-working app that can't reach its database is not ready to serve traffic.

By default you only see the rolled-up status, not the per-indicator breakdown. To see the details, turn them on:

management:
  endpoint:
    health:
      show-details: always

Now the response names each contributor:

{
  "status": "UP",
  "components": {
    "db":        { "status": "UP" },
    "diskSpace": { "status": "UP" }
  }
}

When the built-in indicators aren't enough, you write your own by implementing the HealthIndicator interface. Say your service depends on an external payment gateway and you want its reachability reflected in your health:

@Component
public class PaymentGatewayHealth implements HealthIndicator {

    private final PaymentGatewayClient client;

    public PaymentGatewayHealth(PaymentGatewayClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        if (client.ping()) {
            return Health.up().withDetail("gateway", "reachable").build();
        }
        return Health.down().withDetail("gateway", "unreachable").build();
    }
}

Because it's a @Component, component scanning picks it up and Actuator folds it into the aggregate automatically. The bean name (paymentGatewayHealth → paymentGateway) becomes its key in the response.

Liveness and readiness

Under an orchestrator like Kubernetes, "is it OK?" splits into two genuinely different questions, and answering them with one signal causes real outages.

Liveness asks: is this app broken beyond repair? If the answer is no, restarting it is the fix. Readiness asks: can it take traffic right this second? An app can be perfectly alive yet not ready — still warming a cache, or briefly waiting on a dependency. The distinction matters because the wrong reaction is harmful: restart an app that's only temporarily not ready and you kill a healthy process; keep routing traffic to an app that's fatally broken and every request fails.

Actuator exposes these as health groups — named subsets of indicators — once you enable the probes:

management:
  endpoint:
    health:
      probes:
        enabled: true

You now get two extra URLs, /actuator/health/liveness and /actuator/health/readiness, each aggregating only its own group. You point Kubernetes' liveness probe at the first and its readiness probe at the second, and each gets the answer it should act on.

Metrics: how is it behaving?

Health is a yes/no. Metrics are the numbers over time — memory used, request latency, how many orders were placed. Actuator collects these through a library called Micrometer.

Micrometer is worth understanding for one reason: it's a facade. Just as SLF4J lets you write logging calls without committing to a specific logging backend, Micrometer lets your app record measurements without committing to a specific monitoring system. Your code talks to Micrometer; Micrometer ships the numbers to whatever registry you plug in — Prometheus, Datadog, CloudWatch. Swap the backend by swapping a dependency, not by rewriting your code.

The endpoint first lists the metric names it knows about:

GET /actuator/metrics

{ "names": ["jvm.memory.used", "http.server.requests", "system.cpu.usage", ...] }

To read one, drill into it by name:

GET /actuator/metrics/jvm.memory.used

The response carries the current measurement plus a list of tags — dimensions you can slice the number by. A single metric like http.server.requests is tagged with uri, method, and status, so instead of one blurry total you can ask a precise question:

GET /actuator/metrics/http.server.requests?tag=status:500

That returns only the requests that ended in a 500 — request counts and timings for your failing calls alone.

Recording your own metric means asking Micrometer's registry for a meter. A counter — a value that only ever goes up — is the simplest:

@Service
public class OrderService {

    private final Counter ordersPlaced;

    public OrderService(MeterRegistry registry) {
        this.ordersPlaced = registry.counter("orders.placed");
    }

    public void placeOrder(Order order) {
        // ... business logic ...
        ordersPlaced.increment();
    }
}

MeterRegistry is a bean Actuator has already put in the context, so you just inject it. Now orders.placed shows up alongside the built-in metrics, sliceable and shippable like the rest.

In practice you rarely poll /actuator/metrics by hand. You add micrometer-registry-prometheus, which lights up a /actuator/prometheus endpoint, and a Prometheus server periodically scrapes that URL — pulls the current values on a schedule — into a time-series database your dashboards read from. Your app's only job is to expose the numbers; the monitoring stack does the collecting.

Info: what is this, exactly?

The info endpoint answers the on-call engineer's first question: what am I even looking at?

GET /actuator/info

Out of the box it returns {}, because info is assembled from info contributors, and none carry data until you give them some. The quickest is static properties — anything you nest under an info key in your configuration is surfaced verbatim:

info:
  app:
    name: Orders Service
    team: Payments

The more valuable contributors are generated at build time. Point the spring-boot-maven-plugin at its build-info goal and it writes the app's version and build timestamp into a file Actuator reads; add the git-commit-id plugin and the exact commit hash of the running code appears too. Now /actuator/info tells you precisely which build is live — no guessing whether the deploy actually went through.

Exposing endpoints — and the trap in doing it

Remember the enabled-versus-exposed split. Everything above is enabled, but over HTTP only health is exposed by default. To serve the others, list them explicitly:

management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus

It's tempting to write include: "*" and be done. Don't — that's the trap. Actuator ships more than the three friendly endpoints. env dumps your configuration (potentially including secrets), heapdump downloads a full memory snapshot, loggers lets a caller change log levels at runtime, shutdown can stop the app. Exposing all of that on a public port hands an attacker a detailed map of your system, and sometimes the keys.

Two defenses, ideally together. First, if the app already uses Spring Security, its filter chain protects the /actuator/** paths like any other URL — require an authenticated admin role to reach them. Second, move the whole management surface onto its own port:

management:
  server:
    port: 9001

Actuator endpoints now live on 9001 while your API stays on the main port. You firewall 9001 off from the public internet, so only your monitoring systems inside the network can reach it — the numbers flow to your dashboards, and no further.

Where this leads

Actuator turns the black box into something you can question while it runs: is it healthy (health), how is it behaving (metrics), and what is it (info) — with one dependency and a little safe configuration. That's the app observing itself once it's deployed. The natural next question is how the app gets packaged to be deployed in the first place — how Boot bundles everything into a runnable jar, and what a layered jar buys you — which is exactly where we go next.

SpringApplication.run boot flow + embedded Tomcat

Ankit Verma — Thu, 10 Sep 2026 09:04:13 +0000

Every Spring Boot application begins with the same unremarkable line. You have almost certainly typed it without thinking about it:

@SpringBootApplication
public class StoreApplication {
    public static void main(String[] args) {
        SpringApplication.run(StoreApplication.class, args);
    }
}

That single call is the startup. There is no application server to install first, no WAR file to deploy, no web.xml to configure. You run a plain Java main method, and a second or two later an HTTP server is listening on port 8080. This post is about what happens inside that second — the ordered sequence SpringApplication.run walks through, and exactly where the web server, running inside your own process, slots into it.

One word carries the whole story, so let me define it before using it. A container is just an object whose job is to create your other objects, hold them, wire them together, and manage their lifetimes. In Spring, the objects it manages are called beans — a bean is nothing more exotic than an object the container built and owns instead of you calling new yourself. The container is also called the application context. When you hear "context," picture that one big object holding every bean your app needs. Everything below is the story of how run builds that context and then hands control to it.

The one call, unpacked

SpringApplication.run(StoreApplication.class, args) is a static convenience method. Under the hood it does two separate things, and it helps to see them apart:

// what the static helper expands to
SpringApplication app = new SpringApplication(StoreApplication.class);
ConfigurableApplicationContext context = app.run(args);

First it constructs a SpringApplication object. Then it runs it. The constructor makes a few decisions up front; the run call executes the actual boot sequence. We will take them in that order.

Step 1 — the constructor decides what kind of app this is

Before any bean exists, the SpringApplication constructor asks one important question: what type of application am I? It answers by looking at what is on the classpath — the set of libraries your build pulled in.

The result is a value called the WebApplicationType, and it has three possibilities:

SERVLET — a servlet-based web class (Spring MVC's DispatcherServlet) is on the classpath, so this is a traditional web app. This is the common case.
REACTIVE — only the WebFlux reactive stack is present, no servlet stack.
NONE — no web libraries at all, so this is a plain application that will run some logic and exit.

Nobody sets this flag by hand. The presence of spring-boot-starter-web in your build is what makes it SERVLET. This detection matters enormously, because it decides which context to build in Step 3 and whether a web server starts at all. A batch job with no web starter gets NONE, boots the same way, runs its work, and shuts down — no port is ever opened.

The constructor also loads a couple of lists of helper objects (initializers and listeners) from configuration files bundled in the Spring jars, but you can treat those as pre-wiring for now. The headline decision is the application type.

Step 2 — preparing the environment

Now run(args) begins in earnest. Its first real job is to assemble the environment — the merged bag of all configuration values your app can read.

ConfigurableEnvironment environment = prepareEnvironment(listeners, args);

The environment gathers your application.properties (or .yml), OS environment variables, command-line arguments, and any active profiles — a profile being just a named set of config, like dev or prod, that you switch on to change behavior per deployment. This all happens before any of your beans are created, and that ordering is deliberate: beans frequently need config values (a database URL, a port) at the moment they are built, so the config must already be resolved and waiting.

This is also the point where Boot prints that ASCII banner. Small thing, but it marks the boundary: environment ready, context not yet built.

Step 3 — creating the right kind of context

With the application type known and the environment ready, run creates the context object itself:

context = createApplicationContext();  // picks a class based on WebApplicationType

Here is where the Step 1 decision pays off. For a SERVLET app, Boot instantiates a context class whose full name is a mouthful — AnnotationConfigServletWebServerApplicationContext — but whose meaning is simple: a container that also knows how to run an embedded servlet web server. For a NONE app it picks a plain context with no web machinery at all.

At this moment the context is an empty shell. It knows how to hold beans and how to start a web server, but it contains no beans and has started nothing. Filling it is the next, and biggest, step.

Step 4 — refresh, where the beans actually come alive

The heart of the whole boot is a single method call:

refreshContext(context);   // -> context.refresh()

Refresh is the Spring lifecycle step that turns the empty shell into a fully wired, running application. It is worth knowing the sub-steps it runs, in order, because the web server appears in the middle of them:

Read all bean definitions. The context scans your packages for @Component, @Service, @Controller and friends, and processes every @Configuration class. Crucially, this is where auto-configuration runs — Boot's mechanism that inspects the classpath and registers sensible default beans (a DataSource if a JDBC driver is present, a JSON converter if Jackson is present, and so on). After this step the context has a full catalogue of beans, but has not built most of them yet.
onRefresh() — a hook the servlet context overrides to create the embedded web server. More on this in a moment; this is the key line for our topic.
Instantiate the singletons. The context now actually builds every non-lazy singleton bean and injects their dependencies. Your services, repositories, and controllers become live objects here.
finishRefresh() — the final step, which starts the web server accepting traffic.

Notice the shape: the server is created in step 2 but only opened to traffic in step 4, with all your beans instantiated in between. That gap is not an accident, and we will see why it is exactly right.

Where the embedded server comes in

Let me define embedded plainly, because it is the whole trick. Traditionally you built a WAR file and deployed it into a separately installed Tomcat. Spring Boot inverts that: Tomcat is just a library on your classpath, and Boot starts it from inside your application as an ordinary object. The server runs in your process; your process is not deployed into the server. That is what "embedded" means — the server is embedded in your app, not the other way around.

So how does onRefresh() create it? It looks in the context for a special bean: a ServletWebServerFactory. Auto-configuration will have registered one based on the classpath — TomcatServletWebServerFactory when Tomcat is present (the default), or a Jetty or Undertow variant if you swapped the dependency. The context asks that factory to produce a running server:

// inside the servlet context's createWebServer(), simplified
ServletWebServerFactory factory = getWebServerFactory(); // e.g. Tomcat
this.webServer = factory.getWebServer(getSelfInitializer());

The factory is a bean whose only job is to build and configure a web server. getWebServer(...) constructs the Tomcat instance, applies your settings (port, context path, thread pool), and returns it. Because the factory is an ordinary bean, customizing the server is just a matter of configuration or a bean — no server-install step anywhere:

@Bean
WebServerFactoryCustomizer<TomcatServletWebServerFactory> tuning() {
    return factory -> {
        factory.setPort(9090);
        factory.addConnectorCustomizers(connector ->
            connector.setProperty("maxThreads", "400"));
    };
}

That is the entire reason a Spring Boot fat jar can be launched with java -jar app.jar and just work. The server is a dependency packaged inside the jar, started by your own code. There is no external runtime to match versions with, and the same jar runs identically on your laptop and in a container.

The port opens last — and why that ordering matters

Recall the gap from Step 4: the server is created in onRefresh() but does not accept requests yet. Opening the port is deferred to finishRefresh(), which runs only after every singleton bean has been instantiated.

This ordering is a quiet piece of correctness. If Tomcat began accepting connections the instant it was created, requests could arrive while your services and database connections were still being wired — and hit half-built beans. By holding the connectors closed until the context is fully initialized, Boot guarantees that the first request only lands on a completely assembled application. The port opening is the signal that the app is ready to serve.

There is one genuine trap hiding here, though. After refresh returns — port already open — run does two more things:

callRunners(context, args);          // your ApplicationRunner / CommandLineRunner beans
listeners.ready(context, ...);       // publishes ApplicationReadyEvent

A CommandLineRunner is a bean whose code runs once at startup, right after the context is ready — handy for warming a cache or seeding data:

@Component
class WarmupRunner implements CommandLineRunner {
    public void run(String... args) {
        cache.preload();   // careful: the port is ALREADY open here
    }
}

Because runners execute after finishRefresh has opened the port, Tomcat is already accepting traffic while your runner is still working. A slow runner means real requests can arrive before its warm-up finishes. If a task must complete before any request is served, a CommandLineRunner is the wrong place for it — do that work inside a bean's initialization instead, which happens back in step 3, before the port opens.

A few gotchas worth carrying

The port is already taken. If something else holds 8080, the server fails during finishRefresh and the whole boot aborts with Port 8080 was already in use. Startup is all-or-nothing: a web server that cannot bind is treated as a failed application, not a warning.

A web app that exits immediately. If you expected a running server but the process starts and stops, the usual cause is a missing spring-boot-starter-web — the constructor deduced WebApplicationType.NONE, so no server was ever created. The fix is a dependency, not code.

Graceful shutdown. The server that run started is a managed bean, so it participates in shutdown too. Enabling graceful shutdown lets in-flight requests finish before the process dies, instead of being cut off:

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s

The whole flow in one breath

SpringApplication.run constructs an application object that inspects the classpath to decide it is a servlet web app; prepares the environment so config is ready before any bean; creates a servlet-aware context; and then refreshes it. Refresh reads every bean definition (auto-configuration included), asks a factory bean to create an embedded Tomcat, instantiates all your singletons, and finally opens the port so the first request meets a fully assembled app. Runners fire last, after traffic is already flowing.

Once you can see those phases, "embedded Tomcat" stops being magic. It is just a library, started as a bean, at a carefully chosen point in an ordered sequence — and the fat jar that runs anywhere is the natural consequence of the server living inside your app instead of your app living inside a server.

Profiles

Ankit Verma — Wed, 09 Sep 2026 09:05:12 +0000

The problem profiles solve

Your application runs in more than one place. It runs on your laptop while you build it. It runs on a continuous-integration server that executes the tests. It runs in staging, where the team clicks around before a release. And it runs in production, serving real users.

The code is identical in all four. What changes is the configuration around it: the database it points at, how much it logs, which external services are real versus faked. On your laptop the database might be a throwaway one that lives in memory. In production it is a real, carefully guarded server.

So you need one build that behaves differently depending on where it wakes up. That is exactly what a profile is: a named set of configuration that Spring switches on or off as a group. Name the group dev, prod, or test; turn one on; the pieces tagged with that name come alive, and the rest stay dormant.

First, where configuration lives

Before profiles make sense, one Spring idea has to be clear: the container.

When a Spring application starts, it builds a big registry of the objects your app is made of — the object that talks to the database, the one that handles web requests, the one that sends email. Spring creates them, wires them together, and hands them out wherever they are needed. Each managed object is a bean, and the registry that holds them is the container.

Here is the key part: the container is assembled once, at startup. Spring decides which beans to create, and how to configure them, in those first moments — before a single request is served.

Profiles hook into exactly that decision. A profile can change which beans get created, and it can change the values they are configured with. Let's take those one at a time.

Tagging a bean with a profile

Say you want an in-memory database on your laptop but the real one in production. You describe both, and mark each with the environment it belongs to.

@Configuration
public class DataSourceConfig {

    @Bean
    @Profile("dev")
    public DataSource devDataSource() {
        // an in-memory database, wiped on every restart
        return new EmbeddedDatabaseBuilder()
                .setType(EmbeddedDatabaseType.H2)
                .build();
    }

    @Bean
    @Profile("prod")
    public DataSource prodDataSource() {
        // the real, persistent database
        HikariDataSource ds = new HikariDataSource();
        ds.setJdbcUrl("jdbc:postgresql://db.internal:5432/orders");
        return ds;
    }
}

Two annotations do the work. @Bean marks a method whose return value becomes a bean in the container. @Profile("dev") attaches a condition to it: only register this bean when the dev profile is active.

So on your laptop with dev active, the container builds the in-memory database and never even looks at the production one. Flip to prod and the opposite happens.

Notice what the rest of the app sees. Both methods produce a DataSource. The code that needs a database just asks for a DataSource and gets whichever one this environment built. The switch is invisible to everything downstream — which raises the obvious question: how does Spring know which profile is active?

Turning a profile on

A profile is just a string, and it stays inactive until something names it. That "something" is a property called spring.profiles.active.

You can set it several ways, and they all exist because the answer comes from a different place in each environment.

In a properties file bundled with the app:

spring.profiles.active=dev

As an environment variable, which is how a deployment platform usually does it:

export SPRING_PROFILES_ACTIVE=prod

Or on the command line when you launch the jar:

java -jar orders.jar --spring.profiles.active=prod

All three set the same underlying property. They differ only in who gets to decide, and a more specific source wins: the command line overrides the environment variable, which overrides the file baked into the jar. That ordering is what lets an ops team point the app at a different database without rebuilding anything.

You can also activate more than one profile at once, comma-separated:

spring.profiles.active=prod,metrics,cloud

Now three profiles are active together, and a bean tagged with any of them joins the container. This is how you compose a full environment out of smaller, reusable slices.

The property side: profile-specific files

Beans are one half of the story. The other half is plain configuration values — a URL, a timeout, a log level. For these, Spring Boot gives profiles a naming convention.

There is a base file, application.properties, that always loads. Next to it you place one file per profile: application-dev.properties, application-prod.properties, and so on.

# application.properties  (shared by everyone)
app.name=Orders Service
app.page-size=20

# application-dev.properties  (only when dev is active)
logging.level.root=DEBUG
app.page-size=5

# application-prod.properties  (only when prod is active)
logging.level.root=WARN

Spring loads the base file first, then the file for each active profile on top of it. A key that appears in a profile file overrides the same key in the base. A key that appears only in the base is left untouched.

So with dev active, app.name stays "Orders Service" from the base, logging.level.root becomes DEBUG, and app.page-size becomes 5 — the dev file won the last two. A profile file is an override layer, not a replacement. You keep the shared defaults in one place and state only the differences per environment.

(If you prefer YAML, the same idea lives in a single application.yml split into sections with ---, each tagged by spring.config.activate.on-profile. Same layering, one file.)

The default profile

What if nothing sets spring.profiles.active? No named profile is active — but configuration still has to come from somewhere. Spring covers this with the default profile.

Any bean or property file not tagged with a profile belongs to the default and is always in play. On top of that, there is a fallback profile literally named default, and it is active precisely when no other profile is. So application-default.properties loads only when you launched with nothing set — a handy spot for sensible local values that a real environment overrides.

This catches people out: a bean tagged @Profile("default") disappears the moment you activate any other profile, even an unrelated one. "default" means "when nothing else," not "always."

Profile expressions

Beyond a single name, @Profile understands a small expression language built from ! (not), & (and), and | (or).

@Bean
@Profile("!prod")
public EmailSender loggingEmailSender() {
    // writes the "email" to the log instead of sending it
    return new LoggingEmailSender();
}

Here !prod means "every environment except production." Dev and staging get the harmless logging sender; production gets the real one, defined elsewhere with @Profile("prod"). You can combine terms too: @Profile("prod & cloud") needs both active, @Profile("dev | test") needs either. This lets you express a real condition without inventing a brand-new profile name for every combination.

Profile groups

Long comma-separated lists get repetitive and easy to get wrong. Spring Boot lets you name a bundle once, as a profile group.

spring.profiles.group.prod=metrics,cloud,audit

Now activating prod automatically activates metrics, cloud, and audit as well. One switch, four profiles. Your deployment config stays a single meaningful name — spring.profiles.active=prod — while the composition it expands to lives in one readable line.

Profiles in tests

A test run is just another environment, and it gets first-class support through @ActiveProfiles.

@SpringBootTest
@ActiveProfiles("test")
class OrderServiceTest {
    // the container here is built with the "test" profile active
}

The container for this test is assembled with test active, so application-test.properties and any @Profile("test") beans come into play — an in-memory database, a stubbed payment gateway — without touching how the app boots in production.

The one trap worth internalising

Profiles decide the shape of the container at startup. That is the whole mechanism — and also its main limit.

You cannot switch a profile per request, per user, or at runtime. By the time your code runs, the beans are already chosen and the profile decision is frozen. If you catch yourself wanting to "turn on the prod behaviour for just this one call," profiles are the wrong tool; that is a runtime flag, not a profile.

There is a subtler trap as well. It is tempting to route every optional feature through @Profile, but each profiled bean is a fork in your wiring that appears in only one environment — and therefore gets tested in only one. When the real question is "is this feature on or off," Spring Boot's @ConditionalOnProperty (a bean that appears based on a single property's value) is usually clearer, because the app boots the same way everywhere and simply reads a flag. Reserve profiles for genuine, environment-shaped differences — the database, the external services, the logging posture — and you keep their power without turning startup into a maze.

Putting it together

A profile is a name. You attach that name to beans with @Profile, or to configuration values by dropping them in an application-<name>.properties file, and you switch it on with spring.profiles.active. When the container is assembled at startup, Spring keeps the pieces whose name is active and skips the rest.

That single idea — choose the environment once, at boot — is what lets one identical build behave correctly on your laptop, in your tests, and in production, without a single if (production) anywhere in your code.

DEV Community: Ankit Verma

Filters vs Interceptors vs AOP — when each

🧠 The big idea in one line

🛣️ First, the journey of one request

🧱 Layer 1 — Servlet Filters (the outer wall)

🧭 Layer 2 — HandlerInterceptors (inside Spring MVC)

🎯 Layer 3 — AOP / Aspects (around any bean method)

⚠️ Easy to confuse — the proxy gotcha (self-invocation)

🧩 Bad vs good: picking the wrong layer

⚠️ Easy to confuse — quick separations

📊 Quick summary

🎯 Decision rule

💡 Remember this

Exception handling: @ExceptionHandler / @ControllerAdvice / ProblemDetail

🧠 The big idea in one line

🌊 What Spring does when you do nothing

🎯 Tool 1 — @ExceptionHandler on a controller

A shortcut for simple cases: @ResponseStatus

🌍 Tool 2 — @ControllerAdvice for the whole app

How Spring picks which handler runs

📦 Tool 3 — ProblemDetail for a standard error body

Handling Spring's own errors: ResponseEntityExceptionHandler

🚧 Gotchas the mechanism creates

📊 Quick summary

🎯 Decision rule

💡 Remember this

Bean Validation (@Valid) + binding errors

🧠 The big idea in one line

🩹 The problem: hand-written checks everywhere

🏷️ Step 1 — Rules become annotations (constraints)

⚙️ Step 2 — Who actually runs the rules?

🎯 Step 3 — @Valid triggers the check at the boundary

📥 Step 4 — Where the errors live, and the two paths

🧩 Step 5 — The failure looks different for JSON vs forms

📤 Step 6 — Turning binding errors into a clean response

🪆 Step 7 — Nested objects and collections

🔀 Step 8 — @Validated: groups and validating single params

🛠️ Step 9 — Writing your own constraint (briefly)

⚠️ Step 10 — Traps the mechanism creates

📊 Quick summary

🎯 Decision rule

💡 Remember this

Content negotiation & message converters (Jackson)

🧠 The big idea in one line

🎯 The starting point: a method that returns an object

🔌 What a message converter is

🧭 Content negotiation: which format does the client want?

The other strategies (and why Accept is the default)

📥 The request side: reading a body in

🚦 When negotiation fails: 406 and 415

🧩 Jackson: the converter that does the JSON work

The date trap

Steering serialization with annotations

The unknown-property trap

⚙️ Customizing converters the right way

📊 Quick summary

🎯 Decision rule

💡 Remember this

Request lifecycle: HandlerMapping HandlerAdapter resolvers

🧠 The big idea in one line

🗺️ Three questions, asked in order

📇 The lookup table is built at startup

🔍 Step 1 — the handler mapping picks the method

How a match is actually decided

🔌 Step 2 — the handler adapter, and why there is a middleman

🧩 Step 3 — argument resolvers fill the parameters

Adding your own resolver

📤 Step 4 — return value handlers deal with what comes back

🔗 Interceptors wrap the whole thing

⚠️ Easy to confuse

🕳️ Traps this design creates

📊 Quick summary

🎯 Decision rule

💡 Remember this

@Controller vs @RestController, request mapping

Where this fits

A controller is just a managed object

What @Controller actually signals

Telling Spring "that's the body, not a view name"

@RestController: the shortcut you almost always want

🎯 Tool 1 — `@ExceptionHandler` on a controller

A shortcut for simple cases: `@ResponseStatus`

🌍 Tool 2 — `@ControllerAdvice` for the whole app

📦 Tool 3 — `ProblemDetail` for a standard error body

Handling Spring's own errors: `ResponseEntityExceptionHandler`

🎯 Step 3 — `@Valid` triggers the check at the boundary

🔀 Step 8 — `@Validated`: groups and validating single params