You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Adrian Sutton <ad...@intencha.com> on 2004/08/02 09:41:22 UTC
Documentation Updates
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>
Re: Documentation Updates
Posted by Adrian Sutton <ad...@intencha.com>.
Oops, sorry I forgot about branches. That's now done.
Regards,
Adrian Sutton.
On 03/08/2004, at 8:57 PM, Michael Becke wrote:
> Hi Adrian,
>
> Could you add these to 2.0 as well? The site is currently built from
> 2.0.
>
> Mike
----------------------------------------------
Intencha "tomorrow's technology today"
Ph: 38478913 0422236329
Suite 8/29 Oatland Crescent
Holland Park West 4121
Australia QLD
www.intencha.com
Re: Documentation Updates
Posted by Michael Becke <be...@u.washington.edu>.
Hi Adrian,
Could you add these to 2.0 as well? The site is currently built from
2.0.
Mike
On Aug 3, 2004, at 12:12 AM, Adrian Sutton wrote:
> These updates have now been committed and will go live whenever the
> site is next deployed.
>
> Regards,
>
> Adrian Sutton.
>
> On 02/08/2004, at 9:53 PM, Michael Becke wrote:
>
>> Sounds good.
>>
>> Mike
>>
>> On Aug 2, 2004, at 3:41 AM, Adrian Sutton wrote:
>>
>>> 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>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:
>> commons-httpclient-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail:
>> commons-httpclient-dev-help@jakarta.apache.org
>>
> ----------------------------------------------
> Intencha "tomorrow's technology today"
> Ph: 38478913 0422236329
> Suite 8/29 Oatland Crescent
> Holland Park West 4121
> Australia QLD
> www.intencha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-httpclient-dev-help@jakarta.apache.org
Re: Documentation Updates
Posted by Adrian Sutton <ad...@intencha.com>.
These updates have now been committed and will go live whenever the
site is next deployed.
Regards,
Adrian Sutton.
On 02/08/2004, at 9:53 PM, Michael Becke wrote:
> Sounds good.
>
> Mike
>
> On Aug 2, 2004, at 3:41 AM, Adrian Sutton wrote:
>
>> 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>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> commons-httpclient-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail:
> commons-httpclient-dev-help@jakarta.apache.org
>
----------------------------------------------
Intencha "tomorrow's technology today"
Ph: 38478913 0422236329
Suite 8/29 Oatland Crescent
Holland Park West 4121
Australia QLD
www.intencha.com
Re: Documentation Updates
Posted by Michael Becke <be...@u.washington.edu>.
Sounds good.
Mike
On Aug 2, 2004, at 3:41 AM, Adrian Sutton wrote:
> 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-httpclient-dev-help@jakarta.apache.org