commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsde...@apache.org
Subject cvs commit: jakarta-commons/httpclient/xdocs charencodings.xml methods.xml redirects.xml troubleshooting.xml tutorial.xml
Date Tue, 11 Mar 2003 08:03:13 GMT
jsdever     2003/03/11 00:03:13

  Modified:    httpclient/xdocs charencodings.xml methods.xml redirects.xml
                        troubleshooting.xml tutorial.xml
  Log:
  Minor documentation improvements.
  
  Revision  Changes    Path
  1.2       +23 -16    jakarta-commons/httpclient/xdocs/charencodings.xml
  
  Index: charencodings.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/charencodings.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- charencodings.xml	10 Mar 2003 04:08:06 -0000	1.1
  +++ charencodings.xml	11 Mar 2003 08:03:12 -0000	1.2
  @@ -5,6 +5,7 @@
     <properties>
       <title>Character Encodings</title>
       <author email="adrian@ephox.com">Adrian Sutton</author>
  +    <author email="jsdever@apache.org">Jeff Dever</author>
       <revision>$Id$</revision>
     </properties>
   
  @@ -12,22 +13,28 @@
       <section name="Introduction">
         <p>This document provides an overview of how HttpClient handles character
         encodings and how to use HttpClient in an encoding safe way.  There are
  -      three main sections, HTTP headers, request/response body and URLs.</p>
  +      three main sections: 
  +      <a href="#HTTP Headers">HTTP Headers</a>, 
  +      <a href="#Request/Response Body">Request/Response Body</a> and 
  +      <a href="#URLs">URLs</a>.
  +      </p>
       </section>
   
       <section name="HTTP Headers">
  -      <p>The headers of a HTTP request or response must be in US-ASCII format.
  -      It is not possible to use non US-ASCII characters in the header of a
  -      request or response.  Generally this is not an issue however, because the
  -      HTTP headers are designed to facilite the transfer of data rather than to
  -      actually transfer the data itself.</p>
  +      <p>The headers of a HTTP request or response must be in <tt>US-ASCII</tt>
format.
  +        It is not possible to use non <tt>US-ASCII</tt> characters in the header
of a
  +        request or response.  Generally this is not an issue however, because the
  +        HTTP headers are designed to facilite the transfer of data rather than to
  +        actually transfer the data itself.
  +      </p>
       </section>
   
       <section name="Request/Response Body">
         <p>The request or response body can be any encoding, but by default is
  -      ISO-8859-1.  The encoding may be specified in the Content-Type header,
  -      for example:</p>
  -      <blockquote>Content-Type: text/html; charset=UTF-8</blockquote>
  +        <tt>ISO-8859-1</tt>.  The encoding may be specified in the 
  +        <tt>Content-Type</tt> header, for example:
  +        <blockquote>Content-Type: text/html; charset=UTF-8</blockquote>
  +      </p>
   
         <p>In this case the application should be careful to use UTF-8 encoding
         when converting the body to a String or some characters may be corrupt.
  @@ -38,8 +45,8 @@
   
         <p>If the response is known to be a String, you can use the
         <code>getResponseBodyAsString</code> method which will automatically
use
  -      the encoding specified in the Content-Type header or ISO-8859-1 if no
  -      charset is specified.</p>
  +      the encoding specified in the <tt>Content-Type</tt> header or 
  +      <tt>ISO-8859-1</tt> if no charset is specified.</p>
   
         <p>Note that some document types, such as HTML and XML allow the author
         to specify the content type of the file.  In this case, you should
  @@ -49,11 +56,11 @@
   
       <section name="URLs">
         <p>The standard for URLs (<a
  -      href="http://www.w3c.org/Addressing/rfc1738.txt">RFC1738</a>) explictly
  +      href="http://www.ietf.org/rfc/rfc1738.txt">RFC1738</a>) explictly
         states that URLs may only contain graphic printable characters of the
  -      US-ASCII coded character set and is defined in terms of octets.
  -      The octets 80-FF hexadecimal are not used in US-ASCII and the octets
  -      OO-1F hexadecimal represent control characters; characters in these
  +      <tt>US-ASCII</tt> coded character set and is defined in terms of octets.
  +      The octets <code>80-FF</code> hexadecimal are not used in <tt>US-ASCII</tt>
