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!!!
In case of UriBuilder, the mutability wrt. URI is understandable. In case of Target it is not. And I really don't see
how my arguments about request(String, String) apply in this context.
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.
>>>
>>>> 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.
>>>>
>>> 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. 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.
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.
>
>>> 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.
Marek