Java Automation Job Top
We’re looking for a Backend Java/Spring Developer with Integration Experience: Read More

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:

public class WebConfig implements WebMvcConfigurer {

    public void configurePathMatch(PathMatchConfigurer configurer) {
        UrlPathHelper urlPathHelper = new 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:


or like this:


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:


The request will be handled by the following method:

@RequestMapping(value = "/employeesContacts/{contactNumber}", 
  method = RequestMethod.GET)
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:


The request will be handled by the following method:

@RequestMapping(value = "/employees/{name}", method = RequestMethod.GET)
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:


This request will be handled by the following method:

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:


And we only want to get all the variables that belong to employeeData; then we should use as an input parameter this:

 value = "/companyEmployee/{company}/employeeData/{employee}",
 method = RequestMethod.GET)
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:


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.

REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

REST footer banner
Comments are closed on this article!