001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.client;
029
030import java.util.Map;
031import java.util.Queue;
032
033import org.apache.http.Header;
034import org.apache.http.HttpHost;
035import org.apache.http.HttpResponse;
036import org.apache.http.auth.AuthOption;
037import org.apache.http.auth.AuthScheme;
038import org.apache.http.auth.MalformedChallengeException;
039import org.apache.http.protocol.HttpContext;
040
041/**
042/**
043 * A handler for determining if an HTTP response represents an authentication challenge that was
044 * sent back to the client as a result of authentication failure.
045 * <p>
046 * Implementations of this interface must be thread-safe. Access to shared data must be
047 * synchronized as methods of this interface may be executed from multiple threads.
048 *
049 * @since 4.2
050 */
051public interface AuthenticationStrategy {
052
053    /**
054     * Determines if the given HTTP response response represents
055     * an authentication challenge that was sent back as a result
056     * of authentication failure.
057     *
058     * @param authhost authentication host.
059     * @param response HTTP response.
060     * @param context HTTP context.
061     * @return {@code true} if user authentication is required,
062     *   {@code false} otherwise.
063     */
064    boolean isAuthenticationRequested(
065            HttpHost authhost,
066            HttpResponse response,
067            HttpContext context);
068
069    /**
070     * Extracts from the given HTTP response a collection of authentication
071     * challenges, each of which represents an authentication scheme supported
072     * by the authentication host.
073     *
074     * @param authhost authentication host.
075     * @param response HTTP response.
076     * @param context HTTP context.
077     * @return a collection of challenges keyed by names of corresponding
078     * authentication schemes.
079     * @throws MalformedChallengeException if one of the authentication
080     *  challenges is not valid or malformed.
081     */
082    Map<String, Header> getChallenges(
083            HttpHost authhost,
084            HttpResponse response,
085            HttpContext context) throws MalformedChallengeException;
086
087    /**
088     * Selects one authentication challenge out of all available and
089     * creates and generates {@link AuthOption} instance capable of
090     * processing that challenge.
091     *
092     * @param challenges collection of challenges.
093     * @param authhost authentication host.
094     * @param response HTTP response.
095     * @param context HTTP context.
096     * @return authentication auth schemes that can be used for authentication. Can be empty.
097     * @throws MalformedChallengeException if one of the authentication
098     *  challenges is not valid or malformed.
099     */
100    Queue<AuthOption> select(
101            Map<String, Header> challenges,
102            HttpHost authhost,
103            HttpResponse response,
104            HttpContext context) throws MalformedChallengeException;
105
106    /**
107     * Callback invoked in case of successful authentication.
108     *
109     * @param authhost authentication host.
110     * @param authScheme authentication scheme used.
111     * @param context HTTP context.
112     */
113    void authSucceeded(
114            HttpHost authhost,
115            AuthScheme authScheme,
116            HttpContext context);
117
118    /**
119     * Callback invoked in case of unsuccessful authentication.
120     *
121     * @param authhost authentication host.
122     * @param authScheme authentication scheme used.
123     * @param context HTTP context.
124     */
125    void authFailed(
126            HttpHost authhost,
127            AuthScheme authScheme,
128            HttpContext context);
129
130}