In the last tutorial we saw the primary purpose of @ModelAttribute i.e. if annotated on method level, the Model object is populated with common attributes before a handler method is invoked. Here we are going to see one more use of this annotation.
Two uses of @ModelAttribute:
- Method-Level: Populates the model before the request handler is invoked. (last tutorial).
- Parameter-Level: Retrieves an object from the model to be used as a handler argument. (this tutorial).
Using @ModelAttribute with a handler method parameter
@ModelAttribute annotation on a handler method parameter indicates the parameter's value should be retrieved from the Model map.
There are two main steps to accomplish that.
First step (as we saw in the last tutorial) is to annotate a method with @ModelAttribute and return an object of any type from that method.:
@Controller
@RequestMapping("users")
public class UserController {
@Autowired
private UserService userService;
@ModelAttribute("user")
public User getUser (@PathVariable("userId") long userId) {
return userService.getUserById(userId);
}
}
Second step is to create a handler method and add an extra parameter of the same type returned in the first step. Also annotate the parameter with @ModelAttribute indicating its name.
@Controller
@RequestMapping("users")
public class UserController {
@Autowired
private UserService userService;
@RequestMapping("{userId}")
public String handleRequestById (@ModelAttribute("user") User user, Model model) {
model.addAttribute("msg", "user : " + user);
return user!=null && "admin".equals(user.getRole()) ?
"admin-page" : "user-page";
}
@ModelAttribute("user")
public User getUser (@PathVariable("userId") long userId) {
return userService.getUserById(userId);
}
}
How it works?
Before invoking any handler methods annotated with @RequestMapping, Spring calls all @ModelAttribute methods.
All return values of @ModelAttribute methods are populated in the Model object.
Spring then moves to next step and prepares to call the target handler method (the one which matches the request). On finding @ModelAttribute in the target handler method parameters, Spring tries to find the named object in the Model map. In our example it looks by the name 'user'.
On finding the matching named object, Spring populates the handler parameter with its value and calls the handler.
Also, if there's @SessionAttributes annotation on the controller class, then Spring first checks whether the named value for the handler's @ModelAttribute parameter exists in the HttpSession, if yes, then it will be used rather than invoking the related method with @ModelAttribute. See next tutorial for details.
If there's no match found then Spring attempts to instantiate the object using it's default constructor, then assign to the parameter and call the handler.
When to use @ModelAttribute as handler parameter?
The object returned by @ModelAttribute annotated method, will already be in the Model object, which is accessible in the view. So why we need to access that object in our handler method? The answer is whenever we want to conveniently apply some logic in the handler, based on that object. Like in our above example: based on User#role we are selecting different view name.
Complete Example
package com.logicbig.example;
public class User {
private long id;
private String name;
private String role;
.............
}
package com.logicbig.example;
import org.springframework.stereotype.Service;
@Service
public class UserService {
final static User USER_ADMIN = new User(1, "John", "admin");
final static User USER_DEV = new User(2, "Jim", "dev");
public User getUserById(long id) {
//simulating getting user from db
if (id == 1) {
return USER_ADMIN;
} else {
return USER_DEV;
}
}
}
package com.logicbig.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
@Controller
@RequestMapping("users")
public class UserController {
@Autowired
private UserService userService;
@RequestMapping("{userId}")
public String handleRequestById(@ModelAttribute("user") User user,
Model model) {
model.addAttribute("msg", "user by id: " +user);
return user != null && "admin".equals(user.getRole()) ?
"admin-page" : "user-page";
}
@ModelAttribute("user")
public User getUser(@PathVariable("userId") long userId) {
return userService.getUserById(userId);
}
}
src/main/webapp/WEB-INF/views/admin-page.jsp<%@ page language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<html>
<body>
<h2>Admin Page</h2>
<h3> Message : <h3>
<p>${msg}</p>
</body>
</html>
src/main/webapp/WEB-INF/views/user-page.jsp<%@ page language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<html>
<body>
<h2>User Page</h2>
<h3> Message : <h3>
<p>${msg}</p>
</body>
</html>
Running Example
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run 
$ curl -s http://localhost:8080/users/1
<html>
<body>
<h2>Admin Page</h2>
<h3> Message : <h3>
<p>user by id: User{id=1, name='John', role='admin'}</p>
</body>
</html>
$ curl -s http://localhost:8080/users/2
<html>
<body>
<h2>User Page</h2>
<h3> Message : <h3>
<p>user by id: User{id=2, name='Jim', role='dev'}</p>
</body>
</html>
Integration Test
package com.logicbig.example;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.assertj.MockMvcTester;
import org.springframework.web.context.WebApplicationContext;
import static org.assertj.core.api.Assertions.assertThat;
@ExtendWith(SpringExtension.class)
@WebAppConfiguration
@ContextConfiguration(classes = MyWebConfig.class)
public class UserControllerTest {
@Autowired
private WebApplicationContext wac;
private MockMvcTester mockMvc;
@BeforeEach
public void setup() {
// MockMvcTester can be created directly from the WebApplicationContext
this.mockMvc = MockMvcTester.from(wac);
}
@Test
public void testUserController() {
// Test Admin User
var adminResponse = this.mockMvc.get().uri("/users/1").exchange();
assertThat(adminResponse).hasStatusOk();
assertThat(adminResponse).hasViewName("admin-page");
assertThat(adminResponse).model().containsEntry("user", UserService.USER_ADMIN);
// Test Dev User
var devResponse = this.mockMvc.get().uri("/users/2").exchange();
assertThat(devResponse).hasStatusOk();
assertThat(devResponse).hasViewName("user-page");
assertThat(devResponse).model().containsKey("user");
assertThat(devResponse).model().extractingByKey("user")
.isEqualTo(UserService.USER_DEV);
}
}
mvn clean test -Dtest="UserControllerTest" Output$ mvn clean test -Dtest="UserControllerTest"
[INFO] Scanning for projects...
[WARNING]
[WARNING] Some problems were encountered while building the effective model for com.logicbig.example:spring-model-attribute-on-handler:war:1.0-SNAPSHOT
[WARNING] 'build.plugins.plugin.version' for org.apache.maven.plugins:maven-war-plugin is missing. @ line 42, column 21
[WARNING]
[WARNING] It is highly recommended to fix these problems because they threaten the stability of your build.
[WARNING]
[WARNING] For this reason, future Maven versions might no longer support building such malformed projects.
[WARNING]
[INFO]
[INFO] -------< com.logicbig.example:spring-model-attribute-on-handler >-------
[INFO] Building spring-model-attribute-on-handler 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ spring-model-attribute-on-handler ---
[INFO] Deleting D:\example-projects\spring-mvc\spring-model-attribute-on-handler\target
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ spring-model-attribute-on-handler ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\spring-model-attribute-on-handler\src\main\resources
[INFO]
[INFO] --- compiler:3.5.1:compile (default-compile) @ spring-model-attribute-on-handler ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 5 source files to D:\example-projects\spring-mvc\spring-model-attribute-on-handler\target\classes
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ spring-model-attribute-on-handler ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\spring-model-attribute-on-handler\src\test\resources
[INFO]
[INFO] --- compiler:3.5.1:testCompile (default-testCompile) @ spring-model-attribute-on-handler ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 1 source file to D:\example-projects\spring-mvc\spring-model-attribute-on-handler\target\test-classes
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ spring-model-attribute-on-handler ---
[INFO] Using auto detected provider org.apache.maven.surefire.junit4.JUnit4Provider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.UserControllerTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.497 s -- in com.logicbig.example.UserControllerTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.660 s
[INFO] Finished at: 2026-03-30T20:15:22+08:00
[INFO] ------------------------------------------------------------------------
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 3.2.9.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- spring-test 7.0.6 (Spring TestContext Framework)
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- junit-jupiter-engine 6.0.3 (Module "junit-jupiter-engine" of JUnit)
- hamcrest 3.0 (Core API and libraries of hamcrest matcher framework)
- assertj-core 3.26.3 (Rich and fluent assertions for testing in Java)
- JDK 25
- Maven 3.9.11
|
