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: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    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 }