uk.ac.starlink.auth

## Class Challenge

- java.lang.Object
- - uk.ac.starlink.auth.Challenge

-     public class Challenge
      extends java.lang.Object

  Represents and parses challenge specifications as defined by RFC7235.
  Since:
    9 Jun 2020
  See Also:
    RFC 7235

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Challenge(java.lang.String schemeName, java.lang.String token68)` Constructs a challenge with token68 string
    `Challenge(java.lang.String schemeName, java.lang.String realm, java.util.Map<java.lang.String,java.lang.String> params)` Constructs a challenge with an optional realm and auth parameters.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object o)`
    `java.util.Map<java.lang.String,java.lang.String>` | `getParams()` Returns any auth parameters that form part of this challenge excluding the realm.
    `java.lang.String` | `getRealm()` Returns the authentication realm if defined.
    `java.lang.String` | `getRequiredParameter(java.lang.String key)` Utility method giving a non-empty value for a named parameter of this challenge.
    `java.net.URL` | `getRequiredParameterUrl(java.lang.String key)` Utility method giving a non-null URL value for a named parameter of this challenge.
    `java.lang.String` | `getRequiredRealm()` Utility method giving a non-empty realm for this challenge.
    `java.lang.String` | `getSchemeName()` Returns the authentication scheme name.
    `java.lang.String` | `getToken68()` Returns the token68 value if defined.
    `int` | `hashCode()`
    `static void` | `main(java.lang.String[] args)` Will parse a WWW-Authenticate string on the command line and print out the parsed challenges.
    `static java.util.List<Challenge>` | `parseChallenges(java.lang.String challengeTxt)` Parses the content of a WWW-Authenticate header as a sequence of RFC7235 challenges.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Challenge

          public Challenge(java.lang.String schemeName,
                           java.lang.String realm,
                           java.util.Map<java.lang.String,java.lang.String> params)

      Constructs a challenge with an optional realm and auth parameters.
      Parameters:
        `schemeName` - scheme name, case insensitive
        `realm` - specified realm value, or null
        `params` - additional parameters (excluding realm); keys are case insensitive and will be mapped to lower

    - #### Challenge

          public Challenge(java.lang.String schemeName,
                           java.lang.String token68)

      Constructs a challenge with token68 string
      Parameters:
        `schemeName` - scheme name, case insensitive
        `token68` - token68 string

  - ### Method Detail

    - #### getSchemeName

          public java.lang.String getSchemeName()

      Returns the authentication scheme name.
      Returns:
        scheme name, case insensitive

    - #### getRealm

          public java.lang.String getRealm()

      Returns the authentication realm if defined.
      Returns:
        realm or null

    - #### getToken68

          public java.lang.String getToken68()

      Returns the token68 value if defined. If this is non-null, then there will be no parameters or realm.
      Returns:
        token68 or null

    - #### getParams

          public java.util.Map<java.lang.String,java.lang.String> getParams()

      Returns any auth parameters that form part of this challenge excluding the realm.
      Returns:
        name->value map giving parameters; parameter names have been normalised to lower case

    - #### getRequiredRealm

          public java.lang.String getRequiredRealm()
                                            throws BadChallengeException

      Utility method giving a non-empty realm for this challenge. If no realm has been defined, a BadChallengeException is thrown.
      Returns:
        non-empty realm string
      Throws:
        `BadChallengeException` - if there is no realm

    - #### getRequiredParameter

          public java.lang.String getRequiredParameter(java.lang.String key)
                                                throws BadChallengeException

      Utility method giving a non-empty value for a named parameter of this challenge. If the named parameter has not been specified, a BadChallengeException is thrown.
      Parameters:
        `key` - parameter name, case-insensitive
      Returns:
        non-empty value for parameter `key`
      Throws:
        `BadChallengeException` - if no value is specified for `key`

    - #### getRequiredParameterUrl

          public java.net.URL getRequiredParameterUrl(java.lang.String key)
                                               throws BadChallengeException

      Utility method giving a non-null URL value for a named parameter of this challenge. If the named parameter is not specified or cannot be turned into a URL, a BadChallengeException is thrown.
      Parameters:
        `key` - parameter name, case-insensitive
      Returns:
        non-null URL for parameter `key`
      Throws:
        `BadChallengeException` - if no URL value is specified for `key`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### parseChallenges

          public static java.util.List<Challenge> parseChallenges(java.lang.String challengeTxt)

      Parses the content of a WWW-Authenticate header as a sequence of RFC7235 challenges. According to RFC7235 there should be at least one value in the result, but syntactically invalid challenge text is just ignored, so the result is not guaranteed to be non-empty.
      Parameters:
        `challengeTxt` - text as value of WWW-Authenticate header
      Returns:
        list of parsed challenges

    - #### main

          public static void main(java.lang.String[] args)

      Will parse a WWW-Authenticate string on the command line and print out the parsed challenges.