Re: JSR311: Matrix Params question and concern

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Mon, 17 Dec 2007 11:45:35 -0500

On Dec 17, 2007, at 6:56 AM, Paul Sandoz wrote:
>> * URIBuilder assumes that Matrix parameters only happen once and at
>> the last path segment.
> More specfically the "final segment of the current URI path".

I'll improve the Javadoc to make this point clearer.

> So it is possible to do this:
> URI u = UriBuilder.fromUri("http://localhost/").
> path("p1").matrixParam("a", "x").
> path("p2").matrixParam("a", "y").build();
> which will result in the following URI:
> http://localhost/p1;a=x/p2;a=y
>> * matrix parameter names could be repeated throughout the URI and
>> thus @MatrixParam could be ambiguous.
> Good point. Currently in the RI the most recent matrix parameters
> take precedence, and i suspect it is buggy and recent means for the
> whole URI path rather than the left hand side of the path that has
> been matched so far.
Perhaps we need to add some scoping information to @MatrixParam, more
on this below.

>> ******
>> On a different, but related note, I think it would be interesting
>> to allow injection of a object for a
>> @UriParam
>> @Path("{seg}/more/stuff/follows")
>> public String get(@UriParam("seg") PathSegment param) {...}
I assume the attraction of using PathSegment here is that it provides
access to the getMatrixParameters method - right ? I wonder if a more
general @MatrixParam would fit the use case better, see below.

>> This way, for a specific segment, the app developer can pull out
>> matrix parameters specific to that path segment.
>> What's a usecase? Well, I'm prototyping something that gives
>> access to a specific database and some entities will have composite
>> keys that I want to map into a URI
>> /customerdb/customers/id;name=Bill;ssn=6666666666/picture
>> Would be:
>> @Path("{db}/{entity-name}/{key}/{property}")
>> @GET
>> public JPEG get(@UriParam("db") String db,
>> @UriParam("entity-name") String entity,
>> @UriParam("key") PathSegment key,
>> @UriParam("property) String property) {...}
Rather than re-using @UriParam (now renamed @PathParam BTW) I wonder
if we should revisit @MatrixParam instead to add scoping information
that controls where in the URI the matrix parameter values are
extracted from and add support for injecting a set of values rather
than a single value.

- @MatrixParam(value="name") would extract the value of the most
recent matrix parameter called "name".
- @MatrixParam(value="name", scope="key") would extract the value of
the matrix parameter called "name" from the path segment that contains
the "key" template parameter.
- @MatrixParam(scope="key") extracts the values of all matrix
parameters from the path segment that contains the "key" template
- @MatrixParam extracts the values of all matrix parameters from all
the path segments.

A couple of issues:

(i) How to identify path segments that don't contain template
parameters - should we also support ordinal-based access ?
(ii) What type to support when the value property isn't used -
MultivaluedMap<String, String> seems the obvious choice.


Marc Hadley <marc.hadley at>
CTO Office, Sun Microsystems.