You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by mb...@apache.org on 2003/08/12 04:55:22 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethodBase.java HeaderGroup.java HttpMethod.java
mbecke 2003/08/11 19:55:22
Modified: httpclient/src/java/org/apache/commons/httpclient
HttpMethodBase.java HeaderGroup.java
HttpMethod.java
Log:
Javadoc enhancements.
PR: 22073
Submitted by: Laura Werner
Reviewed by: Michael Becke
Revision Changes Path
1.177 +13 -7 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.176
retrieving revision 1.177
diff -u -r1.176 -r1.177
--- HttpMethodBase.java 12 Aug 2003 02:35:17 -0000 1.176
+++ HttpMethodBase.java 12 Aug 2003 02:55:22 -0000 1.177
@@ -783,8 +783,11 @@
* 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>
- * or there are no footers available.
+ * <tt>null</tt> or there is no matching footer for <i>footerName</i>
+ * or there are no footers available. If there are multiple footers
+ * with the same name, there values will be combined with the ',' separator
+ * as specified by RFC2616.
+ *
* @param footerName the footer name to match
* @return the matching footer
*/
@@ -805,7 +808,10 @@
}
/**
- * Returns the current response stream
+ * Returns a stream from which the body of the current response may be read.
+ * If the method has not yet been executed, if <code>responseBodyConsumed</code>
+ * has been called, or if the stream returned by a previous call has been closed,
+ * <code>null</code> will be returned.
*
* @return the current response stream
*/
1.4 +4 -4 jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HeaderGroup.java
Index: HeaderGroup.java
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HeaderGroup.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- HeaderGroup.java 6 Apr 2003 22:31:52 -0000 1.3
+++ HeaderGroup.java 12 Aug 2003 02:55:22 -0000 1.4
@@ -132,7 +132,7 @@
/**
* Gets a header representing all of the header values with the given name.
* If more that one header with the given name exists the values will be
- * combined with a "," as per RFC 1945.
+ * combined with a "," as per RFC 2616.
*
* <p>Header name comparison is case insensitive.
*
1.28 +141 -57 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.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- HttpMethod.java 12 Aug 2003 02:35:17 -0000 1.27
+++ HttpMethod.java 12 Aug 2003 02:55:22 -0000 1.28
@@ -94,7 +94,9 @@
String getName();
/**
- * Gets the host configuration for this method.
+ * Gets the host configuration for this method. The configuration specifies
+ * the server, port, protocol, and proxy server via which this method will
+ * send its HTTP request.
*
* @return the HostConfiguration or <code>null</code> if none is set
*/
@@ -105,8 +107,8 @@
* It is responsibility of the caller to ensure that the path is
* properly encoded (URL safe).
*
- * @param path the path of the HTTP method. The path is expected
- * to be URL-encoded
+ * @param path The path of the HTTP method. The path is expected
+ * to be URL encoded.
*/
void setPath(String path);
@@ -117,15 +119,15 @@
* return the <em>actual</em> path, following any redirects automatically
* handled by this HTTP method.
*
- * @return the path of the HTTP method
+ * @return the path of the HTTP method, in URL encoded form
*/
String getPath();
/**
- * Gets the URI for this method. The URI will be absolute if the host
- * configuration has been set or relative otherwise.
+ * Returns the URI for this method. The URI will be absolute if the host
+ * configuration has been set and relative otherwise.
*
- * @return URI
+ * @return the URI for this method
*
* @throws URIException if a URI cannot be constructed
*/
@@ -141,13 +143,15 @@
void setURI(URI uri) throws URIException;
/**
- * Defines how strictly the method follows the HTTP protocol specification
- * (RFC 2616 and other relevant RFCs). In the strict mode the method precisely
+ * Defines how strictly the method follows the HTTP protocol specification.
+ * (See 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
+ *
+ * @see #isStrictMode()
*/
void setStrictMode(boolean strictMode);
@@ -155,6 +159,8 @@
* Returns the value of the strict mode flag.
*
* @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
+ *
+ * @see #setStrictMode(boolean)
*/
boolean isStrictMode();
@@ -164,6 +170,10 @@
* Note that header-name matching is case insensitive.
* @param headerName the header's name
* @param headerValue the header's value
+ *
+ * @see #setRequestHeader(Header)
+ * @see #getRequestHeader(String)
+ * @see #removeRequestHeader(String)
*/
void setRequestHeader(String headerName, String headerValue);
@@ -171,29 +181,45 @@
* Sets the specified request header, overwriting any
* previous value.
* Note that header-name matching is case insensitive.
- * @param header the header
+ * @param header the header to be set
+ *
+ * @see #setRequestHeader(String,String)
+ * @see #getRequestHeader(String)
+ * @see #removeRequestHeader(String)
*/
void setRequestHeader(Header header);
/**
- * Adds the specified request header, NOT overwriting any
- * previous value.
+ * Adds the specified request header, <em>not</em> overwriting any previous value.
+ * If the same header is added multiple times, perhaps with different values,
+ * multiple instances of that header will be sent in the HTTP request.
* Note that header-name matching is case insensitive.
* @param headerName the header's name
* @param headerValue the header's value
+ *
+ * @see #addRequestHeader(Header)
+ * @see #getRequestHeader(String)
+ * @see #removeRequestHeader(String)
*/
void addRequestHeader(String headerName, String headerValue);
/**
- * Adds the specified request header, NOT overwriting any
- * previous value.
+ * Adds the specified request header, <em>not</em> overwriting any previous value.
+ * If the same header is added multiple times, perhaps with different values,
+ * multiple instances of that header will be sent in the HTTP request.
* Note that header-name matching is case insensitive.
* @param header the header
+ *
+ * @see #addRequestHeader(String,String)
+ * @see #getRequestHeader(String)
+ * @see #removeRequestHeader(String)
*/
void addRequestHeader(Header header);
/**
- * Gets the request header associated with the given name.
+ * Gets the request header with the given name.
+ * If there are multiple headers with the same name,
+ * there values will be combined with the ',' separator as specified by RFC2616.
* Note that header-name matching is case insensitive.
* @param headerName the header name
* @return the header
@@ -201,18 +227,18 @@
Header getRequestHeader(String headerName);
/**
- * Removes all request headers associated with the given name.
+ * Removes all request headers with the given name.
* Note that header-name matching is case insensitive.
* @param headerName the header name
*/
void removeRequestHeader(String headerName);
/**
- * Returns <tt>true</tt>if the HTTP method should automatically follow HTTP redirects
- * (status code 302, etc.), <tt>false</ff> otherwise.
+ * 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.
+ * <tt>false</tt> otherwise
*/
boolean getFollowRedirects();
@@ -221,36 +247,57 @@
* (status code 302, etc.)
*
* @param followRedirects <tt>true</tt> if the method will automatically follow redirects,
- * <tt>false</ff> otherwise.
+ * <tt>false</tt> otherwise.
*/
void setFollowRedirects(boolean followRedirects);
/**
* Sets the query string of the HTTP method.
+ * It is responsibility of the caller to ensure that the path is
+ * properly encoded (URL safe). The string must not include an initial '?' character.
+ *
+ * @param queryString the query to be used in the request, with no leading '?' character
*
- * @param queryString the query string
+ * @see #getQueryString()
+ * @see #setQueryString(NameValuePair[])
*/
void setQueryString(String queryString);
/**
- * Sets the query string of the method.
- *
- * @param params an array of {@link NameValuePair}s
- * to add as query string parameters
+ * 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 <code>NameValuePair</code>s to use as the query string.
+ * The name/value pairs will be automatically URL encoded and should not
+ * have been encoded previously.
+ *
+ * @see #getQueryString()
+ * @see #setQueryString(String)
+ * @see org.apache.commons.httpclient.util.EncodingUtil#formUrlEncode(NameValuePair[], String)
*/
void setQueryString(NameValuePair[] params);
/**
- * Returns the query string of the HTTP method.
+ * Returns the query string of this HTTP method.
+ *
+ * @return the query string in URL encoded form, without a leading '?'.
*
- * @return the query string
+ * @see #setQueryString(NameValuePair[])
+ * @see #setQueryString(String)
*/
String getQueryString();
/**
- * Returns an array of request headers that the HTTP method currently has.
+ * Returns the current request headers for this HTTP method. The returned headers
+ * will be in the same order that they were added with <code>addRequestHeader</code>.
+ * If there are multiple request headers with the same name (e.g. <code>Cookie</code>),
+ * they will be returned as multiple entries in the array.
*
- * @return an array of request headers.
+ * @return an array containing all of the request headers
+ *
+ * @see #addRequestHeader(Header)
+ * @see #addRequestHeader(String,String)
*/
Header[] getRequestHeaders();
@@ -265,16 +312,17 @@
// ---------------------------------------------------------------- Queries
/**
- * Returns <tt>true</tt> the method is ready to execute, <tt>false</ff> otherwise.
+ * Returns <tt>true</tt> the method is ready to execute, <tt>false</tt> otherwise.
*
- * @return <tt>true</tt> if the method is ready to execute, <tt>false</ff> otherwise.
+ * @return <tt>true</tt> if the method is ready to execute, <tt>false</tt> otherwise.
*/
boolean validate();
/**
* Returns the status code associated with the latest response.
*
- * @return the status code.
+ * @return The status code from the most recent execution of this method.
+ * If the method has not yet been executed, the result is undefined.
*/
int getStatusCode();
@@ -282,14 +330,16 @@
* Returns the status text (or "reason phrase") associated with the latest
* response.
*
- * @return The status text.
+ * @return The status text from the most recent execution of this method.
+ * If the method has not yet been executed, the result is undefined.
*/
String getStatusText();
/**
- * Returns an array of the response headers that the HTTP method currently has.
+ * Returns the response headers from the most recent execution of this request.
*
- * @return An array of all the response headers.
+ * @return A newly-created array containing all of the response headers,
+ * in the order in which they appeared in the response.
*/
Header[] getResponseHeaders();
@@ -298,7 +348,10 @@
* case insensitive.
*
* @param headerName The name of the header to be returned.
- * @return The specified response header.
+ *
+ * @return The specified response header. If the repsonse contained multiple
+ * instances of the header, its values will be combined using the ','
+ * separator as specified by RFC2616.
*/
Header getResponseHeader(String headerName);
@@ -311,9 +364,11 @@
Header[] getResponseHeaders(String headerName);
/**
- * Returns an array of the response footers that the HTTP method currently has
+ * Returns the response footers from the most recent execution of this request.
*
- * @return an array of the response footers
+ * @return an array containing the response footers in the order that they
+ * appeared in the response. If the response had no footers,
+ * an empty array will be returned.
*/
Header[] getResponseFooters();
@@ -328,24 +383,40 @@
/**
* Returns the response body of the HTTP method, if any, as an array of bytes.
+ * If the method has not yet been executed or the response has no body, <code>null</code>
+ * is returned. Note that this method does not propagate I/O exceptions.
+ * If an error occurs while reading the body, <code>null</code> will be returned.
*
- * @return The response body.
+ * @return The response body, or <code>null</code> if the
+ * body is not available.
*/
byte[] getResponseBody();
/**
* Returns the response body of the HTTP method, if any, as a {@link String}.
- *
- * @return THe response body.
+ * If response body is not available or cannot be read, <tt>null</tt> is returned.
+ * The raw bytes in the body are converted to a <code>String</code> using the
+ * character encoding specified in the response's <tt>Content-Type</tt> header, or
+ * ISO-8859-1 if the response did not specify a character set.
+ * <p>
+ * Note that this method does not propagate I/O exceptions.
+ * If an error occurs while reading the body, <code>null</code> will be returned.
+ *
+ * @return The response body converted to a <code>String</code>, or <code>null</code>
+ * if the body is not available.
*/
String getResponseBodyAsString();
/**
- * Returns the response body of the HTTP method, if any, as an {@link InputStream}.
+ * Returns the response body of the HTTP method, if any, as an InputStream.
+ * If the response had no body or the method has not yet been executed,
+ * <code>null</code> is returned. Additionally, <code>null</code> may be returned
+ * if {@link #releaseConnection} has been called or
+ * if this method was called previously and the resulting stream was closed.
*
- * @return The response body
+ * @return The response body, or <code>null</code> if it is not available
*
- * @throws IOException If an I/O (transport) problem occurs.
+ * @throws IOException if an I/O (transport) problem occurs
*/
InputStream getResponseBodyAsStream() throws IOException;
@@ -360,15 +431,16 @@
// --------------------------------------------------------- Action Methods
/**
- * Execute the HTTP method.
+ * Executes this method using the specified <code>HttpConnection</code> and
+ * <code>HttpState</code>.
*
* @param state the {@link HttpState state} information to associate with this method
* @param connection the {@link HttpConnection connection} used to execute
* this HTTP method
*
- * @throws IOException if an I/O (transport) error occurs. Some transport exceptions
+ * @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
+ * @throws HttpException If a protocol exception occurs. Usually protocol exceptions
* cannot be recovered from.
*
* @return the integer status code if one was obtained, or <tt>-1</tt>
@@ -388,25 +460,33 @@
/**
* 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
+ * 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.
+ * <p>
+ * After this method is called, {@link #getResponseBodyAsStream} will return
+ * <code>null</code>, and {@link #getResponseBody} and {@link #getResponseBodyAsString}
+ * <em>may</em> return <code>null</code>.
*/
void releaseConnection();
/**
- * Use this method internally to add footers.
+ * Add a footer to this method's response.
+ * <p>
+ * <b>Note:</b> This method is for
+ * internal use only and should not be called by external clients.
*
- * @param footer The footer to add.
+ * @param footer the footer to add
*
* @since 2.0
*/
void addResponseFooter(Header footer);
/**
- * Returns the Status-Line from the response.
+ * Returns the Status-Line from the most recent response for this method,
+ * or <code>null</code> if the method has not been executed.
*
- * @return The status line
+ * @return the status line, or <code>null</code> if the method has not been executed
*
* @since 2.0
*/
@@ -420,6 +500,8 @@
* automatically, <tt>false</tt> otherwise.
*
* @since 2.0
+ *
+ * @see #setDoAuthentication(boolean)
*/
boolean getDoAuthentication();
@@ -428,9 +510,11 @@
* authentication challenges (status code 401, etc.)
*
* @param doAuthentication <tt>true</tt> to process authentication challenges
- * authomatically, <tt>false</tt> otherwise.
+ * automatically, <tt>false</tt> otherwise.
*
* @since 2.0
+ *
+ * @see #getDoAuthentication()
*/
void setDoAuthentication(boolean doAuthentication);
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org