On 8/26/11 5:53 AM, Marek Potociar wrote:
>
>
> On 08/25/2011 10:27 PM, Bill Burke wrote:
>>
>>
>> On 8/25/11 3:33 PM, Marek Potociar wrote:
>>> On 08/25/2011 08:25 PM, Bill Burke wrote:
>>>>
>>>>
>>>> On 8/25/11 12:49 PM, Markus KARG wrote:
>>>>> While I understand Bill's concerns as a vendor, I need to say that I more care for preventing errors than for reducing
>>>>> the number of classes in this case. As the user will only get in touch the methods, but not directly get in touch with
>>>>> the classes (they do not care that the methods in turn create instances of different classes) the number of classes
>>>>> should not become a problems for users.
>>>>>
>>>>
>>>> This has nothing to do about being a vendor. Its about users being able to understand the API. I don't know where you
>>>> got that idea from...
>>>>
>>>
>>> I would side Markus here - understanding of a fluent API is not expected to be conveyed as a list of class and method
>>> descriptions. It's like learning English from a dictionary without understanding the proper sentence structure. Fluent
>>> API's are best learned by examples. Class hierarchy plays a marginal role when it comes to learning how to use a
>>> *fluent* API.
>>>
>>
>> You make it sound like I'm against a fluent API, I'm not. I just think you can be both fluent and readable, especially
>> when the inconsistencies you've outlined are both edge cases, opinion-based inconsistencies, and something the user will
>> never run into. I've also pointed out a few instances where your API is quite awkward to use.
>>
>> In English, there's many ways to structure a sentence to say the same thing. For example:
>>
>> Your API is like spaghetti to me.
>> Your API, to me, is like spaghetti.
>> Your API is, to me, like spaghetti.
>> To me, your API is like spaghetti.
>>
>> Its all a matter of perspective. Same could be said for how one would like to build an HTTP request. But, saying that
>> "understanding a fluent API is not expected to be conveyed as a list of...descriptions" is a huge cop-out, a lame excuse
>> for a bad design. Especially when we're arguing about trivial differences in opinion that nobody really cares about
>> outside of this list!
>>
>> Anyways, good luck, it's clear I'm not getting anywhere with these arguments, so I give up.
>>
>
> I'm not saying you are against fluent API. I am saying you don't have one. Your design is simple and allows for method
> chaining, but it is not a fluent API at all, because a fluent API is more than just method chaining:
>
request().invoke() is an inconsistency, I'll give you that. But,
request().header(...).method(...).header(...) is not an inconsistency.
The fact that you don't like it is just a matter of personal taste.
One last try:
You could redefine the problem a bit. Remove the ability to change the
method name in the request. Remove the ability to do invoke()/submit()
style invocations. Its really questionable whether *real* users want
these features anyways as they were both suggested, IIRC, by one of us
guessing users would want those features.
If you remove both of those, you get both a
design-that-Bill-thinks-is-simpler and an
API-that-Marek-thinks-is-purely-fluent.
https://github.com/patriot1burke/redhat-jaxrs-2.0-proposals-rev2/tree/master/jax-rs-api-r3/src/main/java/javax/ws/rs
I removed HttpRequest.method(String). invoke()/submit() methods now
take a methodName parameter so that you can make a non-standard HTTP
method invocation. (It made sense to use those method names instance of
method()).
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com