org.apache.commons.httpclient
Class HttpState

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

public class HttpState

extends 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 $ $Date: 2003/05/08 18:39:07 $

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 String	PREEMPTIVE_DEFAULT The default property value for #PREEMPTIVE_PROPERTY.
static String	PREEMPTIVE_PROPERTY The boolean property name to turn on preemptive authentication.

Constructor Summary

HttpState()
Constructor for HttpState.

Method Summary

void	addCookie(Cookie cookie) Add a cookie.
void	addCookies(Cookie[] newcookies) Add zero or more cookies If any given cookie has already expired, deletes the corresponding existing cookie (if any).
int	getCookiePolicy() Return the current CookiePolicy
Cookie[]	getCookies() Obtain an array of my Cookies.
Cookie[]	getCookies(String domain, int port, String path, boolean secure) Obtain an array of my Cookies that match the given request parameters.
Cookie[]	getCookies(String domain, int port, String path, boolean secure, Date now) Deprecated. use HttpState.getCookies(String, int, String, boolean)
Credentials	getCredentials(String realm) Deprecated. This method does not distinguish between realms on different servers with the same name. Use getCredentials(String, String) instead.
Credentials	getCredentials(String realm, String host) Get the Credentials for the given authentication realm.
HttpConnectionManager	getHttpConnectionManager() Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.getHttpConnectionManager() instead.
Credentials	getProxyCredentials(String realm) Deprecated. This method does not distinguish between realms on different hosts. Use getProxyCredentials(String, String) instead.
Credentials	getProxyCredentials(String realm, String proxyHost) Get the Credentials for the proxy with the given authentication realm on the given host.
boolean	isAuthenticationPreemptive() Return true if preemptive authentication should be attempted, otherwise return false
boolean	purgeExpiredCookies() Remove all of my Cookies that have expired according to the current system time.
boolean	purgeExpiredCookies(Date date) Remove all of my Cookies that have expired by the specified date.
void	setAuthenticationPreemptive(boolean value) Defines whether preemptive authentication should be attempted or not.
void	setCookiePolicy(int policy) Set the CookiePolicy to one of CookiePolicy.COMPATIBILITY, CookiePolicy.NETSCAPE_DRAFT or CookiePolicy.RFC2109
void	setCredentials(String realm, Credentials credentials) Deprecated. This method does not distinguish between realms with the same name on different hosts. Use setCredentials(String, Credentials) instead.
void	setCredentials(String realm, String host, Credentials credentials) Sets the credentials for realm on host.
void	setHttpConnectionManager(HttpConnectionManager httpConnectionManager) Deprecated. Connection manager is controlled by the HttpClient class. Use HttpClient.setHttpConnectionManager(HttpConnectionManager) instead.
void	setProxyCredentials(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(String realm, String proxyHost, Credentials credentials) Set the credentials for the proxy with the given authentication realm.
String	toString() Return a string representation of this object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PREEMPTIVE_PROPERTY

public static final String PREEMPTIVE_PROPERTY

The boolean property name to turn on preemptive authentication.

PREEMPTIVE_DEFAULT

public static final 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()

Constructor for HttpState.

Method Detail

addCookie

public void addCookie(Cookie cookie)

Add a cookie. If the given cookie has already expired, deletes the corresponding existing cookie (if any).

Parameters:

cookie - the Cookie to add

See Also:

addCookies(Cookie[])

addCookies

public void addCookies(Cookie[] newcookies)

Add zero or more cookies If any given cookie has already expired, deletes the corresponding existing cookie (if any).

Parameters:

newcookies - the Cookies to add

See Also:

addCookie(Cookie)

getCookies

public Cookie[] getCookies()

Obtain an array of my Cookies.

Returns:

an array of my Cookies.

See Also:

getCookies(String, int, String, boolean, java.util.Date)

getCookies

public Cookie[] getCookies(String domain,
                           int port,
                           String path,
                           boolean secure,
                           Date now)

Deprecated. use HttpState.getCookies(String, int, String, boolean)

Obtain an array of my Cookies 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 my Cookies.

See Also:

Cookie.matches(java.lang.String, int, java.lang.String, boolean, java.util.Date), getCookies()

getCookies

public Cookie[] getCookies(String domain,
                           int port,
                           String path,
                           boolean secure)

Obtain an array of my Cookies 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 my Cookies.

See Also:

Cookie.matches(java.lang.String, int, java.lang.String, boolean, java.util.Date), getCookies()

purgeExpiredCookies

public boolean purgeExpiredCookies()

Remove all of my Cookies that have expired according to the current system time.

See Also:

purgeExpiredCookies(java.util.Date)

purgeExpiredCookies

public boolean purgeExpiredCookies(Date date)

Remove all of my Cookies 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()

Return the current CookiePolicy

Returns:

The cookie policy.

setAuthenticationPreemptive

public void setAuthenticationPreemptive(boolean value)

Defines whether preemptive authentication should be attempted or not.

Parameters:

value - boolean flag

isAuthenticationPreemptive

public boolean isAuthenticationPreemptive()

Return true if preemptive authentication should be attempted, otherwise return false

Returns:

boolean flag.

setCookiePolicy

public void setCookiePolicy(int policy)

Set the CookiePolicy to one of CookiePolicy.COMPATIBILITY, CookiePolicy.NETSCAPE_DRAFT or CookiePolicy.RFC2109

Parameters:

policy - new cookie policy

setCredentials

public void setCredentials(String realm,
                           Credentials credentials)

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

Set the Credentials for the given authentication realm. When realm is null, I'll use the given credentials when no other 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.

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(String realm,
                           String host,
                           Credentials credentials)

Sets the credentials for realm on host. with no host. When realm is null, I'll use the given credentials when no other 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.

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(String realm,
                                  String host)

Get the Credentials for 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

host - the host the realm is on

Returns:

the credentials

See Also:

setCredentials(String, String, Credentials)

getCredentials

public Credentials getCredentials(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. 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.

Parameters:

realm - the authentication realm

Returns:

the credentials

See Also:

setCredentials(String, String, Credentials)

setProxyCredentials

public void setProxyCredentials(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.

Set the for the proxy with the given authentication realm. When realm is null, I'll use the given credentials when no other 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.

Parameters:

realm - the authentication realm

credentials - the authentication credentials for the given realm

See Also:

getProxyCredentials(String), setCredentials(String, Credentials)

setProxyCredentials

public void setProxyCredentials(String realm,
                                String proxyHost,
                                Credentials credentials)

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

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(String realm)

Deprecated. This method does not distinguish between realms on different hosts. Use getProxyCredentials(String, String) instead.

Get the Credentials for the proxy with the given 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(String realm,
                                       String proxyHost)

Get the Credentials for the proxy with 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

proxyHost - the proxy host the realm is on

Returns:

the credentials

See Also:

setProxyCredentials(String, String, Credentials)

toString

public String toString()

Return a string representation of this object.

Overrides:

toString in class Object

Returns:

The string representation.

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