Spring Boot Matrix Variable Annotation

Tutorial | By |

Among these annotations, the MatrixVariable annotation is a powerful tool for parsing and binding name-value pairs within URI path segments. By leveraging this annotation, developers can create more expressive and intuitive URLs, enabling them to pass and retrieve data in a more organized and structured manner. Most developers are usually more familiar with request parameter annotations than matrix variable annotations.

Matrix Variables :: Spring Framework
Overview Spring Boot Spring Framework Spring Cloud Spring Cloud Data Flow Spring Data Spring Integration Spring Batch Spring Security View all projects

The Matrix Variable Concept: A Brief Overview

The concept of matrix variables originates from the RFC 3986 specification, which discusses the use of name-value pairs in path segments. While “matrix variables” is a Spring-coined terminology, it is an alternative implementation for handling URI path parameters.

Matrix variables offer a flexible approach to handling complex GET requests by allowing developers to embed parameters within the different path segments of a URI. This feature becomes particularly useful when dealing with requests involving many parameters or when additional parameters are required to refine the search criteria.

Path Matching :: Spring Framework
Overview Spring Boot Spring Framework Spring Cloud Spring Cloud Data Flow Spring Data Spring Integration Spring Batch Spring Security View all projects

Comparison of @MatrixVariable and @RequestParam in Spring Boot

MatrixVariable annotation

Purpose

  • Used to extract matrix variables from the URL

URL Format

  • Matrix variables are name-value pairs separated by semicolons, appearing after a path segment
  • Example: /cars;color=red;year=2023

Key Features

  1. Allows multiple values for the same variable
  2. Can be optional or required
  3. Supports default values
  4. Can be bound to a Map for all matrix variables

Advantages

  • Helpful in representing multiple non-hierarchical values
  • Keeps URL clean when dealing with numerous optional parameters

Limitations

  • Less widely used or recognized than query parameters
  • Requires particular configuration in Spring Boot to enable

RequestParam annotation

Purpose

  • Used to extract query parameters from the URL

URL Format

  • Query parameters are name-value pairs appended to the URL after a question mark
  • Example: /cars?color=red&year=2023

Key Features

  1. Can handle single or multiple values
  2. Can be optional or required
  3. Supports default values
  4. Can be bound to a Map for all request parameters

Advantages

  • Widely recognized and used in web applications
  • Easy to use and understand
  • Works out of the box in Spring Boot

Limitations

  • Can make URLs long and less readable with many parameters
  • Less suitable for representing structured data

Enabling Matrix Variables in Spring Boot

Before delving into the intricacies of the MatrixVariable annotation, it is crucial to understand how to allow matrix variables in the Spring Boot application. By default, matrix variables are disabled to maintain compatibility with other frameworks and to prevent potential security vulnerabilities.

To enable matrix variables, developers must configure them UrlPathHelper in the application’s configuration. In a Java-based configuration, developers can achieve this by implementing the WebMvcConfigurer interface and overriding the configurePathMatch method, as shown in the following example:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        UrlPathHelper urlPathHelper = new UrlPathHelper();
        urlPathHelper.setRemoveSemicolonContent(false);
        configurer.setUrlPathHelper(urlPathHelper);
    }
}

By enabling matrix variables, developers unlock the ability to parse and bind name-value pairs within URI path segments, paving the way for more expressive and flexible URL structures.

Using the MatrixVariable Annotation

With matrix variables enabled, developers can now leverage the power of the MatrixVariable annotation to bind matrix variables to method parameters in controller classes. This annotation is supported for RequestMapping annotated handler methods in Servlet environments.

Basic Usage

The MatrixVariable annotation can be applied to method parameters to bind them to the corresponding name-value pairs within a path segment. Consider the following example:

@RestController
@Slf4j
public class PetCategoryController {

    // GET /pets/42;q=11;r=22
    @GetMapping("/pets/{petId}")
    public ResponseEntity<String> findPet(@PathVariable String petId, @MatrixVariable int q) {
        // petId == 42
        // q == 11
        log.info("petId {}", petId);
        log.info("q {}", q);
        return ResponseEntity.ok().body("success");
    }

}

