What is the use of @RequestParam Annotation in Spring MVC?

Read this post to understand how to use the @RequestParam annotation in Java web application development with the Spring framework and Spring MVC. Basically, this annotation can be used to bind a method parameter of a handler method in a Spring MVC controller class to a web request parameter, making it easy to handle input from web forms or query strings.

But you don’t always need to use this annotation. Consider using it when you want to:

• specify a specific default value of a parameter
• explicitly declare a parameter as required or optional
• a method parameter to have different name than the bound request parameter

Let me explain further with some real-world examples of the @RequestParam annotation in Spring Web MVC.

Consider the following URL, which will be handled by a Spring MVC controller:

http://localhost:8080/MyWebApp/users?page=2&size=10&sort=name

As you can see, there are 3 query parameters in this request: page, size and name. Their values are 2, 10 and “name”, respectively. With Spring MVC, you can bind these request parameters to method parameters in a controller class as follows:

package net.codejava;

...

@Controller
public class UserController {

	
	@GetMapping("/users")
	public String listUsers(Integer page, Integer size, String sort) {
		
		...

	}
}

In this example, the listUsers() handler method declares 3 parameters: page, size and name, which are bound to the corresponding parameters in the request URL. Note that the method parameter names are identical to the request parameter names.

This is a sensible default in Spring MVC: it automatically binds request parameters of simple types (String, Integer, Long, etc.) to method parameters. This default behavior is both useful and convenient for developers, isn’t it?

And you know, in this automatic binding, method parameters will have a null value if the corresponding request parameters are missing. In other words, request parameters are optional and default to null when not provided.

But what if you want to specify different default values? Or if a parameter is required? Or if you need to use different binding name? In these cases, you need to use the @RequestParam annotation.

1. Use @RequestParam to specify a parameter’s default value

For example, you want the page parameter to have a default value of 1 when it is not present in the request URL, you can use the @RequestParam annotation in the handler method as follows:

@GetMapping("/users")
public String listUsers(@RequestParam(defaultValue = "1") Integer page, 
		Integer size, String sort) {
	...
}

In this case, the page parameter will default to a value of 1 if it is missing from the request URL:

http://localhost:8080/MyWebApp/users?size=10&sort=name

Note that when the defaultValue attribute is used, the parameter becomes optional, as it automatically sets the required flag to false.

2. Use @RequestParam to explicitly specify whether a parameter is required or optional

By default, this annotation requires the bound request parameter be present in the URL. If it is missing, the application will throw a MissingServletRequestParameterException.

You can use the required attribute of the @RequestParam annotation to better document the code, making it clear whether a parameter is required or optional. For example:

@GetMapping("/users")
public String listUsers(
		@RequestParam(defaultValue = "1") Integer page, 
		@RequestParam(required = false) Integer size,
		@RequestParam(required = true) String sort) {
	...
}

This explicitly indicates that the size parameter is optional, while the sort parameter is mandatory.

3. Use @RequestParam to specify a different binding name

If you want the sort request parameter to be bound to a method parameter named sortField, use the name or value attribute of @RequestParam annotation. For example:

@GetMapping("/users")
public String listUsers(...
		@RequestParam(name = "sort") String sortField) {
		
	...
}

This improves the readability of the code: the request parameter is named sort but it is bound to the method parameter named sortField.

By combining all these options, you might end up with the following code:

@GetMapping("/users")
public String listUsers(
		@RequestParam(name = "page", defaultValue = "1", required = false) Integer pageNum, 
		@RequestParam(name = "size", defaultValue = "10", required = false) Integer pageSize,
		@RequestParam(name = "sort", defaultValue = "name", required = false) String sortField) {
	
	...	
	
}

This sets default values for each parameter, specifies different binding names, and makes all parameters optional. While it may be verbose, it improves code readability for developers.

If you want to see the coding in action and how this annotation is used in a real-world project, this video will help you have better understanding: 

Summary

Normally you don’t need to use the @RequestParam annotation because Spring MVC provides automatic parameter binding for simple types. However, it becomes useful when you need to customize the defaults, such as specifying non-null default values, mandatory/optional parameters, or different binding names. I hope the explanation and code examples in this post were helpful.

References:

• Annotation Interface RequestParam (Spring Docs)
• @RequestParam (Spring framework reference)

Other Spring MVC Tutorials:

• A Quick Introduction to Spring MVC
• Spring MVC Form Handling Guide
• Spring MVC Form Validation Examples
• Spring MVC Exception Handling Guide

About the Author:

Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He began programming with Java back in the days of Java 1.4 and has been passionate about it ever since. You can connect with him on Facebook and watch his Java videos on YouTube.