org.apache.commons.httpclient
Class HttpState

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpState

public class HttpState
extends java.lang.Object

A container for HTTP attributes that may persist from request to request, such as cookies and authentication credentials.

Preemptive authentication can be turned on by using the property value of #PREEMPTIVE_PROPERTY. If left unspecified, it has the default value of #PREEMPTIVE_DEFAULT. This configurable behaviour conforms to rcf2617:

Version:
$Revision: 1.22.2.3 $ $Date: 2003/10/29 03:08:49 $
Author:
Remy Maucherat, Rodney Waldhoff, Jeff Dever, Sean C. Sullivan, Michael Becke, Oleg Kalnichevski, Mike Bowler, Adrian Sutton

Field Summary
static HttpAuthRealm DEFAULT_AUTH_REALM
          The default authentication realm.
static java.lang.String PREEMPTIVE_DEFAULT
          The default property value for #PREEMPTIVE_PROPERTY.
static java.lang.String PREEMPTIVE_PROPERTY
          The boolean property name to turn on preemptive authentication.
 
Constructor Summary
HttpState()
          Default constructor.
 
Method Summary
 void addCookie(Cookie cookie)
          Adds an HTTP cookie, replacing any existing equivalent cookies.
 void addCookies(Cookie[] cookies)
          Adds an array of HTTP cookies.
 int getCookiePolicy()
          Returns the current cookie policy for this HTTP state.
 Cookie[] getCookies()
          Returns an array of cookies that this HTTP state currently contains.
 Cookie[] getCookies(java.lang.String domain, int port, java.lang.String path, boolean secure)
          Deprecated. use CookieSpec.match(String, int, String, boolean, Cookie)
 Cookie[] getCookies(java.lang.String domain, int port, java.lang.String path, boolean secure, java.util.Date now)
          Deprecated. use CookieSpec#match(String, int, String, boolean, Cookie)
 Credentials getCredentials(java.lang.String realm)
          Deprecated. This method does not distinguish between realms on different servers with the same name. Use getCredentials(String, String) instead.
 Credentials getCredentials(java.lang.String realm, java.lang.String host)
          Get the credentials for the given authentication realm on the given host.
 HttpConnectionManager getHttpConnectionManager()
          Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.getHttpConnectionManager() instead.
 Credentials getProxyCredentials(java.lang.String realm)
          Deprecated. This method does not distinguish between realms on different hosts. Use getProxyCredentials(String, String) instead.
 Credentials getProxyCredentials(java.lang.String realm, java.lang.String proxyHost)
          Get the credentials for the proxy host with the given authentication realm.
 boolean isAuthenticationPreemptive()
          Returns true if preemptive authentication should be attempted, false otherwise.
 boolean purgeExpiredCookies()
          Removes all of cookies in this HTTP state that have expired according to the current system time.
 boolean purgeExpiredCookies(java.util.Date date)
          Removes all of cookies in this HTTP state that have expired by the specified date.
 void setAuthenticationPreemptive(boolean value)
          Defines whether preemptive authentication should be attempted.
 void setCookiePolicy(int policy)
          Sets the current cookie policy for this HTTP state to one of the following supported policies: CookiePolicy.COMPATIBILITY, CookiePolicy.NETSCAPE_DRAFT or CookiePolicy.RFC2109.
 void setCredentials(java.lang.String realm, Credentials credentials)
          Deprecated. This method does not distinguish between realms with the same name on different hosts. Use setCredentials(String, String, Credentials) instead.
 void setCredentials(java.lang.String realm, java.lang.String host, Credentials credentials)
          Sets the credentials for the given authentication realm on the given host.
 void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)
          Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.setHttpConnectionManager(HttpConnectionManager) instead.
 void setProxyCredentials(java.lang.String realm, Credentials credentials)
          Deprecated. This method does not differentiate between realms with the same name on different servers. Use setProxyCredentials(String, String, Credentials) instead.
 void setProxyCredentials(java.lang.String realm, java.lang.String proxyHost, Credentials credentials)
          Sets the credentials for the given proxy authentication realm on the given proxy host.
 java.lang.String toString()
          Returns a string representation of this HTTP state.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PREEMPTIVE_PROPERTY

