Index: HttpState.java =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpState.java,v retrieving revision 1.22 diff -u -r1.22 HttpState.java --- HttpState.java 8 May 2003 18:39:07 -0000 1.22 +++ HttpState.java 15 Sep 2003 13:39:19 -0000 @@ -78,8 +78,8 @@ /** *
* 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}. *
*
* Preemptive authentication can be turned on by using the property value of
@@ -104,7 +104,7 @@
// ----------------------------------------------------- Instance Variables
/**
- * Whether I should attempt to authenticate preemptively.
+ * Whether authentication should be attempted preemptively.
*/
private boolean preemptive;
@@ -120,12 +120,14 @@
public static final String PREEMPTIVE_DEFAULT = "false";
/**
- * 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();
@@ -135,11 +137,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;
@@ -152,7 +155,7 @@
private static final Log LOG = LogFactory.getLog(HttpState.class);
/**
- * Constructor for HttpState.
+ * Default constructor.
*/
public HttpState() {
@@ -180,11 +183,11 @@
// ------------------------------------------------------------- Properties
/**
- * Add a cookie.
- * If the given cookie 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[])
*
@@ -208,30 +211,30 @@
}
/**
- * Add zero or more cookies
- * If any given cookie 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, java.util.Date)
*
@@ -242,20 +245,20 @@
}
/**
- * 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 true when using HTTPS
- * @param now the {@link Date} by which expiration is determined
- * @return an array of my {@link Cookie}s.
+ * @param now the {@link Date date} by which expiration is determined
+ *
+ * @return an array of {@link Cookie cookies}.
*
- * @see Cookie#matches
* @see #getCookies()
*
- * @deprecated use HttpState.getCookies(String, int, String, boolean)
+ * @deprecated use CookieSpec#match(String, int, String, boolean, Cookie)
*/
public synchronized Cookie[] getCookies(
String domain,
@@ -269,18 +272,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 true when using HTTPS
- * @return an array of my {@link Cookie}s.
*
- * @see Cookie#matches
+ * @return an array of {@link Cookie cookies}.
+ *
* @see #getCookies()
*
+ * @deprecated use {@link CookieSpec#match(String, int, String, boolean, Cookie)}
*/
public synchronized Cookie[] getCookies(
String domain,
@@ -302,9 +306,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)
*
@@ -315,12 +318,15 @@
}
/**
- * Remove all of my {@link Cookie}s that have expired by the specified
- * date.
+ * 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) {
@@ -338,8 +344,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() {
@@ -349,9 +357,10 @@
/**
* Defines whether preemptive authentication should be
- * attempted or not.
+ * attempted.
*
- * @param value boolean flag
+ * @param value true if preemptive authentication should be
+ * attempted, false otherwise.
*/
public void setAuthenticationPreemptive(boolean value) {
@@ -360,8 +369,8 @@
/**
- * Return true if preemptive authentication should be
- * attempted, otherwise return false
+ * Returns true if preemptive authentication should be
+ * attempted, false otherwise.
*
* @return boolean flag.
*/
@@ -372,10 +381,13 @@
/**
- * 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) {
@@ -383,26 +395,21 @@
}
/**
- * Set the Credentials for the given authentication realm.
- *
- * When realm is null, I'll use the given
- * credentials when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a null realm to set the "default"
- * credentials.)
- *
- * Any previous credentials for this realm will be overwritten.
+ * Sets the {@link Credentials credentials} for the given authentication
+ * realm. The null realm signifies default credentials, which
+ * should be used when no {@link Credentials credentials} have been explictly
+ * supplied for the given challenging realm. Any previous credentials for
+ * the given realm will be overwritten.
*
* @deprecated This method does not distinguish between realms with the
- * same name on different hosts. Use
- * {@link HttpState#setCredentials(String, Credentials)} instead.
+ * same name on different hosts.
+ * Use {@link #setCredentials(String, String, Credentials)} instead.
*
* @param realm the authentication realm
* @param credentials the authentication credentials for the given realm
*
* @see #getCredentials(String, String)
* @see #setProxyCredentials(String, String, Credentials)
- *
*/
public synchronized void setCredentials(String realm, Credentials credentials) {
@@ -410,20 +417,20 @@
setCredentials(realm, null, credentials);
}
- /** Sets the credentials for realm on host.
- * with no host.
- *
- * When realm is null, I'll use the given
- * credentials when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a null realm to set the "default"
- * credentials.)
- *
- * Any previous credentials for this realm will be overwritten.
+ /**
+ * Sets the {@link Credentials credentials} for the given authentication
+ * realm on the given host. The null 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 null 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)
@@ -437,7 +444,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 realm exists on host, return the coresponding credentials.
* If the host exists with a null realm, return the corresponding
@@ -471,7 +478,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 realm exists on host, return the coresponding credentials.
* If the host exists with a null realm, return the corresponding
@@ -486,7 +494,6 @@
* @return the credentials
*
* @see #setCredentials(String, String, Credentials)
- *
*/
public synchronized Credentials getCredentials(String realm, String host) {
@@ -495,13 +502,7 @@
}
/**
- * Get the Credentials for the given authentication realm.
- *
- * If the realm exists on host, return the coresponding credentials.
- * If the realm exists with a null host, return the
- * corresponding credentials. If the realm does not exist, return
- * the default Credentials. If there is no default credentials, return
- * null.
+ * Get the {@link Credentials credentials} for the given authentication realm.
*
* @deprecated This method does not distinguish between realms on different
* servers with the same name. Use {@link #getCredentials(String, String)}
@@ -521,17 +522,12 @@
}
/**
- * Set the for the proxy with the given authentication realm.
- *
- * When realm is null, I'll use the given
- * credentials when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a null realm to set the "default"
- * credentials.) Realms rarely make much sense with proxies, so
- * null is normally a good choice here.
- *
- * Any previous credentials for this realm will be overwritten.
- *
+ * Sets the {@link Credentials credentials} for the given proxy authentication
+ * realm. The null realm signifies default credentials, which
+ * should be used when no {@link Credentials credentials} have been explictly
+ * supplied for the given challenging proxy realm. Any previous credentials for
+ * the given realm will be overwritten.
+ *
* @deprecated This method does not differentiate between realms with
* the same name on different servers. Use
* {@link #setProxyCredentials(String, String, Credentials)} instead.
@@ -550,17 +546,16 @@
}
/**
- * Set the credentials for the proxy with the given authentication realm.
- *
- * When realm and proxyHost are null, I'll use the given
- * credentials when no other {@link Credentials} have
- * been supplied for the given challenging realm.
- * (I.e., use a null realm to set the "default"
- * credentials.) Realms rarely make much sense with proxies, so
- * null is normally a good choice here.
- *
- * 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 null 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 null 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
* @param credentials the authentication credentials for the given realm
@@ -579,7 +574,8 @@
}
/**
- * Get the Credentials for the proxy with the given authentication realm.
+ * Get the {@link Credentials credentials} for the given
+ * proxy authentication realm.
*
* If the realm exists, return the coresponding credentials. If the
* realm does not exist, return the default Credentials. If there is
@@ -599,8 +595,8 @@
}
/**
- * Get the Credentials for the proxy with the given authentication realm on the given
- * host.
+ * Get the {@link Credentials credentials} for the proxy host with the given
+ * authentication realm.
*
* If the realm exists on host, return the coresponding credentials.
* If the host exists with a null realm, return the corresponding
@@ -621,8 +617,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() {
@@ -642,7 +640,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.
*/
@@ -663,7 +661,7 @@
}
/**
- * Return a string representation of the credentials.
+ * Returns a string representation of the credentials.
* @param credMap The credentials.
* @return StringBuffer The string representation.
*/