On 15/11/11 19:07, Markus KARG wrote:
>> On 11/11/11 19:23, Markus KARG wrote:
>>> Well, in fact I do not see any confusing in URI encoding, but a lot
>> of confusion in the description of the way JAX-RS handles it. It is
>> just not natural that one has to read *two* JavaDoc locations (path()
>> AND build()) to understand the whole story. It all should be described
>> in one single place in few but clear words. Not scattered among several
>> locations.
>>>
>>
>> In my previous response I tried to sympathize a bit with the plight of
>> the team which spent two days on the URI encoding issue, but you having
>> none of that and just keep blaming the documentation which I just find
>> ridiculous, sorry.
>
> Well, I don't want to respond on what you personally find ridiculous or not. The facts are that the JavaDocs are not unambiguous and two days of my team's time is just too much to just ignore it, and so it need to be changed. I do not see why you make such a story out of this, as finding some improved lines is neither at your personal costs nor something particularly costly to do at all. So what actually do you like to reach with the above? My intention is to improve the docs. What is yours? Stealing my time by forcing answers like this one?
I think the most sensible thing is for me simply not to respond, but
your statement is not fare, misses the fact I agreed few rounds before
that some doc improvements were warranted.
My agenda in this thread is to support Marek's conclusion and stop you
from diverting the original theme of this thread to the deficiencies of
the documentation as opposed to simply saying, "OK, docs needs changing,
here's my new thread which I started and this my new JIRA I opened, but
I do agree with the conclusion". That is my agenda, but I'm failing so I
have nothing more to add accept but only to apologize for the use of
"ridiculous" - it was not quite acceptable
Thanks, Sergey
Can we please go back to discussing facts?
>
>> This particular issue is very straightforward to resolve, the
>> documentation for build() states:
>> "Build a URI, using the supplied values in order to replace any URI
>> template parameters. Values are converted to String using their
>> toString method and are then ***encoded to match the rules of the URI
>> component to which they pertain***"
>>
>> What else one need to tell the users for them to figure out that they
>> need to go and check the documentation of path(), segment(), query(),
>> etc ?
>
> Well, the problem is that it says "URI COMPONENT" but not "METHOD OF PARAMETER REGISTRATION": path() and segment() are methods for parameter registration. But BOTH register parameters in the SAME COMPONENT of an URI: "path", since there is nothing like a "segment" COMPONENT in the description of URI syntax. So, taken that line absolutely literally, it says that path() and segment() MUST work THE SAME wrt encoding -- which it doesn't do, and which nobody but me wanted so far.
>
> But, as we all agreed in the end (even me), both methods do (and shall) work different wrt to encoding of slashes in parameter values, so, what the JavaDocs should in fact say is not "URI COMPONENT" but "METHOD OF PARAMETER REGISTRATION". And, to make it really clear, it would be very beneficial if there would be a short table that gives an overview of the encoding rules for each "METHOD OF PARAMETER REGISTRATION" since otherwise still people would have to check the description of path() and segment() to learn about that.
>
> Regards
> Markus
>
>> IMHO, if someone gets how URI has to be encoded then surely the
>> arguable deficiencies of the docs won't stop him/her from figuring out
>> what the end result has to be. And that was my point. Now, I had my
>> share of confusion to do with the way build() and buildFromEncoded()
>> are supposed to operate but that is another story...
>>
>> Sergey
>>
>>
>>>> -----Original Message-----
>>>> From: Sergey Beryozkin [mailto:sberyozkin_at_talend.com]
>>>> Sent: Mittwoch, 9. November 2011 13:22
>>>> To: jsr339-experts_at_jax-rs-spec.java.net
>>>> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of
>> UriBuilder
>>>> template parameters
>>>>
>>>> Hi Markus, just reread your message, kind of skipped through it
>>>> yesterday :-) On 08/11/11 17:37, Markus KARG wrote:
>>>>> 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.
>>>>>
>>>> Well, I think all to do with URI encoding is confusing and one needs
>>>> to be really well prepared, I can't assert that I really am myself,
>>>> but I think as far as this particular issue is concerned I believe
>>>> the rules are kind of simple, the way the values provided to build()
>>>> have to be encoded according to the rules of particular URI
>> components.
>>>> In this case both path() and segment() all identify the URI path
>> one,
>>>> but we also have segment() further specifying that a "/" has to be
>>>> encoded. Agreed that some better documentation can help
>>>>
>>>> Cheers, Sergey
>>>>
>>>>> 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
>
--
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com