View Javadoc

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