Spring optional @MatrixVariable with default value

In this tutorial I will show you how we use optional @MatrixVariable with default value in Spring Web MVC. I am going to show you how to set default value to matrix variable to make it optional in the URL segment. The URI has the possibility of including name-value pairs within path segments. Within Spring MVC these are referred to as matrix variables.

If a URL is expected to contain matrix variables, the request mapping pattern must represent them with a URI template. This ensures the request can be matched correctly regardless of whether matrix variables are present or not and in what order they are provided.

A matrix variable may be defined as optional and a default value specified:

// GET /pets/42
@RequestMapping(value = "/pets/{petId}", method = RequestMethod.GET)
public void findPet(@MatrixVariable(required=true, defaultValue="1") int q) {
    // q == 1


Java at least 8, Gradle 6.5.1, Maven 3.6.3, Spring Boot 2.3.3, Thymeleaf Template

Project Setup

You can create either gradle or maven based project in your favorite IDE or tool. The name of the project is spring-matrix-variable-default-value.

If you are creating gradle based project then use below build.gradle script:

buildscript {
	ext {
		springBootVersion = '2.3.3.RELEASE'
    repositories {
    dependencies {

plugins {
    id 'java-library'
    id 'org.springframework.boot' version "${springBootVersion}"

sourceCompatibility = 12
targetCompatibility = 12

repositories {

dependencies {
	implementation "org.springframework.boot:spring-boot-starter-web:${springBootVersion}"

If you are creating maven based project then use below pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">





					<source>at least 8</source>
					<target>at least 8</target>

Web Configuration

@MatrixVariable annotation indicates that a method parameter should be bound to a name-value pair within a path segment. @MatrixVariable annotation is disabled by default in Spring MVC. In order to enable it you need to tweak the configuration and set the removeSemicolonContent property of RequestMappingHandlerMapping to false. By default it is set to true.

If you do not set it to false then you will see the following exception in your application:

Missing matrix variable 'q' for method parameter of type String

In order to support matrix variable in your Spring MVC application, you need to do the following in your Spring Boot application:

package com.roytuts.spring.matrix.variable.value.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.util.UrlPathHelper;

public class WebConfig implements WebMvcConfigurer {

	public void configurePathMatch(PathMatchConfigurer configurer) {
		UrlPathHelper urlPathHelper = new UrlPathHelper();

Web Controller

You need to create a Spring web controller to render your view on UI.

In the following example, I have path variable, matrix variable with a default value and the model where I am passing the value of the matrix variable to be available on UI.

package com.roytuts.spring.matrix.variable.value.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.MatrixVariable;
import org.springframework.web.bind.annotation.PathVariable;

public class HomeController {

	public String homePage(@PathVariable String id, @MatrixVariable(required = true, defaultValue = "Hello") String q,
			Model model) {
		System.out.println("id : " + id);
		System.out.println("q: " + q);

		model.addAttribute("q", q);

		return "index";


View File – UI

The following view file displays the value of matrix variable’s value when rendered in the browser. This template file – index.html – is kept under src/main/resources/templates folder.

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<title>Spring Boot Matrix Variable with default value</title>
		 Matrix Variable's Value : <strong th:text="${q}"></strong>

Main Class

A class having main method with @SpringBootApplication is enough to deploy the application into embedded Tomcat server.

package com.roytuts.spring.matrix.variable.value;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

public class SpringMatrixVariableDefaultValueApp {

	public static void main(String[] args) {
		SpringApplication.run(SpringMatrixVariableDefaultValueApp.class, args);


Testing the Application

Now hit the URL http://localhost:8080/report/50;q=1 in the browser, you will see the below output in the browser:

spring mvc matrix variable with default value

Console Output

id : 50
q: 1

Source Code


Thanks for reading.

Related posts

Leave a Comment