commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethod.java HttpMethodBase.java
Date Sun, 03 Aug 2003 21:59:13 GMT
olegk       2003/08/03 14:59:13

  Modified:    httpclient/src/java/org/apache/commons/httpclient
                        HttpMethod.java HttpMethodBase.java
  Log:
  Javadocs clean-up in HttpMethod & HttpMethodBase
  
  Contributed by Oleg Kalnicvhevski
  
  Revision  Changes    Path
  1.26      +19 -14    jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java
  
  Index: HttpMethod.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethod.java,v
  retrieving revision 1.25
  retrieving revision 1.26
  diff -u -r1.25 -r1.26
  --- HttpMethod.java	2 Aug 2003 22:26:55 -0000	1.25
  +++ HttpMethod.java	3 Aug 2003 21:59:13 -0000	1.26
  @@ -86,7 +86,7 @@
       // ------------------------------------------- Property Setters and Getters
   
       /**
  -     * Obtain the name of the HTTP method as used in the HTTP request line,
  +     * Obtains the name of the HTTP method as used in the HTTP request line,
        * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
        * 
        * @return the name of this method
  @@ -102,8 +102,11 @@
   
       /**
        * Sets the path of the HTTP method.
  +     * It is responsibility of the caller to ensure that the path is
  +     * properly encoded (URL safe).
        * 
  -     * @param path the path of the HTTP method
  +     * @param path the path of the HTTP method. The path is expected
  +     *        to be URL-encoded
        */
       void setPath(String path);
   
  @@ -114,7 +117,7 @@
        * return the <em>actual</em> path, following any redirects automatically
        * handled by this HTTP method.
        * 
  -     * @return the path to request
  +     * @return the path of the HTTP method
        */
       String getPath();
   
  @@ -138,12 +141,13 @@
       void setURI(URI uri) throws URIException;
   
       /**
  -     * <p>Turns strict mode on or off. In the strict mode the HTTP method exactly 
  -     * follows the HTTP specification. In the non-strict mode the HTTP method attempts 
  -     * to violate the specification in the same way that most HTTP user agent's do 
  -     * (and, unfortunately, as many HTTP servers expect).</p>
  -     *
  -     * @param strictMode <tt>true</tt> to enable the strict mode.
  +     * Defines how strictly the method follows the HTTP protocol specification  
  +     * (RFC 2616 and other relevant RFCs). In the strict mode the method precisely
  +     * implements the requirements of the specification, whereas in non-strict mode 
  +     * it attempts to mimic the exact behaviour of commonly used HTTP agents, 
  +     * which many HTTP servers expect.
  +     * 
  +     * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
        */
       void setStrictMode(boolean strictMode);
   
  @@ -343,7 +347,8 @@
        * Execute the HTTP method.
        *
        * @param state the {@link HttpState state} information to associate with this method
  -     * @param connection the {@link HttpConnection connection} to be used
  +     * @param connection the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
        *                     can be recovered from.
  
  
  
  1.175     +405 -343  jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethodBase.java
  
  Index: HttpMethodBase.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpMethodBase.java,v
  retrieving revision 1.174
  retrieving revision 1.175
  diff -u -r1.174 -r1.175
  --- HttpMethodBase.java	30 Jul 2003 21:11:17 -0000	1.174
  +++ HttpMethodBase.java	3 Aug 2003 21:59:13 -0000	1.175
  @@ -151,37 +151,38 @@
   
       // ----------------------------------------------------- Instance variables 
   
  -    /** My request headers, if any. */
  +    /** Request headers, if any. */
       private HeaderGroup requestHeaders = new HeaderGroup();
   
       /** The Status-Line from the response. */
       private StatusLine statusLine = null;
   
  -    /** My response headers, if any. */
  +    /** Response headers, if any. */
       private HeaderGroup responseHeaders = new HeaderGroup();
   
  -    /** My response trailer headers, if any. */
  +    /** Response trailer headers, if any. */
       private HeaderGroup responseTrailerHeaders = new HeaderGroup();
   
  -    /** Realms that we tried to authenticate to */
  +    /** Realms this method tried to authenticate to */
       private Set realms = null;
   
       /** Actual authentication realm */
       private String realm = null;
   
  -    /** Proxy Realms that we tried to authenticate to */
  +    /** Proxy Realms this method tried to authenticate to */
       private Set proxyRealms = null;
   
       /** Actual proxy authentication realm */
       private String proxyRealm = null;
   
  -    /** My request path. */
  +    /** Path of the HTTP method. */
       private String path = null;
   
  -    /** My query string, if any. */
  +    /** Query string of the HTTP method, if any. */
       private String queryString = null;
   
  -    /** The response body, assuming it has not be intercepted by a sub-class. */
  +    /** The response body of the HTTP method, assuming it has not be 
  +     * intercepted by a sub-class. */
       private InputStream responseStream = null;
   
       /** The connection that the response stream was read from. */
  @@ -190,25 +191,28 @@
       /** Buffer for the response */
       private byte[] responseBody = null;
   
  -    /** Whether or not I should automatically follow redirects. */
  +    /** True if the HTTP method should automatically follow HTTP redirects.*/
       private boolean followRedirects = false;
   
  -    /** Whether or not I should automatically process authentication. */
  +    /** True if the HTTP method should automatically handle
  +    *  HTTP authentication challenges. */
       private boolean doAuthentication = true;
   
       /** Version of the HTTP protocol to be used. */
       private HttpVersion version = HttpVersion.HTTP_1_1;  
   
  -    /** True if we're in strict mode. The default is <tt>false</tt>. */
  +    /** True if this HTTP method should strictly follow the HTTP protocol
  +    * specification. */
       private boolean strictMode = false;
   
  -    /** Whether or not I have been executed. */
  +    /** True if this method has already been executed. */
       private boolean used = false;
   
  -    /** How many times did this transparently handle a recoverable exception? */
  +    /** Count of how many times did this HTTP method transparently handle 
  +    * a recoverable exception. */
       private int recoverableExceptionCount = 0;
   
  -    /** the host configuration for this method, can be null */
  +    /** the host configuration for this HTTP method, can be null */
       private HostConfiguration hostConfiguration;
   
       /**
  @@ -216,13 +220,13 @@
        */
       private MethodRetryHandler methodRetryHandler;
   
  -    /** true if we are currently executing */
  +    /** True if this method is currently being executed. */
       private boolean inExecute = false;
   
  -    /** true if we are finished with the connection */
  +    /** True if this HTTP method is finished with the connection */
       private boolean doneWithConnection = false;
   
  -    /** true if the connection must be closed when no longer needed */
  +    /** True if the connection must be closed when no longer needed */
       private boolean connectionCloseForced = false;
   
       /** Number of milliseconds to wait for 100-contunue response. */
  @@ -267,17 +271,20 @@
       // ------------------------------------------- Property Setters and Getters
   
       /**
  -     * Obtain the name of this method, suitable for use in the "request line",
  -     * for example <tt>GET</tt> or <tt>POST</tt>.
  -     *
  +     * Obtains the name of the HTTP method as used in the HTTP request line,
  +     * for example <tt>"GET"</tt> or <tt>"POST"</tt>.
  +     * 
        * @return the name of this method
        */
       public abstract String getName();
   
       /**
  -     * Return the URI
  +     * Returns the URI of the HTTP method
  +     * 
        * @return The URI
  +     * 
        * @throws URIException If the URI cannot be created.
  +     * 
        * @see org.apache.commons.httpclient.HttpMethod#getURI()
        */
       public URI getURI() throws URIException {
  @@ -340,31 +347,32 @@
       }
   
       /**
  -     * Set whether or not I should automatically follow HTTP redirects (status
  -     * code 302, etc.)
  -     *
  -     * @param followRedirects true to follow redirects, false otherwise
  +     * Sets whether or not the HTTP method should automatically follow HTTP redirects 
  +     * (status code 302, etc.)
  +     * 
  +     * @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
  +     * <tt>false</ff> otherwise.
        */
       public void setFollowRedirects(boolean followRedirects) {
           this.followRedirects = followRedirects;
       }
   
       /**
  -     * Whether or not I should automatically follow HTTP redirects (status code
  -     * 302, etc.)
  -     *
  -     * @return <tt>true</tt> if I will automatically follow HTTP redirects
  +     * Returns <tt>true</tt> if the HTTP method should automatically follow HTTP redirects 
  +     * (status code 302, etc.), <tt>false</tt> otherwise.
  +     * 
  +     * @return <tt>true</tt> if the method will automatically follow HTTP redirects, 
  +     * <tt>false</ff> otherwise.
        */
       public boolean getFollowRedirects() {
           return this.followRedirects;
       }
   
  -    /**
  -     * Set whether or not I should use the HTTP/1.1 protocol.
  +    /** Sets whether version 1.1 of the HTTP protocol should be used per default.
        *
  -     * @param http11 true to use HTTP/1.1, false to use 1.0
  +     * @param http11 <tt>true</tt> to use HTTP/1.1, <tt>false</tt> to use 1.0
        * 
  -     * @deprecated Use @{link #setHttpVersion(HttpVersion)}
  +     * @deprecated Use {@link #setHttpVersion(HttpVersion)}
        */
       public void setHttp11(boolean http11) {
           if (http11) {
  @@ -374,11 +382,13 @@
           }
       }
   
  -        /**
  -     * Whether or not I should automatically process responses where
  -     * authentication is required (status code 401, etc.)
  +    /**
  +     * Returns <tt>true</tt> if the HTTP method should automatically handle HTTP 
  +     * authentication challenges (status code 401, etc.), <tt>false</tt> otherwise
        *
  -     * @return <tt>true</tt> if authentications will be processed automatically
  +     * @return <tt>true</tt> if authentication challenges will be processed 
  +     * automatically, <tt>false</tt> otherwise.
  +     * 
        * @since 2.0
        */
       public boolean getDoAuthentication() {
  @@ -386,12 +396,14 @@
       }
   
       /**
  -     * Set whether or not I should automatically process responses where
  -     * authentication is required (status code 401, etc.)
  +     * Sets whether or not the HTTP method should automatically handle HTTP 
  +     * authentication challenges (status code 401, etc.)
        *
  -     * @param doAuthentication <tt>true</tt> to process authentications
  +     * @param doAuthentication <tt>true</tt> to process authentication challenges
  +     * authomatically, <tt>false</tt> otherwise.
  +     * 
        * @since 2.0
  -     */
  +    */
       public void setDoAuthentication(boolean doAuthentication) {
           this.doAuthentication = doAuthentication;
       }
  @@ -399,10 +411,10 @@
       // ---------------------------------------------- Protected Utility Methods
   
       /**
  -     * Access to flag to determine if client should use
  -     * HTTP/1.1 protocol. The default is <tt>true</tt>. 
  +     * Returns <tt>true</tt> if version 1.1 of the HTTP protocol should be 
  +     * used per default, <tt>false</tt> if version 1.0 should be used.
        *
  -     * @return <tt>true</tt> if I should use the HTTP/1.1 protocol
  +     * @return <tt>true</tt> to use HTTP/1.1, <tt>false</tt> to use 1.0
        * 
        * @deprecated Use {@link #getHttpVersion()}
        */
  @@ -411,11 +423,11 @@
       }
   
       /**
  -     * Set the path part of my request.
  +     * Sets the path of the HTTP method.
        * It is responsibility of the caller to ensure that the path is
        * properly encoded (URL safe).
        *
  -     * @param path the path to request. The path is expected
  +     * @param path the path of the HTTP method. The path is expected
        *        to be URL-encoded
        */
       public void setPath(String path) {
  @@ -423,9 +435,8 @@
       }
   
       /**
  -     * Add the specified request header. A <i>header</i> value of
  -     * <code>null</code> will be ignored. Note that header-name matching is case
  -     * insensitive.
  +     * Adds the specified request header, NOT overwriting any previous value.
  +     * Note that header-name matching is case insensitive.
        *
        * @param header the header to add to the request
        */
  @@ -440,15 +451,19 @@
       }
   
       /**
  -     * adds a response footer to the internal list
  -     * @param footer The new footer to add.
  +     * Use this method internally to add footers.
  +     * 
  +     * @param footer The footer to add.
        */
       public void addResponseFooter(Header footer) {
           getResponseTrailerHeaderGroup().addHeader(footer);
       }
   
       /**
  -     * Get the path part of my request.
  +     * Gets the path of this HTTP method.
  +     * Calling this method <em>after</em> the request has been executed will 
  +     * return the <em>actual</em> path, following any redirects automatically
  +     * handled by this HTTP method.
        *
        * @return the path to request or "/" if the path is blank.
        */
  @@ -457,8 +472,9 @@
       }
   
       /**
  -     * Sets the query string. The user must ensure that the string is properly 
  -     * URL encoded. The query string should not start with the question mark character.
  +     * Sets the query string of this HTTP method. The caller must ensure that the string 
  +     * is properly URL encoded. The query string should not start with the question 
  +     * mark character.
        *
        * @param queryString the query string
        * 
  @@ -469,8 +485,8 @@
       }
   
       /**
  -     * Sets the query string.  The pairs are encoded as UTF-8 characters.  To use
  -     * a different charset the parameters can be encoded manually using EncodingUtil 
  +     * Sets the query string of this HTTP method.  The pairs are encoded as UTF-8 characters.  
  +     * To use a different charset the parameters can be encoded manually using EncodingUtil 
        * and set as a single String.
        *
        * @param params an array of {@link NameValuePair}s to add as query string
  @@ -486,9 +502,9 @@
       }
   
       /**
  -     * Get my query string.
  +     * Gets the query string of this HTTP method.
        *
  -     * @return The query string portion of the request
  +     * @return The query string
        */
       public String getQueryString() {
           return queryString;
  @@ -507,9 +523,9 @@
       }
   
       /**
  -     * Set the specified request header, overwriting any previous value. Note
  -     * that header-name matching is case insensitive.
  -     *
  +     * Sets the specified request header, overwriting any previous value.
  +     * Note that header-name matching is case insensitive.
  +     * 
        * @param header the header
        */
       public void setRequestHeader(Header header) {
  @@ -525,14 +541,14 @@
       }
   
       /**
  -     * Get the request header associated with the given name. Header name
  -     * matching is case insensitive. <tt>null</tt> will be returned if either
  +     * Returns the specified request header. Note that header-name matching is
  +     * case insensitive. <tt>null</tt> will be returned if either
        * <i>headerName</i> is <tt>null</tt> or there is no matching header for
        * <i>headerName</i>.
  +     * 
  +     * @param headerName The name of the header to be returned.
        *
  -     * @param headerName the header name to match
  -     *
  -     * @return the matching header
  +     * @return The specified request header.
        */
       public Header getRequestHeader(String headerName) {
           if (headerName == null) {
  @@ -543,7 +559,7 @@
       }
   
       /**
  -     * Provides access to the request headers.
  +     * Returns an array of the requests headers that the HTTP method currently has
        *
        * @return an array of my request headers.
        */
  @@ -552,7 +568,7 @@
       }
   
       /**
  -     * Gets the HeaderGroup storing the request headers.
  +     * Gets the {@link HeaderGroup header group} storing the request headers.
        * 
        * @return a HeaderGroup
        * 
  @@ -563,8 +579,8 @@
       }
   
       /**
  -     * Gets the HeaderGroup storing the response trailer headers as per RFC
  -     * 2616 section 3.6.1.
  +     * Gets the {@link HeaderGroup header group} storing the response trailer headers 
  +     * as per RFC 2616 section 3.6.1.
        * 
        * @return a HeaderGroup
        * 
  @@ -575,7 +591,7 @@
       }
   
       /**
  -     * Gets the HeaderGroup storing the response headers.
  +     * Gets the {@link HeaderGroup header group} storing the response headers.
        * 
        * @return a HeaderGroup
        * 
  @@ -586,7 +602,7 @@
       }
       
       /**
  -     * Convenience method top provide access to the status code.
  +     * Returns the response status code.
        *
        * @return the status code associated with the latest response.
        */
  @@ -595,7 +611,7 @@
       }
   
       /**
  -     * Provide access to the status line.
  +     * Provides access to the response status line.
        *
        * @return the status line object from the latest response.
        * @since 2.0
  @@ -606,23 +622,24 @@
   
       /**
        * Checks if response data is available.
  -     * @return true if response data is available, false otherwise.
  +     * @return <tt>true</tt> if response data is available, <tt>false</tt> otherwise.
        */
       private boolean responseAvailable() {
           return (responseBody != null) || (responseStream != null);
       }
   
       /**
  -     * Gets the response headers in the order in which they were read.
  +     * Returns an array of the response headers that the HTTP method currently has
  +     * in the order in which they were read.
        *
  -     * @return an array of my response headers.
  +     * @return an array of response headers.
        */
       public Header[] getResponseHeaders() {
           return getResponseHeaderGroup().getAllHeaders();
       }
   
       /**
  -     * Get the response header associated with the given name. Header name
  +     * Gets the response header associated with the given name. Header name
        * matching is case insensitive. <tt>null</tt> will be returned if either
        * <i>headerName</i> is <tt>null</tt> or there is no matching header for
        * <i>headerName</i>.
  @@ -641,7 +658,7 @@
   
   
       /**
  -     * Return the length (in bytes) of my response body, as specified in a
  +     * Return the length (in bytes) of the response body, as specified in a
        * <tt>Content-Length</tt> header.
        *
        * <p>
  @@ -677,9 +694,10 @@
   
   
       /**
  -     * Return my response body, if any, as a byte array. Otherwise return
  -     * <tt>null</tt>.
  -     * @return The response body as a byte array.
  +     * Returns the response body of the HTTP method, if any, as an array of bytes.
  +     * If response body is not available or cannot be read, returns <tt>null</tt>
  +     * 
  +     * @return The response body.
        */
       public byte[] getResponseBody() {
           if (this.responseBody == null) {
  @@ -706,12 +724,13 @@
       }
   
       /**
  -     * Return my response body, if any, as an {@link InputStream}. Otherwise
  -     * return <tt>null</tt>.
  -     *
  -     * @return the response body as an {@link InputStream}
  -     *
  -     * @throws IOException when there are errors obtaining the response
  +     * Returns the response body of the HTTP method, if any, as an {@link InputStream}. 
  +     * If response body is not available, returns <tt>null</tt>
  +     * 
  +     * @return The response body
  +     * 
  +     * @throws IOException If an I/O (transport) problem occurs while obtaining the 
  +     * response body.
        */
       public InputStream getResponseBodyAsStream() throws IOException {
           if (responseStream != null) {
  @@ -726,15 +745,12 @@
       }
   
       /**
  -     * Gets the response body as a string.
  +     * Returns the response body of the HTTP method, if any, as a {@link String}. 
  +     * If response body is not available or cannot be read, returns <tt>null</tt>
  +     * The string conversion on the data is done using the character encoding specified
  +     * in <tt>Content-Type</tt> header.
        *
  -     * <b>Note:</b> The string conversion done on the data is done with the
  -     * default character encoding.  The use of this method may be non-portable.
  -     * To ensure portability, you can use {@link #getResponseBody()} to get
  -     * the body as an array of bytes and then do your own character encoding.
  -     *
  -     * @return Stringified form of the responseBody if it exists, 
  -     *   otherwise <tt>null</tt>.
  +     * @return The response body.
        */
       public String getResponseBodyAsString() {
           byte[] rawdata = null;
  @@ -749,15 +765,17 @@
       }
   
       /**
  -     * Gets the response footers in the order in which they were read.
  -     * @return an array of headers
  +     * Returns an array of the response footers that the HTTP method currently has
  +     * in the order in which they were read.
  +     *
  +     * @return an array of footers
        */
       public Header[] getResponseFooters() {
           return getResponseTrailerHeaderGroup().getAllHeaders();
       }
   
       /**
  -     * Get the response footer associated with the given name.
  +     * Gets the response footer associated with the given name.
        * Footer name matching is case insensitive.
        * <tt>null</tt> will be returned if either <i>footerName</i> is
        * <tt>null</tt> or there is no matching header for <i>footerName</i>
  @@ -774,7 +792,7 @@
       }
   
       /**
  -     * Set the response stream.
  +     * Sets the response stream.
        * @param responseStream The new response stream.
        */
       protected void setResponseStream(InputStream responseStream) {
  @@ -782,6 +800,8 @@
       }
   
       /**
  +     * Returns the current response stream
  +     *
        * @return the current response stream
        */
       protected InputStream getResponseStream() {
  @@ -789,10 +809,10 @@
       }
       
       /**
  -     * Provide access to the status text
  -     *
  -     * @return the status text (or "reason phrase") associated with the latest
  -     *         response.
  +     * Returns the status text (or "reason phrase") associated with the latest
  +     * response.
  +     * 
  +     * @return The status text.
        */
       public String getStatusText() {
           return statusLine.getReasonPhrase();
  @@ -805,23 +825,23 @@
        * it attempts to mimic the exact behaviour of commonly used HTTP agents, 
        * which many HTTP servers expect.
        * 
  -     * @param strictMode true for strict mode, false otherwise
  +     * @param strictMode <tt>true</tt> for strict mode, <tt>false</tt> otherwise
        */
       public void setStrictMode(boolean strictMode) {
           this.strictMode = strictMode;
       }
   
       /**
  -     * Returns the value of strictMode.
  -     * 
  -     * @return true if strict mode is enabled.
  +     * Returns the value of the strict mode flag.
  +     *
  +     * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
        */
       public boolean isStrictMode() {
           return strictMode;
       }
   
       /**
  -     * Add the specified request header, NOT overwriting any previous value.
  +     * Adds the specified request header, NOT overwriting any previous value.
        * Note that header-name matching is case insensitive.
        *
        * @param headerName the header's name
  @@ -853,9 +873,9 @@
       }
   
       /**
  -     * Return true if we should close the connection now.  The connection will
  -     * only be left open if we are using HTTP1.1 or if "Connection: keep-alive" 
  -     * was sent.
  +     * Tests if the connection should be closed after the method has been executed.
  +     * The connection will be left open when using HTTP/1.1 or if <tt>Connection: 
  +     * keep-alive</tt> header was sent.
        * 
        * @param conn the connection in question
        * 
  @@ -915,10 +935,10 @@
       }
       
       /**
  -     * Return true if a retry is needed.
  +     * Tests if the method needs to be retried.
        * @param statusCode The status code
  -     * @param state The state.
  -     * @param conn The connection
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} to be used
        * @return boolean true if a retry is needed.
        */
       private boolean isRetryNeeded(int statusCode, HttpState state, HttpConnection conn) {
  @@ -957,11 +977,11 @@
       }
   
       /**
  -     * Check to see if the this method is ready to be executed.
  +     * Tests if the this method is ready to be executed.
        * 
  -     * @param state The state.
  -     * @param conn The connection.
  -     * @throws HttpException If the method isn't valid.
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} to be used
  +     * @throws HttpException If the method is in invalid state.
        */
       private void checkExecuteConditions(HttpState state, HttpConnection conn)
       throws HttpException {
  @@ -984,16 +1004,17 @@
       }
   
       /**
  -     * Execute this method. Note that we cannot currently support redirects
  +     * Execute this HTTP method. Note that we cannot currently support redirects
        * that change  the connection parameters (host, port, protocol) because
        * we  don't yet have a good way to get the new connection.  For  the time
        * being, we just return the redirect response code,  and allow the user
        * agent to resubmit if desired.
        *
  -     * @param state {@link HttpState} information to associate with this
  +     * @param state {@link HttpState state} information to associate with this
        *        request. Must be non-null.
  -     * @param conn the{@link HttpConnection} to write to/read from. Must be
  -     *        non-null. Note that we cannot currently support redirects that
  +     * @param conn the {@link HttpConnection connection} to used to execute
  +     *        this HTTP method. Must be non-null.
  +     *        Note that we cannot currently support redirects that
        *        change the HttpConnection parameters (host, port, protocol)
        *        because we don't yet have a good way to get the new connection.
        *        For the time being, we just return the 302 response, and allow
  @@ -1001,10 +1022,11 @@
        *
        * @return the integer status code if one was obtained, or <tt>-1</tt>
        *
  -     * @throws HttpException  if an protocol exception occurs
  -     * @throws HttpRecoverableException if too many redirects occur.
  -     * @throws IOException if an I/O error occurs
  -     * @throws NullPointerException if the state is null
  +     * @throws IOException if an I/O (transport) error occurs
  +     * @throws HttpException  if a protocol exception occurs.
  +     * @throws HttpRecoverableException if a recoverable transport error occurs. 
  +     *                    Usually this kind of exceptions can be recovered from by
  +     *                    retrying the HTTP method 
        */
       public int execute(HttpState state, HttpConnection conn)
           throws HttpException, HttpRecoverableException, IOException {
  @@ -1094,8 +1116,10 @@
   
       /**
        * Process the redirect response.
  -     * @param conn The connection to use.
  -     * @return boolean true if the redirect was successful.
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     * @return boolean <tt>true</tt> if the redirect was successful, <tt>false</tt>
  +     *        otherwise.
        */
       private boolean processRedirectResponse(HttpConnection conn) {
   
  @@ -1177,7 +1201,7 @@
       }
   
       /**
  -     * Check for a valid redirect given the current conn and new URI.
  +     * Check for a valid redirect given the current connection and new URI.
        * Redirect to a different protocol, host or port are checked for validity.
        *
        * @param currentUri The current URI (redirecting from)
  @@ -1221,7 +1245,7 @@
       /**
        * Returns the default port for the given protocol.
        *
  -     * @param protocol currently only http and https are recognized
  +     * @param protocol the given protocol.
        * @return the default port of the given protocol or -1 if the
        * protocol is not recognized.
        *
  @@ -1239,18 +1263,22 @@
       }
   
       /**
  -     * Whether the object has been used and not recycled.
  -     *
  -     * @return <tt>true</tt> if I have been {@link #execute executed} but not
  -     *         recycled.
  +     * Returns <tt>true</tt> if the HTTP method has been already {@link #execute executed},
  +     * but not {@link #recycle recycled}.
  +     * 
  +     * @return <tt>true</tt> if the method has been executed, <tt>false</tt> otherwise
        */
       public boolean hasBeenUsed() {
           return used;
       }
   
       /**
  -     * Recycle this method so that it can be used again. All of my instances
  -     * variables will be reset once this method has been called.
  +     * Recycles the HTTP method so that it can be used again.
  +     * Note that all of the instance variables will be reset
  +     * once this method has been called. This method will also
  +     * release the connection being used by this HTTP method.
  +     * 
  +     * @see #releaseConnection()
        */
       public void recycle() {
           LOG.trace("enter HttpMethodBase.recycle()");
  @@ -1277,7 +1305,10 @@
       }
   
       /**
  -     * @see org.apache.commons.httpclient.HttpMethod#releaseConnection()
  +     * Releases the connection being used by this HTTP method. In particular the
  +     * connection is used to read the response(if there is one) and will be held
  +     * until the response has been read. If the connection can be reused by other 
  +     * HTTP methods it is NOT closed at this point.
        *
        * @since 2.0
        */
  @@ -1316,28 +1347,26 @@
       // ---------------------------------------------------------------- Queries
   
       /**
  -     * Confirm that I am ready to execute.
  -     *
  -     * <p>
  -     * This implementation always returns <tt>true</tt>.
  -     * </p>
  -     *
  -     * @return <tt>true</tt>
  +     * Returns <tt>true</tt> the method is ready to execute, <tt>false</ff> otherwise.
  +     * 
  +     * @return This implementation always returns <tt>true</tt>.
        */
       public boolean validate() {
           return true;
       }
   
       /**
  -     * Adds an <tt>Authorization</tt> request if needed, as long as no
  +     * Generates <tt>Authorization</tt> request header if needed, as long as no
        * <tt>Authorization</tt> request header already exists.
        *
  -     * @param state current state of http requests
  -     * @param conn the connection to use for I/O
  -     *
  -     * @throws IOException when errors occur reading or writing to/from the
  -     *         connection
  -     * @throws HttpException when a recoverable error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addAuthorizationRequestHeader(HttpState state,
                                                    HttpConnection conn)
  @@ -1364,14 +1393,17 @@
       }
   
       /**
  -     * Adds a <tt>Cookie</tt> request containing the matching {@link Cookie}s.
  -     *
  -     * @param state current state of http requests
  -     * @param conn the connection to use for I/O
  +     * Generates <tt>Cookie</tt> request headers for those {@link Cookie cookie}s
  +     * that match the given host, port and path.
        *
  -     * @throws IOException when errors occur reading or writing to/from the
  -     *         connection
  -     * @throws HttpException when a recoverable error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addCookieRequestHeader(HttpState state, HttpConnection conn)
           throws IOException, HttpException {
  @@ -1401,15 +1433,17 @@
       }
   
       /**
  -     * Adds a <tt>Host</tt> request header, as long as no <tt>Host</tt> request
  +     * Generates <tt>Host</tt> request header, as long as no <tt>Host</tt> request
        * header already exists.
        *
  -     * @param state current state of http requests
  -     * @param conn the connection to use for I/O
  -     *
  -     * @throws IOException when errors occur reading or writing to/from the
  -     *         connection
  -     * @throws HttpException when a recoverable error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addHostRequestHeader(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -1455,15 +1489,17 @@
       }
   
       /**
  -     * Adds a <tt>Proxy-Authorization</tt> request if needed, as long as no
  +     * Generates <tt>Proxy-Authorization</tt> request header if needed, as long as no
        * <tt>Proxy-Authorization</tt> request header already exists.
        *
  -     * @param state current state of http requests
  -     * @param conn the connection to use for I/O
  -     *
  -     * @throws IOException when errors occur reading or writing to/from the
  -     *         connection
  -     * @throws HttpException when a recoverable error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addProxyAuthorizationRequestHeader(HttpState state,
                                                         HttpConnection conn)
  @@ -1490,15 +1526,17 @@
       }
   
       /**
  -     * Adds a <tt>Proxy-Connection: Keep-Alive</tt> request when 
  +     * Generates <tt>Proxy-Connection: Keep-Alive</tt> request header when 
        * communicating via a proxy server.
        *
  -     * @param state current state of http requests
  -     * @param conn the connection to use for I/O
  -     *
  -     * @throws IOException when errors occur reading or writing to/from the
  -     *         connection
  -     * @throws HttpException when a recoverable error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addProxyConnectionHeader(HttpState state,
                                               HttpConnection conn)
  @@ -1511,8 +1549,8 @@
       }
   
       /**
  -     * Populates the request headers map to with additional {@link Header
  -     * headers} to be submitted to the given {@link HttpConnection}.
  +     * Generates all the required request {@link Header header}s 
  +     * to be submitted via the given {@link HttpConnection connection}.
        *
        * <p>
        * This implementation adds <tt>User-Agent</tt>, <tt>Host</tt>,
  @@ -1526,11 +1564,14 @@
        * <tt>super</tt>) to add the "standard" headers.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} the headers will eventually be
  -     *        written to
  -     * @throws IOException when an error occurs writing the request
  -     * @throws HttpException when a HTTP protocol error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #writeRequestHeaders
        */
  @@ -1548,14 +1589,17 @@
       }
   
       /**
  -     * Adds a default <tt>User-Agent</tt> request header, as long as no
  +     * Generates default <tt>User-Agent</tt> request header, as long as no
        * <tt>User-Agent</tt> request header already exists.
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} the headers will eventually be
  -     *        written to
  -     * @throws IOException when an error occurs writing the request
  -     * @throws HttpException when a HTTP protocol error occurs
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void addUserAgentRequestHeader(HttpState state,
                                                HttpConnection conn)
  @@ -1569,7 +1613,8 @@
       }
   
       /**
  -     * Throws an {@link IllegalStateException} if used but not recycled.
  +     * Throws an {@link IllegalStateException} if the HTTP method has been already
  +     * {@link #execute executed}, but not {@link #recycle recycled}.
        *
        * @throws IllegalStateException if the method has been used and not
        *      recycled
  @@ -1581,7 +1626,9 @@
       }
   
       /**
  -     * Throws an {@link IllegalStateException} if not used since last recycle.
  +     * Throws an {@link IllegalStateException} if the HTTP method has not been
  +     * {@link #execute executed} since last {@link #recycle recycle}.
  +     *
        *
        * @throws IllegalStateException if not used
        */
  @@ -1594,15 +1641,16 @@
       // ------------------------------------------------- Static Utility Methods
   
       /**
  -     * Generate an HTTP/S request line according to the specified attributes.
  +     * Generates HTTP request line according to the specified attributes.
        *
  -     * @param connection the connection the request will be sent to
  +     * @param connection the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        * @param name the method name generate a request for
        * @param requestPath the path string for the request
        * @param query the query string for the request
        * @param version the protocol version to use (e.g. HTTP/1.0)
        *
  -     * @return a line to send to the server that will fulfil the request
  +     * @return HTTP request line
        */
       protected static String generateRequestLine(HttpConnection connection,
           String name, String requestPath, String query, String version) {
  @@ -1651,19 +1699,17 @@
       }
       
       /**
  -     * When this method is invoked, {@link #readResponseBody
  -     * readResponseBody(HttpState,HttpConnection)} will have been invoked.
  +     * This method is invoked immediately after 
  +     * {@link #readResponseBody(HttpState,HttpConnection)} and can be overridden by
  +     * sub-classes in order to provide custom body processing.
        *
        * <p>
        * This implementation does nothing.
        * </p>
        *
  -     * <p>
  -     * Subclasses may want to override this method.
  -     * </p>
  -     *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @see #readResponse
        * @see #readResponseBody
  @@ -1672,25 +1718,19 @@
       }
   
       /**
  -     * When this method is invoked, the response headers map will have been
  -     * populated with the response headers (in other words, {@link
  -     * #readResponseHeaders readResponseHeaders(HttpState,HttpConnection)}
  -     * will have been invoked).
  -     *
  +     * This method is invoked immediately after 
  +     * {@link #readResponseHeaders(HttpState,HttpConnection)} and can be overridden by
  +     * sub-classes in order to provide custom response headers processing.
  +
        * <p>
        * This implementation will handle the <tt>Set-Cookie</tt> and
        * <tt>Set-Cookie2</tt> headers, if any, adding the relevant cookies to
        * the given {@link HttpState}.
        * </p>
        *
  -     * <p>
  -     * Subclasses may want to override this method to specially process
  -     * additional headers, and/or invoke this method (via <tt>super</tt>) to
  -     * process the <tt>Set-Cookie</tt> and <tt>Set-Cookie2</tt> headers.
  -     * </p>
  -     *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @see #readResponse
        * @see #readResponseHeaders
  @@ -1752,18 +1792,13 @@
       }
   
       /**
  -     * When this method is invoked, the {@link #getStatusCode status code} and
  -     * {@link #getStatusText status text} values will have been set (in other
  -     * words, {@link #readStatusLine readStatusLine(HttpState,HttpConnection}
  -     * will have been invoked).
  -     *
  -     * <p>
  -     * Subclasses may want to override this method to respond to these value.
  -     * This implementation does nothing.
  -     * </p>
  -     *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  +     * This method is invoked immediately after 
  +     * {@link #readStatusLine(HttpState,HttpConnection)} and can be overridden by
  +     * sub-classes in order to provide custom response status line processing.
  +     *
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @see #readResponse
        * @see #readStatusLine
  @@ -1772,39 +1807,36 @@
       }
   
       /**
  -     * Reads the response from the given {@link HttpConnection}.
  +     * Reads the response from the given {@link HttpConnection connection}.
        *
        * <p>
  -     * The response is written according to the following logic:
  +     * The response is processed as the following sequence of actions:
        *
        * <ol>
        * <li>
  -     * {@link #readStatusLine readStatusLine(HttpState,HttpConnection)} is
  +     * {@link #readStatusLine(HttpState,HttpConnection)} is
        * invoked to read the request line.
        * </li>
        * <li>
  -     * {@link #processStatusLine processStatusLine(HttpState,HttpConnection)}
  -     * is invoked, allowing the method to respond to the status line if
  +     * {@link #processStatusLine(HttpState,HttpConnection)}
  +     * is invoked, allowing the method to process the status line if
        * desired.
        * </li>
        * <li>
  -     * {@link #readResponseHeaders
  -     * readResponseHeaders(HttpState,HttpConnection} is invoked to read the
  -     * associated headers.
  +     * {@link #readResponseHeaders(HttpState,HttpConnection)} is invoked to read
  +     * the associated headers.
        * </li>
        * <li>
  -     * {@link #processResponseHeaders
  -     * processResponseHeaders(HttpState,HttpConnection} is invoked, allowing
  -     * the method to respond to the headers if desired.
  +     * {@link #processResponseHeaders(HttpState,HttpConnection)} is invoked, allowing
  +     * the method to process the headers if desired.
        * </li>
        * <li>
  -     * {@link #readResponseBody readResponseBody(HttpState,HttpConnection)} is
  +     * {@link #readResponseBody(HttpState,HttpConnection)} is
        * invoked to read the associated body (if any).
        * </li>
        * <li>
  -     * {@link #processResponseBody
  -     * processResponseBody(HttpState,HttpConnection} is invoked, allowing the
  -     * method to respond to the body if desired.
  +     * {@link #processResponseBody(HttpState,HttpConnection)} is invoked, allowing the
  +     * method to process the response body if desired.
        * </li>
        * </ol>
        *
  @@ -1813,9 +1845,14 @@
        * if dramatically different processing is required.)
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  -     * @throws HttpException when a protocol or i/o error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void readResponse(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -1856,10 +1893,14 @@
        * processing.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #readResponse
        * @see #processResponseBody
  @@ -1882,20 +1923,22 @@
       }
   
       /**
  -     * Read the response body from the given {@link HttpConnection}.
  -     * <p>
  -     * The current implementation returns an appropriate stream
  -     * (according to the values of the
  -     * <tt>Content-Length</tt> and <tt>Transfer-Encoding</tt>
  -     * headers, if any).
  +     * Returns the response body as an {@link InputStream input stream}
  +     * corresponding to the values of the <tt>Content-Length</tt> and 
  +     * <tt>Transfer-Encoding</tt> headers. If no response body is available
  +     * returns <tt>null</tt>.
        * <p>
        *
        * @see #readResponse
        * @see #processResponseBody
        *
  -     * @param conn the {@link HttpConnection} to read the response from
  -     * @return InputStream to read the response body from
  -     * @throws IOException if an IO problem occurs.
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       private InputStream readResponseBody(HttpConnection conn)
           throws HttpException, IOException {
  @@ -1975,8 +2018,7 @@
       }
   
       /**
  -     * Read response headers from the given {@link HttpConnection}, populating
  -     * the response headers map.
  +     * Reads the response headers from the given {@link HttpConnection connection}.
        *
        * <p>
        * Subclasses may want to override this method to to customize the
  @@ -1990,10 +2032,14 @@
        * separated by a comma." - HTTP/1.0 (4.3)
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #readResponse
        * @see #processResponseHeaders
  @@ -2023,15 +2069,14 @@
        * processing.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to read the response from
  -     *
  -     * @throws IOException when errors occur reading the status line
  -     * @throws HttpException If there is no status line, the protocol is not
  -     *      recognised, if we are unable to parse the status code from the line,
  -     *      or there was no status text
  -     * @throws HttpRecoverableException when the status line is null and the
  -     *      request should be retried
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see StatusLine
        */
  @@ -2077,28 +2122,28 @@
   
       /**
        * <p>
  -     * Writes my request to the given {@link HttpConnection}.
  +     * Sends the request via the given {@link HttpConnection connection}.
        * </p>
        *
        * <p>
  -     * The request is written according to the following logic:
  +     * The request is written as the following sequence of actions:
        * </p>
        *
        * <ol>
        * <li>
  -     * {@link #writeRequestLine writeRequestLine(HttpState, HttpConnection)} is
  -     * invoked to write the request line.
  +     * {@link #writeRequestLine(HttpState, HttpConnection)} is invoked to 
  +     * write the request line.
        * </li>
        * <li>
  -     * {@link #writeRequestHeaders writeRequestHeaders(HttpState,
  -     * HttpConnection)} is invoked to write the associated headers.
  +     * {@link #writeRequestHeaders(HttpState, HttpConnection)} is invoked 
  +     * to write the associated headers.
        * </li>
        * <li>
        * <tt>\r\n</tt> is sent to close the head part of the request.
        * </li>
        * <li>
  -     * {@link #writeRequestBody writeRequestBody(HttpState, HttpConnection)} is
  -     * invoked to write the body part of the request.
  +     * {@link #writeRequestBody(HttpState, HttpConnection)} is invoked to 
  +     * write the body part of the request.
        * </li>
        * </ol>
        *
  @@ -2108,10 +2153,14 @@
        * if dramatically different processing is required.)
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to write the request to
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected void writeRequest(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -2172,29 +2221,28 @@
       }
   
       /**
  -     * Write the request body to the given {@link HttpConnection}.
  -     *
  -     * <p>
  -     * If an expectation is required, this method should ensure that it has
  -     * been sent by checking the {@link #getStatusCode status code}.
  -     * </p>
  +     * Writes the request body to the given {@link HttpConnection connection}.
        *
        * <p>
        * This method should return <tt>true</tt> if the request body was actually
        * sent (or is empty), or <tt>false</tt> if it could not be sent for some
  -     * reason (for example, expectation required but not present).
  +     * reason.
        * </p>
        *
        * <p>
        * This implementation writes nothing and returns <tt>true</tt>.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the connection to write to
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @return <tt>true</tt>
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        */
       protected boolean writeRequestBody(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -2202,12 +2250,11 @@
       }
   
       /**
  -     * Writes the request headers to the given {@link HttpConnection}.
  +     * Writes the request headers to the given {@link HttpConnection connection}.
        *
        * <p>
  -     * This implementation invokes {@link #addRequestHeaders
  -     * addRequestHeaders(HttpState,HttpConnection)}, and then writes each
  -     * header to the request stream.
  +     * This implementation invokes {@link #addRequestHeaders(HttpState,HttpConnection)},
  +     * and then writes each header to the request stream.
        * </p>
        *
        * <p>
  @@ -2215,10 +2262,14 @@
        * processing.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to write to
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #addRequestHeaders
        * @see #getRequestHeaders
  @@ -2240,17 +2291,21 @@
       }
   
       /**
  -     * Writes the "request line" to the given {@link HttpConnection}.
  +     * Writes the request line to the given {@link HttpConnection connection}.
        *
        * <p>
        * Subclasses may want to override this method to to customize the
        * processing.
        * </p>
        *
  -     * @param state the client state
  -     * @param conn the {@link HttpConnection} to write to
  -     * @throws IOException when i/o errors occur reading the response
  -     * @throws HttpException when a protocol error occurs or state is invalid
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
  +     *
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #generateRequestLine
        */
  @@ -2266,11 +2321,11 @@
       }
   
       /**
  -     * Gets the request line that was sent to the http server.
  -     * Consider making this public.  Consider creating a new class
  -     * RequestLine for this purpose.
  +     * Returns the request line.
  +     * 
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        * 
  -     * @param conn The http connection
        * @return The request line.
        */
       private String getRequestLine(HttpConnection conn) {
  @@ -2308,7 +2363,7 @@
        *
        * @param status - the HTTP status code
        *
  -     * @return true if the message may contain a body, false if it can not
  +     * @return <tt>true</tt> if the message may contain a body, <tt>false</tt> if it can not
        *         contain a message body
        */
       private static boolean canResponseHaveBody(int status) {
  @@ -2325,10 +2380,11 @@
       }
   
       /**
  -     * process a response that requires authentication
  +     * Processes a response that requires authentication
        *
  -     * @param state the current state
  -     * @param conn The connection
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
        * @return true if the request has completed process, false if more
        *         attempts are needed
  @@ -2455,22 +2511,22 @@
       }
   
       /**
  -     * Write a request and read the response. Both the write to the server will
  -     * be retried {@link #maxRetries} times if the operation fails with a
  -     * HttpRecoverableException. The write will only be attempted if the read
  -     * has succeeded.
  +     * Sends the request and reads the response. The request will be retried 
  +     * {@link #maxRetries} times if the operation fails with a
  +     * {@link HttpRecoverableException}.
        *
        * <p>
  -     * The <i>used</i> is set to true if the write succeeds.
  +     * The {@link #isUsed()} is set to true if the write succeeds.
        * </p>
        *
  -     * @param state the current state
  -     * @param connection the connection for communication
  +     * @param state the {@link HttpState state} information associated with this method
  +     * @param conn the {@link HttpConnection connection} used to execute
  +     *        this HTTP method
        *
  -     * @throws HttpException when errors occur as part of the HTTP protocol
  -     *         conversation
  -     * @throws IOException when an I/O error occurs communicating with the
  -     *         server
  +     * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
  +     *                     can be recovered from.
  +     * @throws HttpException  if a protocol exception occurs. Usually protocol exceptions 
  +     *                    cannot be recovered from.
        *
        * @see #writeRequest(HttpState,HttpConnection)
        * @see #readResponse(HttpState,HttpConnection)
  @@ -2530,7 +2586,7 @@
       }
   
       /**
  -     * Return the character set from the header.
  +     * Returns the character set from the <tt>Content-Type</tt> header.
        * @param contentheader The content header.
        * @return String The character set.
        */
  @@ -2561,8 +2617,8 @@
   
   
       /**
  -     * Return the character set for the request.  This is determined from the
  -     * "Content-Type" header.
  +     * Returns the character encoding of the request from the <tt>Content-Type</tt> header.
  +     * 
        * @return String The character set.
        */
       public String getRequestCharSet() {
  @@ -2571,8 +2627,8 @@
   
   
       /**  
  -     * Return the character set for the response.  This is determined from the
  -     * "Content-Type" header.
  +     * Returns the character encoding of the response from the <tt>Content-Type</tt> header.
  +     * 
        * @return String The character set.
        */
       public String getResponseCharSet() {
  @@ -2626,15 +2682,17 @@
       }
   
       /**
  -     * Returns the hostConfiguration.
  -     * @return HostConfiguration
  +     * Returns the {@link HostConfiguration host configuration}.
  +     * 
  +     * @return the host configuration
        */
       public HostConfiguration getHostConfiguration() {
           return hostConfiguration;
       }
   
       /**
  -     * Sets the hostConfiguration.
  +     * Sets the {@link HostConfiguration host configuration}.
  +     * 
        * @param hostConfiguration The hostConfiguration to set
        */
       public void setHostConfiguration(HostConfiguration hostConfiguration) {
  @@ -2642,6 +2700,8 @@
       }
   
       /**
  +     * Returns the {@link MethodRetryHandler retry handler} for this HTTP method
  +     * 
        * @return the methodRetryHandler
        */
       public MethodRetryHandler getMethodRetryHandler() {
  @@ -2654,6 +2714,8 @@
       }
   
       /**
  +     * Sets the {@link MethodRetryHandler retry handler} for this HTTP method
  +     * 
        * @param handler the methodRetryHandler to use when this method executed
        */
       public void setMethodRetryHandler(MethodRetryHandler handler) {
  
  
  

Mime
View raw message