Spring MVC and the @ModelAttribute Annotation

1. Overview

One of the most important Spring-MVC annotations is the @ModelAttribute annotation.

The @ModelAttribute is an annotation that binds a method parameter or method return value to a named model attribute and then exposes it to a web view.

In the following example, we will demonstrate the usability and functionality of the annotation, through a common concept: a form submitted from a company’s employee.

2. The @ModelAttribute in Depth

As the introductory paragraph revealed, @ModelAttribute can be used either as a method parameter or at the method level.

2.1 At the Method Level

When the annotation is used at the method level it indicates the purpose of that method is to add one or more model attributes. Such methods support the same argument types as @RequestMapping methods but that cannot be mapped directly to requests.

Let’s have a look at a quick example here to start understanding how this works:

@ModelAttribute
public void addAttributes(Model model) {
    model.addAttribute("msg", "Welcome to the Netherlands!");
}

In the example, we show a method that adds an attribute named msg to all models defined in the controller class.

Of course we’ll see this in action later on in the article.

In general, Spring-MVC will always make a call first to that method, before it calls any request handler methods. That is, @ModelAttribute methods are invoked before the controller methods annotated with @RequestMapping are invoked. The logic behind the sequence is that, the model object has to be created before any processing starts inside the controller methods.

It is also important that you annotate the respective class as @ControllerAdvice. Thus, you can add values in Model which will be identified as global. This actually means that for every request a default value exists, for every method in the response part.

2.2 As a Method Argument

When used as a method argument, it indicates the argument should be retrieved from the model. When not present, it should be first instantiated and then added to the model and once present in the model, the arguments fields should be populated from all request parameters that have matching names.

In the code snippet that follows the employee model attribute is populated with data from a form submitted to the addEmployee endpoint. Spring MVC does this behind the scenes before invoking the submit method:

@RequestMapping(value = "/addEmployee", method = RequestMethod.POST)
public String submit(@ModelAttribute("employee") Employee employee) {
    // Code that uses the employee object

    return "employeeView";
}

Later on in this article we will see a complete example of how to use the employee object to populate the employeeView template.

So, it binds the form data with a bean. The controller annotated with @RequestMapping can have custom class argument(s) annotated with @ModelAttribute.

This is what is commonly know as data binding in Spring-MVC, a common mechanism that saves you from having to parse each form field individually.

3. Form Example

In this section we will provide the example referred to in the overview section: a very basic form that prompts a user (employee of a company, in our specific example), to enter some personal information (specifically name and id). After the submission is completed and without any errors, the user expects to see the previously submitted data, displayed on another screen.

3.1 The View

Let’s first create a simple form with id and name fields:

<form:form method="POST" action="/spring-mvc-java/addEmployee" 
  modelAttribute="employee">
    <form:label path="name">Name</form:label>
    <form:input path="name" />
		
    <form:label path="id">Id</form:label>
    <form:input path="id" />
		
    <input type="submit" value="Submit" />
</form:form>

3.2 The Controller

Here is the controller class, where the logic for the afore-mentioned view is being implemented:

@Controller
@ControllerAdvice
public class EmployeeController {

    private Map<Long, Employee> employeeMap = new HashMap<>();

    @RequestMapping(value = "/addEmployee", method = RequestMethod.POST)
    public String submit(
      @ModelAttribute("employee") Employee employee,
      BindingResult result, ModelMap model) {
        if (result.hasErrors()) {
            return "error";
        }
        model.addAttribute("name", employee.getName());
        model.addAttribute("id", employee.getId());

        employeeMap.put(employee.getId(), employee);

        return "employeeView";
    }

    @ModelAttribute
    public void addAttributes(Model model) {
        model.addAttribute("msg", "Welcome to the Netherlands!");
    }
}

In the submit() method we have an Employee object bound to our View. Can you see the power of this annotation? You can map your form fields to an object model as simply as that. In the method we are fetching values from the form and setting them to ModelMap.

In the end we return employeeView, which means that the respective JSP file is going to be called as a View representative.

Furthermore, there is also an addAttributes() method. It’s purpose is to add values in the Model which will be identified globally. That is, a default value will be returned as a response for every request to every controller method. We also have to annotate the specific class as @ControllerAdvice.

3.3 The Model

As mentioned before, the Model object is very simplistic and contains all that is required by the “front-end” attributes. Now, let’s have a look at an example:

@XmlRootElement
public class Employee {

    private long id;
    private String name;

    public Employee(long id, String name) {
        this.id = id;
        this.name = name;
    }

    // standard getters and setters removed
}

3.4 Wrap Up

The @ControllerAdvice assists a controller and in particular, @ModelAttribute methods that apply to all @RequestMapping methods. Of course, our addAttributes() method will be the very first to run, prior to the rest of the @RequestMapping methods.

Keeping that in mind and after both of submit() and addAttributes() are run, we could just refer to them in the View returned from the Controller class, by mentioning their given name inside a dollarised curly-braces duo, like for example ${name}.

3.5 Results View

Let’s now print what we received from the form:

<h3>${msg}</h3>
Name : ${name}
ID : ${id}

4. Conclusion

In this tutorial we investigated the usage of @ModelAttribute annotation, for both method arguments and method level usage cases.

The implementation of this simple tutorial can be found in the github project – this is an Maven based project, so it should be easy to import and run as it is.