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. */