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 22:01:32 GMT
olegk       2003/08/03 15:01:32

  Modified:    httpclient/src/java/org/apache/commons/httpclient Tag:
                        HTTPCLIENT_2_0_BRANCH HttpMethod.java
                        HttpMethodBase.java
  Log:
  Javadocs clean-up in HttpMethod & HttpMethodBase
  
  Contributed by Oleg Kalnichevski
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.23.2.2  +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.23.2.1
  retrieving revision 1.23.2.2
  diff -u -r1.23.2.1 -r1.23.2.2
  --- HttpMethod.java	2 Aug 2003 22:27:49 -0000	1.23.2.1
  +++ HttpMethod.java	3 Aug 2003 22:01:31 -0000	1.23.2.2
  @@ -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();
   
  @@ -129,12 +132,13 @@
       URI getURI() 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);
   
  @@ -336,7 +340,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.159.2.6 +438 -359  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.159.2.5
  retrieving revision 1.159.2.6
  diff -u -r1.159.2.5 -r1.159.2.6
  --- HttpMethodBase.java	26 Jul 2003 14:07:34 -0000	1.159.2.5
  +++ HttpMethodBase.java	3 Aug 2003 22:01:31 -0000	1.159.2.6
  @@ -161,37 +161,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. */
  @@ -200,25 +201,29 @@
       /** 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;
   
  -    /** Whether or not I should use the HTTP/1.1 protocol. The default is <tt>true</tt>. */
  +    /** True if version 1.1 of the HTTP protocol should be used per default. */
       private boolean http11 = true;
   
  -    /** 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;
   
       /**
  @@ -226,13 +231,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. */
  @@ -296,17 +301,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,39 +348,43 @@
       }
   
       /**
  -     * 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
        */
       public void setHttp11(boolean http11) {
           this.http11 = http11;
       }
   
  -        /**
  -     * 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() {
  @@ -380,10 +392,12 @@
       }
   
       /**
  -     * 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) {
  @@ -393,21 +407,21 @@
       // ---------------------------------------------- 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
        */
       public boolean isHttp11() {
           return http11;
       }
   
       /**
  -     * 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) {
  @@ -415,9 +429,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
        */
  @@ -432,15 +445,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.
        */
  @@ -449,8 +466,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
        * 
  @@ -461,8 +479,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
  @@ -478,9 +496,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;
  @@ -499,9 +517,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) {
  @@ -517,14 +535,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) {
  @@ -535,7 +553,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.
        */
  @@ -544,7 +562,7 @@
       }
   
       /**
  -     * Gets the HeaderGroup storing the request headers.
  +     * Gets the {@link HeaderGroup header group} storing the request headers.
        * 
        * @return a HeaderGroup
        * 
  @@ -555,8 +573,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
        * 
  @@ -567,7 +585,7 @@
       }
   
       /**
  -     * Gets the HeaderGroup storing the response headers.
  +     * Gets the {@link HeaderGroup header group} storing the response headers.
        * 
        * @return a HeaderGroup
        * 
  @@ -578,7 +596,7 @@
       }
       
       /**
  -     * Convenience method top provide access to the status code.
  +     * Returns the response status code.
        *
        * @return the status code associated with the latest response.
        */
  @@ -587,7 +605,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
  @@ -598,23 +616,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>.
  @@ -633,7 +652,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>
  @@ -669,9 +688,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) {
  @@ -698,12 +718,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) {
  @@ -718,15 +739,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;
  @@ -741,15 +759,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>
  @@ -766,7 +786,7 @@
       }
   
       /**
  -     * Set the response stream.
  +     * Sets the response stream.
        * @param responseStream The new response stream.
        */
       protected void setResponseStream(InputStream responseStream) {
  @@ -774,6 +794,8 @@
       }
   
       /**
  +     * Returns the current response stream
  +     *
        * @return the current response stream
        */
       protected InputStream getResponseStream() {
  @@ -781,10 +803,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();
  @@ -797,23 +819,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
  @@ -845,9 +867,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
        * 
  @@ -857,7 +879,7 @@
   
           // Connection must be closed due to an abnormal circumstance 
           if (isConnectionCloseForced()) {
  -            LOG.debug("Should forcefully close connection.");
  +            LOG.debug("Should force-close connection.");
               return true;
           }
   
  @@ -903,10 +925,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) {
  @@ -945,20 +967,20 @@
       }
   
       /**
  -     * 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 {
   
  -        if (null == state) {
  -            throw new NullPointerException("HttpState parameter");
  +        if (state == null) {
  +            throw new IllegalArgumentException("HttpState parameter may not be null");
           }
  -        if (null == conn) {
  -            throw new NullPointerException("HttpConnection parameter");
  +        if (conn == null) {
  +            throw new IllegalArgumentException("HttpConnection parameter may not be null");
           }
           if (hasBeenUsed()) {
               throw new HttpException("Already used, but not recycled.");
  @@ -972,16 +994,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
  @@ -989,14 +1012,15 @@
        *
        * @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, NullPointerException {
  +            IOException {
                   
           LOG.trace("enter HttpMethodBase.execute(HttpState, HttpConnection)");
   
  @@ -1083,8 +1107,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) {
   
  @@ -1166,7 +1192,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)
  @@ -1216,7 +1242,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.
        *
  @@ -1234,18 +1260,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()");
  @@ -1272,7 +1302,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
        */
  @@ -1311,13 +1344,9 @@
       // ---------------------------------------------------------------- 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;
  @@ -1343,15 +1372,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addAuthorizationRequestHeader(HttpState state,
                                                    HttpConnection conn)
  @@ -1378,20 +1410,19 @@
       }
   
       /**
  -     * Adds a <tt>Content-Length</tt> or <tt>Transfer-Encoding: Chunked</tt>
  +     * Generates <tt>Content-Length</tt> or <tt>Transfer-Encoding: Chunked</tt>
        * request header, as long as no <tt>Content-Length</tt> request header
        * already exists.
        * 
  -     * TODO: Revise this method as it is potentially error-prone. 
  -     * 'Transfer-encoding: chunked' header should not be set here 
  -     * as some sub classes may not support chunk-encoding.
  -     *
  -     * @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
  +     * @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 
        */
       protected void addContentLengthRequestHeader(HttpState state,
                                                    HttpConnection conn)
  @@ -1411,14 +1442,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addCookieRequestHeader(HttpState state, HttpConnection conn)
           throws IOException, HttpException {
  @@ -1448,15 +1483,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addHostRequestHeader(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -1502,15 +1540,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addProxyAuthorizationRequestHeader(HttpState state,
                                                         HttpConnection conn)
  @@ -1537,15 +1578,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addProxyConnectionHeader(HttpState state,
                                               HttpConnection conn)
  @@ -1558,8 +1602,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>,
  @@ -1573,11 +1617,15 @@
        * <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
  +     * @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 
        *
        * @see #writeRequestHeaders
        */
  @@ -1596,14 +1644,18 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected void addUserAgentRequestHeader(HttpState state,
                                                HttpConnection conn)
  @@ -1617,7 +1669,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
  @@ -1629,7 +1682,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
        */
  @@ -1642,15 +1697,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) {
  @@ -1699,19 +1755,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
  @@ -1720,25 +1774,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
  @@ -1800,18 +1848,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
  @@ -1820,39 +1863,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>
        *
  @@ -1861,9 +1901,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 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 
        */
       protected void readResponse(HttpState state, HttpConnection conn)
       throws HttpException {
  @@ -1908,10 +1953,15 @@
        * 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
  +     * @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 
        *
        * @see #readResponse
        * @see #processResponseBody
  @@ -1934,20 +1984,23 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       private InputStream readResponseBody(HttpConnection conn)
           throws IOException {
  @@ -2027,8 +2080,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
  @@ -2042,10 +2094,15 @@
        * 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
  +     * @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 
        *
        * @see #readResponse
        * @see #processResponseHeaders
  @@ -2075,15 +2132,15 @@
        * 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
  +     * @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 
        *
        * @see StatusLine
        */
  @@ -2132,28 +2189,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>
        *
  @@ -2163,10 +2220,15 @@
        * 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
  +     * @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 
        */
       protected void writeRequest(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -2227,29 +2289,29 @@
       }
   
       /**
  -     * 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
  +     * @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 
        */
       protected boolean writeRequestBody(HttpState state, HttpConnection conn)
       throws IOException, HttpException {
  @@ -2257,12 +2319,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>
  @@ -2270,10 +2331,15 @@
        * 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
  +     * @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 
        *
        * @see #addRequestHeaders
        * @see #getRequestHeaders
  @@ -2295,17 +2361,22 @@
       }
   
       /**
  -     * 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
  +     * @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 
        *
        * @see #generateRequestLine
        */
  @@ -2321,11 +2392,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) {
  @@ -2336,7 +2407,7 @@
       /**
        * Get the HTTP version.
        *
  -     * @return HTTP/1.1 if http11, HTTP/1.0 otherwise
  +     * @return HTTP/1.1 if version 1.1 of HTTP protocol is used, HTTP/1.0 otherwise
        *
        * @since 2.0
        */
  @@ -2350,7 +2421,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) {
  @@ -2367,10 +2438,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
  @@ -2490,22 +2562,23 @@
       }
   
       /**
  -     * 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
  +     * @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 
        *
        * @see #writeRequest(HttpState,HttpConnection)
        * @see #readResponse(HttpState,HttpConnection)
  @@ -2565,7 +2638,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.
        */
  @@ -2600,8 +2673,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() {
  @@ -2610,8 +2683,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() {
  @@ -2665,15 +2738,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) {
  @@ -2681,6 +2756,8 @@
       }
   
       /**
  +     * Returns the {@link MethodRetryHandler retry handler} for this HTTP method
  +     * 
        * @return the methodRetryHandler
        */
       public MethodRetryHandler getMethodRetryHandler() {
  @@ -2693,6 +2770,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