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.hc.client5.http.auth;
28  
29  import java.util.Queue;
30  
31  import org.apache.hc.core5.util.Args;
32  
33  /**
34   * This class represents the actual state of authentication handshake including the current {@link AuthScheme}
35   * used for request authorization as well as a collection of backup authentication options if available.
36   *
37   * @since 4.5
38   */
39  public class AuthExchange {
40  
41      // This only tracks the server state. In particular, even if the state is SUCCESS,
42      // the authentication may still fail if the challenge sent with a response cannot
43      // be validated locally in case of a mutual authentication.
44      public enum State {
45  
46          UNCHALLENGED, CHALLENGED, HANDSHAKE, FAILURE, SUCCESS
47  
48      }
49  
50      private State state;
51      private AuthScheme authScheme;
52      private Queue<AuthScheme> authOptions;
53      private String pathPrefix;
54  
55      public AuthExchange() {
56          super();
57          this.state = State.UNCHALLENGED;
58      }
59  
60      public void reset() {
61          this.state = State.UNCHALLENGED;
62          this.authOptions = null;
63          this.authScheme = null;
64          this.pathPrefix = null;
65      }
66  
67      public State getState() {
68          return this.state;
69      }
70  
71      public void setState(final State state) {
72          this.state = state != null ? state : State.UNCHALLENGED;
73      }
74  
75      /**
76       * Returns actual {@link AuthScheme}. May be null.
77       */
78      public AuthScheme getAuthScheme() {
79          return this.authScheme;
80      }
81  
82      /**
83       * Returns {@code true} if the actual authentication scheme is connection based.
84       */
85      public boolean isConnectionBased() {
86          return this.authScheme != null && this.authScheme.isConnectionBased();
87      }
88  
89      /**
90       * @since 5.2
91       */
92      public String getPathPrefix() {
93          return pathPrefix;
94      }
95  
96      /**
97       * @since 5.2
98       */
99      public void setPathPrefix(final String pathPrefix) {
100         this.pathPrefix = pathPrefix;
101     }
102 
103     /**
104      * Resets the auth state with {@link AuthScheme} and clears auth options.
105      *
106      * @param authScheme auth scheme. May not be null.
107      */
108     public void select(final AuthScheme authScheme) {
109         Args.notNull(authScheme, "Auth scheme");
110         this.authScheme = authScheme;
111         this.authOptions = null;
112     }
113 
114     /**
115      * Returns available auth options. May be null.
116      */
117     public Queue<AuthScheme> getAuthOptions() {
118         return this.authOptions;
119     }
120 
121     /**
122      * Updates the auth state with a queue of auth options.
123      *
124      * @param authOptions a queue of auth options. May not be null or empty.
125      */
126     public void setOptions(final Queue<AuthScheme> authOptions) {
127         Args.notEmpty(authOptions, "Queue of auth options");
128         this.authOptions = authOptions;
129     }
130 
131     @Override
132     public String toString() {
133         final StringBuilder buffer = new StringBuilder();
134         buffer.append("[").append(this.state);
135         if (this.authScheme != null) {
136             buffer.append(" ").append(this.authScheme);
137         }
138         buffer.append("]");
139         return buffer.toString();
140     }
141 
142 }