View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/auth/AuthScope.java $
3    * $Revision: 1425331 $
4    * $Date: 2012-12-22 18:29:41 +0000 (Sat, 22 Dec 2012) $
5    *
6    * ====================================================================
7    *
8    *  Licensed to the Apache Software Foundation (ASF) under one or more
9    *  contributor license agreements.  See the NOTICE file distributed with
10   *  this work for additional information regarding copyright ownership.
11   *  The ASF licenses this file to You under the Apache License, Version 2.0
12   *  (the "License"); you may not use this file except in compliance with
13   *  the License.  You may obtain a copy of the License at
14   *
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   *
17   *  Unless required by applicable law or agreed to in writing, software
18   *  distributed under the License is distributed on an "AS IS" BASIS,
19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   *  See the License for the specific language governing permissions and
21   *  limitations under the License.
22   * ====================================================================
23   *
24   * This software consists of voluntary contributions made by many
25   * individuals on behalf of the Apache Software Foundation.  For more
26   * information on the Apache Software Foundation, please see
27   * <http://www.apache.org/>.
28   *
29   */
30  
31  package org.apache.commons.httpclient.auth;
32  
33  import org.apache.commons.httpclient.util.LangUtils;
34  
35  /*** 
36   * The class represents an authentication scope consisting of a host name,
37   * a port number, a realm name and an authentication scheme name which 
38   * {@link org.apache.commons.httpclient.Credentials} apply to.
39   * 
40   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
41   * @author <a href="mailto:adrian@intencha.com">Adrian Sutton</a>
42   * 
43   * @since 3.0
44   */
45  public class AuthScope {
46      
47      /*** 
48       * The <tt>null</tt> value represents any host. In the future versions of 
49       * HttpClient the use of this parameter will be discontinued.  
50       */
51      public static final String ANY_HOST = null;
52  
53      /*** 
54       * The <tt>-1</tt> value represents any port.  
55       */
56      public static final int ANY_PORT = -1;
57  
58      /*** 
59       * The <tt>null</tt> value represents any realm.  
60       */
61      public static final String ANY_REALM = null;
62  
63      /*** 
64       * The <tt>null</tt> value represents any authentication scheme.  
65       */
66      public static final String ANY_SCHEME = null;
67      
68      /*** 
69       * Default scope matching any host, port, realm and authentication scheme. 
70       * In the future versions of HttpClient the use of this parameter will be 
71       * discontinued.  
72       */
73      public static final AuthScope ANY = new AuthScope(ANY_HOST, ANY_PORT, ANY_REALM, ANY_SCHEME);
74  
75      /*** The authentication scheme the credentials apply to. */
76      private String scheme = null;
77      
78      /*** The realm the credentials apply to. */
79      private String realm = null;
80      
81      /*** The host the credentials apply to. */
82      private String host = null;
83          
84      /*** The port the credentials apply to. */
85      private int port = -1;
86          
87      /*** Creates a new credentials scope for the given 
88       * <tt>host</tt>, <tt>port</tt>, <tt>realm</tt>, and 
89       * <tt>authentication scheme</tt>.
90       * 
91       * @param host the host the credentials apply to. May be set
92       *   to <tt>null</tt> if credenticals are applicable to
93       *   any host. 
94       * @param port the port the credentials apply to. May be set
95       *   to negative value if credenticals are applicable to
96       *   any port. 
97       * @param realm the realm the credentials apply to. May be set 
98       *   to <tt>null</tt> if credenticals are applicable to
99       *   any realm. 
100      * @param scheme the authentication scheme the credentials apply to. 
101      *   May be set to <tt>null</tt> if credenticals are applicable to
102      *   any authentication scheme. 
103      * 
104      * @since 3.0
105      */
106     public AuthScope(final String host, int port, 
107         final String realm, final String scheme)
108     {
109         this.host =   (host == null)   ? ANY_HOST: host.toLowerCase();
110         this.port =   (port < 0)       ? ANY_PORT: port;
111         this.realm =  (realm == null)  ? ANY_REALM: realm;
112         this.scheme = (scheme == null) ? ANY_SCHEME: scheme.toUpperCase();;
113     }
114     
115     /*** Creates a new credentials scope for the given 
116      * <tt>host</tt>, <tt>port</tt>, <tt>realm</tt>, and any
117      * authentication scheme.
118      * 
119      * @param host the host the credentials apply to. May be set
120      *   to <tt>null</tt> if credenticals are applicable to
121      *   any host. 
122      * @param port the port the credentials apply to. May be set
123      *   to negative value if credenticals are applicable to
124      *   any port. 
125      * @param realm the realm the credentials apply to. May be set 
126      *   to <tt>null</tt> if credenticals are applicable to
127      *   any realm. 
128      * 
129      * @since 3.0
130      */
131     public AuthScope(final String host, int port, final String realm) {
132         this(host, port, realm, ANY_SCHEME);
133     }
134     
135     /*** Creates a new credentials scope for the given 
136      * <tt>host</tt>, <tt>port</tt>, any realm name, and any
137      * authentication scheme.
138      * 
139      * @param host the host the credentials apply to. May be set
140      *   to <tt>null</tt> if credenticals are applicable to
141      *   any host. 
142      * @param port the port the credentials apply to. May be set
143      *   to negative value if credenticals are applicable to
144      *   any port. 
145      * 
146      * @since 3.0
147      */
148     public AuthScope(final String host, int port) {
149         this(host, port, ANY_REALM, ANY_SCHEME);
150     }
151     
152     /*** 
153      * Creates a copy of the given credentials scope.
154      * 
155      * @since 3.0
156      */
157     public AuthScope(final AuthScope authscope) {
158         super();
159         if (authscope == null) {
160             throw new IllegalArgumentException("Scope may not be null");
161         }
162         this.host = authscope.getHost();
163         this.port = authscope.getPort();
164         this.realm = authscope.getRealm();
165         this.scheme = authscope.getScheme();
166     }
167     
168     /***
169      * @return the host
170      * 
171      * @since 3.0
172      */
173     public String getHost() {
174         return this.host;
175     }
176 
177     /***
178      * @return the port
179      * 
180      * @since 3.0
181      */
182     public int getPort() {
183         return this.port;
184     }
185 
186     /***
187      * @return the realm name
188      * 
189      * @since 3.0
190      */
191     public String getRealm() {
192         return this.realm;
193     }
194 
195     /***
196      * @return the scheme type
197      * 
198      * @since 3.0
199      */
200     public String getScheme() {
201         return this.scheme;
202     }
203 
204     /*** Determines if the given parameters are equal.
205      * 
206      * @param p1 the parameter
207      * @param p2 the other parameter
208      * @return boolean true if the parameters are equal, otherwise false.
209      */
210     private static boolean paramsEqual(final String p1, final String p2) {
211         if (p1 == null) {
212             return p1 == p2;
213         } else {
214             return p1.equals(p2);
215         }
216     }
217 
218     /*** Determines if the given parameters are equal.  
219      * 
220      * @param p1 the parameter
221      * @param p2 the other parameter
222      * @return boolean true if the parameters are equal, otherwise false.
223      */
224     private static boolean paramsEqual(int p1, int p2) {
225         return p1 == p2;
226     }
227 
228     /***
229      * Tests if the authentication scopes match. 
230      * 
231      * @return the match factor. Negative value signifies no match. 
232      *    Non-negative signifies a match. The greater the returned value 
233      *    the closer the match.
234      * 
235      * @since 3.0
236      */
237     public int match(final AuthScope that) {
238         int factor = 0;
239         if (paramsEqual(this.scheme, that.scheme)) {
240             factor += 1;
241         } else {
242             if (this.scheme != ANY_SCHEME && that.scheme != ANY_SCHEME) {
243                 return -1;
244             }
245         }
246         if (paramsEqual(this.realm, that.realm)) {
247             factor += 2;
248         } else {
249             if (this.realm != ANY_REALM && that.realm != ANY_REALM) {
250                 return -1;
251             }
252         }
253         if (paramsEqual(this.port, that.port)) {
254             factor += 4;
255         } else {
256             if (this.port != ANY_PORT && that.port != ANY_PORT) {
257                 return -1;
258             }
259         }
260         if (paramsEqual(this.host, that.host)) {
261             factor += 8;
262         } else {
263             if (this.host != ANY_HOST && that.host != ANY_HOST) {
264                 return -1;
265             }
266         }
267         return factor;
268     }
269 
270     /***
271      * @see java.lang.Object#equals(Object)
272      */
273     public boolean equals(Object o) {
274         if (o == null) {
275             return false;
276         }
277         if (o == this) {
278             return true;
279         }
280         if (!(o instanceof AuthScope)) {
281             return super.equals(o);
282         }
283         AuthScope that = (AuthScope) o;
284         return 
285         paramsEqual(this.host, that.host) 
286           && paramsEqual(this.port, that.port)
287           && paramsEqual(this.realm, that.realm)
288           && paramsEqual(this.scheme, that.scheme);
289     }
290 
291     /***
292      * @see java.lang.Object#toString()
293      */
294     public String toString() {
295         StringBuffer buffer = new StringBuffer();
296         if (this.scheme != null) {
297             buffer.append(this.scheme.toUpperCase());
298             buffer.append(' ');
299         }
300         if (this.realm != null) {
301             buffer.append('\'');
302             buffer.append(this.realm);
303             buffer.append('\'');
304         } else {
305             buffer.append("<any realm>");
306         }
307         if (this.host != null) {
308             buffer.append('@');
309             buffer.append(this.host);
310             if (this.port >= 0) {
311                 buffer.append(':');
312                 buffer.append(this.port);
313             }
314         }
315         return buffer.toString();
316     }
317     
318     /***
319      * @see java.lang.Object#hashCode()
320      */
321     public int hashCode() {
322         int hash = LangUtils.HASH_SEED;
323         hash = LangUtils.hashCode(hash, this.host);
324         hash = LangUtils.hashCode(hash, this.port);
325         hash = LangUtils.hashCode(hash, this.realm);
326         hash = LangUtils.hashCode(hash, this.scheme);
327         return hash;
328     }
329 }