You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ol...@apache.org on 2004/09/16 08:24:43 UTC
cvs commit: jakarta-commons/httpclient/xdocs exception-handling.xml navigation.xml preference-api.xml redirects.xml sslguide.xml tutorial.xml userguide.xml
olegk 2004/09/15 23:24:43
Modified: httpclient/xdocs exception-handling.xml navigation.xml
preference-api.xml redirects.xml sslguide.xml
tutorial.xml userguide.xml
Log:
PR #31180 (HttpClient tutorial update)
The patch revises and brings the tutorial, the SSL guide, the redirect guide, the exception handling guides, and the preference api guide up to date with the latest changes for the 3.0-alpha2 release
Contributed by Oleg Kalnichevski
Reviewed by Michael Becke
Revision Changes Path
1.2 +2 -2 jakarta-commons/httpclient/xdocs/exception-handling.xml
Index: exception-handling.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/exception-handling.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- exception-handling.xml 4 Sep 2004 17:02:04 -0000 1.1
+++ exception-handling.xml 16 Sep 2004 06:24:43 -0000 1.2
@@ -327,7 +327,7 @@
GetMethod httpget = new GetMethod("http://www.whatever.com/");
httpget.getParams().
- setParameter(HttpMethodRetryHandler.HANDLER, myretryhandler);
+ setParameter(HttpMethodParams.RETRY_HANDLER, myretryhandler);
try {
client.executeMethod(httpget);
System.out.println(httpget.getStatusLine().toString());
1.13 +2 -2 jakarta-commons/httpclient/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/navigation.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- navigation.xml 15 Sep 2004 02:50:11 -0000 1.12
+++ navigation.xml 16 Sep 2004 06:24:43 -0000 1.13
@@ -20,11 +20,11 @@
<item name="Authentication Guide" href="/authentication.html"/>
<item name="Character Encodings" href="/charencodings.html"/>
<item name="Cookies" href="/cookies.html"/>
- <item name="Cross Host Redirects" href="/redirects.html"/>
<item name="Exception Handling" href="/exception-handling.html"/>
<item name="Logging Guide" href="/logging.html"/>
<item name="Methods" href="/methods.html"/>
<item name="Preference Architecture" href="/preference-api.html"/>
+ <item name="Redirects Handling" href="/redirects.html"/>
<item name="Sample Code" href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/"/>
<item name="SSL Guide" href="/sslguide.html"/>
<item name="Threading" href="/threading.html"/>
1.2 +81 -2 jakarta-commons/httpclient/xdocs/preference-api.xml
Index: preference-api.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/preference-api.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- preference-api.xml 15 Sep 2004 02:50:11 -0000 1.1
+++ preference-api.xml 16 Sep 2004 06:24:43 -0000 1.2
@@ -350,6 +350,37 @@
<td><p><a href="apidocs/org/apache/commons/httpclient/DefaultHttpMethodRetryHandler.html">
default implementation</a></p></td>
</tr>
+ <tr>
+ <td><p>http.dateparser.patterns</p></td>
+ <td><p><a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collection.html">
+ Collection</a></p></td>
+ <td>
+ <p>Date patterns used for parsing. The patterns are stored in a
+ <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collection.html">
+ Collection</a> and must be compatible with
+ <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">
+ SimpleDateFormat</a>.
+ </p>
+ </td>
+ <td>
+ <p>
+ 'EEE, dd MMM yyyy HH:mm:ss zzz',<br/>
+ 'EEEE, dd-MMM-yy HH:mm:ss zzz',<br/>
+ 'EEE MMM d HH:mm:ss yyyy',<br/>
+ 'EEE, dd-MMM-yyyy HH:mm:ss z',<br/>
+ 'EEE, dd-MMM-yyyy HH-mm-ss z',<br/>
+ 'EEE, dd MMM yy HH:mm:ss z',<br/>
+ 'EEE dd-MMM-yyyy HH:mm:ss z',<br/>
+ 'EEE dd MMM yyyy HH:mm:ss z',<br/>
+ 'EEE dd-MMM-yyyy HH-mm-ss z',<br/>
+ 'EEE dd-MMM-yy HH:mm:ss z',<br/>
+ 'EEE dd MMM yy HH:mm:ss z',<br/>
+ 'EEE,dd-MMM-yy HH:mm:ss z',<br/>
+ 'EEE,dd-MMM-yyyy HH:mm:ss z',<br/>
+ 'EEE, dd-MM-yyyy HH:mm:ss z'
+ </p>
+ </td>
+ </tr>
</table>
<p>
Whenever a parameter is left undefined (no value is explicitly set anywhere in
@@ -420,6 +451,21 @@
<td><p><code><undefined></code></p></td>
</tr>
<tr>
+ <td><p>http.socket.linger</p></td>
+ <td><p>Integer</p></td>
+ <td>
+ <p>
+ The linger time (<code>SO_LINGER</code>) 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 <code>0</code> implies that the option is disabled. Value
+ <code>-1</code> implies that the JRE default is used.
+ </p>
+ </td>
+ <td><p><code><undefined></code></p></td>
+ </tr>
+ <tr>
<td><p>http.connection.timeout</p></td>
<td><p>Integer</p></td>
<td>
@@ -500,9 +546,42 @@
default behavior is likely to provide the best compatibility with widely used HTTP servers.
</p>
</subsection>
+
+ <subsection name="Host configuration parameters">
+ <p>
+ Applicable at the following levels: <b>global</b> -> <b>client</b> -> <b>host</b>
+ </p>
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ <th>Default</th>
+ </tr>
+ <tr>
+ <td><p>http.default-headers</p></td>
+ <td><p><a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collection.html">
+ Collection</a></p></td>
+ <td>
+ <p>The request headers to be sent per default with each request. This parameter expects
+ a value of type
+ <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collection.html">Collection</a>.
+ The collection is expected to contain
+ <a href="apidocs/org/apache/commons/httpclient/Header.html">HTTP headers</a></p>
+ </td>
+ <td><p><code><undefined></code></p></td>
+ </tr>
+ </table>
+ <p>
+ 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.
+ </p>
+ </subsection>
+
<subsection name="HTTP client parameters">
<p>
- Applicable at the following levels: <b>client</b>
+ Applicable at the following levels: <b>global</b> -> <b>client</b>
</p>
<table>
<tr>
1.4 +5 -9 jakarta-commons/httpclient/xdocs/redirects.xml
Index: redirects.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/redirects.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- redirects.xml 4 Jun 2003 02:28:14 -0000 1.3
+++ redirects.xml 16 Sep 2004 06:24:43 -0000 1.4
@@ -11,14 +11,10 @@
<body>
<section name="Introduction">
- <p>This document provides a brief guide to handling cross host redirects
- with <em>HttpClient</em>. In future versions, it is anticipated that
- this will be handled by the <code>HttpClient</code> 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.</p>
+ <p>This document provides a brief guide to custom handling of redirects
+ with <em>HttpClient</em>.</p>
- <p>There are also a few types of redirect that HttpClient can't handle
+ <p>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 <a
href="#Special%20Redirect%20Codes">below</a>.</p>
@@ -28,7 +24,7 @@
<p>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:</p>
<ul>
1.5 +37 -38 jakarta-commons/httpclient/xdocs/sslguide.xml
Index: sslguide.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/sslguide.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- sslguide.xml 15 Apr 2004 21:07:45 -0000 1.4
+++ sslguide.xml 16 Sep 2004 06:24:43 -0000 1.5
@@ -32,9 +32,12 @@
<source><![CDATA[
HttpClient httpclient = new HttpClient();
GetMethod httpget = new GetMethod("https://www.verisign.com/");
- httpclient.executeMethod(httpget);
- System.out.println(httpget.getStatusLine().toString());
- ]]></source>
+ try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+ } finally {
+ httpget.releaseConnection();
+ }]]></source>
<p>
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());
- ]]></source>
+ GetMethod httpget = new GetMethod("https://www.verisign.com/");
+ try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+ } finally {
+ httpget.releaseConnection();
+ }]]></source>
</section>
@@ -114,8 +120,12 @@
HttpClient httpclient = new HttpClient();
httpclient.getHostConfiguration().setHost("www.whatever.com", 443, myhttps);
GetMethod httpget = new GetMethod("/");
-httpclient.executeMethod(httpget);
- ]]></source>
+try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+} finally {
+ httpget.releaseConnection();
+}]]></source>
</li>
@@ -140,8 +150,13 @@
<source><![CDATA[
HttpClient httpclient = new HttpClient();
GetMethod httpget = new GetMethod("myhttps://www.whatever.com/");
-httpclient.executeMethod(httpget);
- ]]></source>
+try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+} finally {
+ httpget.releaseConnection();
+}]]></source>
+
<p>
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);
- ]]></source>
+try {
+ httpclient.executeMethod(httpget);
+ System.out.println(httpget.getStatusLine());
+} finally {
+ httpget.releaseConnection();
+}]]></source>
</li>
@@ -223,35 +242,15 @@
<li>
<p>
- <strong>Non-preemptive authentication with a HTTPS server fails when connecting via a proxy</strong>
- </p>
-
- <p>
- 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.
- </p>
- <p>
- <strong>Workaround:</strong> 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
- <a href="authentication.html">Authentication Guide</a>.
- </p>
- </li>
-
- <li>
- <p>
<strong>JSSE prior to Java 1.4 incorrectly reports socket timeout.</strong>
</p>
<p>
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.
</p>
<p>
<strong>Work-around:</strong> One possible solution is to increase the timeout value as the server is
1.7 +102 -98 jakarta-commons/httpclient/xdocs/tutorial.xml
Index: tutorial.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/tutorial.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- tutorial.xml 3 Aug 2004 04:11:09 -0000 1.6
+++ tutorial.xml 16 Sep 2004 06:24:43 -0000 1.7
@@ -5,6 +5,7 @@
<properties>
<title>HttpClient Tutorial</title>
<author email="adrian@ephox.com">Adrian Sutton</author>
+ <author email="oleg -at- ural.ru">Oleg Kalnichevski</author>
<revision>$Id$</revision>
</properties>
@@ -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. <em>HttpClient</em> tries to handle this but to avoid problems it is
- important to always read the entire response and release the connection.</p>
+ important to always release the connection.</p> Upon the connection release
+ HttpClient will do its best to ensure that the connection is reusable.
<div style="font-style: italic; border: 1px solid #888; margin-left: 7px; margin-right: 7px; margin-top: 1em; margin-bottom: 1px;">
<p>
- 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.
</p>
</div>
@@ -90,54 +91,64 @@
with any errors that occur.</p>
<p>There are two kinds of exceptions that could be thrown by
- executeMethod, <code>HttpRecoverableException</code> and
- <code>IOException</code>.</p>
+ executeMethod, <code>HttpException</code> and <code>IOException</code>.
+ </p>
- <subsection name="HttpRecoverableException">
- <p>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.</p>
- </subsection>
-
- <subsection name="IOException">
- <p>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.</p>
- </subsection>
-
<p>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.</p>
+ <subsection name="HttpException">
+ <p>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
+ <a href="exception-handling.html#Protocol exceptions">the HttpClient exception
+ handling guide</a>. 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.</p>
+ </subsection>
+
+ <subsection name="IOException">
+ <p>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
+ <a href="exception-handling.html#Transport exceptions">the HttpClient exception
+ handling guide</a>.</p>
+ </subsection>
+
+ <subsection name="Method recovery">
+ <p>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 <a href="exception-handling.html#HTTP transport safety">the HttpClient
+ exception handling guide</a></p>
+
+ <source><![CDATA[
+// set per default
+client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER,
+ new DefaultHttpMethodRetryHandler());]]></source>
+
+ <p>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.</p>
+ <p>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.</p>
+
<source><![CDATA[
- int statusCode = -1;
- // We will retry up to 3 times.
- for (int attempt = 0; statusCode == -1 && attempt < 3; attempt++) {
- try {
- // execute the method.
- statusCode = client.executeMethod(method);
- } catch (HttpRecoverableException e) {
- System.err.println("A recoverable exception occurred,
- retrying. " + e.getMessage());
- } catch (IOException e) {
- System.err.println("Failed to download file.");
- e.printStackTrace();
- System.exit(-1);
- }
- }
- // Check that we didn't run out of retries.
- if (statusCode == -1) {
- System.err.println("Failed to recover from exception.");
- System.exit(-2);
- }]]>
- </source>
+DefaultMethodRetryHandler retryhandler = new DefaultMethodRetryHandler(10, true);
+client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, retryhandler);]]></source>
+ </subsection>
</section>
<section name="Read the Response">
@@ -193,61 +204,54 @@
the program below.</p>
<source><![CDATA[
- import org.apache.commons.httpclient.*;
- import org.apache.commons.httpclient.methods.*;
- import java.io.*;
-
- public class HttpClientTutorial {
-
- private static String url = "http://www.apache.org/";
+import org.apache.commons.httpclient.*;
+import org.apache.commons.httpclient.methods.*;
+import org.apache.commons.httpclient.params.HttpMethodParams;
+
+import java.io.*;
+
+public class HttpClientTutorial {
+
+ private static String url = "http://www.apache.org/";
+
+ public static void main(String[] args) {
+ // Create an instance of HttpClient.
+ HttpClient client = new HttpClient();
- public static void main(String[] args) {
- // Create an instance of HttpClient.
- HttpClient client = new HttpClient();
-
- // Create a method instance.
- HttpMethod method = new GetMethod(url);
-
- try {
- // Execute the method.
- int statusCode = -1;
- byte[] responseBody = null;
- // We will retry up to 3 times.
- for (int attempt = 0; statusCode == -1 && attempt < 3; attempt++) {
- try {
- // execute the method.
- statusCode = client.executeMethod(method);
- } catch (HttpRecoverableException e) {
- System.err.println(
- "A recoverable exception occurred, retrying." +
- e.getMessage());
- } catch (IOException e) {
- System.err.println("Failed to download file.");
- e.printStackTrace();
- System.exit(-1);
- }
- }
- // Check that we didn't run out of retries.
- if (statusCode == -1) {
- System.err.println("Failed to recover from exception.");
- System.exit(-2);
- }
-
- // Read the response body.
- responseBody = method.getResponseBody();
-
- } finally {
- // Release the connection.
- method.releaseConnection();
- }
-
- // Deal with the response.
- // Use caution: ensure correct character encoding and is not binary data
- System.err.println(new String(responseBody));
-
- }
- }
- ]]></source>
+ // 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();
+ }
+ }
+}]]></source>
</section>
</body>
</document>
1.5 +3 -4 jakarta-commons/httpclient/xdocs/userguide.xml
Index: userguide.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/userguide.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- userguide.xml 15 Sep 2004 02:50:11 -0000 1.4
+++ userguide.xml 16 Sep 2004 06:24:43 -0000 1.5
@@ -35,9 +35,8 @@
HttpClient.</td>
</tr>
<tr>
- <td><a href="redirects.html">Cross Host Redirects</a></td>
- <td>Provide sample code for handling redirects
- across hosts.</td>
+ <td><a href="redirects.html">Redirects Handling</a></td>
+ <td>Provide sample code for custom redirects handling.</td>
</tr>
<tr>
<td><a href="exception-handling.html">Exception Handling</a></td>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org