Some minor documentation updates:
* Remove "To be completed" from the index pages. Those pages were completed long ago.
* Moved the call to releaseConnection into a finally block in the tutorial (that code is getting copied into a lot of projects so we should probably get it right).
* Added a note that users should ensure that log4j is configured to avoid performance problems. (Bug 29973)
Patch is inline below, if I don't hear any complaints I'll commit it later on tonight or tomorrow.
Regards,
Adrian Sutton.
Index: logging.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/logging.xml,v
retrieving revision 1.13
diff -u -r1.13 logging.xml
--- logging.xml 5 Jul 2004 20:47:53 -0000 1.13
+++ logging.xml 2 Aug 2004 07:35:07 -0000
@@ -142,6 +142,11 @@
log4j.logger.org.apache.commons.httpclient=DEBUG<br />
</blockquote>
</p>
+ <p>Note that the default configuration for Log4J is very
+ inefficient as it causes all the logging information to be
+ generated but not actually sent anywhere. The Log4J manual is the
+ best reference for how to configure Log4J. It is available at <a
+ href="http://logging.apache.org/log4j/docs/manual.html";>http:// logging.apache.org/log4j/docs/manual.html</a>
</subsection>
</section>
</body>
Index: tutorial.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/tutorial.xml,v
retrieving revision 1.5
diff -u -r1.5 tutorial.xml
--- tutorial.xml 23 Feb 2004 23:05:43 -0000 1.5
+++ tutorial.xml 2 Aug 2004 07:35:07 -0000
@@ -207,39 +207,44 @@
// Create a method instance.
HttpMethod method = new GetMethod(url);
-
- // Execute the method.
- 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);
+
+ 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);
}
- }
- // 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. - byte[] responseBody = method.getResponseBody(); + // Read the response body. + responseBody = method.getResponseBody();
- // Release the connection.
- method.releaseConnection();
+ } 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>
Index: userguide.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/userguide.xml,v
retrieving revision 1.2
diff -u -r1.2 userguide.xml
--- userguide.xml 21 Aug 2003 16:08:54 -0000 1.2
+++ userguide.xml 2 Aug 2004 07:35:07 -0000
@@ -30,13 +30,13 @@
</tr>
<tr>
<td><a href="charencodings.html">Character Encodings</a></td>
- <td>To be completed. Guidelines for correctly detecting the
+ <td>Guidelines for correctly detecting the
character encoding to use when sending and receiving data with
HttpClient.</td>
</tr>
<tr>
<td><a href="redirects.html">Cross Host Redirects</a></td>
- <td>To be completed. Provide sample code for handling redirects
+ <td>Provide sample code for handling redirects
across hosts.</td>
</tr>
<tr>
@@ -46,7 +46,7 @@
</tr>
<tr>
<td><a href="methods.html">Methods</a></td>
- <td>To be completed. This document describes the various methods
+ <td>This document describes the various methods
that are provided by HttpClient and how to use them.</td>
</tr>
<tr>
PGP.sig
Description: This is a digitally signed message part
