On Sep 2, 2011, at 7:48 AM, 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) :-)
On the topic of immutability and chaining path()'s, let me add my $.02. I think there's value in defining Target immutable, much like there's value in defining String immutable. I can pass it around with the guarantee that no other class will change it. With Strings I can also write:
new String("abc").append("def").append("ghk") (1)
and should know from the documentation that a new String is created on each step. Builder patterns typically use a build() method at the end of the chain, and the type returned by the intermediate steps is different from that returned by build().
Perhaps the origin of this discussion can be traced back to Form and the proposed chaining of:
new Form().param(…).param(…) (2)
which has different semantics since Form was defined as mutable. I would agree that this could create some confusion since mutable classes don't often allow method chaining as shown above. OTOH, I can't think of a case in which a Form with one param can be used to create other Forms with more params to justify its immutability.
If (2) is really the reason for this discussion, maybe we should look at alternatives to it that are less confusing.
-- Santiago