AuthScheme (HttpClient Library (Version 3.1))
Date: 2019-01-01

org.apache.commons.httpclient.auth

## Interface AuthScheme

- All Known Implementing Classes:
    AuthSchemeBase, BasicScheme, DigestScheme, NTLMScheme, RFC2617Scheme

      public interface AuthScheme

  This interface represents an abstract challenge-response oriented authentication scheme.

  An authentication scheme should be able to support the following functions:

  - Parse and process the challenge sent by the targer server in response to request for a protected resource
  - Provide its textual designation
  - Provide its parameters, if available
  - Provide the realm this authentication scheme is applicable to, if available
  - Generate authorization string for the given set of credentials, request method and URI as specificed in the HTTP request line in response to the actual authorization challenge

  Authentication schemes may ignore method name and URI parameters if they are not relevant for the given authentication mechanism

  Authentication schemes may be stateful involving a series of challenge-response exchanges

  Since:
    2.0beta1
  Author:
    Oleg Kalnichevski, Adrian Sutton

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `authenticate(Credentials credentials, HttpMethod method)` Produces an authorization string for the given set of `Credentials`.
    `java.lang.String` | `authenticate(Credentials credentials, java.lang.String method, java.lang.String uri)` Deprecated. Use `authenticate(Credentials, HttpMethod)` Produces an authorization string for the given set of `Credentials`, method name and URI using the given authentication scheme in response to the actual authorization challenge.
    `java.lang.String` | `getID()` Deprecated. no longer used
    `java.lang.String` | `getParameter(java.lang.String name)` Returns authentication parameter with the given name, if available.
    `java.lang.String` | `getRealm()` Returns authentication realm.
    `java.lang.String` | `getSchemeName()` Returns textual designation of the given authentication scheme.
    `boolean` | `isComplete()` Authentication process may involve a series of challenge-response exchanges.
    `boolean` | `isConnectionBased()` Tests if the authentication scheme is provides authorization on a per connection basis instead of usual per request basis
    `void` | `processChallenge(java.lang.String challenge)` Processes the given challenge token.

- - ### Method Detail

    - #### processChallenge

          void processChallenge(java.lang.String challenge)
                         throws MalformedChallengeException

      Processes the given challenge token. Some authentication schemes may involve multiple challenge-response exchanges. Such schemes must be able to maintain the state information when dealing with sequential challenges
      Parameters:
        `challenge` - the challenge string
      Throws:
        `MalformedChallengeException`
      Since:
        3.0

    - #### getSchemeName

          java.lang.String getSchemeName()

      Returns textual designation of the given authentication scheme.
      Returns:
        the name of the given authentication scheme

    - #### getParameter

          java.lang.String getParameter(java.lang.String name)

      Returns authentication parameter with the given name, if available.
      Parameters:
        `name` - The name of the parameter to be returned
      Returns:
        the parameter with the given name

    - #### getRealm

          java.lang.String getRealm()

      Returns authentication realm. If the concept of an authentication realm is not applicable to the given authentication scheme, returns `null`.
      Returns:
        the authentication realm

    - #### getID

          java.lang.String getID()

      Deprecated. no longer used
      Returns a String identifying the authentication challenge. This is used, in combination with the host and port to determine if authorization has already been attempted or not. Schemes which require multiple requests to complete the authentication should return a different value for each stage in the request.

      Additionally, the ID should take into account any changes to the authentication challenge and return a different value when appropriate. For example when the realm changes in basic authentication it should be considered a different authentication attempt and a different value should be returned.

      Returns:
        String a String identifying the authentication challenge. The returned value may be null.

    - #### isConnectionBased

          boolean isConnectionBased()

      Tests if the authentication scheme is provides authorization on a per connection basis instead of usual per request basis
      Returns:
        `true` if the scheme is connection based, `false` if the scheme is request based.
      Since:
        3.0

    - #### isComplete

          boolean isComplete()

      Authentication process may involve a series of challenge-response exchanges. This method tests if the authorization process has been completed, either successfully or unsuccessfully, that is, all the required authorization challenges have been processed in their entirety.
      Returns:
        `true` if the authentication process has been completed, `false` otherwise.
      Since:
        3.0

    - #### authenticate

          java.lang.String authenticate(Credentials credentials,
                                        java.lang.String method,
                                        java.lang.String uri)
                                 throws AuthenticationException

      Deprecated. Use `authenticate(Credentials, HttpMethod)` Produces an authorization string for the given set of `Credentials`, method name and URI using the given authentication scheme in response to the actual authorization challenge.
      Parameters:
        `credentials` - The set of credentials to be used for athentication
        `method` - The name of the method that requires authorization. This parameter may be ignored, if it is irrelevant or not applicable to the given authentication scheme
        `uri` - The URI for which authorization is needed. This parameter may be ignored, if it is irrelevant or not applicable to the given authentication scheme
      Returns:
        the authorization string
      Throws:
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      See Also:
        `HttpMethod.getName()`, `HttpMethod.getPath()`

    - #### authenticate

          java.lang.String authenticate(Credentials credentials,
                                        HttpMethod method)
                                 throws AuthenticationException

      Produces an authorization string for the given set of `Credentials`.
      Parameters:
        `credentials` - The set of credentials to be used for athentication
        `method` - The method being authenticated
      Returns:
        the authorization string
      Throws:
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      Since:
        3.0

Copyright (c) 1999-2005 - Apache Software Foundation