View Javadoc

    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/auth/AuthScheme.java,v 1.12 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 org.apache.commons.httpclient.Credentials;
    34  import org.apache.commons.httpclient.HttpMethod;
    35
    36  /**
    37   * <p>
    38   * This interface represents an abstract challenge-response oriented
    39   * authentication scheme.
    40   * </p>
    41   * <p>
    42   * An authentication scheme should be able to support the following
    43   * functions:
    44   * <ul>
    45   *   <li>Parse and process the challenge sent by the targer server
    46   *       in response to request for a protected resource
    47   *   <li>Provide its textual designation
    48   *   <li>Provide its parameters, if available
    49   *   <li>Provide the realm this authentication scheme is applicable to,
    50   *       if available
    51   *   <li>Generate authorization string for the given set of credentials,
    52   *       request method and URI as specificed in the HTTP request line
    53   *       in response to the actual authorization challenge
    54   * </ul>
    55   * </p>
    56   * <p>
    57   * Authentication schemes may ignore method name and URI parameters
    58   * if they are not relevant for the given authentication mechanism
    59   * </p>
    60   * <p>
    61   * Authentication schemes may be stateful involving a series of
    62   * challenge-response exchanges
    63   * </p>
    64   *
    65   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    66   * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
    67   *
    68   * @since 2.0beta1
    69   */
    70
    71  public interface AuthScheme {
    72
    73      /**
    74       * Processes the given challenge token. Some authentication schemes
    75       * may involve multiple challenge-response exchanges. Such schemes must be able
    76       * to maintain the state information when dealing with sequential challenges
    77       *
    78       * @param challenge the challenge string
    79       *
    80       * @since 3.0
    81       */
    82      void processChallenge(final String challenge) throws MalformedChallengeException;
    83
    84      /**
    85       * Returns textual designation of the given authentication scheme.
    86       *
    87       * @return the name of the given authentication scheme
    88       */
    89      String getSchemeName();
    90
    91      /**
    92       * Returns authentication parameter with the given name, if available.
    93       *
    94       * @param name The name of the parameter to be returned
    95       *
    96       * @return the parameter with the given name
    97       */
    98      String getParameter(final String name);
    99
    100     /**
    101      * Returns authentication realm. If the concept of an authentication
    102      * realm is not applicable to the given authentication scheme, returns
    103      * <code>null</code>.
    104      *
    105      * @return the authentication realm
    106      */
    107     String getRealm();
    108
    109     /**
    110      * Returns a String identifying the authentication challenge.  This is
    111      * used, in combination with the host and port to determine if
    112      * authorization has already been attempted or not.  Schemes which
    113      * require multiple requests to complete the authentication should
    114      * return a different value for each stage in the request.
    115      *
    116      * <p>Additionally, the ID should take into account any changes to the
    117      * authentication challenge and return a different value when appropriate.
    118      * For example when the realm changes in basic authentication it should be
    119      * considered a different authentication attempt and a different value should
    120      * be returned.</p>
    121      *
    122      * @return String a String identifying the authentication challenge.  The
    123      * returned value may be null.
    124      *
    125      * @deprecated no longer used
    126      */
    127     String getID();
    128
    129     /**
    130      * Tests if the authentication scheme is provides authorization on a per
    131      * connection basis instead of usual per request basis
    132      *
    133      * @return <tt>true</tt> if the scheme is connection based, <tt>false</tt>
    134      * if the scheme is request based.
    135      *
    136      * @since 3.0
    137      */
    138     boolean isConnectionBased();
    139
    140     /**
    141      * Authentication process may involve a series of challenge-response exchanges.
    142      * This method tests if the authorization process has been completed, either
    143      * successfully or unsuccessfully, that is, all the required authorization
    144      * challenges have been processed in their entirety.
    145      *
    146      * @return <tt>true</tt> if the authentication process has been completed,
    147      * <tt>false</tt> otherwise.
    148      *
    149      * @since 3.0
    150      */
    151     boolean isComplete();
    152     /**
    153      * @deprecated Use {@link #authenticate(Credentials, HttpMethod)}
    154      *
    155      * Produces an authorization string for the given set of {@link Credentials},
    156      * method name and URI using the given authentication scheme in response to
    157      * the actual authorization challenge.
    158      *
    159      * @param credentials The set of credentials to be used for athentication
    160      * @param method The name of the method that requires authorization.
    161      *   This parameter may be ignored, if it is irrelevant
    162      *   or not applicable to the given authentication scheme
    163      * @param uri The URI for which authorization is needed.
    164      *   This parameter may be ignored, if it is irrelevant or not
    165      *   applicable to the given authentication scheme
    166      * @throws AuthenticationException if authorization string cannot
    167      *   be generated due to an authentication failure
    168      *
    169      * @return the authorization string
    170      *
    171      * @see org.apache.commons.httpclient.HttpMethod#getName()
    172      * @see org.apache.commons.httpclient.HttpMethod#getPath()
    173      */
    174     String authenticate(Credentials credentials, String method, String uri)
    175       throws AuthenticationException;
    176
    177     /**
    178      * Produces an authorization string for the given set of {@link Credentials}.
    179      *
    180      * @param credentials The set of credentials to be used for athentication
    181      * @param method The method being authenticated
    182      * @throws AuthenticationException if authorization string cannot
    183      *   be generated due to an authentication failure
    184      *
    185      * @return the authorization string
    186      *
    187      * @since 3.0
    188      */
    189     String authenticate(Credentials credentials, HttpMethod method) throws AuthenticationException;
    190
    191 }