and the octets
  +      <code>OO-1F</code> hexadecimal represent control characters; characters
in these
         ranges must be encoded.</p>
         
         <p>Characters which cannot be represented by an 8-bit ASCII code, can not
  
  
  
  1.3       +3 -3      jakarta-commons/httpclient/xdocs/methods.xml
  
  Index: methods.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/methods.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- methods.xml	10 Mar 2003 04:49:22 -0000	1.2
  +++ methods.xml	11 Mar 2003 08:03:12 -0000	1.3
  @@ -12,7 +12,7 @@
   
       <section name="Introduction">
         <p>These documents provide a brief introduction to using the methods
  -      provided by HttpClient.  The information here does not cover all the
  +        provided by <em>HttpClient</em>.  The information here does not cover
all the
         possible options, but covers enough of the basics to get you up and
         running.  For more information on the available options, refer to the <a
         href="apidocs/index.html">API Reference</a>.</p>
  @@ -57,7 +57,7 @@
             data-handling process or posting to a message board.</td>
           </tr>
           <tr>
  -          <td><a href="methods/multipartpost.html">Multipart Post</a></td>
  +          <td><a href="methods/multipartpost.html"><nobr>Multipart Post</nobr></a></td>
             <td>The multipart post method is identical to the POST method,
             except that the request body is separated into multiple parts.  This
             method is generally used when uploading files to the server.</td>
  
  
  
  1.2       +11 -11    jakarta-commons/httpclient/xdocs/redirects.xml
  
  Index: redirects.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/redirects.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- redirects.xml	10 Mar 2003 04:08:06 -0000	1.1
  +++ redirects.xml	11 Mar 2003 08:03:12 -0000	1.2
  @@ -12,11 +12,11 @@
   
       <section name="Introduction">
         <p>This document provides a brief guide to handling cross host redirects
  -      with HttpClient.  In future versions of HttpClient it is anticipated that
  -      this will be handled by HttpClient 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 is supported however.</p>
  +        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>
       </section>
   
       <section name="Handling Redirects">
  @@ -37,12 +37,12 @@
           <code>HttpStatus.SC_TEMPORARY_REDIRECT</code></li>
         </ul>
   
  -      <p>When your application receives one of these codes it should extract
  -      the new URL to use and retry downloading from that URL.  Additionally, it
  -      is usually a good idea to limit the number of redirects that will be
  -      followed in the redirects point to each other.</p>
  +      <p>When your application receives one of these codes, it should extract
  +        the new URL from the HttpMethod object and retry downloading from that URL.  
  +        Additionally, it is usually a good idea to limit the number of redirects that will