public static final java.lang.String PREEMPTIVE_PROPERTY
The boolean property name to turn on preemptive authentication.

PREEMPTIVE_DEFAULT

public static final java.lang.String PREEMPTIVE_DEFAULT
The default property value for #PREEMPTIVE_PROPERTY.

DEFAULT_AUTH_REALM

public static final HttpAuthRealm DEFAULT_AUTH_REALM
The default authentication realm.
Constructor Detail

HttpState

public HttpState()
Default constructor.
Method Detail

addCookie

public void addCookie(Cookie cookie)
Adds an 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.
Parameters:
cookie - the cookie to be added
See Also:
addCookies(Cookie[])

addCookies

public void addCookies(Cookie[] cookies)
Adds an array of 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.
Parameters:
cookies - the cookies to be added
See Also:
addCookie(Cookie)

getCookies

public Cookie[] getCookies()
Returns an array of cookies that this HTTP state currently contains.
Returns:
an array of cookies.
See Also:
getCookies(String, int, String, boolean, java.util.Date)

getCookies

public Cookie[] getCookies(java.lang.String domain,
                           int port,
                           java.lang.String path,
                           boolean secure,
                           java.util.Date now)
Deprecated. use CookieSpec#match(String, int, String, boolean, Cookie)

Returns an array of cookies in this HTTP state that match the given request parameters.
Parameters:
domain - the request domain
port - the request port
path - the request path
secure - true when using HTTPS
now - the date by which expiration is determined
Returns:
an array of cookies.
See Also:
getCookies()

getCookies

public Cookie[] getCookies(java.lang.String domain,
                           int port,
                           java.lang.String path,
                           boolean secure)
Deprecated. use CookieSpec.match(String, int, String, boolean, Cookie)

Returns an array of cookies in this HTTP state that match the given request parameters.
Parameters:
domain - the request domain
port - the request port
path - the request path
secure - true when using HTTPS
Returns:
an array of cookies.
See Also:
getCookies()

purgeExpiredCookies

public boolean purgeExpiredCookies()
Removes all of cookies in this HTTP state that have expired according to the current system time.
See Also:
purgeExpiredCookies(java.util.Date)

purgeExpiredCookies

public boolean purgeExpiredCookies(java.util.Date date)
Removes all of cookies in this HTTP state that have expired by the specified date.
Parameters:
date - The date to compare against.
Returns:
true if any cookies were purged.
See Also:
Cookie.isExpired(java.util.Date), purgeExpiredCookies()

getCookiePolicy

public int getCookiePolicy()
Returns the current cookie policy for this HTTP state.
Returns:
The cookie policy.

setAuthenticationPreemptive

public void setAuthenticationPreemptive(boolean value)
Defines whether preemptive authentication should be attempted.
Parameters:
value - true if preemptive authentication should be attempted, false otherwise.

isAuthenticationPreemptive

public boolean isAuthenticationPreemptive()
Returns true if preemptive authentication should be attempted, false otherwise.
Returns:
boolean flag.

setCookiePolicy

public void setCookiePolicy(int policy)
Sets the current cookie policy for this HTTP state to one of the following supported policies: CookiePolicy.COMPATIBILITY, CookiePolicy.NETSCAPE_DRAFT or CookiePolicy.RFC2109.
Parameters:
policy - new cookie policy

setCredentials

public void setCredentials(java.lang.String realm,
                           Credentials credentials)
Deprecated. This method does not distinguish between realms with the same name on different hosts. Use setCredentials(String, String, Credentials) instead.

