1. Overview
The URI specification RFC 3986 defined URI path parameters as name-value pairs. Matrix variables is a Spring coined term and an alternative implementation for passing and parsing URI path parameters.
Matrix variables support became available in Spring MVC 3.2 and is meant to simplify requests with a large number of parameters.
In this article, we will show how we can simplify complex GET requests that use either variable or optional path parameters inside the different path segments of a URI.
2. Configuration
To enable Spring MVC Matrix Variables, let’s start with the configuration:
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
UrlPathHelper urlPathHelper = new UrlPathHelper();
urlPathHelper.setRemoveSemicolonContent(false);
configurer.setUrlPathHelper(urlPathHelper);
}
}
Otherwise, they’re disabled by default.
3. How to Use Matrix Variables
These variables can appear in any part of the path, and the character equals (“=”) is used for giving values and the semicolon(‘;’) for delimiting each matrix variable. On the same path, we can also repeat the same variable name or separate different values using the character comma(‘,’).
Our example has a controller that provides information about the employees. Each employee has a working area, and we can search by that attribute. The following request could be used for searching:
http://localhost:8080/spring-mvc-java-2/employeeArea/workingArea=rh,informatics,admin
or like this:
http://localhost:8080/spring-mvc-java-2
/employeeArea/workingArea=rh;workingArea=informatics;workingArea=admin
When we want to refer to these variables in Spring MVC, we should use the annotation @MatrixVariable.
In our examples, we will use the Employee class:
public class Employee {
private long id;
private String name;
private String contactNumber;
// standard setters and getters
}
And also the Company class:
public class Company {
private long id;
private String name;
// standard setters and getters
}
These two classes will bind the request parameters.
4. Defining Matrix Variable Properties
We can specify required or default properties for the variable. In the following example, the contactNumber is required, so it must be included in our path, something like this:
http://localhost:8080/spring-mvc-java-2/employeesContacts/contactNumber=223334411
The request will be handled by the following method:
@RequestMapping(value = "/employeesContacts/{contactNumber}",
method = RequestMethod.GET)
@ResponseBody
public ResponseEntity<List<Employee>> getEmployeeByContactNumber(
@MatrixVariable(required = true) String contactNumber) {
List<Employee> employeesList = new ArrayList<Employee>();
...
return new ResponseEntity<List<Employee>>(employeesList, HttpStatus.OK);
}
As a result, we will get all the employees who have the contact number 223334411.
5. Complement Parameter
Matrix variables can complement path variables.
For example, we are searching an employee for his/her name, but we can also include the starting numbers of his/her contact number.
The request for this search should be like this:
http://localhost:8080/spring-mvc-java-2/employees/John;beginContactNumber=22001
The request will be handled by the following method:
@RequestMapping(value = "/employees/{name}", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity<List<Employee>> getEmployeeByNameAndBeginContactNumber(
@PathVariable String name, @MatrixVariable String beginContactNumber) {
List<Employee> employeesList = new ArrayList<Employee>();
...
return new ResponseEntity<>(employeesList, HttpStatus.OK);
}
As a result, we will get all the employees who have the contact number 22001 or whose name is John.
6. Binding All Matrix Variables
If for some reason, we want to get all the variables that are available on the path, we can bind them to a Map:
http://localhost:8080/spring-mvc-java-2/employeeData/id=1;name=John;contactNumber=2200112334
This request will be handled by the following method:
@GetMapping("employeeData/{employee}")
@ResponseBody
public ResponseEntity<Map<String, String>> getEmployeeData(
@MatrixVariable Map<String, String> matrixVars) {
return new ResponseEntity<>(matrixVars, HttpStatus.OK);
}
Of course, we can restrict binding to the matrix variables of a specific part of the path. For example, if we have a request like this:
http://localhost:8080/spring-mvc-java-2/
companyEmployee/id=2;name=Xpto/employeeData/id=1;name=John;
contactNumber=2200112334
And we only want to get all the variables that belong to employeeData; then we should use as an input parameter this:
@RequestMapping(
value = "/companyEmployee/{company}/employeeData/{employee}",
method = RequestMethod.GET)
@ResponseBody
public ResponseEntity<Map<String, String>> getEmployeeDataFromCompany(
@MatrixVariable(pathVar = "employee") Map<String, String> matrixVars) {
...
}
7. Partial Binding
Apart from simplicity, flexibility is another gain, matrix variables can be used in a variety of different ways. For example, we can get each variable from each path segment. Consider the following request:
http://localhost:8080/spring-mvc-java-2/
companyData/id=2;name=Xpto/employeeData/id=1;name=John;
contactNumber=2200112334
If we only want to know the matrix variable name of the companyData segment, then, we should use as an input parameter the following:
@MatrixVariable(value="name", pathVar="company") String name
8. Firewall Setup
If the application uses Spring Security, then StrictHttpFirewall is used by default. This blocks requests that appear to be malicious, including Matrix Variables with semicolon separator.
We can customize this implementation in application configuration and allow such variables whilst rejecting other possibly malicious requests.
However, this way, we can open the application to attacks. Therefore, we should only implement this after careful analysis of the application and security requirements.
9. Conclusion
This article illustrated some of the various ways that matrix variables can be used.
It’s essential to understand how this new tool can deal with requests that are too complex or help us add more parameters to delimit our search.
The implementation of all these examples and code snippets can be found in a GitHub project – this is a Maven-based project, so it should be easy to import and run as it is.