From olegk@apache.org Sat Aug 2 22:26:42 2003 Return-Path: Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 61635 invoked by uid 500); 2 Aug 2003 22:26:42 -0000 Received: (qmail 61632 invoked from network); 2 Aug 2003 22:26:42 -0000 Received: from unknown (HELO minotaur.apache.org) (209.237.227.194) by daedalus.apache.org with SMTP; 2 Aug 2003 22:26:42 -0000 Received: (qmail 21804 invoked by uid 1624); 2 Aug 2003 22:26:55 -0000 Date: 2 Aug 2003 22:26:55 -0000 Message-ID: <20030802222655.21803.qmail@minotaur.apache.org> From: olegk@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethod.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N olegk 2003/08/02 15:26:55 Modified: httpclient/src/java/org/apache/commons/httpclient HttpMethod.java Log: Javadoc clean-ups in HttpMethod Contributed by Oleg Kalnichevski Revision Changes Path 1.25 +111 -82 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.24 retrieving revision 1.25 diff -u -r1.24 -r1.25 --- HttpMethod.java 22 Jul 2003 18:17:48 -0000 1.24 +++ HttpMethod.java 2 Aug 2003 22:26:55 -0000 1.25 @@ -68,15 +68,17 @@ /** *

- * A request to be applied to an {@link HttpConnection}, and a container for the - * associated response. + * HttpMethod interface represents a request to be sent via a + * {@link HttpConnection HTTP connection} and a corresponding response. *

* @author Remy Maucherat * @author Rod Waldhoff * @author Jeff Dever * @author Mike Bowler + * @author Oleg Kalnichevski * * @version $Revision$ $Date$ + * * @since 1.0 */ public interface HttpMethod { @@ -84,8 +86,9 @@ // ------------------------------------------- Property Setters and Getters /** - * Obtain the name of this method, suitable for use in the "request line", + * Obtain the name of the HTTP method as used in the HTTP request line, * for example "GET" or "POST". + * * @return the name of this method */ String getName(); @@ -98,25 +101,25 @@ HostConfiguration getHostConfiguration(); /** - * Set the path part of my request. - * @param path the path to request + * Sets the path of the HTTP method. + * + * @param path the path of the HTTP method */ void setPath(String path); /** - * Get the path part of my request. + * Returns the path of the HTTP method. * - * Calling this method AFTER the request - * has been executed will return the ACTUAL path, following any 301 or 302 - * redirects (except for redirects off the initial server, which are not - * supported, or when HttpClient is set to not follow redirects; in either - * case, HttpClient returns the 301 or 302 status code). + * Calling this method after the request has been executed will + * return the actual path, following any redirects automatically + * handled by this HTTP method. + * * @return the path to request */ String getPath(); /** - * Gets the URI for this method. The URI will be absolute if the host + * Gets the URI for this method. The URI will be absolute if the host * configuration has been set or relative otherwise. * * @return URI @@ -135,29 +138,24 @@ void setURI(URI uri) throws URIException; /** - *

Turns strict mode on or off. In strict mode (the default) we - * following the letter of RFC 2616, the Http 1.1 specification. If strict - * mode is turned off we attempt to violate the specification in the same - * way that most Http user agent's do (and many HTTP servers expect.

+ *

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).

* - *

NOTE: StrictMode is currently experimental and its functionaity may - * change in the future.

