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 00:26:55 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpMethod.java
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 @@
/**
* <p>
- * 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.
* </p>
* @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
* @author Rod Waldhoff
* @author <a href="jsdever@apache.org">Jeff Dever</a>
* @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
+ * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
*
* @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 <tt>"GET"</tt> or <tt>"POST"</tt>.
+ *
* @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 <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
*/
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;
/**
- * <p>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.</p>
+ * <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>
*
- * <p>NOTE: StrictMode is currently experimental and its functionaity may
- * change in the future.</p>
- *
- * @param strictMode True to enable strict mode.
+ * @param strictMode <tt>true</tt> 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 <tt>true</tt> if strict mode is enabled, <tt>false</tt> 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 <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</ff> otherwise.
+ *
+ * @return <tt>true</tt> if the method will automatically follow HTTP redirects,
+ * <tt>false</ff> 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 <tt>true</tt> if the method will automatically follow redirects,
+ * <tt>false</ff> 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 <tt>true</tt> the method is ready to execute, <tt>false</ff> otherwise.
+ *
+ * @return <tt>true</tt> if the method is ready to execute, <tt>false</ff> 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 <tt>null</tt> 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
- * <tt>null</tt>.
+ * 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
- * <tt>null</tt>.
- * @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 <tt>null</tt>.
- * @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 <tt>true</tt> if I have been {@link #execute executed}
- * but not recycled.
- * @return true if this has been used.
+ * 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
*/
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 <tt>-1</tt>
*/
@@ -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 <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
*/
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 <tt>true</tt> to process authentications
+ * @param doAuthentication <tt>true</tt> to process authentication challenges
+ * authomatically, <tt>false</tt> otherwise.
+ *
* @since 2.0
*/
void setDoAuthentication(boolean doAuthentication);
-
+
}