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

From: Marek Potociar <>
Date: Thu, 22 Dec 2011 18:35:11 +0100

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.

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.

> 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.


> Thanks
> Sergey
>> BTW, there is one issue that is really bad: There are lots of overloaded
>> path() signatures being able to use an annotation's path. But those do
>> not exist for segment(). So how to get this working with automatic %2F
>> encoding? If you don't change the actual implementation, then one must
>> MANUALLY check the value of @Path and apply ReplaceAll("/","%2F") every
>> time. It would make much sense to copy the overloaded signatures into
>> new versions fo segment() then, e. g. segment(Class) and segment(Class,
>> String) so one would get the automatic encoding of slashes without
>> dealing with Reflection API.
>> Regards
>> Markus
>> *From:*Santiago Pericas-Geertsen
>> []
>> *Sent:* Donnerstag, 8. Dezember 2011 19:46
>> *To:*
>> *Cc:* Markus KARG
>> *Subject:* Re: [jax-rs-spec users] [jsr339-experts] Re: HEADS-UP:
>> Encoding values of UriBuilder template parameters
>> On Dec 8, 2011, at 5:07 AM, Marek Potociar wrote:
>> Check the JAX-RS 1.x UriBuilder javadoc for path(String) and
>> segment(String...):
>> <>
>> <>
>> It contains explicit and unambiguous explanation of the difference
>> between encoding segment and path template values as
>> you requested earlier in your email. What we should do in this space wrt
>> issue JAX_RS_SPEC-70 is to improve the summary
>> information about encoding the template values in the class-level
>> javadoc (once we reach an agreement), which is
>> currently incomplete and does not explicitly take path segments or
>> matrix parameters into account even though they are
>> clearly supported by the API as independent contextually encoded entities.
>> I hope that from the referenced javadoc it is clear that in order to
>> support your proposal in JAX_RS_SPEC-70 we would
>> need to break the UriBuilder javadoc, which means breaking BW
>> compatibility of the API at the application level, which
>> we simply cannot do.
>> As I tried to outline earlier, what you want to achieve can be provided
>> via UriBuilder.segment(...) method. This would
>> preserve BW-compatibility with the 1.x API.
>> It's good that you brought this up. I was under the impression the
>> proposal in JAX_RS-SPEC-70 was not BW compatible, and the Javadoc makes
>> that clear.
>> -- Santiago