be
  +        followed in the redirects point to each other.</p>
   
  -      <p>The URL to connect to can be extracted from the <code>Location</code>
  +      <p>The URL to connect to can be extracted from the <tt>Location</tt>
         header.</p>
   
         <source><![CDATA[
  
  
  
  1.2       +12 -12    jakarta-commons/httpclient/xdocs/troubleshooting.xml
  
  Index: troubleshooting.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/troubleshooting.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- troubleshooting.xml	10 Mar 2003 04:08:06 -0000	1.1
  +++ troubleshooting.xml	11 Mar 2003 08:03:12 -0000	1.2
  @@ -12,10 +12,10 @@
   
       <section name="Introduction">
         <p>This document outlines some of the techniques that often help when
  -      trying to track down a problem in HttpClient.  Please try the suggestions
  -      on this page before emailing the user or dev lists with questions.  If
  -      none of these things help, please provide the information they provide to
  -      help the developers track down the problem.</p>
  +        trying to track down a problem in <em>HttpClient</em>.  Please try
the suggestions
  +        on this page before emailing the user or dev lists with questions.  If
  +        none of these things help, please provide the information they provide to
  +        help the developers track down the problem.</p>
       </section>
   
       <section name="Things To Try">
  @@ -29,7 +29,7 @@
           different server software).</li>
   
           <li>Check that your code matches the general pattern for using
  -        HttpClient as described in the <a
  +          <em>HttpClient</em> as described in the <a
           href="tutorial.html">tutorial</a>.</li>
   
           <li>Set the <a href="logging.html">logging level</a> to debug
and check
  @@ -41,13 +41,13 @@
   
           <li>Use telnet or netcat to manually send the request to the server.
           This is particularly useful once you think you know what the problem is
  -        and you want to easily test that changing what HttpClient sends will
  +        and you want to easily test that changing what <em>HttpClient</em>
sends will
           fix it.</li>
   
           <li>Use netcat in listen mode to act as the server and check how
  -        HttpClient handles various responses.</li>
  +          <em>HttpClient</em> handles various responses.</li>
   
  -        <li>Try updating to the latest nightly build of HttpClient.  Bugs
  +        <li>Try updating to the latest nightly build of <em>HttpClient</em>.
 Bugs
           happen and they are generally fixed pretty quickly so testing against
           the latest build is often worthwhile.</li>
         </ol>
  @@ -59,7 +59,7 @@
         href="mail-lists.html">mailing lists</a> for support.  Which list to
         contact depends on exactly where you think the problem lies.  If you
         think you've just got an error in your code somewhere, probably the
  -      commons-user list is the best place, but if you think that HttpClient is
  +      commons-user list is the best place, but if you think that <em>HttpClient</em>
is
         at fault, the commons-httpclient-dev list is probably a better choice.</p>
   
         <p style="color: red">Please do not cross-post to both lists.</p>
  @@ -73,8 +73,8 @@
       </section>
   
       <section name="Reporting Bugs">
  -      <p>If you're fairly certain that the problem is a bug in HttpClient or
  -      something that HttpClient doesn't currently support but probably should,
  +      <p>If you're fairly certain that the problem is a bug in <em>HttpClient</em>
or
  +        something that <em>HttpClient</em> doesn't currently support but probably
should,
         log it in <a href="http://nagoya.apache.org/bugzilla/">Bugzilla</a>.
         Make sure you spend some time searching the existing bugs to make sure it
         hasn't already been logged.  If you're unsure about whether or not to log
  
  
  
  1.2       +19 -18    jakarta-commons/httpclient/xdocs/tutorial.xml
  
  Index: tutorial.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/tutorial.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- tutorial.xml	10 Mar 2003 04:08:06 -0000	1.1
  +++ tutorial.xml	11 Mar 2003 08:03:12 -0000	1.2
  @@ -11,36 +11,36 @@
     <body>
       <section name="Overview">
         <p>This tutorial is designed to provide a basic overview of how to use
  -      HttpClient.  When you have completed the tutorial you will have written
  -      a simple application that downloads a page using HttpClient.</p>
  +        <em>HttpClient</em>.  When you have completed the tutorial you will
have written
  +        a simple application that downloads a page using <em>HttpClient</em>.</p>
   
         <p>It is assumed that you have an understanding of how to program in
         Java and are familiar with the development environment you are using.</p>
       </section>
   
       <section name="Getting Ready">
  -      <p>The first thing you need to do is get a copy of HttpClient and it's
  +      <p>The first thing you need to do is get a copy of <em>HttpClient</em>
and it's
         dependencies.  Currently the only required dependency is
         <a href="/commons/logging/">commons-logging</a>.  This tutorial was
  -      written for HttpClient 2.0 and at a minimum requires HttpClient 2.0 Alpha
  +      written for <em>HttpClient</em> 2.0 and at a minimum requires 2.0 Alpha
         2.  You will also need JDK 1.2.2 or above.</p>
   
  -      <p>Once you've downloaded HttpClient and commons-logging you'll need to
  +    <p>Once you've downloaded <em>HttpClient</em> and commons-logging
you'll need to
         put them on your classpath.  There is also an optional dependency on JSSE
         which is required for HTTPS connections;  this is not required for this
         tutorial.</p>
       </section>
   
       <section name="Concepts">
  -      <p>The general process for using HttpClient consists of a number of
  +      <p>The general process for using <em>HttpClient</em> consists of
a number of
         steps:</p>
   
         <ol>
  -        <li>Create an instance of HttpClient.</li>
  +        <li>Create an instance of <code>HttpClient</code>.</li>
           <li>Create an instance of one of the methods (GetMethod in this
           case).  The URL to connect to is passed in to the the method
           constructor.</li>
  -        <li>Tell HttpClient to execute the message.</li>
  +        <li>Tell <code>HttpClient</code> to execute the message.</li>
           <li>Read the response.</li>
           <li>Release the connection.</li>
           <li>Deal with the response.</li>
  @@ -52,7 +52,7 @@
         requests to use the same connection by simply sending the requests one
         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
  +      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>
   
         <div style="font-style: italic; border: 1px solid #888; margin-left: 7px; margin-right:
7px; margin-top: 1em; margin-bottom: 1px;">
  @@ -65,7 +65,7 @@
       </section>
   
       <section name="Instantiating HttpClient">
  -      <p>The no argument constructor for HttpClient provides a good set of
  +      <p>The no argument constructor for <code>HttpClient</code> provides
a good set of
         defaults for most situations so that is what we'll use.</p>
   
         <source>HttpClient client = new HttpClient();</source>
  @@ -73,14 +73,14 @@
   
       <section name="Creating a Method">
         <p>The various methods defined by the HTTP specification correspond to
  -      the various classes in HttpClient which implement the HttpMethod
  +        the various classes in <em>HttpClient</em> which implement the HttpMethod
         interface.  These classes are all found in the package
         <code>org.apache.commons.httpclient.methods</code>.</p>
   
         <p>We will be using the Get method which is a simple method that simply
         takes a URL and gets the document the URL points to.</p>
   
  -      <source>HttpMethod method = new GetMethod(url);</source>
  +      <source>HttpMethod method = new GetMethod("http://www.apache.org/");</source>
       </section>
   
       <section name="Execute the Method">
  @@ -159,22 +159,22 @@
           always read the entirety of the data and call close on the stream.</li>
         </ul>
   
  -      <p>For this tutorial we will use getResponseBody() for simplicity.</p>
  +      <p>For this tutorial we will use <code>getResponseBody()</code>
for simplicity.</p>
   
         <source>byte[] responseBody = method.getResponseBody();</source>
       </section>
   
       <section name="Release the Connection">
         <p>This is a crucial step to keep things flowing.  We must tell
  -      HttpClient that we are done with the connection and that it can now be
  -      reused.  Without doing this HttpClient will wait indefinitely for a
  -      connection to free up so that it can be reused.</p>
  +        <em>HttpClient</em> that we are done with the connection and that it
can now be
  +        reused.  Without doing this <em>HttpClient</em> will wait indefinitely
for a
  +        connection to free up so that it can be reused.</p>
   
         <source>method.releaseConnection();</source>
       </section>
   
       <section name="Deal with the Repsonse">
  -      <p>We've now completed our interaction with HttpClient and can just
  +      <p>We've now completed our interaction with <em>HttpClient</em>
and can just
         concentrate on doing what we need to do with the data.  In our case,
         we'll just print it out to the console.</p>
   
  @@ -240,6 +240,7 @@
               method.releaseConnection();
   
               // Deal with the response.
  +            // Use caution: ensure correct character encoding and is not binary data
               System.err.println(new String(responseBody));
             }
           }
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message