Review of new Http client API

[Michael McMahon]

Paul,

Thanks for looking at it. Yes, this is an area that needs some more work.
The current thinking is along the lines that Chris just posted and I hope to
have another version of the API to look at tomorrow.

What you suggest seems like an unusual usage of Future<>  as we have 
tried to provide
a mode of operation where applications can get a Future<HttpResponse>
which would work in the conventional way of returning the result "in the 
future".
But, it raises a question in that while we currently have callback 
interfaces for both
headers and data, we only have a Future based interface for headers (but 
not data).

- Michael

On 23/08/12 15:20, Paul Sandoz wrote:
> Hi,
>
> A potential simplification of the HttpResponseHeadersHandler interface is to turn it into a functional interface:
>
>    HttpResponseHandler onHeaders(Future<HttpResponse>  dresp) throws InterruptedException, ExecutionException;
>
> [Chris, i am not sure if an interface with two methods, one default, is classified as a functional interface.]
>
> - mirrors the pull-based asynchronous approach
>
> - dresp.isDone() always returns true
>
> - the Future encapsulates the underling exception, if any
>
> - harder to swallow errors, since the exception from drep.get() will propagate if not caught.
>
> - a return of a null HttpResponseHandler means "not interested in the body".
>
> FWIW the use of Future is the approach i chose for the Jersey client.
>
> HttpResponseHandler would also be a functional interface:
>
>      void onBodyPart(Future<ByteBuffer>  bb) throws InterruptedException, ExecutionException
>
> - there is no inheritance relationship between HttpResponseHeadersHandler and HttpResponseHandler.
>
> - a "bb" with a capacity of 0 indicates the last part.
>
> - the HttpResponse is not required as a parameter because the implementation can obtain it from the onHeaders method.
>
> If the use of Future is a bit extreme for some :-) then things can still be simplified by following the above approach with an additional, and optional, functional interface to handle errors when HttpClient.sendRequest is called.
>
> --
>
> Rather than setting the bytes on the HttpRequest with numerous methods i wonder if it is better to have a functional interfaces for both OutputStream and the NIO equivalent:
>
>    interface EntityWriter<T>  { // Oh for disjunct types!
>      /**
>       * @return true if there is more to write
>       */
>      boolean write(T t) throws IOException;
>    }
>
> I believe the above can support all the existing functionality currently expressed as methods, including the Iterable/Iterator. There can be instances of EntityWriter for common functionality:
>
>    EntityWriters.fromBytes(byte[] b, ...);
>
> The same might be applicable to HttpResponse with an EntityReader:
>
>    interface EntityReader<T, U>  {
>      U read(T t) throws IOException;
>    }
>
> Of course i might be missing something obvious here in terms of optimisation currently performed by the implementation!
>
> --
>
> It somewhat bugs me that blocking and asynchronous pull/push functionality is all defined using the same artifacts. But, my imagination is currently is failing me on how to improve on such matters. Perhaps something better may come out of fluent-based API?
>
> Paul.
>
> On Aug 14, 2012, at 2:01 PM, Michael McMahon<michael.x.mcmahon at oracle.com>  wrote:
>
>> Hi,
>>
>> (apologies for sending this again)
>> We have just published a draft of a proposed new Http client API [1] for JDK 8.
>>
>> This message has been cc'd to jdk8-dev so that as many people as possible
>> know about it, but the discussion will be on the net-dev list (net-dev at openjdk.java.net).
>> So, folks will have to join that list [2], in order to take part.
>>
>> Thanks,
>> Michael.
>>
>> [1] http://cr.openjdk.java.net/~michaelm/httpclient/v0.3/
>>
>> [2] http://mail.openjdk.java.net/mailman/listinfo/net-dev