[jax-rs-spec users] [jsr339-experts] Re: HEADS-UP: Encoding values of UriBuilder template parameters

From: Marek Potociar <>
Date: Mon, 05 Dec 2011 11:00:30 +0100

On 12/03/2011 04:45 PM, Markus KARG wrote:
>> -----Original Message-----
>> From: Marek Potociar []
>> Sent: Montag, 28. November 2011 17:02
>> To:
>> Cc: Markus KARG
>> Subject: Re: [jsr339-experts] Re: HEADS-UP: Encoding values of
>> UriBuilder template parameters
>> Markus, sorry for the late reply.
>> On 11/01/2011 05:38 PM, Markus KARG wrote:
>>> Sorry for the late answer, had been out of office.
>>> Actually I have to disagree to your conclusion! I do not see any
>> difference in path parameters vs. segment parameters.
>> Path parameter is something that may contain a path (including slash).
>> Unlike path, a path segment, from the URI spec is something that cannot
>> contain slash. IOW, path parameter, path segment parameter as well as
>> e.g. query or schema parameters have all different encoding schemes as
>> they all define different sets of allowed characters.
>> I think your fault is that you think encoding is depentent of the
>> method, but it is solely dependend of the target.
> No the problem is that the RFC does not name a segment as being a standalone part of an URI, but says a segment is part of the path part. There is nothing like a "segment" part of an URI. So I understand what you like to tell, but it is just wrong to say that it is dependent of the component, as a segment IS PART OF THE PATH component. As a conclusion, as there is no segment component, the sole difference is THE METHOD named either path() or segment(), as segment() IS WRITING THE COMPONENT NAMED "PATH". Got the point?

Why would we need to constrain parameter encoding to standalone spec components only? We support segment as a separate
parameterized target as part of the URI builder API. It's IMHO only natural to expect that as part of this support we
will also support the proper encoding for this parameterized target, right?

>> Exactly. :) To me, path and path segment are different targets for the
>> reasons explained above.
> I understand how you interpret it, but the WORDS OF THE RFC do NOT say that segment is a standalone entity but it is PART OF PATH (what actually do you not understand with that?). So it is NOT a differenct target, so we have to change the JavaDocs. Our docs are not bound to your interpretation but have to match the clear words of the RFC.

I disagree. Words of spec do not say that path segment is a separate URI component. But the spec clearly recognizes path
segment as a separate entity (even as part of the URI grammar):

   A path consists of a sequence of path segments separated by a slash
   ("/") character.

I do understand your reasoning now, but to me, we need to primarily consider what we support in our API. In our API we
clearly recognize segment as a separate entity. UriBuilder.path("{template}") and UriBuilder.segment("{template}")
simply mean different things IMO, just as UriBuilder.path("a/b") and UriBuilder.segment("a/b") do.

>> And the target of both, path and segment, is the URI's path -- so there
>> is no difference (while there is one for the query part, obviously)!
>> I disagree. Look at the URI spec and check the definition of path and
>> path segment.
> Sorry but, do YOU please look at the definition of which components a URI breaks up. It is clearly told that there is NOTHING like a "segment" component, but ONLY a path, which splits up into segments. But a segment IS A PATH, not a standalone normative target.

Hmm, segment is most certainly NOT a path. Otherwise using this twisted logic I would have to conclude that if segment
is a PATH then segment is a standalone URI component, which is an obvious fallacy.

Similarly, segment is clearly defined in URI grammar. What makes you think that it is not a valid target of a
URI-related API? Is query parameter not a valid part of the API too? It is certainly not part of the SPEC, worse there
is no grammar in the spec that would define a query parameter...

I'd say that the argumentation based on supporting purely standalone URI components as part of a URI-based API does not
hold. Both - query parameter as well as path segment - are useful and valid URI targets for the purpose of UriBuilder
API and as such we need to treat them as first-class citizens, including support for proper independent template value

Also, please consider the following examples:

UriBuilder.from("").userInfo("{t1}").path("{t2}").segment("{t3}").build("a/b", "a/b", "a/b");

IMHO they all mean the same thing and should produce the same URI:


>> In fact, *both places* have to resolve to an encoded form, as *both*
>> have to take respect of the target, which is the URI's path:
>>> UriBuilder.path("abc/def/{arg1}).segment("123", "456",
>>> "{arg1}").build("A/B")
>>> *obviously* have to resolve exactly to:
>>> abc/def/A%2FB/123/456/A%2FB
>>> and to nothing else!
>>> (If arg1 would be a queryParam, too, THEN (!) it would stay as A/B as
>>> a slash is valid in the query part of the URI!)
>> Basically it seems to me that we agree to the same set of rules, the
>> only difference is that you feel path and path segement are same
>> targets, whereas I argue that they are not. We should focus on
>> resolving this first.
> This has nothing to do with feeling but just with accepting the words of the RFC or your will to add another component named "segment" which definitively IS NOT A STANDALONE NORMATIVE ENTITY.
>> Marek
>>> Can you please explain why you think it would be beneficial to *not*
>> encode the provided value? In what case would that make any sense? And
>> what is your source (spec)?
>>> The sole difference between path and segment is only that using
>> path() you can supply a complete chain of segments, i. e.
>> path("abc/def"), while you have to provide a set of segments using
>> segment(), i. e. segment ("abc", "def"). In fact, it is a fault to
>> provide a slash to a segment as by URI's definition, a segment cannot
>> contain a slash.
>>> But, that has nothing to do with encoding! Encoding will *always* be
>> applied to any build() paramater's value *according to the template
>> parameter's position in the template"! That means, a slash must be
>> encoded in a path() or segment() template, but not in a queryParam()
>> template. And, whatever is given to path() or segment(), will itself
>> get never encoded, as only the values provided to build() are getting
>> encoded.
>>> Everything else just makes no sense to me.
>>> Or can you provide a real world example, where it makes sense to
>> either encode the value given to path() or segment() / not to encode
>> the value given to build()?
>>> Regards
>>> Markus
>>>> -----Original Message-----
>>>> From: Sergey Beryozkin []
>>>> Sent: Dienstag, 25. Oktober 2011 23:27
>>>> To:
>>>> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of
>> UriBuilder
>>>> template parameters
>>>> On 25/10/11 20:50, Marek Potociar wrote:
>>>>> Experts,
>>>>> please read through the following CRITICAL issue& the attached
>>>> comments:
>>>>> I am interested in your feedback to the conclusion I provided in my
>>>>> comment attached to the issue. Please provide your feedback by
>>>>> Monday
>>>> next week Oct 31, 2011 CoB.
>>>> agreed
>>>>> Feel free to attach the feedback or any new comments directly to
>> the
>>>> issue.
>>>>> Many thanks,
>>>>> Marek
>>>> --
>>>> Sergey Beryozkin
>>>> Talend -