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.

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

• @CookieValue → Access cookie values.

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

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

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

• @RequestPart → Handle multipart file uploads.

  @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

Annotation	HTTP Method	Description
@GetMapping	GET	Retrieve a resource from the server.
@PostMapping	POST	Create a new resource on the server.
@PutMapping	PUT	Update or completely replace a resource.
@PatchMapping	PATCH	Partially update an existing resource.
@DeleteMapping	DELETE	Remove a resource from the server.

---

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