- /*
- * $Header: /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: 1.12 $
- * $Date: 2004/05/13 04:02:00 $
- *
- * ====================================================================
- *
- * Copyright 2002-2004 The Apache Software Foundation
- *
- * Licensed 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;
-
- /**
- * <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
- *
- * @param challenge the challenge string
- *
- * @since 3.0
- */
- void processChallenge(final String challenge) throws MalformedChallengeException;
-
- /**
- * 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.
- *
- * @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
- * <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.
- *
- * <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
- *
- * @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.
- *
- * @return <tt>true</tt> if the authentication process has been completed,
- * <tt>false</tt> otherwise.
- *
- * @since 3.0
- */
- boolean isComplete();
- /**
- * @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 {@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;
-
- }