On 02/09/11 14:08, Marek Potociar wrote:
>
>
> On 09/02/2011 01:48 PM, Sergey Beryozkin wrote:
>>>>> Consider looking at it in the following perspective:
>>>>>
>>>>> 1. Target is a link to a particular resource
>>>>> 2. The invocation above, in terms of resources captures a resource transition:
>>>>>
>>>>> client.target("http://bar").path(1).path(2).path(2).path(4)
>>>>> R1 ----------> R2 ---> R3 ---> R4 ---> R5
>>>>>
>>>>> So, the Target.path() tells you "from here, go there", not "change this resource into that resource".
>>>>>
>>>> OK. This looks OK. I guess I'm saying that .path(1).path(2).path(2).path(4) does look like a classical builder chain to
>>>> me and perhaps it might be a bit confusing...Assuming you want to keep the immutability, then may be rename path() to
>>>> toPath() or next() or forward(), to capture "from here, go there" better.
>>>
>>> I just used the names from UriBuilder, since JAX-RS 1.x users should be familiar with those names.
>>>
>> UriBuilder is a mutable one, isn't it ? That is what I'm trying to say, path().path() is associated with the state being
>> mutated - for me at least. You can have path() unchanged - JavaDocs will be there, but recall your argument about
>> revert(String, String) :-)
>
> State being mutated does not necessarily mean that objects holding the state are mutated too, e.g.:
>
> String s1 = "a";
> String s2 = s1.replace('a', 'b'); // s1 "state" is being mutated
> s1 != s2; // the instances do not mutate with the state!!!
OK. I see what you and Santiago are saying...
>
> In case of UriBuilder, the mutability wrt. URI is understandable. In case of Target it is not.
this is due to to your position on how API should be done - I'm fine
with it though. A week earlier, I'd reply 'What ?' - but I'm getting a
clearer picture why some design decisions have been made this or that
way - not that I agree with them - but I see why at least
And I really don't see
> how my arguments about request(String, String) apply in this context.
>
When we talked about it earlier, I was saying JavaDocs would help to
make it plain obvious that the 1st String is CT, and one of your
counter-arguments was that it was confusing nonetheless when looking at
the code what was where...That is why I referred to it when indicating
JavaDocs would help to understand that path().path() is not mutable
> Anyway, I do understand that you are pointing out at the potential confusion. Still, I'd rather live with such risk than
> to change the 'path()' method name to 'toPath()', 'next()' or 'forward()'. First one is just longer, but does not really
> deal with the potential confusion, and the latter two ones seem just even more confusing.
>
OK
>>>>
>>>>> Another example to illustrate that the resources are really different is here - consider which of the following reads
>>>>> better:
>>>>>
>>>>> A)
>>>>> Target library = Client.target("http://library");
>>>>> Target books = library.path("books");
>>>>> Target dantesDivineComedy = books.queryParam("ISBN-13", "978-0451208637");
>>>>>
>>>>> B)
>>>>> Target library = Client.target("http://library");
>>>>> library = library.path("books");
>>>>> library = books.queryParam("ISBN-13", "978-0451208637");
>>>>>
>>>>> I hope we can agree that A) makes more sense.
Funny we are still talking about A & B :-)
>>>>>
>>>> A) looks fine, but a bit unusual, when I type a URI in the browser, I'm still working with the same URI string, which I
>>>> guess B) captures pretty well.
>>>
>>> What are you trying to say? We don't work here with strings, we work with resources and their URIs. This is not a text
>>> editor API.
>>>
>> I'm simply giving you my feedback. You cleverly chose the naming of Target in A) to demo the immutability and yes, the
>> fact we have 3 individual resources there.
>
> It's not me being clever.
It was a positive statement on my behalf.
> Those 3 different URIs represent different resources. In general different URIs typically
> represent different resources or different resource representations or at least different contexts of the same resource.
> It's not a hard rule, but that's how it typically is, especially in a single-rooted URI hierarchies, which is what we
> are talking about.
>
>> I said that B) can also be used to reflect the actual way a user works with
>> the service.
>
> IMHO, anyone who would use the API as described in B is just a fool with a tool, who sooner or later will hit the wall
> with the code he wrote. There's unfortunately no protection against fools. We can only strongly encourage people to read
> some good books on designing and consuming RESTful services and the principles behind REST before using our API. Our
> users don't need to be REST gurus, but I think it is appropriate to assume at least a basic level of understanding of
> the REST problem domain. Relationship between URIs and Resources IMHO belongs to the very basic REST/ROA concepts.
>
?
Just wondering why I haven't heard CXF users hitting a wall yet, given
that we support the mutability...
> Sure, one can chain the path() methods and ignore the intermediate resource targets in the code, that's perfectly valid.
> But that does not mean that those intermediate resources were suddenly all merged into one library resource. And when I
> say "library resource" I mean *library* resource, not some other esoteric meaning of "library resource" expression.
>
I don;t see how the above relates to my earlier comments. Merged ? Just
because a single var is used ?
Is this totally wrong :
URI lib;
lib = UriBuilder.fromURI(lib).path(books).path(1).build() ?
Does it mean we have merged a /books/1 resource into a lib one ?
Are we at the stage where we can agree to disagree :-) ?
>>
>>>> A is more naturally readable - but you can't get from the books section back to the
>>>> library entry. Which is possible with B...
>>>
>>> Are you really suggesting, that in the example A, after executing line 2 you cannot refer to the library, but in the
>>> (corrected) example B you can?? Are we both still talking about Java code? :)
>>>
>> I clearly said that you can't move back from
>> books to library - are you suggesting that is possible ?
>
> Yes, in A you still have the reference to the original library resource in the library variable, don't you.
>
Are always keeping all the variables we ever need in scope ?
Sergey
> Marek
--
Sergey Beryozkin
http://sberyozkin.blogspot.com
Talend - http://www.talend.com