View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  package org.apache.http.auth;
28  
29  import java.util.Queue;
30  
31  import org.apache.http.annotation.NotThreadSafe;
32  import org.apache.http.util.Args;
33  
34  /**
35   * This class provides detailed information about the state of the authentication process.
36   *
37   * @since 4.0
38   */
39  @NotThreadSafe
40  public class AuthState {
41  
42      /** Actual state of authentication protocol */
43      private AuthProtocolState state;
44  
45      /** Actual authentication scheme */
46      private AuthScheme authScheme;
47  
48      /** Actual authentication scope */
49      private AuthScope authScope;
50  
51      /** Credentials selected for authentication */
52      private Credentials credentials;
53  
54      /** Available auth options */
55      private Queue<AuthOption> authOptions;
56  
57      public AuthState() {
58          super();
59          this.state = AuthProtocolState.UNCHALLENGED;
60      }
61  
62      /**
63       * Resets the auth state.
64       *
65       * @since 4.2
66       */
67      public void reset() {
68          this.state = AuthProtocolState.UNCHALLENGED;
69          this.authOptions = null;
70          this.authScheme = null;
71          this.authScope = null;
72          this.credentials = null;
73      }
74  
75      /**
76       * @since 4.2
77       */
78      public AuthProtocolState getState() {
79          return this.state;
80      }
81  
82      /**
83       * @since 4.2
84       */
85      public void setState(final AuthProtocolState state) {
86          this.state = state != null ? state : AuthProtocolState.UNCHALLENGED;
87      }
88  
89      /**
90       * Returns actual {@link AuthScheme}. May be null.
91       */
92      public AuthScheme getAuthScheme() {
93          return this.authScheme;
94      }
95  
96      /**
97       * Returns actual {@link Credentials}. May be null.
98       */
99      public Credentials getCredentials() {
100         return this.credentials;
101     }
102 
103     /**
104      * Updates the auth state with {@link AuthScheme} and {@link Credentials}.
105      *
106      * @param authScheme auth scheme. May not be null.
107      * @param credentials user crednetials. May not be null.
108      *
109      * @since 4.2
110      */
111     public void update(final AuthScheme authScheme, final Credentials credentials) {
112         Args.notNull(authScheme, "Auth scheme");
113         Args.notNull(credentials, "Credentials");
114         this.authScheme = authScheme;
115         this.credentials = credentials;
116         this.authOptions = null;
117     }
118 
119     /**
120      * Returns available {@link AuthOption}s. May be null.
121      *
122      * @since 4.2
123      */
124     public Queue<AuthOption> getAuthOptions() {
125         return this.authOptions;
126     }
127 
128     /**
129      * Returns {@code true} if {@link AuthOption}s are available, {@code false}
130      * otherwise.
131      *
132      * @since 4.2
133      */
134     public boolean hasAuthOptions() {
135         return this.authOptions != null && !this.authOptions.isEmpty();
136     }
137 
138     /**
139      * Updates the auth state with a queue of {@link AuthOption}s.
140      *
141      * @param authOptions a queue of auth options. May not be null or empty.
142      *
143      * @since 4.2
144      */
145     public void update(final Queue<AuthOption> authOptions) {
146         Args.notEmpty(authOptions, "Queue of auth options");
147         this.authOptions = authOptions;
148         this.authScheme = null;
149         this.credentials = null;
150     }
151 
152     /**
153      * Invalidates the authentication state by resetting its parameters.
154      *
155      * @deprecated (4.2)  use {@link #reset()}
156      */
157     @Deprecated
158     public void invalidate() {
159         reset();
160     }
161 
162     /**
163      * @deprecated (4.2) do not use
164      */
165     @Deprecated
166     public boolean isValid() {
167         return this.authScheme != null;
168     }
169 
170     /**
171      * Assigns the given {@link AuthScheme authentication scheme}.
172      *
173      * @param authScheme the {@link AuthScheme authentication scheme}
174      *
175      * @deprecated (4.2)  use {@link #update(AuthScheme, Credentials)}
176      */
177     @Deprecated
178     public void setAuthScheme(final AuthScheme authScheme) {
179         if (authScheme == null) {
180             reset();
181             return;
182         }
183         this.authScheme = authScheme;
184     }
185 
186     /**
187      * Sets user {@link Credentials} to be used for authentication
188      *
189      * @param credentials User credentials
190      *
191      * @deprecated (4.2)  use {@link #update(AuthScheme, Credentials)}
192      */
193     @Deprecated
194     public void setCredentials(final Credentials credentials) {
195         this.credentials = credentials;
196     }
197 
198     /**
199      * Returns actual {@link AuthScope} if available
200      *
201      * @return actual authentication scope if available, {@code null} otherwise
202      *
203      * @deprecated (4.2)  do not use.
204      */
205     @Deprecated
206     public AuthScope getAuthScope() {
207         return this.authScope;
208     }
209 
210     /**
211      * Sets actual {@link AuthScope}.
212      *
213      * @param authScope Authentication scope
214      *
215      * @deprecated (4.2)  do not use.
216      */
217     @Deprecated
218     public void setAuthScope(final AuthScope authScope) {
219         this.authScope = authScope;
220     }
221 
222     @Override
223     public String toString() {
224         final StringBuilder buffer = new StringBuilder();
225         buffer.append("state:").append(this.state).append(";");
226         if (this.authScheme != null) {
227             buffer.append("auth scheme:").append(this.authScheme.getSchemeName()).append(";");
228         }
229         if (this.credentials != null) {
230             buffer.append("credentials present");
231         }
232         return buffer.toString();
233     }
234 
235 }