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 */ 027package org.apache.http.auth; 028 029import java.util.Queue; 030 031import org.apache.http.util.Args; 032 033/** 034 * This class provides detailed information about the state of the authentication process. 035 * 036 * @since 4.0 037 */ 038public class AuthState { 039 040 /** Actual state of authentication protocol */ 041 private AuthProtocolState state; 042 043 /** Actual authentication scheme */ 044 private AuthScheme authScheme; 045 046 /** Actual authentication scope */ 047 private AuthScope authScope; 048 049 /** Credentials selected for authentication */ 050 private Credentials credentials; 051 052 /** Available auth options */ 053 private Queue<AuthOption> authOptions; 054 055 public AuthState() { 056 super(); 057 this.state = AuthProtocolState.UNCHALLENGED; 058 } 059 060 /** 061 * Resets the auth state. 062 * 063 * @since 4.2 064 */ 065 public void reset() { 066 this.state = AuthProtocolState.UNCHALLENGED; 067 this.authOptions = null; 068 this.authScheme = null; 069 this.authScope = null; 070 this.credentials = null; 071 } 072 073 /** 074 * @since 4.2 075 */ 076 public AuthProtocolState getState() { 077 return this.state; 078 } 079 080 /** 081 * @since 4.2 082 */ 083 public void setState(final AuthProtocolState state) { 084 this.state = state != null ? state : AuthProtocolState.UNCHALLENGED; 085 } 086 087 /** 088 * Returns actual {@link AuthScheme}. May be null. 089 */ 090 public AuthScheme getAuthScheme() { 091 return this.authScheme; 092 } 093 094 /** 095 * Returns actual {@link Credentials}. May be null. 096 */ 097 public Credentials getCredentials() { 098 return this.credentials; 099 } 100 101 /** 102 * Updates the auth state with {@link AuthScheme} and {@link Credentials}. 103 * 104 * @param authScheme auth scheme. May not be null. 105 * @param credentials user crednetials. May not be null. 106 * 107 * @since 4.2 108 */ 109 public void update(final AuthScheme authScheme, final Credentials credentials) { 110 Args.notNull(authScheme, "Auth scheme"); 111 Args.notNull(credentials, "Credentials"); 112 this.authScheme = authScheme; 113 this.credentials = credentials; 114 this.authOptions = null; 115 } 116 117 /** 118 * Returns available {@link AuthOption}s. May be null. 119 * 120 * @since 4.2 121 */ 122 public Queue<AuthOption> getAuthOptions() { 123 return this.authOptions; 124 } 125 126 /** 127 * Returns {@code true} if {@link AuthOption}s are available, {@code false} 128 * otherwise. 129 * 130 * @since 4.2 131 */ 132 public boolean hasAuthOptions() { 133 return this.authOptions != null && !this.authOptions.isEmpty(); 134 } 135 136 /** 137 * Updates the auth state with a queue of {@link AuthOption}s. 138 * 139 * @param authOptions a queue of auth options. May not be null or empty. 140 * 141 * @since 4.2 142 */ 143 public void update(final Queue<AuthOption> authOptions) { 144 Args.notEmpty(authOptions, "Queue of auth options"); 145 this.authOptions = authOptions; 146 this.authScheme = null; 147 this.credentials = null; 148 } 149 150 /** 151 * Invalidates the authentication state by resetting its parameters. 152 * 153 * @deprecated (4.2) use {@link #reset()} 154 */ 155 @Deprecated 156 public void invalidate() { 157 reset(); 158 } 159 160 /** 161 * @deprecated (4.2) do not use 162 */ 163 @Deprecated 164 public boolean isValid() { 165 return this.authScheme != null; 166 } 167 168 /** 169 * Assigns the given {@link AuthScheme authentication scheme}. 170 * 171 * @param authScheme the {@link AuthScheme authentication scheme} 172 * 173 * @deprecated (4.2) use {@link #update(AuthScheme, Credentials)} 174 */ 175 @Deprecated 176 public void setAuthScheme(final AuthScheme authScheme) { 177 if (authScheme == null) { 178 reset(); 179 return; 180 } 181 this.authScheme = authScheme; 182 } 183 184 /** 185 * Sets user {@link Credentials} to be used for authentication 186 * 187 * @param credentials User credentials 188 * 189 * @deprecated (4.2) use {@link #update(AuthScheme, Credentials)} 190 */ 191 @Deprecated 192 public void setCredentials(final Credentials credentials) { 193 this.credentials = credentials; 194 } 195 196 /** 197 * Returns actual {@link AuthScope} if available 198 * 199 * @return actual authentication scope if available, {@code null} otherwise 200 * 201 * @deprecated (4.2) do not use. 202 */ 203 @Deprecated 204 public AuthScope getAuthScope() { 205 return this.authScope; 206 } 207 208 /** 209 * Sets actual {@link AuthScope}. 210 * 211 * @param authScope Authentication scope 212 * 213 * @deprecated (4.2) do not use. 214 */ 215 @Deprecated 216 public void setAuthScope(final AuthScope authScope) { 217 this.authScope = authScope; 218 } 219 220 @Override 221 public String toString() { 222 final StringBuilder buffer = new StringBuilder(); 223 buffer.append("state:").append(this.state).append(";"); 224 if (this.authScheme != null) { 225 buffer.append("auth scheme:").append(this.authScheme.getSchemeName()).append(";"); 226 } 227 if (this.credentials != null) { 228 buffer.append("credentials present"); 229 } 230 return buffer.toString(); 231 } 232 233}