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}