http://jakarta.apache.org/httpcomponents/httpclient-3.x/: The HttpClient component supports the client-side of RFC 1945 (HTTP/1.0) and RFC 2616 (HTTP/1.1) , several related specifications (RFC 2109 (Cookies) , RFC 2617 (HTTP Authentication) , etc.), and provides a framework by which new request types (methods) or HTTP extensions can be created easily. (Apache Software Foundation)
  • Armando Anton
  • Sebastian Bazley
  • Ola Berg
  • Sam Berlin
  • Mike Bowler
  • Samit Jain
  • Eric Johnson
  • Christian Kohlschuetter
  • Ryan Lubke
  • Sam Maloney
  • Rob Di Marco
  • Juergen Pill
  • Mohammad Rezaei
  • Roland Weber
  • Laura Werner
  • Mikael Wilstrom
  • Michael Becke ()
  • Jeff Dever (Independent consultant)
  • dIon Gillard (Multitask Consulting)
  • Ortwin Glueck ()
  • Sung-Gu ()
  • Oleg Kalnichevski
  • Sean C. Sullivan (Independent consultant)
  • Adrian Sutton (Intencha)
  • Rodney Waldhoff (Britannica) 
/*
 * $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 $
 * $Revision: 480424 $
 * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
 *
 * ====================================================================
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.commons.httpclient.auth;

import org.apache.commons.httpclient.Credentials;
import org.apache.commons.httpclient.HttpMethod;



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



Author:Oleg Kalnichevski, Adrian Sutton
Since:2.0beta1
/**
 * <p>
 * This interface represents an abstract challenge-response oriented 
 * authentication scheme.
 * </p>
 * <p>
 * An authentication scheme should be able to support the following
 * functions:
 * <ul>
 *   <li>Parse and process the challenge sent by the targer server
 *       in response to request for a protected resource
 *   <li>Provide its textual designation
 *   <li>Provide its parameters, if available
 *   <li>Provide the realm this authentication scheme is applicable to,
 *       if available
 *   <li>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
 * </ul>
 * </p>
 * <p>
 * Authentication schemes may ignore method name and URI parameters
 * if they are not relevant for the given authentication mechanism
 * </p>
 * <p>
 * Authentication schemes may be stateful involving a series of 
 * challenge-response exchanges
 * </p>
 * 
 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
 * @author <a href="mailto:adrian@ephox.com">Adrian Sutton</a>
 *
 * @since 2.0beta1
 */

public interface AuthScheme {

    
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 

Params:
  • challenge – the challenge string
Since:3.0
/**
     * 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 
     * 
     * @param challenge the challenge string
     * 
     * @since 3.0
     */
    void processChallenge(final String challenge) throws MalformedChallengeException;
    
    
Returns textual designation of the given authentication scheme.

Returns:the name of the given authentication scheme
/**
     * Returns textual designation of the given authentication scheme.
     * 
     * @return the name of the given authentication scheme
     */
    String getSchemeName();

    
Returns authentication parameter with the given name, if available.

Params:
  • name – The name of the parameter to be returned
Returns:the parameter with the given name
/**
     * Returns authentication parameter with the given name, if available.
     * 
     * @param name The name of the parameter to be returned
     * 
     * @return the parameter with the given name
     */
    String getParameter(final String name);

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

Returns:the authentication realm
/**
     * Returns authentication realm. If the concept of an authentication
     * realm is not applicable to the given authentication scheme, returns
     * <code>null</code>.
     * 
     * @return the authentication realm
     */
    String getRealm();
    
    
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.
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.
     * 
     * <p>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.</p>
     * 
     * @return String a String identifying the authentication challenge.  The
     * returned value may be null.
     * 
     * @deprecated no longer used
     */
    String getID();

    
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
/**
     * Tests if the authentication scheme is provides authorization on a per
     * connection basis instead of usual per request basis
     * 
     * @return <tt>true</tt> if the scheme is connection based, <tt>false</tt>
     * if the scheme is request based.
     * 
     * @since 3.0
     */
    boolean isConnectionBased();    
    
    
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
/**
     * 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.
     * 
     * @return <tt>true</tt> if the authentication process has been completed, 
     * <tt>false</tt> otherwise.
     * 
     * @since 3.0
     */
    boolean isComplete();    
    
Params:
  • 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
Throws:
See Also:
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.
Returns:the authorization string
/**
     * @deprecated Use {@link #authenticate(Credentials, HttpMethod)}
     * 
     * Produces an authorization string for the given set of {@link Credentials},
     * method name and URI using the given authentication scheme in response to 
     * the actual authorization challenge.
     * 
     * @param credentials The set of credentials to be used for athentication
     * @param 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
     * @param 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
     * @throws AuthenticationException if authorization string cannot 
     *   be generated due to an authentication failure
     * 
     * @return the authorization string
     * 
     * @see org.apache.commons.httpclient.HttpMethod#getName()
     * @see org.apache.commons.httpclient.HttpMethod#getPath()
     */
    String authenticate(Credentials credentials, String method, String uri) 
      throws AuthenticationException;

    
Produces an authorization string for the given set of Credentials. 
Params:
  • credentials – The set of credentials to be used for athentication
  • method – The method being authenticated
Throws:
Returns:the authorization string
Since:3.0
/**
     * Produces an authorization string for the given set of {@link Credentials}.
     * 
     * @param credentials The set of credentials to be used for athentication
     * @param method The method being authenticated
     * @throws AuthenticationException if authorization string cannot 
     *   be generated due to an authentication failure
     * 
     * @return the authorization string
     * 
     * @since 3.0
     */
    String authenticate(Credentials credentials, HttpMethod method) throws AuthenticationException;
    
}