Whenever a parameter is left undefined (no value is explicitly set anywhere in
@@ -420,6 +451,21 @@
<undefined>
+
http.socket.linger
+
Integer
+
+
+ The linger time (SO_LINGER) in seconds. This option disables/enables
+ immediate return from a close() of a TCP Socket. Enabling this option with a non-zero
+ Integer timeout means that a close() will block pending the transmission and
+ acknowledgement of all data written to the peer, at which point the socket is closed
+ gracefully. Value 0 implies that the option is disabled. Value
+ -1 implies that the JRE default is used.
+
+
+
<undefined>
+
+
http.connection.timeout
Integer
@@ -500,9 +546,42 @@
default behavior is likely to provide the best compatibility with widely used HTTP servers.
+
+
+
+ Applicable at the following levels: global -> client -> host
+
The request headers to be sent per default with each request. This parameter expects
+ a value of type
+ Collection.
+ The collection is expected to contain
+ HTTP headers
+
+
<undefined>
+
+
+
+ Whenever a parameter is left undefined (no value is explicitly set anywhere in
+ the parameter hierarchy) HttpClient will use its best judgment to pick up a value. This
+ default behavior is likely to provide the best compatibility with widely used HTTP servers.
+
+
+
- Applicable at the following levels: client
+ Applicable at the following levels: global -> client
This document provides a brief guide to handling cross host redirects
- with HttpClient. In future versions, it is anticipated that
- this will be handled by the HttpClient class automatically.
- However due to technical constraints and the desire to stabilise the API for a 2.0
- release sooner rather than later, this ability is yet to be implemented.
- Redirects to a different URL on the same host, port and protocol is supported.
+
This document provides a brief guide to custom handling of redirects
+ with HttpClient.
-
There are also a few types of redirect that HttpClient can't handle
+
There are a few types of redirect that HttpClient can't handle
automatically either because they require user interaction or are
outside of the scope of HttpClient. These status codes are listed below.
@@ -28,7 +24,7 @@
When a server returns a redirect instruction to HttpClient that
requires connecting to a different host, HttpClient will simply return
the redirect status code as the response status. All response codes
- between 300 and 399 inclusive are redirect resonses of
+ between 300 and 399 inclusive are redirect responses of
some form. The most common redirect response codes are:
HTTPS communication via an authenticating proxy server is also no different from plain HTTP
@@ -47,10 +50,13 @@
httpclient.getHostConfiguration().setProxy("myproxyhost", 8080);
httpclient.getState().setProxyCredentials("my-proxy-realm", " myproxyhost",
new UsernamePasswordCredentials("my-proxy-username", "my-proxy-password"));
- GetMethod httpget = new GetMethod("https://www.verisign.com/");
- httpclient.executeMethod(httpget);
- System.out.println(httpget.getStatusLine().toString());
- ]]>
+ GetMethod httpget = new GetMethod("https://www.verisign.com/");
+ try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+ } finally {
+ httpget.releaseConnection();
+ }]]>
If you want this protocol to represent the default SSL protocol implementation, simply register
@@ -153,8 +168,12 @@
new Protocol("https", new MySSLSocketFactory(), 443));
HttpClient httpclient = new HttpClient();
GetMethod httpget = new GetMethod("https://www.whatever.com/");
-httpclient.executeMethod(httpget);
- ]]>
+try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+} finally {
+ httpget.releaseConnection();
+}]]>
@@ -223,35 +242,15 @@
- Non-preemptive authentication with a HTTPS server fails when connecting via a proxy
-
-
-
- This problem is caused by a serious flaw in HttpClient design and cannot be fixed without
- breaking the existing APIs. The problem will be addressed in HttpClient release 2.1.
-
-
- Workaround: Use preemptive server authentication or
- configure the server to keep the connection alive when returning an
- authorization challenge. Please note that only
- BASIC authentication can be used preemptively. For more detailed
- information please refer to the
- Authentication Guide.
-
-
-
-
-
JSSE prior to Java 1.4 incorrectly reports socket timeout.
Prior to Java 1.4, in Sun's JSSE implementation, a read operation that has timed out incorrect
reports end of stream condition instead of throwing java.io.InterruptedIOException as expected.
- HttpClient responds to this exception by assuming that the connection was dropped and throws a recoverable
- HTTP exception: Error in parsing the status line from the response: unable to find line starting with "HTTP".
- It should instead report "java.io.InterruptedIOException: Read timed out". If you see the "unable to find
- line..." message when working with an older version of JDK and JSSE, it can be caused by the timeout
- waiting for data and not by a problem with the connection.
+ HttpClient responds to this exception by assuming that the connection was dropped and throws a
+ NoHttpResponseException. It should instead report "java.io.InterruptedIOException: Read timed
+ out". If you encounter NoHttpResponseException when working with an older version of JDK and
+ JSSE, it can be caused by the timeout waiting for data and not by a problem with the connection.
Work-around: One possible solution is to increase the timeout value as the server is
Index: tutorial.xml
===================================================================
RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/tutorial.xml,v
retrieving revision 1.6
diff -u -r1.6 tutorial.xml
--- tutorial.xml 3 Aug 2004 04:11:09 -0000 1.6
+++ tutorial.xml 15 Sep 2004 11:29:25 -0000
@@ -5,6 +5,7 @@
HttpClient TutorialAdrian Sutton
+ Oleg Kalnichevski$Id: tutorial.xml,v 1.6 2004/08/03 04:11:09 adrian Exp $
@@ -53,12 +54,12 @@
after the other. Obviously, if we don't read the entire response to
the first request, the left over data will get in the way of the second
response. HttpClient tries to handle this but to avoid problems it is
- important to always read the entire response and release the connection.
+ important to always release the connection. Upon the connection release
+ HttpClient will do its best to ensure that the connection is reusable.
- It is important to always read the entire
- response and release the connection regardless of whether the server
+ It is important to always release the connection regardless of whether the server
returned an error or not.
@@ -90,54 +91,64 @@
with any errors that occur.
There are two kinds of exceptions that could be thrown by
- executeMethod, HttpRecoverableException and
- IOException.
+ executeMethod, HttpException and IOException.
+
-
-
A HttpRecoverableException is thrown when an error occurs that is
- likely to be a once-off problem. Usually the request will succeed on
- a second attempt, so retrying the connection is generally
- recommended. Note that HttpRecoverableException actually extends
- IOException so you can just ignore it and catch the IOException if
- your application does not retry the request.
-
-
-
-
An IOException is thrown when the request cannot be sent at all
- and retrying the connection is also likely to fail. This may be
- caused by a number of situations including the server being down,
- inability to resolve the domain name or the server refusing the
- connection.
-
-
The other useful piece of information is the status code that is
returned by the server. This code is returned by executeMethod as an
int and can be used to determine if the request was successful or not
and can sometimes indicate that further action is required by the
client such as providing authentication credentials.
+
+
An HttpException represents a logical error and is thrown when the request
+ cannot be sent or the response cannot be processed due to a fatal violation of
+ the HTTP protocol violation. Usually this kind of exceptions cannot be recovered
+ from. For a detailed discussion on protocol exceptions please refer to
+ the HttpClient exception
+ handling guide. Note that HttpException actually extends IOException
+ so you can just ignore it and catch the IOException if your application does
+ not distinguish between protocol and transport errors.
+
+
+
+
A plain IOException (which is not a subclass of HttpException) represents a
+ transport error and is thrown when an error occurs that is likely to be a
+ once-off I/O problem. Usually the request has a good chance of succeeding on
+ a second attempt, so per default HttpClient will try to recover the request
+ automatically. For a detailed discussion on transport exceptions please refer to
+ the HttpClient exception
+ handling guide.
+
+
+
+
Per default HttpClient will automatically attempt to recover from the not-fatal
+ errors, that is, when a plain IOException is thrown. HttpClient will retry the
+ method five times provided that the request has never been fully transmitted to
+ the target server. For a detailed discussion on HTTP method recovery please refer
+ to the HttpClient
+ exception handling guide
+
+
+
+
Default recovery procedure can be replaced with a custom one. The number
+ of automatic retries can be increased. HttpClient can also be instructed to
+ retry the method even though the request may have already been processed by
+ the server and the I/O exception has occurred while receiving the response.
+ Please exercise caution when enabling auto-retrial. Use it only if the method
+ is known to be idempotent, that is, it is known to be safe to retry multiple
+ times without causing data corruption or data inconsistency.
+
The rule of thumb is GET methods are usually safe unless known otherwise,
+ entity enclosing methods such as POST and PUT are usually unsafe unless known
+ otherwise.
+
-
+DefaultMethodRetryHandler retryhandler = new DefaultMethodRetryHandler(10, true);
+client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, retryhandler);]]>
+
@@ -193,61 +204,54 @@
the program below.
+ // Create a method instance.
+ GetMethod method = new GetMethod(url);
+
+ // Provide custom retry handler is necessary
+ method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER,
+ new DefaultHttpMethodRetryHandler(3, false));
+
+ try {
+ // Execute the method.
+ int statusCode = client.executeMethod(method);
+
+ if (statusCode != HttpStatus.SC_OK) {
+ System.err.println("Method failed: " + method.getStatusLine());
+ }
+
+ // Read the response body.
+ byte[] responseBody = method.getResponseBody();
+
+ // Deal with the response.
+ // Use caution: ensure correct character encoding and is not binary data
+ System.out.println(new String(responseBody));
+
+ } catch (HttpException e) {
+ System.err.println("Fatal protocol violation: " + e.getMessage());
+ e.printStackTrace();
+ } catch (IOException e) {
+ System.err.println("Fatal transport error: " + e.getMessage());
+ e.printStackTrace();
+ } finally {
+ // Release the connection.
+ method.releaseConnection();
+ }
+ }
+}]]>
Index: userguide.xml
===================================================================
RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/userguide.xml,v
retrieving revision 1.4
diff -u -r1.4 userguide.xml
--- userguide.xml 15 Sep 2004 02:50:11 -0000 1.4
+++ userguide.xml 15 Sep 2004 11:29:25 -0000
@@ -35,9 +35,8 @@
HttpClient.