In this example, the @MatrixVariable annotation binds the value of the q matrix variable to the q method parameter. The petId parameter is bound using the @PathVariable annotation, representing a path variable.

Handling Multiple Matrix Variables

Matrix variables can appear in any path segment, with each variable separated by a semicolon (;) and multiple values separated by commas (,). For instance, the following URL contains multiple matrix variables with different values:

/cars;color=red,green;year=2012

To handle such scenarios, developers can use multiple @MatrixVariable annotations or leverage the MultiValueMap Data structure, as shown in the following example:

@RestController
@Slf4j
public class PetCategoryController {

    // GET /owners/42;q=11;r=12/pets/21;q=22;s=23
    @GetMapping("/owners/{ownerId}/pets/{petId}")
    public ResponseEntity<String> findPet(
            @PathVariable String petId,
            @PathVariable String ownerId,
            @MatrixVariable MultiValueMap<String, String> matrixVars,
            @MatrixVariable(pathVar="ownerId") MultiValueMap<String, String> ownerMatrixVars,
            @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {
        // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
        // petMatrixVars: ["q" : 22, "s" : 23]
        log.info("ownerId {}", ownerId);
        log.info("petId {}", petId);
        log.info("ownerMatrixVars {}", ownerMatrixVars.toString());
        log.info("petMatrixVars {}", petMatrixVars.toString());
        return ResponseEntity.ok().body("success");
    }

}

In this example, the matrixVars parameter holds all the matrix variables present in the URL, while the petMatrixVars parameter contains only the matrix variables associated with the petId path variable.

2024-10-17T15:25:01.333+07:00  INFO 12384 --- [matrix-variable] [nio-8080-exec-1] c.e.m.controller.PetCategoryController   : ownerId 42
2024-10-17T15:25:01.333+07:00  INFO 12384 --- [matrix-variable] [nio-8080-exec-1] c.e.m.controller.PetCategoryController   : petId 21
2024-10-17T15:25:01.333+07:00  INFO 12384 --- [matrix-variable] [nio-8080-exec-1] c.e.m.controller.PetCategoryController   : ownerMatrixVars {q=[11], r=[12]}
2024-10-17T15:25:01.334+07:00  INFO 12384 --- [matrix-variable] [nio-8080-exec-1] c.e.m.controller.PetCategoryController   : petMatrixVars {q=[22], s=[23]}

Specifying Optional Matrix Variables and Default Values

The MatrixVariable annotation provides additional options to handle optional matrix variables and specify default values. By setting the required attribute to false, developers can indicate that a matrix variable is optional. Additionally, developers can provide a defaultValue to be used when the matrix variable is not present in the request:

@RestController
@Slf4j
public class PetCategoryController {

