Mailing-List: contact dev-help@hc.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "HttpComponents Project" <dev@hc.apache.org>
Received-SPF: neutral (nike.apache.org: local policy)
Subject: Re: HttpEntity#consumeContent deprecated; was Re:
 HttpEntity#writeTo and #consumeContent
From: Oleg Kalnichevski <olegk@apache.org>
To: HttpComponents Project <dev@hc.apache.org>
In-Reply-To: <1270912340.3286.27.camel@isaac>
References: <1270750680.3593.22.camel@isaac>
	 <1270752939.3166.14.camel@ubuntu>  <1270754311.3593.36.camel@isaac>
	 <1270755948.5587.15.camel@ubuntu>  <1270759124.3593.42.camel@isaac>
	 <1270840361.2345.5.camel@ubuntu>  <1270912340.3286.27.camel@isaac>
Content-Type: text/plain; charset="UTF-8"
Date: Sat, 10 Apr 2010 17:43:56 +0200
Message-ID: <1270914236.4493.12.camel@ubuntu>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On Sat, 2010-04-10 at 11:12 -0400, James Leigh wrote:
> On Fri, 2010-04-09 at 21:12 +0200, Oleg Kalnichevski wrote:
> > ...
> > 
> > > > 
> > > > > I still don't understand what should be done if an IOException occurs
> > > > > (or RuntimeException) while in the read() method. Must consumeContent be
> > > > > called then? Or, in an exception enough to consider the stream released?
> > > > > 
> > > > 
> > > > When reading from an input stream, #close method should be called from a
> > > > finally clause to ensure proper resource release. 
> > > > 
> > > 
> > > Sounds like you think/agree that writeTo implementations should close
> > > the inputstream in a finally block (since they read from it). I'll file
> > > a bug report and include a patch next week.
> > > 
> > > James
> > > 
> > 
> > James et al
> > 
> > I deprecated HttpEntity#consumeContent in favor of a more standard
> > InputStream#close contract. Javadocs / tutorial have been updated to
> > describe the recommended way to ensure resource deallocation: 
> > 
> > http://svn.apache.org/viewvc?rev=932551&view=rev
> > 
> > Please review / comment / critique
> > 
> > Oleg
> > 
> 
> Thanks for doing this Oleg. However, it is not clear from the revised
> javadocs if getContent().close() must be called if the content is not
> read. 

The trouble is this very much depends on the connection management
logic, which is out of scope for HttpCore. If one does not intent to
re-use the underlying connection is going to close it in any way, there
is no point reading the content.

I intent to address this issue in the documentation for HttpClient once
HttpClient is upgraded to the next version of HttpCore.  

> There needs to be a clear way to free the resources of the
> HttpMessage even if the caller does not care to process the HTTP message
> body.
> 
> I also want to point out another use-case that is relevant here. Often
> the HttpResponse is dependent on external resources, such as a database
> connections or a read locks, and these need to be closed when the
> response message body is consumed.

I am not entirely sure this is a good idea to make HttpResponse
responsible for cleanup of such resources. Unless I am missing
something, it just does not sound right to me.


>  By using InputStream#close() as the
> signal to free up resources the implementers are required to wrap the
> underlying InputSteam to intercept this call and release locks and/or
> free db connections. This prevents some read optimizations to occur.
> 
> In the case of a FileInputStream, for example, the OS can bypass
> in-memory buffers using FileChannel#transferTo, but a FileInputStream
> wound not be detectable if the InputStream was wrapped. However, by
> using the ProducingNHttpEntity interface the finish() method allows
> implementers to override the clean-up method without interfering with
> read optimizations, such as with NFileEntity.
> 
> While getContent().close() works there are now many ways to clean-up the
> same resources and the javadocs need to be very clear. Perhaps more
> information in needed in HttpMessage and its sub-interfaces?
> 

I am not much of a writer. I always tend to be too terse with my
writing. Please do feel free to improve the javadocs and submit the
changes as a patch.

Cheers

Oleg


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org