/usr/share/doc/libcommons-httpclient-java/docs/threading.html is in libcommons-httpclient-java-doc 3.1-14.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - Threading</title><style type="text/css" media="all">
@import url("./style/maven-base.css");
@import url("./style/maven-theme.css");@import url("./style/project.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Michael Becke"></meta><meta name="email" content="becke@u.washington.edu"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src=""></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="./images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
<span class="separator">|</span> Doc for 3.1
</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="features.html">Features</a></li><li class="none"><a href="news.html">News</a></li><li class="none"><a href="status.html">Status</a></li><li class="none"><a href="downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="userguide.html">User Guide</a><ul><li class="none"><a href="authentication.html">Authentication Guide</a></li><li class="none"><a href="charencodings.html">Character Encodings</a></li><li class="none"><a href="cookies.html">Cookies</a></li><li class="none"><a href="exception-handling.html">Exception Handling</a></li><li class="none"><a href="logging.html">Logging Guide</a></li><li class="none"><a href="methods.html">Methods</a></li><li class="none"><a href="performance.html">Optimization Guide</a></li><li class="none"><a href="preference-api.html">Preference Architecture</a></li><li class="none"><a href="redirects.html">Redirects Handling</a></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="sslguide.html">SSL Guide</a></li><li class="none"><strong><a href="threading.html">Threading</a></strong></li><li class="none"><a href="troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Introduction"></a><h2>Introduction</h2>
<p>This document provides an overview of how to use HttpClient safely from within a
multi-threaded environment. It is broken down into the following main sections: </p>
<ul>
<li><a href="#MultiThreadedHttpConnectionManager">MultiThreadedHttpConnectionManager</a></li>
<li><a href="#Connection_Release">Connection Release</a></li>
</ul>
<p>Please see the <a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/MultiThreadedExample.java?view=markup" class="externalLink" title="External Link">MultiThreadedExample</a>
for a concrete example.</p>
</div><div class="section"><a name="MultiThreadedHttpConnectionManager"></a><h2>MultiThreadedHttpConnectionManager</h2>
<p>The main reason for using multiple theads in HttpClient is to allow the
execution of multiple methods at once (Simultaniously downloading the latest builds of HttpClient and
Tomcat for example). During execution each method uses an instance of an HttpConnection.
Since connections can only be safely used from a single thread and method at a time and
are a finite resource, we need to ensure that connections are properly allocated to the methods that require them.
This job goes to the <a href="apidocs/org/apache/commons/httpclient/MultiThreadedHttpConnectionManager.html">MultiThreadedHttpConnectionManager</a>.</p>
<p>To get started one must create an instance of the MultiThreadedHttpConnectionManager
and give it to an HttpClient. This looks something like:</p>
<div class="source"><pre>
MultiThreadedHttpConnectionManager connectionManager =
new MultiThreadedHttpConnectionManager();
HttpClient client = new HttpClient(connectionManager);
</pre></div>
<p>This instance of HttpClient can now be used to execute multiple methods from multiple
threads. Each subsequent call to HttpClient.executeMethod() will go to the connection
manager and ask for an instance of HttpConnection. This connection will be checked out
to the method and as a result it must also be returned. More on this below in <b>Connection Release</b>.</p>
<div class="subsection"><a name="Options"></a><h3>Options</h3>
<p>The MultiThreadedHttpConnectionManager supports the following options:</p>
<table class="bodyTable">
<tr class="a">
<td>connectionStaleCheckingEnabled</td>
<td>The <tt>connectionStaleCheckingEnabled</tt> flag to set on all created connections. This value
should be left <tt>true</tt> except in special circumstances. Consult the
<a href="apidocs/org/apache/commons/httpclient/HttpConnection.html#setStaleCheckingEnabled(boolean)">HttpConnection</a>
docs for more detail.</td>
</tr>
<tr class="b">
<td>maxConnectionsPerHost</td>
<td>The maximum number of connections that will be created for any particular
HostConfiguration. Defaults to 2.</td>
</tr>
<tr class="a">
<td>maxTotalConnections</td>
<td>The maximum number of active connections. Defaults to 20.</td>
</tr>
</table>
<p>In general the connection manager makes an attempt to reuse connections
for a particular host while still allowing different connections to
be used simultaneously. Connection are reclaimed using a least recently
used approach.</p>
</div>
</div><div class="section"><a name="Connection_Release"></a><h2>Connection Release</h2>
<p>One main side effect of connection management is that connections must
be manually released when no longer used. This is due to the fact
that HttpClient cannot determine when a method is no longer using its connection.
This occurs because a method's response body is not read directly by
HttpClient, but by the application using HttpClient. When the response is read it must obviously make use of the method's
connection. Thus, a connection cannot be released from a method until the method's
response body is read which is after HttpClient finishes executing the
method. The application therefore must manually release the
connection by calling releaseConnection() on the method after the
response body has been read. To safely ensure
connection release HttpClient should be used in the following manner:</p>
<div class="source"><pre>
MultiThreadedHttpConnectionManager connectionManager =
new MultiThreadedHttpConnectionManager();
HttpClient client = new HttpClient(connectionManager);
...
// and then from inside some thread executing a method
GetMethod get = new GetMethod("http://jakarta.apache.org/");
try {
client.executeMethod(get);
// print response to stdout
System.out.println(get.getResponseBodyAsStream());
} finally {
// be sure the connection is released back to the connection
// manager
get.releaseConnection();
}
</pre></div>
<p>Particularly, notice that the connection is released regardless of
what the result of executing the method was or whether or not an
exception was thrown. For every call to HttpClient.executeMethod there
must be a matching call to method.releaseConnection().</p>
</div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
|