Sets the credentials for the given authentication realm. The null realm signifies default credentials, which should be used when no credentials have been explictly supplied for the given challenging realm. Any previous credentials for the given realm will be overwritten.
Parameters:
realm - the authentication realm
credentials - the authentication credentials for the given realm
See Also:
getCredentials(String, String), setProxyCredentials(String, String, Credentials)

setCredentials

public void setCredentials(java.lang.String realm,
                           java.lang.String host,
                           Credentials credentials)
Sets the 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 credentials have been explictly supplied for the challenging realm. The null host signifies default credentials, which should be used when no credentials have been explictly supplied for the challenging host. Any previous credentials for the given realm on the given host will be overwritten.
Parameters:
realm - the authentication realm
host - the host the realm belongs to
credentials - the authentication credentials for the given realm.
See Also:
getCredentials(String, String), setProxyCredentials(String, String, Credentials)

getCredentials

public Credentials getCredentials(java.lang.String realm,
                                  java.lang.String host)
Get the 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 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 are no default credentials, return null.
Parameters:
realm - the authentication realm
host - the host the realm is on
Returns:
the credentials
See Also:
setCredentials(String, String, Credentials)

getCredentials

public Credentials getCredentials(java.lang.String realm)
Deprecated. This method does not distinguish between realms on different servers with the same name. Use getCredentials(String, String) instead.

Get the credentials for the given authentication realm.
Parameters:
realm - the authentication realm
Returns:
the credentials
See Also:
setCredentials(String, String, Credentials)

setProxyCredentials

public void setProxyCredentials(java.lang.String realm,
                                Credentials credentials)
Deprecated. This method does not differentiate between realms with the same name on different servers. Use setProxyCredentials(String, String, Credentials) instead.

Sets the credentials for the given proxy authentication realm. The null realm signifies default credentials, which should be used when no credentials have been explictly supplied for the given challenging proxy realm. Any previous credentials for the given realm will be overwritten.
Parameters:
realm - the authentication realm
credentials - the authentication credentials for the given realm
See Also:
getProxyCredentials(String), setCredentials(String, Credentials)

setProxyCredentials

public void setProxyCredentials(java.lang.String realm,
                                java.lang.String proxyHost,
                                Credentials credentials)
Sets the 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 credentials have been explictly supplied for the challenging proxy realm. The null proxy host signifies default credentials, which should be used when no 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.
Parameters:
realm - the authentication realm
proxyHost - the proxy host
credentials - the authentication credentials for the given realm
See Also:
getProxyCredentials(String), setCredentials(String, Credentials)

getProxyCredentials

public Credentials getProxyCredentials(java.lang.String realm)
Deprecated. This method does not distinguish between realms on different hosts. Use getProxyCredentials(String, String) instead.

Get the 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 no default credentials, return null.
Parameters:
realm - the authentication realm
Returns:
the credentials
See Also:
setProxyCredentials(String, String, Credentials)

getProxyCredentials

public Credentials getProxyCredentials(java.lang.String realm,
                                       java.lang.String proxyHost)
Get the 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 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 are no default credentials, return null.
Parameters:
realm - the authentication realm
proxyHost - the proxy host the realm is on
Returns:
the credentials
See Also:
setProxyCredentials(String, String, Credentials)

toString

public java.lang.String toString()
Returns a string representation of this HTTP state.
Overrides:
toString in class java.lang.Object
Returns:
The string representation of the HTTP state.
See Also:
Object.toString()

getHttpConnectionManager

public HttpConnectionManager getHttpConnectionManager()
Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.getHttpConnectionManager() instead.

Returns the httpConnectionManager.
Returns:
HttpConnectionManager
Since:
2.0

setHttpConnectionManager

public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)
Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.setHttpConnectionManager(HttpConnectionManager) instead.

Sets the httpConnectionManager.
Parameters:
httpConnectionManager - The httpConnectionManager to set
Since:
2.0


Copyright © 2001-2004 Apache Software Foundation. All Rights Reserved.