mbecke 2003/08/11 19:39:41 Modified: httpclient/src/java/org/apache/commons/httpclient Tag: HTTPCLIENT_2_0_BRANCH HttpMethod.java HeaderGroup.java HttpMethodBase.java Log: Javadoc enhancements. PR: 22073 Submitted by: Laura Werner Reviewed by: Michael Becke Revision Changes Path No revision No revision 1.23.2.3 +141 -55 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.2 retrieving revision 1.23.2.3 diff -u -r1.23.2.2 -r1.23.2.3 --- HttpMethod.java 3 Aug 2003 22:01:31 -0000 1.23.2.2 +++ HttpMethod.java 12 Aug 2003 02:39:41 -0000 1.23.2.3 @@ -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,28 +119,30 @@ * 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 */ URI getURI() 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); @@ -146,6 +150,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(); @@ -155,6 +161,10 @@ * * @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); @@ -162,29 +172,47 @@ * 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 @@ -193,7 +221,7 @@ 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 @@ -201,11 +229,11 @@ 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(); @@ -214,52 +242,74 @@ * (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 string + * @param queryString the query to be used in the request, with no leading '?' character + * + * @see #getQueryString() + * @see #setQueryString(NameValuePair[]) */ void setQueryString(String queryString); /** - * Sets the query string of the method. - * - * @param params an array of [EMAIL PROTECTED] 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 containing all of the request headers * - * @return an array of request headers. + * @see #addRequestHeader(Header) + * @see #addRequestHeader(String,String) */ Header[] getRequestHeaders(); // ---------------------------------------------------------------- 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(); @@ -267,14 +317,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(); @@ -283,14 +335,19 @@ * 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); /** - * 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(); @@ -305,24 +362,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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #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; @@ -337,15 +410,16 @@ // --------------------------------------------------------- Action Methods /** - * Execute the HTTP method. + * Executes this method using the specified <code>HttpConnection</code> and + * <code>HttpState</code>. * * @param state the [EMAIL PROTECTED] HttpState state} information to associate with this method * @param connection the [EMAIL PROTECTED] 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> @@ -365,25 +439,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, [EMAIL PROTECTED] #getResponseBodyAsStream} will return + * <code>null</code>, and [EMAIL PROTECTED] #getResponseBody} and [EMAIL PROTECTED] #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 */ @@ -397,6 +479,8 @@ * automatically, <tt>false</tt> otherwise. * * @since 2.0 + * + * @see #setDoAuthentication(boolean) */ boolean getDoAuthentication(); @@ -405,9 +489,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); 1.3.2.1 +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.3.2.1 diff -u -r1.3 -r1.3.2.1 --- HeaderGroup.java 6 Apr 2003 22:31:52 -0000 1.3 +++ HeaderGroup.java 12 Aug 2003 02:39:41 -0000 1.3.2.1 @@ -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.159.2.7 +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.159.2.6 retrieving revision 1.159.2.7 diff -u -r1.159.2.6 -r1.159.2.7 --- HttpMethodBase.java 3 Aug 2003 22:01:31 -0000 1.159.2.6 +++ HttpMethodBase.java 12 Aug 2003 02:39:41 -0000 1.159.2.7 @@ -772,8 +772,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 */ @@ -794,7 +797,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 */
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]