You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ol...@apache.org on 2003/08/03 23:59:13 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethod.java HttpMethodBase.java
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) {