commons-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Attila Szegedi <szege...@freemail.hu>
Subject [HttpClient] Clarification of documentation regarding connection release
Date Fri, 28 May 2004 17:44:23 GMT
Hi all,

the docs at <http://jakarta.apache.org/commons/httpclient/threading.html> state 
that this is the recommended way of using HttpClient to ensure connections are 
released:

try {
    client.executeMethod(get);
    ...
    } finally {
        get.releaseConnection();
    }

Now, this is counterintuitive to me. I'd expect the usage to be:

client.executeMethod(get);
try {
    ...
    } finally {
        get.releaseConnection();
    }

since it's the contract of all well-behaved libraries I came across to date that 
methods that exit abruptly (i.e. throw an exception) must not leave any 
resources allocated. Therefore, it must be safe to call executeMethod() 
*outside* the try block, since if it exits with an exception, the connection 
will not be allocated. I took the time to actually go through the source code of 
HttpClient 2.0, and have found out that:
- HttpClient.java lines 650-678 make sure that the connection object gets 
released if the connection can't be established. 
- HttpMethodBase.java lines 2663-2696 make sure that the connection is closed if 
an exception is encountered during sending request/receiving response. 
These catch blocks have the "doneWithConnection = true" statement that'll in 
turn cause releasing of the connection object in HttpMethodBase.java, 
lines 1122-1124.
 
The only case an already allocated connection object won't get released in a 
failed call to executeMethod() is in two cases of incorrect usage by the 
library's client. These are:
- a HttpMethod object is reused without being recycle()d first, (exception 
thrown in HttpMethodBase.java line 1007).
- preemptive authentication is used, but the supplied credentials aren't 
username/password but some other kind of credentials (exception thrown in 
HttpAuthenticator.java line 204).

(Now, you could claim that these conditions are incorrect usage of the library 
and that you feel no obligation to release the connection under these 
circumstances, but IMHO you should.)

Anyway, it'd be good if the documentation at the URL cited above would be 
changed to indicate that the executeMethod() should be called *outside* the try 
block - I think it's just the standard rule for all well-behaved libraries that 
users of the library are expected to release a resource only after the method 
that allocated the resource completes normally.

Regards,
  Attila.

-- 
home: http://www.szegedi.org
Visit Szegedi Butterfly fractals at:
  http://www.szegedi.org/fractals/butterfly/index.html



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-user-help@jakarta.apache.org


Mime
View raw message