diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index d2368ba1881..9235d08a425 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -1013,11 +1013,10 @@ Java 8+: `java.time.ZoneId` |`@PathVariable` |For access to URI template variables. -// TODO: See <>. +See <>. |`@MatrixVariable` -|For access to name-value pairs in URI path segments. -// TODO: See <>. +|For access to name-value pairs in URI path segments. See <>. |`@RequestParam` |For access to Servlet request parameters. Parameter values are converted to the declared @@ -1180,6 +1179,90 @@ can be customized through a `WebDataBinder`, see <>, or by r <>. +[[webflux-ann-matrix-variables]] +==== Matrix variables +[.small]#<># + +http://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in +path segments. In Spring WebFlux we refer to those as "matrix variables" based on an +http://www.w3.org/DesignIssues/MatrixURIs.html["old post"] by Tim Berners-Lee but they +can be also be referred to as URI path parameters. + +Matrix variables can appear in any path segment, each variable separated by semicolon and +multiple values separated by comma, e.g. `"/cars;color=red,green;year=2012"`. Multiple +values can also be specified through repeated variable names, e.g. +`"color=red;color=green;color=blue"`. + +Unlike Spring MVC, in WebFlux the presence or absence of matrix variables in a URL does +not affect request mappings. In other words you're not required to use a URI variable +to mask variable content. That said if you want to access matrix variables from a +controller method you need to add a URI variable to the path segment where matrix +variables are expected. Below is an example: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + public void findPet(@PathVariable String petId, @MatrixVariable int q) { + + // petId == 42 + // q == 11 + } +---- + +Given that all path segments may contain matrix variables, sometimes you may need to +disambiguate which path variable the matrix variable is expected to be in. +For example: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /owners/42;q=11/pets/21;q=22 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable(name="q", pathVar="ownerId") int q1, + @MatrixVariable(name="q", pathVar="petId") int q2) { + + // q1 == 11 + // q2 == 22 + } +---- + +A matrix variable may be defined as optional and a default value specified: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { + + // q == 1 + } +---- + +To get all matrix variables, use a `MultiValueMap`: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable MultiValueMap matrixVars, + @MatrixVariable(pathVar="petId"") MultiValueMap petMatrixVars) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- + + [[webflux-ann-requestparam]] ==== @RequestParam [.small]#<># diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 4d427fe262a..352864154a1 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -1266,125 +1266,6 @@ recommendations related to RFD. -[[mvc-ann-matrix-variables]] -==== Matrix variables - -The URI specification http://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] defines -the possibility of including name-value pairs within path segments. There is no specific -term used in the spec. The general "URI path parameters" could be applied although the -more unique http://www.w3.org/DesignIssues/MatrixURIs.html["Matrix URIs"], originating -from 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 be -either "," (comma) separated `"color=red,green,blue"` or the variable name may be -repeated `"color=red;color=green;color=blue"`. - -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. - -Below is an example of extracting the matrix variable "q": - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - // GET /pets/42;q=11;r=22 - - @GetMapping("/pets/{petId}") - 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 more -specific to identify where the variable is expected to be: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - // GET /owners/42;q=11/pets/21;q=22 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable(name="q", pathVar="ownerId") int q1, - @MatrixVariable(name="q", pathVar="petId") int q2) { - - // q1 == 11 - // q2 == 22 - } ----- - -A matrix variable may be defined as optional and a default value specified: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - // GET /pets/42 - - @GetMapping("/pets/{petId}") - public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { - - // q == 1 - } ----- - -All matrix variables may be obtained in a Map: - -[source,java,indent=0] -[subs="verbatim,quotes"] ----- - // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 - - @GetMapping("/owners/{ownerId}/pets/{petId}") - public void findPet( - @MatrixVariable MultiValueMap matrixVars, - @MatrixVariable(pathVar="petId"") MultiValueMap petMatrixVars) { - - // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] - // petMatrixVars: ["q" : 22, "s" : 23] - } ----- - -Note that to enable the use of matrix variables, you must set the -`removeSemicolonContent` property of `RequestMappingHandlerMapping` to `false`. By -default it is set to `true`. - -[TIP] -==== -The MVC Java config and the MVC namespace both provide options for enabling the use of -matrix variables. - -If you are using Java config, The <> section describes how the `RequestMappingHandlerMapping` can -be customized. - -In the MVC namespace, the `` element has an -`enable-matrix-variables` attribute that should be set to `true`. By default it is set -to `false`. - -[source,xml,indent=0] -[subs="verbatim,quotes"] ----- - - - - - - ----- -==== [[mvc-ann-requestmapping-consumes]] ==== Consumable media types @@ -1768,6 +1649,94 @@ can be customized through a `WebDataBinder`, see <>, or by r <>. +[[mvc-ann-matrix-variables]] +==== Matrix variables +[.small]#<># + +http://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in +path segments. In Spring MVC we refer to those as "matrix variables" based on an +http://www.w3.org/DesignIssues/MatrixURIs.html["old post"] by Tim Berners-Lee but they +can be also be referred to as URI path parameters. + +Matrix variables can appear in any path segment, each variable separated by semicolon and +multiple values separated by comma, e.g. `"/cars;color=red,green;year=2012"`. Multiple +values can also be specified through repeated variable names, e.g. +`"color=red;color=green;color=blue"`. + +If a URL is expected to contain matrix variables, the request mapping for a controller +method must use a URI variable to mask that variable content and ensure the request can +be matched successfully independent of matrix variable order and presence. +Below is an example: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /pets/42;q=11;r=22 + + @GetMapping("/pets/{petId}") + public void findPet(@PathVariable String petId, @MatrixVariable int q) { + + // petId == 42 + // q == 11 + } +---- + +Given that all path segments may contain matrix variables, sometimes you may need to +disambiguate which path variable the matrix variable is expected to be in. +For example: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /owners/42;q=11/pets/21;q=22 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable(name="q", pathVar="ownerId") int q1, + @MatrixVariable(name="q", pathVar="petId") int q2) { + + // q1 == 11 + // q2 == 22 + } +---- + +A matrix variable may be defined as optional and a default value specified: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /pets/42 + + @GetMapping("/pets/{petId}") + public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) { + + // q == 1 + } +---- + +To get all matrix variables, use a `MultiValueMap`: + +[source,java,indent=0] +[subs="verbatim,quotes"] +---- + // GET /owners/42;q=11;r=12/pets/21;q=22;s=23 + + @GetMapping("/owners/{ownerId}/pets/{petId}") + public void findPet( + @MatrixVariable MultiValueMap matrixVars, + @MatrixVariable(pathVar="petId"") MultiValueMap petMatrixVars) { + + // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23] + // petMatrixVars: ["q" : 22, "s" : 23] + } +---- + +Note that you need to enable the use of matrix variables. In the MVC Java config you need +to set a `UrlPathHelper` with `removeSemicolonContent=false` via +<>. In the MVC XML namespace, use +``. + + [[mvc-ann-requestparam]] ==== @RequestParam [.small]#<>#