Matrix Variables

The URI specification RFC 3986 definesthe possibility of including name-value pairs within path segments. There is no specificterm used in the spec. The general "URI path parameters" could be applied although themore unique "Matrix URIs", originatingfrom an old post by Tim Berners-Lee, is also frequently used and fairly well known.Within Spring MVC these are referred to as matrix variables.

Matrix variables can appear in any path segment, each matrix variable separated with a";" (semicolon). For example: "/cars;color=red;year=2012". Multiple values may beeither "," (comma) separated "color=red,green,blue" or the variable name may berepeated "color=red;color=green;color=blue".

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

Below is an example of extracting the matrix variable "q":

// GET /pets/42;q=11;r=22

@RequestMapping(value = "/pets/{petId}", method = RequestMethod.GET)
public void findPet(@PathVariable String petId, @MatrixVariable int q) {

    // petId == 42
    // q == 11

}

Since all path segments may contain matrix variables, in some cases you need to be morespecific to identify where the variable is expected to be:

// GET /owners/42;q=11/pets/21;q=22

@RequestMapping(value = "/owners/{ownerId}/pets/{petId}", method = RequestMethod.GET)
public void findPet(
        @MatrixVariable(value="q", pathVar="ownerId") int q1,
        @MatrixVariable(value="q", pathVar="petId") int q2) {

    // q1 == 11
    // q2 == 22

}

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=false, defaultValue="1") int q) {

    // q == 1

}

All matrix variables may be obtained in a Map:

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@RequestMapping(value = "/owners/{ownerId}/pets/{petId}", method = RequestMethod.GET)
public void findPet(
        @MatrixVariable Map<String, String> matrixVars,
        @MatrixVariable(pathVar="petId"") Map<String, String> petMatrixVars) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 11, "s" : 23]

}

Note that to enable the use of matrix variables, you must set theremoveSemicolonContent property of RequestMappingHandlerMapping to false. Bydefault it is set to true.

The MVC Java config and the MVC namespace both provide options for enabling the use ofmatrix variables. If you are using Java config, The Advanced Customizationswith MVC Java Config section describes how the RequestMappingHandlerMapping canbe customized. In the MVC namespace, the <mvc:annotation-driven> element has anenable-matrix-variables attribute that should be set to true. By default it is setto false. <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd"> <mvc:annotation-driven enable-matrix-variables="true"/> </beans>