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.

Version:

$Revision$ $Date$

Author:

Remy Maucherat, Rodney Waldhoff, Jeff Dever, Sean C. Sullivan, Michael Becke, Oleg Kalnichevski, Mike Bowler, Adrian Sutton

Field Summary

Fields

Modifier and Type	Field and Description
static String	PREEMPTIVE_DEFAULT Deprecated. This field and feature will be removed following HttpClient 3.0.
static String	PREEMPTIVE_PROPERTY Deprecated. This field and feature will be removed following HttpClient 3.0.

Constructor Summary

Constructors

Constructor and Description
HttpState() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	addCookie(Cookie cookie) Adds an HTTP cookie, replacing any existing equivalent cookies.
void	addCookies(Cookie[] cookies) Adds an array of HTTP cookies.
void	clear() Clears the state information (all cookies, credentials and proxy credentials).
void	clearCookies() Clears all cookies.
void	clearCredentials() Clears all credentials.
void	clearProxyCredentials() Clears all proxy credentials.
int	getCookiePolicy() Deprecated. Use HttpMethodParams.getCookiePolicy(), HttpMethod.getParams().
Cookie[]	getCookies() Deprecated. use getCookiesMap() // <- IA/HERITRIX CHANGE
Cookie[]	getCookies(String domain, int port, String path, boolean secure) Deprecated. use CookieSpec#match(String, int, String, boolean, Cookie)
SortedMap<String,Cookie>	getCookiesMap() Returns a sorted map of cookies that this HTTP state currently contains.
org.apache.commons.httpclient.Credentials	getCredentials(org.apache.commons.httpclient.auth.AuthScope authscope) Get the credentials for the given authentication scope.
org.apache.commons.httpclient.Credentials	getCredentials(String realm, String host) Deprecated. use #getCredentials(AuthScope)
org.apache.commons.httpclient.Credentials	getProxyCredentials(org.apache.commons.httpclient.auth.AuthScope authscope) Get the proxy credentials for the given authentication scope.
org.apache.commons.httpclient.Credentials	getProxyCredentials(String realm, String proxyHost) Deprecated. use #getProxyCredentials(AuthScope)
boolean	isAuthenticationPreemptive() Deprecated. Use HttpClientParams.isAuthenticationPreemptive(), HttpClient.getParams().
boolean	purgeExpiredCookies() Removes all of cookies in this HTTP state that have expired according to the current system time.
boolean	purgeExpiredCookies(Date date) Removes all of cookies in this HTTP state that have expired by the specified date.
void	setAuthenticationPreemptive(boolean value) Deprecated. Use HttpClientParams.setAuthenticationPreemptive(boolean), HttpClient.getParams().
void	setCookiePolicy(int policy) Deprecated. Use HttpMethodParams.setCookiePolicy(String), HttpMethod.getParams().
void	setCookiesMap(SortedMap<String,Cookie> map) Replace the standard sorted map with an external implemenations (such as one backed by persistent store, like BDB's StoredSortedMap.)
void	setCredentials(org.apache.commons.httpclient.auth.AuthScope authscope, org.apache.commons.httpclient.Credentials credentials) Sets the credentials for the given authentication scope.
void	setCredentials(String realm, String host, org.apache.commons.httpclient.Credentials credentials) Deprecated. use #setCredentials(AuthScope, Credentials)
void	setProxyCredentials(org.apache.commons.httpclient.auth.AuthScope authscope, org.apache.commons.httpclient.Credentials credentials) Sets the proxy credentials for the given authentication realm.
void	setProxyCredentials(String realm, String proxyHost, org.apache.commons.httpclient.Credentials credentials) Deprecated. use #setProxyCredentials(AuthScope, Credentials)
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 String PREEMPTIVE_PROPERTY

Deprecated. This field and feature will be removed following HttpClient 3.0.

The boolean system property name to turn on preemptive authentication.

See Also:

Constant Field Values

PREEMPTIVE_DEFAULT

public static final String PREEMPTIVE_DEFAULT

Deprecated. This field and feature will be removed following HttpClient 3.0.

The default value for PREEMPTIVE_PROPERTY.

See Also:

Constant Field Values

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

Deprecated. use getCookiesMap() // <- IA/HERITRIX CHANGE

Returns an array of cookies that this HTTP state currently contains.

Returns:

an array of cookies.

See Also:

getCookies(String, int, String, boolean)

getCookiesMap

public SortedMap<String,Cookie> getCookiesMap()

Returns a sorted map of cookies that this HTTP state currently contains. Any operations on this map should be synchronized with respect to this HttpState instance.

Returns:

sorter map of cookies

setCookiesMap

public void setCookiesMap(SortedMap<String,Cookie> map)

Replace the standard sorted map with an external implemenations (such as one backed by persistent store, like BDB's StoredSortedMap.)

Parameters:

map - alternate sorted map to use to store cookies

getCookies

public Cookie[] getCookies(String domain,
                  int port,
                  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(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()

Deprecated. Use HttpMethodParams.getCookiePolicy(), HttpMethod.getParams().

Returns the current cookie policy for this HTTP state.

Returns:

The cookie policy.

setAuthenticationPreemptive

public void setAuthenticationPreemptive(boolean value)

Deprecated. Use HttpClientParams.setAuthenticationPreemptive(boolean), HttpClient.getParams().

Defines whether preemptive authentication should be attempted.

Parameters:

value - true if preemptive authentication should be attempted, false otherwise.

isAuthenticationPreemptive

public boolean isAuthenticationPreemptive()

Deprecated. Use HttpClientParams.isAuthenticationPreemptive(), HttpClient.getParams().

Returns true if preemptive authentication should be attempted, false otherwise.

Returns:

boolean flag.

setCookiePolicy

public void setCookiePolicy(int policy)

Deprecated. Use HttpMethodParams.setCookiePolicy(String), HttpMethod.getParams().

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(String realm,
                  String host,
                  org.apache.commons.httpclient.Credentials credentials)

Deprecated. use #setCredentials(AuthScope, 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)

setCredentials

public void setCredentials(org.apache.commons.httpclient.auth.AuthScope authscope,
                  org.apache.commons.httpclient.Credentials credentials)

Sets the credentials for the given authentication scope. Any previous credentials for the given scope will be overwritten.

Parameters:

authscope - the authentication scope

credentials - the authentication credentials for the given scope.

Since:

3.0

See Also:

getCredentials(AuthScope), setProxyCredentials(AuthScope, Credentials)

getCredentials

public org.apache.commons.httpclient.Credentials getCredentials(String realm,
                                                       String host)

Deprecated. use #getCredentials(AuthScope)

Get the credentials for the given authentication scope 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 org.apache.commons.httpclient.Credentials getCredentials(org.apache.commons.httpclient.auth.AuthScope authscope)

Get the credentials for the given authentication scope.

Parameters:

authscope - the authentication scope

Returns:

the credentials

Since:

3.0

See Also:

setCredentials(AuthScope, Credentials)

setProxyCredentials

public void setProxyCredentials(String realm,
                       String proxyHost,
                       org.apache.commons.httpclient.Credentials credentials)

Deprecated. use #setProxyCredentials(AuthScope, 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(AuthScope), setCredentials(AuthScope, Credentials)

setProxyCredentials

public void setProxyCredentials(org.apache.commons.httpclient.auth.AuthScope authscope,
                       org.apache.commons.httpclient.Credentials credentials)

Sets the proxy credentials for the given authentication realm. Any previous credentials for the given realm will be overwritten.

Parameters:

authscope - the authentication scope

credentials - the authentication credentials for the given realm.

Since:

3.0

See Also:

getProxyCredentials(AuthScope), setCredentials(AuthScope, Credentials)

getProxyCredentials

public org.apache.commons.httpclient.Credentials getProxyCredentials(String realm,
                                                            String proxyHost)

Deprecated. use #getProxyCredentials(AuthScope)

Get the credentials for the proxy host with the given authentication scope. 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)

getProxyCredentials

public org.apache.commons.httpclient.Credentials getProxyCredentials(org.apache.commons.httpclient.auth.AuthScope authscope)

Get the proxy credentials for the given authentication scope.

Parameters:

authscope - the authentication scope

Returns:

the credentials

Since:

3.0

See Also:

setProxyCredentials(AuthScope, Credentials)

toString

public String toString()

Returns a string representation of this HTTP state.

Overrides:

toString in class Object

Returns:

The string representation of the HTTP state.

See Also:

Object.toString()

clearCredentials

public void clearCredentials()

Clears all credentials.

clearProxyCredentials

public void clearProxyCredentials()

Clears all proxy credentials.

clearCookies

public void clearCookies()

Clears all cookies.

clear

public void clear()

Clears the state information (all cookies, credentials and proxy credentials).