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/09/16 23:29:45 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient HttpClient.java HttpState.java
olegk 2003/09/16 14:29:45
Modified: httpclient/src/java/org/apache/commons/httpclient
HttpClient.java HttpState.java
Log:
HttpState & HttpClient javadocs cleanup
Contributed by Oleg Kalnichevski
Revision Changes Path
1.82 +91 -54 jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpClient.java
Index: HttpClient.java
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpClient.java,v
retrieving revision 1.81
retrieving revision 1.82
diff -u -r1.81 -r1.82
--- HttpClient.java 11 Sep 2003 20:08:32 -0000 1.81
+++ HttpClient.java 16 Sep 2003 21:29:45 -0000 1.82
@@ -74,9 +74,9 @@
/**
* <p>
- * An HTTP "user-agent", containing an {@link HttpState} and
- * one or more {@link HttpConnection}s, to which
- * {@link HttpMethod}s can be applied.
+ * An HTTP "user-agent", containing an {@link HttpState HTTP state} and
+ * one or more {@link HttpConnection HTTP connections}, to which
+ * {@link HttpMethod HTTP methods} can be applied.
* </p>
* @author <a href="mailto:remm@apache.org">Remy Maucherat</a>
* @author <a href="mailto:rwaldhoff@apache.org">Rodney Waldhoff</a>
@@ -87,6 +87,7 @@
* @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
* @author Sam Maloney
* @author Laura Werner
+ * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
*
* @version $Revision$ $Date$
*/
@@ -120,7 +121,8 @@
// ----------------------------------------------------------- Constructors
/**
- * Creates an HttpClient using <code>SimpleHttpConnectionManager</code>.
+ * Creates an instance of HttpClient using a
+ * {@link SimpleHttpConnectionManager simple HTTP connection manager}.
*
* @see SimpleHttpConnectionManager
*/
@@ -129,8 +131,9 @@
}
/**
- * Creates an HttpClient with a user specified connection manager.
- * @param httpConnectionManager The connection manager to use.
+ * Creates an instance of HttpClient with a user specified connection manager.
+ * @param httpConnectionManager The {@link HttpConnectionManager connection manager}
+ * to use.
*
* @since 2.0
*/
@@ -150,23 +153,29 @@
// ----------------------------------------------------- Instance Variables
- /** The current connection manager */
+ /**
+ * The {@link HttpConnectionManager connection manager} being used to manage
+ * connections for this HttpClient
+ */
private HttpConnectionManager httpConnectionManager;
/**
- * My {@link HttpState state}.
+ * The {@link HttpState HTTP state} associated with this HttpClient.
*/
private HttpState state;
private HttpClientParams params;
- /** The host configuration to use */
+ /**
+ * The {@link HostConfiguration host configuration} associated with
+ * the HttpClient
+ */
private HostConfiguration hostConfiguration;
// ------------------------------------------------------------- Properties
/**
- * Get my {@link HttpState state}.
+ * Returns {@link HttpState HTTP state} associated with the HttpClient.
*
* @see #setState(HttpState)
* @return the shared client state
@@ -176,18 +185,25 @@
}
/**
- * Set my {@link HttpState state}.
+ * Assigns {@link HttpState HTTP state} for the HttpClient.
*
* @see #getState()
- * @param state the new state for the client
+ * @param state the new {@link HttpState HTTP state} for the client
*/
public synchronized void setState(HttpState state) {
this.state = state;
}
/**
- *
- * @param strictMode <code>true</code> if strict mode should be used
+ * 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()
*
@@ -203,8 +219,9 @@
}
/**
- *
- * @return <code>false</code>
+ * Returns the value of the strict mode flag.
+ *
+ * @return <tt>true</tt> if strict mode is enabled, <tt>false</tt> otherwise
*
* @see #setStrictMode(boolean)
*
@@ -216,9 +233,9 @@
}
/**
- * Sets the SO_TIMEOUT which is the timeout for waiting for data.
- *
- * A timeout value of zero is interpreted as an infinite timeout.
+ * Sets the socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
+ * timeout for waiting for data. A timeout value of zero is interpreted as an
+ * infinite timeout.
*
* @param newTimeoutInMilliseconds Timeout in milliseconds
*
@@ -231,8 +248,9 @@
}
/**
- * Sets the timeout used when retrieving an HttpConnection from the
- * HttpConnectionManager.
+ * Sets the timeout in milliseconds used when retrieving an
+ * {@link HttpConnection HTTP connection} from the
+ * {@link HttpConnectionManager HTTP connection manager}.
*
* @param timeout the timeout in milliseconds
*
@@ -246,8 +264,9 @@
}
/**
- * Sets the timeout until a connection is etablished. A value of 0 means
- * the timeout is not used. The default value is 0.
+ * Sets the timeout until a connection is etablished. A value of zero
+ * means the timeout is not used. The default value is zero.
+ *
* @see HttpConnection#setConnectionTimeout(int)
* @param newTimeoutInMilliseconds Timeout in milliseconds.
*
@@ -260,14 +279,16 @@
// --------------------------------------------------------- Public Methods
- /**
- * Executes the given method.
+ /**
+ * Executes the given {@link HttpMethod HTTP method}.
*
- * @param method the {@link HttpMethod} to execute.
+ * @param method the {@link HttpMethod HTTP method} to execute.
* @return the method's response code
*
- * @throws IOException if an I/O error occurs
- * @throws HttpException if a 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.
*/
public int executeMethod(HttpMethod method)
throws IOException, HttpException {
@@ -285,14 +306,17 @@
}
/**
- * Executes the given method.
+ * Executes the given {@link HttpMethod HTTP method} using custom
+ * {@link HostConfiguration host configuration}.
*
- * @param hostConfiguration The configuration to use.
- * @param method the {@link HttpMethod} to execute.
+ * @param hostConfiguration The {@link HostConfiguration host configuration} to use.
+ * @param method the {@link HttpMethod HTTP method} to execute.
* @return the method's response code
*
- * @throws IOException if an I/O error occurs
- * @throws HttpException if a 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.
* @since 2.0
*/
public int executeMethod(HostConfiguration hostConfiguration, HttpMethod method)
@@ -306,17 +330,21 @@
/**
- * Executes the given method.
- *
- * @param hostConfiguration The configuration to use.
- * @param method the {@link HttpMethod} to execute.
- * @param state the {@link HttpState} to use when executing the method.
+ * Executes the given {@link HttpMethod HTTP method} using the given custom
+ * {@link HostConfiguration host configuration} with the given custom
+ * {@link HttpState HTTP state}.
+ *
+ * @param hostConfiguration The {@link HostConfiguration host configuration} to use.
+ * @param method the {@link HttpMethod HTTP method} to execute.
+ * @param state the {@link HttpState HTTP state} to use when executing the method.
* If <code>null</code>, the state returned by {@link #getState} will be used instead.
*
* @return the method's response code
*
- * @throws IOException if an I/O error occurs
- * @throws HttpException if a 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.
* @since 2.0
*/
public int executeMethod(HostConfiguration hostConfiguration,
@@ -387,7 +415,7 @@
}
/**
- * Return the host that the client is accessing.
+ * Returns the host that the client is accessing.
*
* @return The host that the client is accessing, or <code>null</code> if
* the session has not been started via startSession.
@@ -397,7 +425,7 @@
}
/**
- * Return the port that the client is accessing.
+ * Returns the port that the client is accessing.
*
* @return The port that the client is accessing, or -1 if the session
* has not been started via startSession().
@@ -407,8 +435,10 @@
}
/**
- * Returns the hostConfiguration.
- * @return HostConfiguration
+ * Returns the {@link HostConfiguration host configuration} associated with the
+ * HttpClient.
+ *
+ * @return {@link HostConfiguration host configuration}
*
* @since 2.0
*/
@@ -417,8 +447,10 @@
}
/**
- * Sets the hostConfiguration.
- * @param hostConfiguration The hostConfiguration to set
+ * Assigns the {@link HostConfiguration host configuration} to use with the
+ * HttpClient.
+ *
+ * @param hostConfiguration The {@link HostConfiguration host configuration} to set
*
* @since 2.0
*/
@@ -427,8 +459,10 @@
}
/**
- * Returns the httpConnectionManager.
- * @return HttpConnectionManager
+ * Returns the {@link HttpConnectionManager HTTP connection manager} associated
+ * with the HttpClient.
+ *
+ * @return {@link HttpConnectionManager HTTP connection manager}
*
* @since 2.0
*/
@@ -437,8 +471,11 @@
}
/**
- * Sets the httpConnectionManager.
- * @param httpConnectionManager The httpConnectionManager to set
+ * Assigns the {@link HttpConnectionManager HTTP connection manager} to use with
+ * the HttpClient.
+ *
+ * @param httpConnectionManager The {@link HttpConnectionManager HTTP connection manager}
+ * to set
*
* @since 2.0
*/
1.27 +96 -81 jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpState.java
Index: HttpState.java
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpState.java,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- HttpState.java 11 Sep 2003 20:08:33 -0000 1.26
+++ HttpState.java 16 Sep 2003 21:29:45 -0000 1.27
@@ -78,8 +78,8 @@
/**
* <p>
* A container for HTTP attributes that may persist from request
- * to request, such as {@link Cookie}s and authentication
- * {@link Credentials}.
+ * to request, such as {@link Cookie cookies} and authentication
+ * {@link Credentials credentials}.
* </p>
* <p>
* Preemptive authentication can be turned on by using the property value of
@@ -104,12 +104,14 @@
// ----------------------------------------------------- Instance Variables
/**
- * My {@link Credentials Credentials}s, by realm.
+ * Map of {@link Credentials credentials} by realm that this
+ * HTTP state contains.
*/
private HashMap credMap = new HashMap();
/**
- * My proxy {@link Credentials Credentials}, by realm.
+ * Map of {@link Credentials proxy credentials} by realm that this
+ * HTTP state contains
*/
private HashMap proxyCred = new HashMap();
@@ -119,11 +121,12 @@
public static final HttpAuthRealm DEFAULT_AUTH_REALM = new HttpAuthRealm(null, null);
/**
- * My {@link Cookie Cookie}s.
+ * Array of {@link Cookie cookies} that this HTTP state contains.
*/
private ArrayList cookies = new ArrayList();
/**
- * My cookie policy. Default is {@link CookiePolicy.RFC2109}
+ * Cookie policy that applies to this HTTP state. Default is
+ * {@link CookiePolicy#RFC2109}
*/
private int cookiePolicy = CookiePolicy.RFC2109;
@@ -135,7 +138,7 @@
private static final Log LOG = LogFactory.getLog(HttpState.class);
/**
- * Constructor for HttpState.
+ * Default constructor.
*/
public HttpState() {
@@ -148,11 +151,11 @@
// ------------------------------------------------------------- Properties
/**
- * Add a cookie.
- * If the given <i>cookie</i> has already expired,
- * deletes the corresponding existing cookie (if any).
+ * Adds an {@link Cookie HTTP cookie}, replacing any existing equivalent cookies.
+ * If the given cookie has already expired it will not be added, but existing
+ * values will still be removed.
*
- * @param cookie the {@link Cookie} to add
+ * @param cookie the {@link Cookie cookie} to be added
*
* @see #addCookies(Cookie[])
*
@@ -176,30 +179,31 @@
}
/**
- * Add zero or more cookies
- * If any given <i>cookie</i> has already expired,
- * deletes the corresponding existing cookie (if any).
+ * Adds an array of {@link Cookie HTTP cookies}. Cookies are added individually and
+ * in the given array order. If any of the given cookies has already expired it will
+ * not be added, but existing values will still be removed.
*
- * @param newcookies the {@link Cookie}s to add
+ * @param cookies the {@link Cookie cookies} to be added
*
* @see #addCookie(Cookie)
*
*
*/
- public synchronized void addCookies(Cookie[] newcookies) {
+ public synchronized void addCookies(Cookie[] cookies) {
LOG.trace("enter HttpState.addCookies(Cookie[])");
- if (newcookies != null) {
- for (int i = 0; i < newcookies.length; i++) {
- this.addCookie(newcookies[i]);
+ if (cookies != null) {
+ for (int i = 0; i < cookies.length; i++) {
+ this.addCookie(cookies[i]);
}
}
}
/**
- * Obtain an array of my {@link Cookie}s.
+ * Returns an array of {@link Cookie cookies} that this HTTP
+ * state currently contains.
*
- * @return an array of my {@link Cookie}s.
+ * @return an array of {@link Cookie cookies}.
*
* @see #getCookies(String, int, String, boolean)
*
@@ -210,19 +214,19 @@
}
/**
- * Obtain an array of my {@link Cookie}s that
- * match the given request parameters.
+ * Returns an array of {@link Cookie cookies} in this HTTP
+ * state that match the given request parameters.
*
* @param domain the request domain
* @param port the request port
* @param path the request path
* @param secure <code>true</code> when using HTTPS
- * @return an array of my {@link Cookie}s.
*
- * @see #getCookies()
+ * @return an array of {@link Cookie cookies}.
*
- * @deprecated Use {@link CookieSpec#match(String,int,String,boolean,Cookie)}
+ * @see #getCookies()
*
+ * @deprecated use CookieSpec#match(String, int, String, boolean, Cookie)
*/
public synchronized Cookie[] getCookies(
String domain,
@@ -244,9 +248,8 @@
}
/**
- * Remove all of my {@link Cookie}s that
- * have expired according to the current
- * system time.
+ * Removes all of {@link Cookie cookies} in this HTTP state
+ * that have expired according to the current system time.
*
* @see #purgeExpiredCookies(java.util.Date)
*
@@ -257,12 +260,15 @@
}
/**
- * Remove all of my {@link Cookie}s that have expired by the specified
- * <i>date</i>.
+ * Removes all of {@link Cookie cookies} in this HTTP state
+ * that have expired by the specified {@link java.util.Date date}.
+ *
+ * @param date The {@link java.util.Date date} to compare against.
*
- * @param date The date to compare against.
* @return true if any cookies were purged.
+ *
* @see Cookie#isExpired(java.util.Date)
+ *
* @see #purgeExpiredCookies()
*/
public synchronized boolean purgeExpiredCookies(Date date) {
@@ -280,8 +286,10 @@
/**
- * Return the current {@link CookiePolicy}
- * @return The cookie policy.
+ * Returns the current {@link CookiePolicy cookie policy} for this
+ * HTTP state.
+ *
+ * @return The {@link CookiePolicy cookie policy}.
*/
public int getCookiePolicy() {
@@ -291,12 +299,14 @@
/**
* Defines whether preemptive authentication should be
- * attempted or not.
+ * attempted.
*
- * @param value boolean flag
+ * @param value <tt>true</tt> if preemptive authentication should be
+ * attempted, <tt>false</tt> otherwise.
*
- * @deprecated Use {@link HttpClientParams#setAuthenticationPreemptive(boolean)},
- * {@link HttpClient#getParams()}.
+ * @deprecated Use
+ * {@link org.apache.commons.httpclient.params.HttpClientParams#setAuthenticationPreemptive(boolean)},
+ * {@link HttpClient#getParams()}.
*/
public void setAuthenticationPreemptive(boolean value) {
@@ -305,13 +315,14 @@
/**
- * Return <tt>true</tt> if preemptive authentication should be
- * attempted, otherwise return <tt>false</tt>
+ * Returns <tt>true</tt> if preemptive authentication should be
+ * attempted, <tt>false</tt> otherwise.
*
* @return boolean flag.
*
- * @deprecated Use {@link HttpClientParams#isAuthenticationPreemptive()},
- * {@link HttpClient#getParams()}.
+ * @deprecated Use
+ * {@link org.apache.commons.httpclient.params.HttpClientParams#isAuthenticationPreemptive()},
+ * {@link HttpClient#getParams()}.
*/
public boolean isAuthenticationPreemptive() {
@@ -320,30 +331,33 @@
/**
- * Set the {@link CookiePolicy} to one of {@link
- * CookiePolicy#COMPATIBILITY}, {@link CookiePolicy#NETSCAPE_DRAFT} or
- * {@link CookiePolicy#RFC2109}
- * @param policy new cookie policy
+ * Sets the current {@link CookiePolicy cookie policy} for this HTTP
+ * state to one of the following supported policies:
+ * {@link CookiePolicy#COMPATIBILITY},
+ * {@link CookiePolicy#NETSCAPE_DRAFT} or
+ * {@link CookiePolicy#RFC2109}.
+ *
+ * @param policy new {@link CookiePolicy cookie policy}
*/
public void setCookiePolicy(int policy) {
this.cookiePolicy = policy;
}
- /** Sets the credentials for <tt>realm</tt> on <tt>host</tt>.
- * with no host.
- *
- * When <i>realm</i> is <code>null</code>, I'll use the given
- * <i>credentials</i> when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a <code>null</code> realm to set the "default"
- * credentials.)
- * <p>
- * Any previous credentials for this realm will be overwritten.
+ /**
+ * Sets the {@link Credentials credentials} for the given authentication
+ * realm on the given host. The <code>null</code> realm signifies default
+ * credentials for the given host, which should be used when no
+ * {@link Credentials credentials} have been explictly supplied for the
+ * challenging realm. The <code>null</code> host signifies default
+ * credentials, which should be used when no {@link Credentials credentials}
+ * have been explictly supplied for the challenging host. Any previous
+ * credentials for the given realm on the given host will be overwritten.
*
* @param realm the authentication realm
* @param host the host the realm belongs to
- * @param credentials the authentication credentials for the given realm.
+ * @param credentials the authentication {@link Credentials credentials}
+ * for the given realm.
*
* @see #getCredentials(String, String)
* @see #setProxyCredentials(String, String, Credentials)
@@ -357,7 +371,7 @@
/**
- * Find matching credentials for the given authentication realm and host.
+ * Find matching {@link Credentials credentials} for the given authentication realm and host.
*
* If the <i>realm</i> exists on <i>host</i>, return the coresponding credentials.
* If the <i>host</i> exists with a <tt>null</tt> <i>realm</i>, return the corresponding
@@ -391,7 +405,8 @@
}
/**
- * Get the Credentials for the given authentication realm.
+ * Get the {@link Credentials credentials} for the given authentication realm on the
+ * given host.
*
* If the <i>realm</i> exists on <i>host</i>, return the coresponding credentials.
* If the <i>host</i> exists with a <tt>null</tt> <i>realm</i>, return the corresponding
@@ -406,7 +421,6 @@
* @return the credentials
*
* @see #setCredentials(String, String, Credentials)
- *
*/
public synchronized Credentials getCredentials(String realm, String host) {
@@ -415,16 +429,15 @@
}
/**
- * Set the credentials for the proxy with the given authentication realm.
- *
- * When <i>realm</i> and <i>proxyHost</i> are <code>null</code>, I'll use the given
- * <i>credentials</i> when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a <code>null</code> realm to set the "default"
- * credentials.) Realms rarely make much sense with proxies, so
- * <code>null</code> is normally a good choice here.
- * <p>
- * Any previous credentials for this realm will be overwritten.
+ * Sets the {@link Credentials credentials} for the given proxy authentication
+ * realm on the given proxy host. The <code>null</code> proxy realm signifies
+ * default credentials for the given proxy host, which should be used when no
+ * {@link Credentials credentials} have been explictly supplied for the
+ * challenging proxy realm. The <code>null</code> proxy host signifies default
+ * credentials, which should be used when no {@link Credentials credentials}
+ * have been explictly supplied for the challenging proxy host. Any previous
+ * credentials for the given proxy realm on the given proxy host will be
+ * overwritten.
*
* @param realm the authentication realm
* @param proxyHost the proxy host
@@ -444,8 +457,8 @@
}
/**
- * Get the Credentials for the proxy with the given authentication realm on the given
- * <i>host</i>.
+ * Get the {@link Credentials credentials} for the proxy host with the given
+ * authentication realm.
*
* If the <i>realm</i> exists on <i>host</i>, return the coresponding credentials.
* If the <i>host</i> exists with a <tt>null</tt> <i>realm</i>, return the corresponding
@@ -466,8 +479,10 @@
}
/**
- * Return a string representation of this object.
- * @return The string representation.
+ * Returns a string representation of this HTTP state.
+ *
+ * @return The string representation of the HTTP state.
+ *
* @see java.lang.Object#toString()
*/
public synchronized String toString() {
@@ -487,7 +502,7 @@
}
/**
- * Return a string representation of the proxy credentials
+ * Returns a string representation of the proxy credentials
* @param proxyCredMap The proxy credentials
* @return StringBuffer The string representation.
*/
@@ -508,7 +523,7 @@
}
/**
- * Return a string representation of the credentials.
+ * Returns a string representation of the credentials.
* @param credMap The credentials.
* @return StringBuffer The string representation.
*/
@@ -529,7 +544,7 @@
}
/**
- * Return a string representation of the cookies.
+ * Returns a string representation of the cookies.
* @param cookies The cookies
* @return StringBuffer The string representation.
*/