View Javadoc

    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/auth/RFC2617Scheme.java,v 1.10 2004/05/13 04:02:00 mbecke Exp $
    3    * $Revision: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    5    *
    6    * ====================================================================
    7    *
    8    *  Licensed to the Apache Software Foundation (ASF) under one or more
    9    *  contributor license agreements.  See the NOTICE file distributed with
    10   *  this work for additional information regarding copyright ownership.
    11   *  The ASF licenses this file to You under the Apache License, Version 2.0
    12   *  (the "License"); you may not use this file except in compliance with
    13   *  the License.  You may obtain a copy of the License at
    14   *
    15   *      http://www.apache.org/licenses/LICENSE-2.0
    16   *
    17   *  Unless required by applicable law or agreed to in writing, software
    18   *  distributed under the License is distributed on an "AS IS" BASIS,
    19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    20   *  See the License for the specific language governing permissions and
    21   *  limitations under the License.
    22   * ====================================================================
    23   *
    24   * This software consists of voluntary contributions made by many
    25   * individuals on behalf of the Apache Software Foundation.  For more
    26   * information on the Apache Software Foundation, please see
    27   * <http://www.apache.org/>.
    28   *
    29   */
    30
    31  package org.apache.commons.httpclient.auth;
    32
    33  import java.util.Map;
    34
    35  /**
    36   * <p>
    37   * Abstract authentication scheme class that lays foundation for all
    38   * RFC 2617 compliant authetication schemes and provides capabilities common
    39   * to all authentication schemes defined in RFC 2617.
    40   * </p>
    41   *
    42   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    43  */
    44  public abstract class RFC2617Scheme implements AuthScheme {
    45
    46      /**
    47       * Authentication parameter map.
    48       */
    49      private Map params = null;
    50
    51      /**
    52       * Default constructor for RFC2617 compliant authetication schemes.
    53       *
    54       * @since 3.0
    55       */
    56      public RFC2617Scheme() {
    57          super();
    58      }
    59
    60      /**
    61       * Default constructor for RFC2617 compliant authetication schemes.
    62       *
    63       * @param challenge authentication challenge
    64       *
    65       * @throws MalformedChallengeException is thrown if the authentication challenge
    66       * is malformed
    67       *
    68       * @deprecated Use parameterless constructor and {@link AuthScheme#processChallenge(String)}
    69       *             method
    70       */
    71      public RFC2617Scheme(final String challenge) throws MalformedChallengeException {
    72          super();
    73          processChallenge(challenge);
    74      }
    75
    76      /**
    77       * Processes the given challenge token. Some authentication schemes
    78       * may involve multiple challenge-response exchanges. Such schemes must be able
    79       * to maintain the state information when dealing with sequential challenges
    80       *
    81       * @param challenge the challenge string
    82       *
    83       * @throws MalformedChallengeException is thrown if the authentication challenge
    84       * is malformed
    85       *
    86       * @since 3.0
    87       */
    88      public void processChallenge(final String challenge) throws MalformedChallengeException {
    89          String s = AuthChallengeParser.extractScheme(challenge);
    90          if (!s.equalsIgnoreCase(getSchemeName())) {
    91              throw new MalformedChallengeException(
    92                "Invalid " + getSchemeName() + " challenge: " + challenge);
    93          }
    94          this.params = AuthChallengeParser.extractParams(challenge);
    95      }
    96
    97      /**
    98       * Returns authentication parameters map. Keys in the map are lower-cased.
    99       *
    100      * @return the map of authentication parameters
    101      */
    102     protected Map getParameters() {
    103         return this.params;
    104     }
    105
    106     /**
    107      * Returns authentication parameter with the given name, if available.
    108      *
    109      * @param name The name of the parameter to be returned
    110      *
    111      * @return the parameter with the given name
    112      */
    113     public String getParameter(String name) {
    114         if (name == null) {
    115             throw new IllegalArgumentException("Parameter name may not be null");
    116         }
    117         if (this.params == null) {
    118             return null;
    119         }
    120         return (String) this.params.get(name.toLowerCase());
    121     }
    122
    123     /**
    124      * Returns authentication realm. The realm may not be null.
    125      *
    126      * @return the authentication realm
    127      */
    128     public String getRealm() {
    129         return getParameter("realm");
    130     }
    131
    132     /**
    133      * Returns a String identifying the authentication challenge.  This is
    134      * used, in combination with the host and port to determine if
    135      * authorization has already been attempted or not.  Schemes which
    136      * require multiple requests to complete the authentication should
    137      * return a different value for each stage in the request.
    138      *
    139      * <p>Additionally, the ID should take into account any changes to the
    140      * authentication challenge and return a different value when appropriate.
    141      * For example when the realm changes in basic authentication it should be
    142      * considered a different authentication attempt and a different value should
    143      * be returned.</p>
    144      *
    145      * <p>This method simply returns the realm for the challenge.</p>
    146      *
    147      * @return String a String identifying the authentication challenge.  The
    148      * returned value may be null.
    149      *
    150      * @deprecated no longer used
    151      */
    152     public String getID() {
    153         return getRealm();
    154     }
    155 }