The idea is that with these interfaces you will be able to provide a fluent common API for a type-safe access to any
client extension. The two-phase process (Factory->Builder) is there to enable the ability to type-safely configure the
produced custom client before it is built. I took the inspiration in Bean Validation spec. Additionally, the API was
supposed to provide injection support for the custom client builder artifacts.
In an example, I wanted to make sure users are able to write this (see also in JAX-RS API client examples):
ThrottledClient Client = ClientFactory
.newClientBy(ThrottledClient.Builder.Factory.class)
.requestQueueCapacity(10)
.build();
The above produces a ThrottledClient instance that uses a blocking queue to throttle the amount of client requests
flowing through the client instance (see Staged Event Driven Architecture (SEDA) for more on this concept).
Let's analyze the details of the example:
ClientFactory.newClientBy(ThrottledClient.Builder.Factory.class)
instantiates and possibly injects the factory that returns a typed ThrottledClient.Builder instance. The returned
builder exposes a type-safe configuration method...
.requestQueueCapacity(10)
... that is used to configure the client instance request queue capacity (note that this capacity is not modifiable once
the client instance is created). At last a typed ThrottledClient instance is built and returned
.build()
so that the instance information can further be accessed in a type safe way (e.g. client.getRequestQueueCapacity()).
That's for the explanation of why it is designed the way it is designed.
I do not feel too strongly about this part of the API though. There are obviously other ways of achieving at least part
of the same functionality even though I have yet to see a solution that would look more elegant in the code (from the
user's perspective).
To sum up, I like the current API but if you can find more support in EG for removing the API or propose a solid
replacement for the functionality covered by the API, I would not stand in your way...
Marek
On 12/12/2011 02:47 PM, Bill Burke wrote:
> Maybe I should give more detail (again):
>
> * We don't need a set of interfaces the application developer will never see
> * The interfaces are redudant. All you really need is to specify a javax.ws.rs.ext.ClientFactory with the class name of
> your impl's factory within it.
> * If you want to be able to support extensions (i.e. an extended interface to ClientFactory or Client), then it should
> be left up to the provider how they want to support it. For example, I don't want Resteasy to be forced to use your
> interfaces, especially when a typecast or even a constructor invocation would be good enough for this scenario.
>
> On 12/12/11 8:35 AM, Bill Burke wrote:
>> I've already complained about this before and gave in-depth reasons why
>> we don't need these interfaces, but can we please remove Client.Builder
>> and ClientFactoryBuilder? They are not needed by either the jaxrs
>> implementation or the application developer. All logic can be contained
>> within ClientFactory or Java EE app server.
>>
>> I have yet to hear a good reason from you guys why we need this extra
>> bloat.
>>
>> Bill
>>
>