libjava/java/net/Authenticator.java

   1 /* Authenticator.java -- Abstract class for obtaining authentication info
   2    Copyright (C) 1998, 2000, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.net;
  39
  40 /**
  41   * This abstract class provides a model for obtaining authentication
  42   * information (in the form of a username and password) required by
  43   * some network operations (such as hitting a password protected
  44   * web site).
  45   * <p>
  46   * To make use of this feature, a programmer must create a subclass
  47   * that knows how to obtain the necessary info.  An example
  48   * would be a class that popped up a dialog box to prompt the user.
  49   * After creating an instance of that subclass, the static
  50   * <code>setDefault</code> method of this class is called to set up
  51   * that instance as the object to use on subsequent calls to obtain
  52   * authorization.
  53   *
  54   * @since 1.2
  55   *
  56   * @author Aaron M. Renn (arenn@urbanophile.com)
  57   * @status Believed to be JDK 1.4 complete
  58   */
  59 public abstract class Authenticator
  60 {
  61   /*
  62    * Class Variables
  63    */
  64
  65   /**
  66     * This is the default Authenticator object to use for password requests
  67     */
  68   private static Authenticator defaultAuthenticator;
  69
  70   /*
  71    * Instance Variables
  72    */
  73
  74   /**
  75     * The hostname of the site requesting authentication
  76     */
  77   private String host;
  78
  79   /**
  80     * InternetAddress of the site requesting authentication
  81     */
  82   private InetAddress addr;
  83
  84   /**
  85     * The port number of the site requesting authentication
  86     */
  87   private int port;
  88
  89   /**
  90     * The protocol name of the site requesting authentication
  91     */
  92   private String protocol;
  93
  94   /**
  95     * The prompt to display to the user when requesting authentication info
  96     */
  97   private String prompt;
  98
  99   /**
 100     * The authentication scheme in use
 101     */
 102   private String scheme;
 103
 104   /*
 105    * Class Methods
 106    */
 107
 108   /**
 109     * This method sets the default <code>Authenticator</code> object (an
 110     * instance of a subclass of <code>Authenticator</code>) to use when
 111     * prompting the user for
 112     * information.  Note that this method checks to see if the caller is
 113     * allowed to set this value (the "setDefaultAuthenticator" permission)
 114     * and throws a <code>SecurityException</code> if it is not.
 115     *
 116     * @param defAuth The new default <code>Authenticator</code> object to use
 117     *
 118     * @exception SecurityException If the caller does not have permission
 119     * to perform this operation
 120     */
 121   public static void setDefault(Authenticator defAuth)
 122   {
 123     SecurityManager sm = System.getSecurityManager();
 124     if (sm != null)
 125       sm.checkPermission(new NetPermission("setDefaultAuthenticator"));
 126
 127     defaultAuthenticator = defAuth;
 128   }
 129
 130   /**
 131     * This method is called whenever a username and password for a given
 132     * network operation is required.  First, a security check is made to see
 133     * if the caller has the "requestPasswordAuthentication"
 134     * permission.  If not, the method thows an exception.  If there is no
 135     * default <code>Authenticator</code> object, the method then returns
 136     * <code>null</code>.  Otherwise, the default authenticators's instance
 137     * variables are initialized and it's <code>getPasswordAuthentication</code>
 138     * method is called to get the actual authentication information to return.
 139     *
 140     * @param addr The address requesting authentication
 141     * @param port The port requesting authentication
 142     * @param protocol The protocol requesting authentication
 143     * @param prompt The prompt to display to the user when requesting
 144     *        authentication info
 145     * @param scheme The authentication scheme in use
 146     *
 147     * @return A <code>PasswordAuthentication</code> object with the user's
 148     *         authentication info.
 149     *
 150     * @exception SecurityException If the caller does not have permission to
 151     *         perform this operation
 152     */
 153   public static PasswordAuthentication
 154     requestPasswordAuthentication(InetAddress addr, int port, String protocol,
 155       String prompt, String scheme)
 156     throws SecurityException
 157   {
 158     return(requestPasswordAuthentication (null, addr, port, protocol,
 159                                         prompt, scheme));
 160   }
 161
 162   /**
 163     * This method is called whenever a username and password for a given
 164     * network operation is required.  First, a security check is made to see
 165     * if the caller has the "requestPasswordAuthentication"
 166     * permission.  If not, the method thows an exception.  If there is no
 167     * default <code>Authenticator</code> object, the method then returns
 168     * <code>null</code>.  Otherwise, the default authenticators's instance
 169     * variables are initialized and it's <code>getPasswordAuthentication</code>
 170     * method is called to get the actual authentication information to return.
 171     * This method is the preferred one as it can be used with hostname
 172     * when addr is unknown.
 173     *
 174     * @param host The hostname requesting authentication
 175     * @param addr The address requesting authentication
 176     * @param port The port requesting authentication
 177     * @param protocol The protocol requesting authentication
 178     * @param prompt The prompt to display to the user when requesting
 179     *        authentication info
 180     * @param scheme The authentication scheme in use
 181     *
 182     * @return A <code>PasswordAuthentication</code> object with the user's
 183     *         authentication info.
 184     *
 185     * @exception SecurityException If the caller does not have permission to
 186     *         perform this operation
 187     *
 188     * @since 1.4
 189     */
 190   public static PasswordAuthentication
 191     requestPasswordAuthentication(String host, InetAddress addr, int port,
 192         String protocol, String prompt, String scheme)
 193     throws SecurityException
 194   {
 195     SecurityManager sm = System.getSecurityManager();
 196     if (sm != null)
 197       sm.checkPermission(new NetPermission("requestPasswordAuthentication"));
 198
 199     if (defaultAuthenticator == null)
 200       return(null);
 201
 202     defaultAuthenticator.host = host;
 203     defaultAuthenticator.addr = addr;
 204     defaultAuthenticator.port = port;
 205     defaultAuthenticator.protocol = protocol;
 206     defaultAuthenticator.prompt = prompt;
 207     defaultAuthenticator.scheme = scheme;
 208
 209     return(defaultAuthenticator.getPasswordAuthentication());
 210   }
 211
 212   /*
 213    * Constructors
 214    */
 215
 216   /**
 217     * Default, no-argument constructor for subclasses to call.
 218     */
 219   public Authenticator()
 220   {
 221   }
 222
 223   /*
 224    * Instance Methods
 225    */
 226
 227   /**
 228     * This method returns the address of the site that is requesting
 229     * authentication.
 230     *
 231     * @return The requesting site's address
 232     */
 233   protected final InetAddress getRequestingSite()
 234   {
 235     return(addr);
 236   }
 237
 238   /**
 239    * Returns the hostname of the host or proxy requesting authorization,
 240    * or <code>null</code> if not available.
 241    *
 242    * @return The name of the host requesting authentication, or
 243    * </code>null</code> if it is not available.
 244    *
 245    * @since 1.4
 246    */
 247   protected final String getRequestingHost()
 248   {
 249     return(host);
 250   }
 251
 252   /**
 253     * This method returns the port of the site that is requesting
 254     * authentication.
 255     *
 256     * @return The requesting port
 257     */
 258   protected final int getRequestingPort()
 259   {
 260     return(port);
 261   }
 262
 263   /**
 264     * This method returns the requesting protocol of the operation that is
 265     * requesting authentication
 266     *
 267     * @return The requesting protocol
 268     */
 269   protected final String getRequestingProtocol()
 270   {
 271     return(protocol);
 272   }
 273
 274   /**
 275     * Returns the prompt that should be used when requesting authentication
 276     * information from the user
 277     *
 278     * @return The user prompt
 279     */
 280   protected final String getRequestingPrompt()
 281   {
 282     return(prompt);
 283   }
 284
 285   /**
 286     * This method returns the authentication scheme in use
 287     *
 288     * @return The authentication scheme
 289     */
 290   protected final String getRequestingScheme()
 291   {
 292     return(scheme);
 293   }
 294
 295   /**
 296     * This method is called whenever a request for authentication is made.  It
 297     * can call the other getXXX methods to determine the information relevant
 298     * to this request.  Subclasses should override this method, which returns
 299     * <code>null</code> by default.
 300     *
 301     * @return The <code>PasswordAuthentication</code> information
 302     */
 303   protected PasswordAuthentication getPasswordAuthentication()
 304   {
 305     return(null);
 306   }
 307
 308 } // class Authenticator
 309