Support for matrix parameters [SPR-5499]

[spring-projects-issues]

Chris Beams opened SPR-5499 and commented

---

Affects: 3.0.5

This issue is a sub-task of #9097

Issue Links:

• 12474 Use of semicolon delimited lists in REST URIs ("is duplicated by")

Referenced from: commits https://github.com/spring-projects/spring-framework/commit/2201dd8c45051230ad1a5a0e895cb5951edbfb74

8 votes, 12 watchers

[spring-projects-issues]

Christian Tzolov commented

Several of projects that I am working on expose public Restfull APIs (I can not change) that extensively use the matrix parameters. Until this issue is resolved would it be safe if we use the urlwriter to convert the matrix into normal parameters (e.g. ';' -> '&')?

[spring-projects-issues]

Chris Beams commented

Assigning to Arjen for comment

[spring-projects-issues]

Satyabodha Rao commented

We have a need for matrix parameters in our project. Can we get an estimated date/version for this fix to be available to use please?

[spring-projects-issues]

J. Russell Smyth commented

This seems to be a significant hole in the REST support in Spring, and over 2 years without any plan to resolve?

[spring-projects-issues]

Arjen Poutsma commented

Rossen, could you take a look at this for 3.1?

[spring-projects-issues]

Rossen Stoyanchev commented

Modified title (was: "Support for matrix parameters"). RFC 3986 ("URI: Generic Syntax") refers to these as path parameters and so does RFC 6570 ("URI Template").

[spring-projects-issues]

Rossen Stoyanchev commented

There seems to be one discrepancy in the treatment of (","). RFC 3986 implies it's interchangeable with (";"):

For example, one URI producer might use a segment such as "name;v=1.1" to indicate a reference to version 1.1 of "name", whereas another might use a segment such as "name,1.1" to indicate the same.

While in RFC 6570, a (",") is only used to separate values:

;list=red,green,blue

RFC 6570 is consistent with the syntax for query params and makes sense to target as part of this issue. If you have specific examples or references either way, please comment.

[spring-projects-issues]

Rossen Stoyanchev commented

A note on the relationship of this ticket to #12474. The two are related only so far as they both use a semicolon (";") in a path segment but in terms of intent they are different in a subtle way. The ticket here has to do with path parameters (also known as matrix parameters, essentially name-value pairs) in a path segment, e.g:

/moremaps.com/map/color;lat=50;long=20;scale=32000

Here the path segment color has 3 parameters. The example in #12474, on the other hand, is about putting multiple but equal pieces of information in one path segment and using semicolon or comma to separate them, e.g:

/earth/24.9195,17.821
/color-blend/red;blue;green

Note that the comma implies that order matters (longitude must come before latitude) while the semicolon implies the order doesn't matter, i.e. colors can be blended in any order.

Good examples of URLs with semicolons are hard to come by, especially the matrix parameter kind. Having good examples however is key to the design of this feature, so if you are interested in it and have (or know of) examples where semicolon is used, in your application or in the wild, please comment.

[spring-projects-issues]

Chris Beams commented

Here is an example from the Artifactory REST API. Matrix parameters are how they attach key/value metadata to artifacts as they are uploaded. And that same metadata may be specified by matrix params when resolving artifacts.

http://wiki.jfrog.org/confluence/display/RTF/Using+Properties+in+Deployment+and+Resolution

[spring-projects-issues]

Rossen Stoyanchev commented

Switching back to "matrix parameters". Although that term is not mentioned in the URI RFC 3986, its meaning is widely understood and much more distinctive than "path parameters".

[spring-projects-issues]

Rossen Stoyanchev commented

A new @MatrixVariable annotation is now available. See the commit description and the updated documentation for further details.