On 09/02/2011 03:31 PM, Santiago Pericas-Geertsen wrote:
>
> 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 <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
>
The way I understand it, it's the mutability of UriBuilder that may cause the confusion. But as I said, it seems to me
that the potential confusion is more of an academic than a practical issue in this case.
Marek