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

From: Sergey Beryozkin <>
Date: Fri, 23 Dec 2011 10:47:55 +0000

On 22/12/11 17:35, Marek Potociar wrote:
> On 12/22/2011 11:01 AM, Sergey Beryozkin wrote:
>> Hi All,
>> On 21/12/11 17:24, Markus KARG wrote:
>>> A JavaDoc change is all I asked for (while I would really love to see
>>> the API work as I proposed, instead). :-) But note that segment() is
>>> currently NOT able to encode slashes in JAX-RS 1.0, as I wrote you
>>> privately before, so to get %2F one must actually encode this MANUALLY
>>> at the moment (I want to get rid of String.ReplaceAll)! So technically
>>> spoken, you won't break too much anyways… ;-)
>> Is it a spec issue or a specific implementation issue ?
> Was found in implementation, but it turned out it affects TCK, so it needs to be addressed in the spec because the TCK
> is currently enforcing behavior that is undefined by the spec and inconsistent with treating path template variables in
> @Path annotation.
>> I'm really sorry if I'm showing my ignorance here. I'm finding it difficult and daunting to figure out from this thread
>> why the need for the new build overload is needed,
>> Please, for my benefit as well as for the benefit of others who may've not followed this thread, give 2 examples
>> demonstrating
>> 1. The combination of segment() and path() is not enough to resolve unambiguously the issue of encoding template parameters
> Read the javadoc of the above carefully. It took me some time too to realize that the javadoc does not specify template
> value encoding. It only discusses how the particular string input is encoded.
I recall now asking Paul about it all.
My position is that
path("a/b") and path("{a}"), segment("a/b") and segment("{a}") both
contribute to the same final result.
IMHO it does not matter where the values came from, whether they have
been passed to path()/segment completely or fed in later on via build(),
the rules of path() and segment() needs to be consistent and applicable
in the same way in all the cases.

> The encoding of template values should be controlled by the build method, but when it comes to path templates, the
> build() javadoc does not say much either.

we have build() and buildFromEncoded(), two variations which say what
sort of data (encoding wise) have been submitted.
IMHO it's not the right approach to get the build() take the extra
responsibility - this needs to retain with path() & segment().

We need to get the fix done to the UriBuilder java docs, and say that
the data passed in to segment() directly or indirectly are controlled by
the segment() rules

>> 2. What happens with builder.segment("{bar}").path("{foo}") and a value 'true' passed to a new overload, where a "{bar}"
>> substitution will also contain "/" characters. I feel at the moment that given that both segment() and path() operate on
>> the same URI component this extra flag will confuse people like me at least a lot
> I fail to understand what would make the new method so confusing, esp. if it is carefuly and extensively javadoced.
> Users don't have to use the new method. It is just a fall-back for people who would by any chance rely on the old
> behavior enforced by TCK but not covered by the spec. For all other people nothing changes.

I'll comment a bit later on this one,

> Marek