Controllers

Controllers are the core components that handle HTTP requests in Spring applications. Every web request—whether for an HTML page or a REST API—ultimately passes through a controller.

What is a Controller?

A Controller is a Java class that:

• Receives HTTP requests from clients
• Processes the request (or delegates it to the service layer)
• Returns a response (JSON/XML for REST APIs or HTML view for MVC)

Spring detects controllers during component scanning and registers them with the DispatcherServlet.

Types of Controllers

Spring provides two main types of controllers depending on the application needs:

1. @Controller (MVC Controller)

Used in traditional web applications that return HTML views.

• Returns view names (e.g., JSP, Thymeleaf, FreeMarker)
• Uses ViewResolver to render HTML pages
• Suitable for server-side rendering

Example:

@Controller
publicclassHomeController {

@GetMapping("/home")
public StringhomePage() {
return"home";// home.html / home.jsp
    }
}

✔ ViewResolver is involved

✔ Best for web pages

2. @RestController (REST Controller)

Used in RESTful web services that return data (JSON/XML).

• Returns data instead of view names
• Automatically uses HttpMessageConverter
• Combines @Controller + @ResponseBody

Example:

@RestController
publicclassUserController {

@GetMapping("/users")
public List<User>getUsers() {
return userService.findAll();
    }
}

✔ Automatically converts Java objects to JSON/XML

✔ Best for APIs

Data Handling in Controllers

Spring MVC provides annotations to extract data from HTTP requests.

Query Parameters

Used to read values from the query string of a URL.

Best for filtering or searching data.

@GetMapping("/search")
public List<User>search(@RequestParam String name) {
return userService.search(name);
}

Example URL:

/search?name=John

Used for filtering or searching data.

Path Variables

Used to read values directly from the URL path.

Best for identifying a specific resource.

@GetMapping("/{id}")
public UsergetUser(@PathVariable Long id) {
return userService.findById(id);
}

Example URL:

/users/10

Used to identify a specific resource.

Request Body (JSON)

Used to read the request payload in POST/PUT/PATCH requests.

Typically used for creating or updating resources.

@PostMapping
public Usercreate(@RequestBody User user) {
return userService.save(user);
}

Advanced Data Handling

Spring MVC also provides annotations for handling more specialized request data:

• @RequestHeader → Read values from HTTP headers.

  Copy

  @GetMapping("/greet")
  public Stringgreet(@RequestHeader("User-Agent") String userAgent) {
  return"Hello! Your agent: " + userAgent;
  }
  

• @CookieValue → Access cookie values.

  Copy

  @GetMapping("/welcome")
  public Stringwelcome(@CookieValue("sessionId") String sessionId) {
  return"Welcome! Session ID: " + sessionId;
  }
  

• @MatrixVariable → Extract matrix variables from the URI (less common).

  Copy

  @GetMapping("/products/{id}")
  public Stringfilter(@MatrixVariableint price) {
  return"Products under price: " + price;
  }
  

• @RequestPart → Handle multipart file uploads.

  Copy

  @PostMapping("/upload")
  public StringuploadFile(@RequestPart("file") MultipartFile file) {
  return"File uploaded: " + file.getOriginalFilename();
  }
  

Returning Responses

Controllers in Spring MVC / Spring Boot can return responses in different ways depending on the requirements.

Simple JSON

Spring automatically converts the returned object to JSON using HttpMessageConverter.

@GetMapping("/{id}")
public UsergetUser(@PathVariable Long id) {
return userService.findById(id);
}

Using ResponseEntity (Production-ready)

ResponseEntity allows full control over the HTTP response, including status codes and headers.

@GetMapping("/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return ResponseEntity
            .ok()                 // HTTP 200 OK
            .header("Custom-Header", "value")  // Optional headers
            .body(user);          // Response body
}

Advantages:

• Allows custom HTTP status codes (e.g., 200, 201, 404)
• Enables adding headers to the response
• Recommended for production-ready REST APIs

HTTP Method-Specific Annotations

CRUD Examples Using HTTP Method Annotations

GET – Fetch Resource

@GetMapping("/{id}")
public UsergetUser(@PathVariable Long id) {
return userService.findById(id);
}

Retrieves a resource by its ID without modifying it.

POST – Create Resource

@PostMapping
public UsercreateUser(@RequestBody User user) {
return userService.save(user);
}

Creates a new resource on the server.

PUT – Update Full Resource

@PutMapping("/{id}")
public UserupdateUser(@PathVariable Long id,@RequestBody User user) {
return userService.update(id, user);
}

Updates or replaces an existing resource completely.

PATCH – Partial Update

@PatchMapping("/{id}")
public UserupdateEmail(@PathVariable Long id,@RequestParam String email) {
return userService.updateEmail(id, email);
}

Updates only specific fields of an existing resource.

DELETE – Remove Resource

@DeleteMapping("/{id}")
publicvoiddeleteUser(@PathVariable Long id) {
    userService.delete(id);
}

Deletes a resource from the server.

Request Flow in Spring MVC

Client
 ↓
DispatcherServlet
 ↓
HandlerMapping
 ↓
HandlerAdapter
 ↓
Controller
 ↓
JSON (REST) /ViewResolver (MVC)
 ↓
Response

Exception Handling

• Use @ControllerAdvice to handle exceptions globally.
• Can return consistent error responses for REST APIs.

@ControllerAdvice
publicclassGlobalExceptionHandler {

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<String>handleNotFound(ResourceNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

Best Practices

• Keep controllers thin; delegate business logic to services
• Use DTOs instead of exposing entities directly
• Validate input using @Valid
• Use ResponseEntity for production-ready APIs
• Prefer HTTP method-specific annotations over generic @RequestMapping

Conclusion

Controllers are the entry point for all HTTP requests in Spring applications.

• @Controller handles traditional web pages
• @RestController handles REST APIs
• @RequestMapping and its shortcut annotations map URLs, HTTP methods, headers, and content types to controller methods