Http client API

[Kurchi Subhra Hazra]

Just as a reminder, for reading the response, we had originally decided to
simply terminate whatever bytebuffer/byte arrays we have with a -1 to 
indicate
EOF. But if returning the number of bytes read results in cleaner code, 
maybe we should do this.

>>
>> HttpResponse::
>>
>> - getBodyAsBytes(byte[], int) - I would rather the return the number 
>> of bytes put into the buffer.
> yes. Actually the number of bytes read needs to be returned somewhere. 
> It should return
> an int or long
>> - getBodyAsBytes(byte[], int) - Why would I ever want a max size less 
>> than the size of my byte buffer?
> I originally wanted to implement the no-arg getBodyAsBytes() using the 
> other method.
> Maybe it's better to replace them both with:
>
> long getBodyAsBytes(byte[] buffer) - buffer can't be null, use entire 
> buffer, return # bytes read
> byte[] getBodyAsBytes() - size limited by 
> HttpClient.getResponseBodyBufferLimit()
>
>> - getBodyAsBytes -- Document handling for content-length>  
>> Integer.MAX_VALUE
> dealt with implicitly from above change and the response body buffer 
> limit itself.
>> - getBodyAsByteBuffers -- handling for not enough space in the array 
>> needs to be documented. Unused entries nulled out?
> situation would only arise through ByteBuffer allocation failure, and 
> presumably OOM exception would be thrown.
> Is it necessary to document this?
>> - Perhaps maxlength ->  maxBytes to be more clear?
>>
>> - getBodyAsByteBufferSource -- if the same iterator is always 
>> returned why not return the iterator rather than an iterable?
> The idea was to allow for use of the foreach convenience. eg
>
> Iterable<ByteBuffer>  buffers = response.getBodyAsByteBufferSource();
> for (ByteBuffer buffer : buffers) {
>     // handle data in buffer
> }
>
>
> This raises the same concern then about the Iterable being 
> non-restartable, which in this case
> it clearly can't be. This is a "one-shot" streaming API. I notice that 
> the documentation for
> Iterable is rather terse and doesn't say whether
> this usage is encouraged or discouraged. So, I'm not sure now. The 
> question is if programmers would
> really be confused by the fact that the Iterable can only be used to 
> return one Iterator instance.
>>
>>
>> HttpConnectionCache.CachedConnection::
>> - I would expect this to be abstract and that client providers would 
>> extend.
>>
>> - getCache() to return the client provider.
>>
>>
>> On Aug 7 2012, at 16:09 , Michael McMahon wrote:
>>
>>> Hi,
>>>
>>> A new revision of the Http client API planned for jdk 8 can be viewed
>>> at the following link
>>>
>>> http://cr.openjdk.java.net/~michaelm/httpclient/v0.3/
>>>
>>> We would like to review the api on this mailing list.
>>> So, all comments are welcome.
>>>
>>> Thanks
>>> Michael McMahon.
>
>