    // GET /pets/42
    public ResponseEntity<String> findPet(@PathVariable String petId, 
                                          @MatrixVariable(required=false, defaultValue="1") int q) {
        // q == 1
        return ResponseEntity.ok().body("success q="+q);
    }

}

In this example, if the q matrix variable is not present in the request, the value of q will be set to the default value of 1.

Disambiguating Matrix Variables

In scenarios where multiple path segments contain matrix variables with the same name, developers can use the pathVar attribute to disambiguate which path variable the matrix variable belongs to:

@GetMapping("/owners/{ownerId}/pets/{petId}")
public ResponseEntity<String> findPet(
        @MatrixVariable(name="q", pathVar="ownerId") int q1,
        @MatrixVariable(name="q", pathVar="petId") int q2) {
    // q1 == 11
    // q2 == 22
    return ResponseEntity.ok().body("ownerId q="+q1+"petId q="+q2);
}

In this case, the q1 parameter is bound to the q matrix variable associated with the ownerId path variable, while the q2 parameter is bound to the q matrix variable associated with the petId path variable.

Practical Use Cases and Examples

Matrix variables can be instrumental when handling complex queries or filter requests based on multiple criteria. Here are a few practical examples to illustrate the utility of matrix variables:

Filtering Products by Multiple Attributes

Imagine developers have an e-commerce application where users can filter products based on various attributes, such as color, size, and price range. Instead of passing these filters as query parameters, developers can leverage matrix variables to create a more organized and readable URL structure:

/products;color=red,blue;size=M,L;price=50-100

In the controller method, developers can then bind these matrix variables to method parameters and use them to filter the product list accordingly:

@GetMapping("/products")
public ResponseEntity<List<Product>> filterProducts(
    @MatrixVariable List<String> color,
    @MatrixVariable List<String> size,
    @MatrixVariable(name="price") String priceRange) {
    // Filter products based on color, size, and price range
    List<Product> filteredProducts = productService.filterProducts(color, size, priceRange);
    return ResponseEntity.ok(filteredProducts);
}

Retrieving User Preferences

In a social media application, users often can customize their preferences, such as the types of content they want to see or the notification settings they prefer. Instead of storing these preferences in the application’s database, developers can encode them in the URL using matrix variables:

/user/42;showPosts=true;showVideos=false;notifyOnMentions=true

The controller method can then retrieve these preferences and use them to personalize the user’s experience:

@GetMapping("/user/{userId}")
public ResponseEntity<UserProfile> getUserProfile(
    @PathVariable Long userId,
    @MatrixVariable(defaultValue="true") boolean showPosts,
    @MatrixVariable(defaultValue="true") boolean showVideos,
    @MatrixVariable(defaultValue="false") boolean notifyOnMentions) {
    // Retrieve user profile and apply preferences
    UserProfile profile = userService.getUserProfile(userId, showPosts, showVideos, notifyOnMentions);
    return ResponseEntity.ok(profile);
}

In this example, the showPosts and showVideos matrix variables are set to true by default, while the notifyOnMentions a variable is set to false by default. The default values will be used if the user has not specified these preferences.

Handling Complex API Requests

Matrix variables can also be helpful when building RESTful APIs that handle complex requests with multiple parameters. Instead of passing these parameters as query strings, developers can use matrix variables to create more structured and readable URLs:

/api/v1/reports;type=sales,inventory;period=monthly,quarterly;region=us-east,eu-west

In the controller method, developers can bind these matrix variables to method parameters and use them to generate the requested reports:

@GetMapping("/api/v1/reports")
public ResponseEntity<List<Report>> generateReports(
    @MatrixVariable List<String> type,
    @MatrixVariable List<String> period,
    @MatrixVariable List<String> region) {
    // Generate reports based on the specified parameters
    List<Report> reports = reportService.generateReports(type, period, region);
    return ResponseEntity.ok(reports);
}

These examples demonstrate the versatility and power of matrix variables in creating more expressive and intuitive URLs, while enabling developers to handle complex requests with ease.

Performance Considerations

Matrix variables offer a convenient way to manage complex requests and create expressive URLs. However, developers should be aware of potential performance impacts. Parsing and binding matrix variables can introduce overhead, mainly when many are used in a single URL.

To minimize performance issues, follow best practices and optimize your code for optimal performance. For example, you can implement caching to store and reuse parsed values. Alternatively, consider using query parameters or request bodies for handling complex data.

Monitoring performance is also crucial. Conduct regular load testing to identify bottlenecks and enhance efficiency. Spring Boot supports performance tuning through tools like Micrometer and the Actuator module. These tools help track metrics and optimize your application effectively.

Conclusion

The @MatrixVariable annotation in Spring Boot empowers developers to create more readable and flexible URLs. It allows you to embed name-value pairs directly within URI segments, supporting advanced filtering and user preferences.

While matrix variables are powerful, be mindful of their impact on security and performance. Apply security best practices and performance optimization to ensure your application remains robust.

Understanding the nuances of @MatrixVariable will help you build scalable and high-performing web applications with Spring Boot.

Related Posts