Hi Markus
On 16/11/11 18:07, Markus KARG wrote:
> Sergey,
>
> agreed. :-)
>
> And sorry for my bad mood, seems I just have had a bad day.
np, sorry too for may be getting you into a mood in the first place :-),
may be I have a 'knack' for that when I become involved in lengthy
discussions :-)
>
> It's OK for me either way: If Marek does an improved JavaDocs that is OK. It is also OK if the JavaDocs stays as it is and the software is made to behave as the JavaDocs tell literally. I just want one consistent and clear solution.
>
Sounds good, Sergey
> Regards
> Markus
>
>> -----Original Message-----
>> From: Sergey Beryozkin [mailto:sberyozkin_at_talend.com]
>> Sent: Mittwoch, 16. November 2011 08:33
>> To: jsr339-experts_at_jax-rs-spec.java.net
>> Subject: [jsr339-experts] Re: HEADS-UP: Encoding values of UriBuilder
>> template parameters
>>
>> 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
>
--
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com