I totally agree with you that the API must be absolutely unambiguous. But exactly this is the point: It IS ambiguous currently. See, our complete team of graduated engineers totally misunderstood how path / segment / build is intended to work in the case of slash encoding. After spending two days (then we invented a workaround). So either we all are dumb idiots (what might be the case), OR the API IS ambiguous. I won't actually say that there ain't a possibility that we ARE dumb idiots, really, but in fact, I do more believe that this particular piece of JavaDoc is just not clearly documented regarding what happens when a slash is found in build(). If the solution is to use segment instead of path, well, that's pretty nice. But THEN we should at least improve the JavaDocs so dumb idiots like our team will understand how the F* one can get %2F in the end when putting in a slash into build(). Particularly, build() should clearly say what happens with slashes for parameter in path() / segment() placeholders, as the encoding is described in build(), and readers do not expect to check a second location to get the whole story.
Regards
Markus
> -----Original Message-----
> From: Sergey Beryozkin [mailto:sberyozkin_at_talend.com]
> Sent: Montag, 7. November 2011 11:41
> To: jsr339-experts_at_jax-rs-spec.java.net
> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of UriBuilder
> template parameters
>
> On 06/11/11 13:51, Markus KARG wrote:
> > Sergey,
> >
> >> -----Original Message-----
> >> From: Sergey Beryozkin [mailto:sberyozkin_at_talend.com]
> >> Sent: Mittwoch, 2. November 2011 11:13
> >> To: jsr339-experts_at_jax-rs-spec.java.net
> >> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of
> UriBuilder
> >> template parameters
> >>
> >> On 01/11/11 18:37, Markus KARG wrote:
> >>>>> what the JIRA issue actually is talking about is not the *name*
> of
> >>>> the parameter, but _solely_ slashes contained in *values* provided
> >> to
> >>>> *build()* (maybe this is not clear in JIRA?).
> >>>> That is the value, with UriBuilder one can just do
> >>>> path("bar").build();
> >>> Wrong. Check http://jackson.codehaus.org/javadoc/jax-
> >>> rs/1.0/javax/ws/rs/core/UriBuilder.html#build(java.lang.Object...):
> >>> Certainly you can provide values to build().
> >>
> >> What is wrong ? Have I said you can't pass pass values to build ?
> >> Look at my last response again please.
> >
> > Well, you response said that one can just do path("bar").build() -- I
> don't see any parameters in build() there. So yes, you said that -- or
> at least I read it that way.
> >
>
> Sorry, I guess I should've used 'also' instead of 'just'...
>
> >>> Actually this issue is just about the values provided to *build*,
> >>> not to *path*. In fact, I opened that JIRA issue *because* I
> >>> experienced the described problem with values passed into *build*.
> >> Well. IMHO whether it's a value which is passed directly to path()
> or
> >> to build(), it probably needs to be consistent.
> >> In other words, the output of
> >>
> >> builder.path(value).build()
> >>
> >> and
> >>
> >> builder.path("{value}").build(value)
> >>
> >> should produce the same output, no ?
> >>
> >> same for segment calls...
> >
> > I think here is the difference in out visions. I actually expect it
> TO BE a difference wheter I pass a value to path(), or to build().
> Otherwise it wouldn't make much sense to have either way to do it. The
> sense of path() is to define position and semantics of parameters.
>
>
> From
> http://jsr311.java.net/nonav/releases/1.1/javax/ws/rs/core/UriBuilder.h
> tml#path(java.lang.String):
>
> "Append path to the existing path. When constructing the final path, a
> '/' separator will be inserted between the existing path and the
> supplied path if necessary. Existing '/' characters are preserved thus
> a single value can represent multiple URI path segments."
>
> It's clear that a single path values may represent multiple segments.
>
> From
> http://jsr311.java.net/nonav/releases/1.1/javax/ws/rs/core/UriBuilder.h
> tml#segment(java.lang.String...):
>
> "Append path segments to the existing path. When constructing the final
> path, a '/' separator will be inserted between the existing path and
> the first path segment if necessary and each supplied segment will also
> be separated by '/'. Existing '/' characters are encoded thus a single
> value can only represent a single URI path segment."
>
> It's also plain obvious that a single parameter to segment(...)
> represents a single URI path segment.
>
> I don't care what build(...) docs say, I'm not even there yet, if I do
> segment("a/b") I need to get "/" encoded but keep "/" if I do
> path("a/b").
>
> The sense of build is to encode values. At least that is what makes
> sense from the view of a user, and it is what the javadocs of JAX-RS
> 1.0 say.
> >
> > Anyway, this is what users need.
>
> Really ? Users need a simple, unambiguous and straightforward api which
> does not give a space for multiple interpretations of how this API will
> work.
>
> > So we have to find a way to make it work. If you have a better
> solution how users can write applications without thinking about
> encoding, please present it. Until then, I do not see another way of
> working with data that contains slashes.
> >
>
> Lets focus at the issue at hand.
> Segment value, either passed to build() or buildFromEncoded() or
> directly to segment() represents a single URI path segment. That is
> all.
> Hence the "/" characters needs to be encoded but in case of
> buildFromEncoded() a care should be taken to avoid the double-encoding
>
> Sergey
>
> > Regards
> > Markus
> >
> >>
> >> Sergey
> >>
> >>>>> Regarding your example: (1) http is part of the scheme, not part
> >>>>> of
> >>>> the path, so the below code is rather error prone. Shouldn't we
> >>>> define specs for correct use instead? (2) As the slashes are part
> >>>> of the
> >>>> *name* of the parameter, and as it just makes no sense to render
> >>>> the URI without providing a value to each parameter in this case,
> >>>> there is no need to touch the name of the parameter, so you will
> >>>> not
> >> encode it.
> >>>>>
> >>>> Cheers, Sergey
> >>>>
> >>>>>
> >>>>> Regards
> >>>>> Markus
> >>>>>
> >>>>>> -----Original Message-----
> >>>>>> From: Sergey Beryozkin [mailto:sberyozkin_at_talend.com]
> >>>>>> Sent: Dienstag, 1. November 2011 18:07
> >>>>>> To: jsr339-experts_at_jax-rs-spec.java.net
> >>>>>> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of
> >>>> UriBuilder
> >>>>>> template parameters
> >>>>>>
> >>>>>> just recently we had a case like this:
> >>>>>>
> >>>>>> builder.path("{http://myns}service").build().
> >>>>>>
> >>>>>> Does "//" have to be encoded or not ?
> >>>>>> I think if I do want to encode then saying
> >>>>>>
> >>>>>> builder.segment("{http://myns}service").build().
> >>>>>>
> >>>>>> makes sense.
> >>>>>>
> >>>>>> However, perhaps this should be treated differently when
> template
> >>>>>> parameters are involved, but I'd not be worried about it
> >>>>>>
> >>>>>> Sergey
> >>>>>>
> >>>>>> On 01/11/11 16:38, 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. I think
> >>>>>> your fault is that you think encoding is depentent of the
> method,
> >>>>>> but
> >> it
> >>>>>> is solely dependend of the target. 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)! 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!)
> >>>>>>>
> >>>>>>> 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 [mailto:sberyozkin_at_talend.com]
> >>>>>>>> Sent: Dienstag, 25. Oktober 2011 23:27
> >>>>>>>> To: jsr339-experts_at_jax-rs-spec.java.net
> >>>>>>>> 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:
> >>>>>>>>>
> >>>>>>>>> http://java.net/jira/browse/JAX_RS_SPEC-70
> >>>>>>>>>
> >>>>>>>>> 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
>
> http://sberyozkin.blogspot.com
> Talend - http://www.talend.com