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...):
>
> http://jsr311.java.net/nonav/releases/1.1/javax/ws/rs/core/UriBuilder.html#path%28java.lang.String%29
> http://jsr311.java.net/nonav/releases/1.1/javax/ws/rs/core/UriBuilder.html#segment%28java.lang.String...%29
>
> 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