- * - * @param strictMode True to enable strict mode. + * @param strictMode true to enable the strict mode. */ void setStrictMode(boolean strictMode); /** - * Returns the value of strictMode. + * Returns the value of the strict mode flag. * - * NOTE: StrictMode is currently experimental and its functionlaity may change in the future. - * - * @return true if strict mode is enabled. + * @return true if strict mode is enabled, false otherwise */ boolean isStrictMode(); /** - * Set the specified request header, overwriting any + * Sets the specified request header, overwriting any * previous value. * Note that header-name matching is case insensitive. * @param headerName the header's name @@ -166,7 +164,7 @@ void setRequestHeader(String headerName, String headerValue); /** - * Set the specified request header, overwriting any + * Sets the specified request header, overwriting any * previous value. * Note that header-name matching is case insensitive. * @param header the header @@ -191,7 +189,7 @@ void addRequestHeader(Header header); /** - * Get the request header associated with the given name. + * Gets the request header associated with the given name. * Note that header-name matching is case insensitive. * @param headerName the header name * @return the header @@ -199,47 +197,55 @@ Header getRequestHeader(String headerName); /** - * Remove all request headers associated with the given name. + * Removes all request headers associated with the given name. * Note that header-name matching is case insensitive. * @param headerName the header name */ void removeRequestHeader(String headerName); /** - * Whether or not I should automatically follow - * HTTP redirects (status code 302, etc.) - * @return true if I will automatically follow HTTP redirects + * Returns trueif the HTTP method should automatically follow HTTP redirects + * (status code 302, etc.), false otherwise. + * + * @return true if the method will automatically follow HTTP redirects, + * false otherwise. */ boolean getFollowRedirects(); /** - * Set whether or not I should automatically follow HTTP redirects (status - * code 302, etc.) - * @param followRedirects True if I should automatically follow redirects. + * Sets whether or not the HTTP method should automatically follow HTTP redirects + * (status code 302, etc.) + * + * @param followRedirects true if the method will automatically follow redirects, + * false otherwise. */ void setFollowRedirects(boolean followRedirects); /** - * Set my query string. + * Sets the query string of the HTTP method. + * * @param queryString the query string */ void setQueryString(String queryString); /** - * Set my query string. + * Sets the query string of the method. + * * @param params an array of {@link NameValuePair}s - * to add as query string parameterss + * to add as query string parameters */ void setQueryString(NameValuePair[] params); /** - * Get my query string. - * @return my query string + * Returns the query string of the HTTP method. + * + * @return the query string */ String getQueryString(); /** - * Return an array of my request headers. + * Returns an array of request headers that the HTTP method currently has. + * * @return an array of request headers. */ Header[] getRequestHeaders(); @@ -247,91 +253,102 @@ // ---------------------------------------------------------------- Queries /** - * Confirm that I am ready to execute. - * @return True if I am ready to execute. + * Returns true the method is ready to execute, false otherwise. + * + * @return true if the method is ready to execute, false otherwise. */ boolean validate(); /** - * Return the status code associated with the latest response. + * Returns the status code associated with the latest response. + * * @return the status code. */ int getStatusCode(); /** - * Return the status text (or "reason phrase") associated with the latest + * Returns the status text (or "reason phrase") associated with the latest * response. + * * @return The status text. */ String getStatusText(); /** - * Return an array of my response headers. + * Returns an array of the response headers that the HTTP method currently has. + * * @return An array of all the response headers. */ Header[] getResponseHeaders(); /** - * Return the specified response header. Note that header-name matching is + * Returns the specified response header. Note that header-name matching is * case insensitive. + * * @param headerName The name of the header to be returned. * @return The specified response header. */ Header getResponseHeader(String headerName); /** - * Return an array of my response footers - * @return null if no footers are available + * Returns an array of the response footers that the HTTP method currently has + * + * @return an array of the response footers */ Header[] getResponseFooters(); /** * Return the specified response footer. Note that footer-name matching is * case insensitive. + * * @param footerName The name of the footer. * @return The response footer. */ Header getResponseFooter(String footerName); /** - * Return my response body, if any, as a byte array. Otherwise return - * null. + * Returns the response body of the HTTP method, if any, as an array of bytes. + * * @return The response body. */ byte[] getResponseBody(); /** - * Return my response body, if any, as a {@link String}. Otherwise return - * null. - * @return response body. + * Returns the response body of the HTTP method, if any, as a {@link String}. + * + * @return THe response body. */ String getResponseBodyAsString(); /** - * Return my response body, if any, as an {@link InputStream}. Otherwise - * return null. - * @return As above. - * @throws IOException If an IO problem occurs. + * Returns the response body of the HTTP method, if any, as an {@link InputStream}. + * + * @return The response body + * + * @throws IOException If an I/O (transport) problem occurs. */ InputStream getResponseBodyAsStream() throws IOException; /** - * Return true if I have been {@link #execute executed} - * but not recycled. - * @return true if this has been used. + * Returns true if the HTTP method has been already {@link #execute executed}, + * but not {@link #recycle recycled}. + * + * @return true if the method has been executed, false otherwise */ boolean hasBeenUsed(); // --------------------------------------------------------- Action Methods /** - * Execute this method. + * Execute the HTTP method. * - * @param state state information to associate with this request - * @param connection the {@link HttpConnection} to write to/read from + * @param state the {@link HttpState state} information to associate with this method + * @param connection the {@link HttpConnection connection} to be used * - * @throws IOException if an I/O error occurs - * @throws HttpException if an protocol exception occurs + * @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. * * @return the integer status code if one was obtained, or -1 */ @@ -339,49 +356,61 @@ throws HttpException, IOException; /** - * Recycle this method so that it can be used again. - * Note that all of my instance 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() */ void recycle(); /** - * Releases the connection being used by this method. In particular the + * 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. + * until the response has been read. If the connection can be reused by other + * HTTP methods it is NOT closed at this point. */ void releaseConnection(); /** * Use this method internally to add footers. + * * @param footer The footer to add. + * * @since 2.0 */ void addResponseFooter(Header footer); /** - * Return the Status-Line from the response. + * Returns the Status-Line from the response. + * * @return The status line + * * @since 2.0 */ StatusLine getStatusLine(); /** - * Whether or not I should automatically process responses where - * authentication is required (status code 401, etc.) + * Returns true if the HTTP method should automatically handle HTTP + * authentication challenges (status code 401, etc.), false otherwise * - * @return true if authentications will be processed automatically + * @return true if authentication challenges will be processed + * automatically, false otherwise. + * * @since 2.0 */ boolean getDoAuthentication(); /** - * 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 true to process authentications + * @param doAuthentication true to process authentication challenges + * authomatically, false otherwise. + * * @since 2.0 */ void setDoAuthentication(boolean doAuthentication); - + }