Index: tutorial.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/tutorial.xml,v retrieving revision 1.2.2.4 diff -u -r1.2.2.4 tutorial.xml --- tutorial.xml 3 Aug 2004 21:48:24 -0000 1.2.2.4 +++ tutorial.xml 11 Sep 2004 21:50:07 -0000 @@ -53,12 +53,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.

@@ -116,28 +116,35 @@ and can sometimes indicate that further action is required by the client such as providing authentication credentials.

+ +

Per default HttpClient will automatically attempt to recover from the + not-fatal errors, that is, when HttpRecoverableException is thrown. + HttpClient will retry the method three times provided that the request + has never been fully transmitted to the target server.

+ + + + +

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(); +retryhandler.setRequestSentRetryEnabled(true); +retryhandler.setRetryCount(5); +method.setMethodRetryHandler(retryhandler);]]> +
@@ -193,61 +200,53 @@ the program below.

+ // Create a method instance. + GetMethod method = new GetMethod(url); + + // Provide custom retry handler is necessary + DefaultMethodRetryHandler retryhandler = new DefaultMethodRetryHandler(); + retryhandler.setRequestSentRetryEnabled(false); + retryhandler.setRetryCount(3); + method.setMethodRetryHandler(retryhandler); + + try { + // Execute the method. + int statusCode = client.executeMethod(method); + + if (statusCode != HttpStatus.SC_OK) { + System.err.println("Method failed: " + method.getStatusLine()); + System.exit(-2); + } + + // 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 (IOException e) { + System.err.println("Failed to download file."); + e.printStackTrace(); + System.exit(-1); + } finally { + // Release the connection. + method.releaseConnection(); + } + } +}]]>