HttpState (HttpClient Library (Version 3.1))
Date: 2016-03-09

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

  Version:
    $Revision: 561099 $ $Date: 2007-07-30 21:41:17 +0200 (Mon, 30 Jul 2007) $
  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
    --- | ---
    `protected java.util.ArrayList` | `cookies` Array of `cookies` that this HTTP state contains.
    `protected java.util.HashMap` | `credMap` Map of `credentials` by realm that this HTTP state contains.
    `static java.lang.String` | `PREEMPTIVE_DEFAULT` Deprecated. This field and feature will be removed following HttpClient 3.0.
    `static java.lang.String` | `PREEMPTIVE_PROPERTY` Deprecated. This field and feature will be removed following HttpClient 3.0.
    `protected java.util.HashMap` | `proxyCred` Map of `proxy credentials` by realm that this HTTP state contains

  - ### 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()` 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)
    `Credentials` | `getCredentials(AuthScope authscope)` Get the `credentials` for the given authentication scope.
    `Credentials` | `getCredentials(java.lang.String realm, java.lang.String host)` Deprecated. use #getCredentials(AuthScope)
    `Credentials` | `getProxyCredentials(AuthScope authscope)` Get the `proxy credentials` for the given authentication scope.
    `Credentials` | `getProxyCredentials(java.lang.String realm, java.lang.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(java.util.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` | `setCredentials(AuthScope authscope, Credentials credentials)` Sets the `credentials` for the given authentication scope.
    `void` | `setCredentials(java.lang.String realm, java.lang.String host, Credentials credentials)` Deprecated. use #setCredentials(AuthScope, Credentials)
    `void` | `setProxyCredentials(AuthScope authscope, Credentials credentials)` Sets the `proxy credentials` for the given authentication realm.
    `void` | `setProxyCredentials(java.lang.String realm, java.lang.String proxyHost, Credentials credentials)` Deprecated. use #setProxyCredentials(AuthScope, Credentials)
    `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

    - #### credMap

          protected java.util.HashMap credMap

      Map of `credentials` by realm that this HTTP state contains.

    - #### proxyCred

          protected java.util.HashMap proxyCred

      Map of `proxy credentials` by realm that this HTTP state contains

    - #### cookies

          protected java.util.ArrayList cookies

      Array of `cookies` that this HTTP state contains.

    - #### PREEMPTIVE_PROPERTY

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

      Returns an array of `cookies` that this HTTP state currently contains.
      Returns:
        an array of `cookies`.
      See Also:
        `getCookies(String, int, String, boolean)`

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

      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(java.lang.String realm,
                            java.lang.String host,
                            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(AuthScope authscope,
                            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 Credentials getCredentials(java.lang.String realm,
                                   java.lang.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 Credentials getCredentials(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(java.lang.String realm,
                                 java.lang.String proxyHost,
                                 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(AuthScope authscope,
                                 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 Credentials getProxyCredentials(java.lang.String realm,
                                        java.lang.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 Credentials getProxyCredentials(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 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()`

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

Copyright (c) 1999-2005 - Apache Software Foundation