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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - HttpClient exception handling guide</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="Oleg Kalnichevski"></meta><meta name="email" content="oleg -at- ural.ru"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://jakarta.apache.org/images/jakarta-logo.gif"></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"><strong><a href="exception-handling.html">Exception Handling</a></strong></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"><a href="threading.html">Threading</a></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="Exception_handling"></a><h2>Exception handling</h2>
<p>
There are two main type of exceptions that the user of HttpClient may encounter
when executing HTTP methods:
<ol>
<li><strong>transport exceptions</strong></li>
<li><strong>protocol exceptions</strong></li>
</ol>
Not all of these exceptions will be propagated to the user in regular HttpClient use.
Exceptions handled internally by HttpClient are marked below as <b>INTERNAL</b>.
</p>
<ul>
<li><a href="#Transport_exceptions">Transport exceptions</a></li>
<li><a href="#Protocol_exceptions">Protocol exceptions</a></li>
<li><a href="#HTTP_transport_safety">HTTP transport safety</a></li>
<li><a href="#Automatic_exception_recovery">Automatic exception recovery</a></li>
<li><a href="#Custom_exception_handler">Custom exception handler</a></li>
</ul>
</div><div class="section"><a name="Transport_exceptions"></a><h2>Transport exceptions</h2>
<p>
Transport exceptions are those caused by input/output failures such as an unreliable connection
or an inability to complete the execution of an HTTP method within the given time constraint
(socket timeout). Generally transport exceptions are non-fatal and may be recovered from by
retrying the failed method. However, special care must be taken when recovering from
exceptions in non-idempotent methods (refer to <a href="#HTTP_transport_safety">HTTP transport safety</a>
for details).
</p>
<div class="subsection"><a name="java_io_IOException"></a><h3>java.io.IOException</h3>
<p>
Generic transport exceptions in HttpClient are represented by the standard Java
java.io.IOException class or its sub classes such as java.net.SocketException and
java.net.InterruptedIOException.
</p>
<p>
In addition to standard input/output exception classes HttpClient defines several custom transport
exceptions that convey HttpClient specific information.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_NoHttpResponseException"></a><h3>org.apache.commons.httpclient.NoHttpResponseException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.NoHttpResponseException</pre></div>
<p>
In some circumstances, usually when under heavy load, the web server may be able to receive
requests but unable to process them. A lack of sufficient resources like worker threads is a good
example. This may cause the server to drop the connection to the client
without giving any response. HttpClient throws NoHttpResponseException when it encounters
such a condition. In most cases it is safe to retry a method that failed with
NoHttpResponseException.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_ConnectTimeoutException"></a><h3>org.apache.commons.httpclient.ConnectTimeoutException</h3>
<div class="source"><pre>
java.io.IOException
+- java.io.InterruptedIOException
+- org.apache.commons.httpclient.ConnectTimeoutException</pre></div>
<p>
This exception signals that HttpClient is unable to establish a connection with the target
server or proxy server within the given period of time.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_ConnectionPoolTimeoutException"></a><h3>org.apache.commons.httpclient.ConnectionPoolTimeoutException</h3>
<div class="source"><pre>
java.io.IOException
+- java.io.InterruptedIOException
+- org.apache.commons.httpclient.ConnectTimeoutException
+- org.apache.commons.httpclient.ConnectionPoolTimeoutException</pre></div>
<p>
This exception can only occur when using the multithreaded connection manager. The exception
signals that the connection manager fails to obtain a free connection from the connection pool
within the given period of time.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_HttpRecoverableException"></a><h3>org.apache.commons.httpclient.HttpRecoverableException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.HttpRecoverableException</pre></div>
<p>
Deprecated and no longer thrown any of the standard HttpClient classes.
</p>
</div>
</div><div class="section"><a name="Protocol_exceptions"></a><h2>Protocol exceptions</h2>
<p>
Protocol exceptions generally indicate logical errors caused by a mismatch between the client
and the server (web server or proxy server) in their interpretation of the HTTP specification.
Usually protocol exceptions cannot be recovered from without making adjustments to either
the client request or the server. Some aspects of the HTTP specification allow for different,
at times conflicting, interpretations. HttpClient can be configured to support different degrees
of HTTP specification compliance varying from very lenient to very strict.
</p>
<div class="subsection"><a name="org_apache_commons_httpclient_HttpException"></a><h3>org.apache.commons.httpclient.HttpException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException</pre></div>
<p>
HttpException represents an abstract logical error in HttpClient. Generally this kind of exception
cannot be automatically recovered from.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_ProtocolException"></a><h3>org.apache.commons.httpclient.ProtocolException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException</pre></div>
<p>
ProtocolException signals a violation of the HTTP specification. It is important to note that HTTP
proxies and HTTP servers can have different level of HTTP specification compliance. It may be
possible to recover from some HTTP protocol exceptions by configuring HttpClient to be more
lenient about non-fatal protocol violations.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_auth_MalformedChallengeException"></a><h3>org.apache.commons.httpclient.auth.MalformedChallengeException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.auth.MalformedChallengeException</pre></div>
<p><b>INTERNAL</b></p>
<p>
MalformedChallengeException signals that an authentication challenge is in some way invalid or
illegal in the given authentication context.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_auth_AuthenticationException"></a><h3>org.apache.commons.httpclient.auth.AuthenticationException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.auth.AuthenticationException</pre></div>
<p><b>INTERNAL</b></p>
<p>
AuthenticationException signals a failure in the authentication process. Usually authentication
exceptions are handled internally when executing HTTP methods and are not propagated to the
caller.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_auth_AuthChallengeException"></a><h3>org.apache.commons.httpclient.auth.AuthChallengeException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.auth.AuthenticationException
+- org.apache.commons.httpclient.auth.AuthChallengeException</pre></div>
<p><b>INTERNAL</b></p>
<p>
AuthenticationException is thrown when HttpClient is unable to respond to any of the authentication
challenges sent by the server.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_auth_CredentialsNotAvailableException"></a><h3>org.apache.commons.httpclient.auth.CredentialsNotAvailableException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.auth.AuthenticationException
+- org.apache.commons.httpclient.auth.CredentialsNotAvailableException</pre></div>
<p><b>INTERNAL</b></p>
<p>
CredentialsNotAvailableException indicates that credentials required to respond to the authentication
challenge are not available.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_auth_InvalidCredentialsException"></a><h3>org.apache.commons.httpclient.auth.InvalidCredentialsException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.auth.AuthenticationException
+- org.apache.commons.httpclient.auth.InvalidCredentialsException</pre></div>
<p><b>INTERNAL</b></p>
<p>
InvalidCredentialsException indicates that the credentials used to respond to the authentication
challenge have been rejected by the server.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_cookie_MalformedCookieException"></a><h3>org.apache.commons.httpclient.cookie.MalformedCookieException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.cookie.MalformedCookieException</pre></div>
<p><b>INTERNAL</b></p>
<p>
MalformedCookieException signals that the cookie is in some way invalid or illegal in the given
HTTP session context.
</p>
<p>
There are several cookie specifications that are often incompatible. Thus the validity of
a cookie is established within a context of a specific cookie specification used to parse
and validate the cookie header(s) sent by the server. If the application needs to process cookies
differently from the commonly used cookie specifications, it may choose to provide a
custom cookie policy or extend the existing one. Please see <a href="cookies.html">cookies</a>
for more details.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_RedirectException"></a><h3>org.apache.commons.httpclient.RedirectException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.ProtocolException
+- org.apache.commons.httpclient.RedirectException</pre></div>
<p>
RedirectException signals violation of the HTTP specification caused by an invalid
redirect response. If the application that uses HttpClient needs to be more lenient
about redirect responses, it may choose to disable automatic redirect processing and implement
a custom redirect strategy.
</p>
</div>
<div class="subsection"><a name="org_apache_commons_httpclient_URIException"></a><h3>org.apache.commons.httpclient.URIException</h3>
<div class="source"><pre>
java.io.IOException
+- org.apache.commons.httpclient.HttpException
+- org.apache.commons.httpclient.URIException</pre></div>
<p>
URIException is thrown when the request URI violates the URI specification.
</p>
</div>
</div><div class="section"><a name="HTTP_transport_safety"></a><h2>HTTP transport safety</h2>
<p>
It is important to understand that the HTTP protocol is not well suited for all types of applications.
HTTP is a simple request/response oriented protocol which was initially designed to support static
or dynamically generated content retrieval. It has never been intended to support transactional
operations. For instance, the HTTP server will consider its part of the contract fulfilled if it
succeeds in receiving and processing the request, generating a response and sending a status code back
to the client. The server will make no attempts to roll back the transaction if the client fails to
receive the response in its entirety due to a read timeout, a request cancellation or a system crash.
If the client decides to retry the same request, the server will inevitably end up executing the same
transaction more than once. In some cases this may lead to application data corruption or inconsistent
application state.
</p>
<p>
Even though HTTP has never been designed to support transactional processing, it can still be used
as a transport protocol for mission critical applications provided certain conditions are met. To
ensure HTTP transport layer safety the system must ensure the idempotency of HTTP methods on the
application layer.
</p>
<div class="subsection"><a name="Idempotent_methods"></a><h3>Idempotent methods</h3>
<p>HTTP/1.1 specification defines idempotent method as</p>
<blockquote>
<p>
Methods can also have the property of "idempotence" in that (aside from error or expiration
issues) the side-effects of N > 0 identical requests is the same as for a single request.
</p>
</blockquote>
<p>
In other words the application ought to ensure that it is prepared to deal with the
implications of multiple execution of the same method. This can be achieved, for instance,
by providing a unique transaction id and by other means of avoiding execution of the same
logical operation.
</p>
<p>
Please note that this problem is not specific to HttpClient. Browser based applications
are subject to exactly the same issues related to HTTP methods non-idempotency.
</p>
</div>
</div><div class="section"><a name="Automatic_exception_recovery"></a><h2>Automatic exception recovery</h2>
<p>
By default HttpClient attempts to automatically recover from exceptions. The default
auto-recovery mechanism is limited to just a few exceptions that are known to be safe.
</p>
<p>
HttpClient will make no attempt to recover from any logical or HTTP protocol error (those derived
from HttpException class).
</p>
<p>
HttpClient will automatically retry up to 5 times those methods that fail with a transport exception
while the HTTP request is still being transmitted to the target server (i.e. the request has
not been fully transmitted to the server).
</p>
<p>
HttpClient will automatically retry up to 5 times those methods that have been fully transmitted to
the server, but the server failed to respond with an HTTP status code (the server simply drops the
connection without sending anything back). In this case it is assumed that the request has not been
processed by the server and the application state has not changed. If this assumption may not hold
true for the web server your application is targeting it is highly recommended to provide a custom
exception handler.
</p>
</div><div class="section"><a name="Custom_exception_handler"></a><h2>Custom exception handler</h2>
<p>
In order to enable a custom exception recovery mechanism one should provide an implementation
of the <a href="apidocs/org/apache/commons/httpclient/HttpMethodRetryHandler.html">
HttpMethodRetryHandler</a> interface.
</p>
<div class="source"><pre>
HttpClient client = new HttpClient();
HttpMethodRetryHandler myretryhandler = new HttpMethodRetryHandler() {
public boolean retryMethod(
final HttpMethod method,
final IOException exception,
int executionCount) {
if (executionCount >= 5) {
// Do not retry if over max retry count
return false;
}
if (exception instanceof NoHttpResponseException) {
// Retry if the server dropped connection on us
return true;
}
if (!method.isRequestSent()) {
// Retry if the request has not been sent fully or
// if it's OK to retry methods that have been sent
return true;
}
// otherwise do not retry
return false;
}
};
GetMethod httpget = new GetMethod("http://www.whatever.com/");
httpget.getParams().
setParameter(HttpMethodParams.RETRY_HANDLER, myretryhandler);
try {
client.executeMethod(httpget);
System.out.println(httpget.getStatusLine().toString());
} finally {
httpget.releaseConnection();
}</pre></div>
</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>
|
