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}