001/* Authenticator.java -- Abstract class for obtaining authentication info 002 Copyright (C) 1998, 2000, 2003 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038package java.net; 039 040 041/** 042 * This abstract class provides a model for obtaining authentication 043 * information (in the form of a username and password) required by 044 * some network operations (such as hitting a password protected 045 * web site). 046 * <p> 047 * To make use of this feature, a programmer must create a subclass 048 * that knows how to obtain the necessary info. An example 049 * would be a class that popped up a dialog box to prompt the user. 050 * After creating an instance of that subclass, the static 051 * <code>setDefault</code> method of this class is called to set up 052 * that instance as the object to use on subsequent calls to obtain 053 * authorization. 054 * 055 * @since 1.2 056 * 057 * @author Aaron M. Renn (arenn@urbanophile.com) 058 * @status Believed to be JDK 1.4 complete 059 */ 060public abstract class Authenticator 061{ 062 /* 063 * Class Variables 064 */ 065 066 /** 067 * This is the default Authenticator object to use for password requests 068 */ 069 private static Authenticator defaultAuthenticator; 070 071 /* 072 * Instance Variables 073 */ 074 075 /** 076 * The hostname of the site requesting authentication 077 */ 078 private String host; 079 080 /** 081 * InternetAddress of the site requesting authentication 082 */ 083 private InetAddress addr; 084 085 /** 086 * The port number of the site requesting authentication 087 */ 088 private int port; 089 090 /** 091 * The protocol name of the site requesting authentication 092 */ 093 private String protocol; 094 095 /** 096 * The prompt to display to the user when requesting authentication info 097 */ 098 private String prompt; 099 100 /** 101 * The authentication scheme in use 102 */ 103 private String scheme; 104 105 /* 106 * Class Methods 107 */ 108 109 /** 110 * This method sets the default <code>Authenticator</code> object (an 111 * instance of a subclass of <code>Authenticator</code>) to use when 112 * prompting the user for 113 * information. Note that this method checks to see if the caller is 114 * allowed to set this value (the "setDefaultAuthenticator" permission) 115 * and throws a <code>SecurityException</code> if it is not. 116 * 117 * @param defAuth The new default <code>Authenticator</code> object to use 118 * 119 * @exception SecurityException If the caller does not have permission 120 * to perform this operation 121 */ 122 public static void setDefault(Authenticator defAuth) 123 { 124 SecurityManager sm = System.getSecurityManager(); 125 if (sm != null) 126 sm.checkPermission(new NetPermission("setDefaultAuthenticator")); 127 128 defaultAuthenticator = defAuth; 129 } 130 131 /** 132 * This method is called whenever a username and password for a given 133 * network operation is required. First, a security check is made to see 134 * if the caller has the "requestPasswordAuthentication" 135 * permission. If not, the method thows an exception. If there is no 136 * default <code>Authenticator</code> object, the method then returns 137 * <code>null</code>. Otherwise, the default authenticators's instance 138 * variables are initialized and it's <code>getPasswordAuthentication</code> 139 * method is called to get the actual authentication information to return. 140 * 141 * @param addr The address requesting authentication 142 * @param port The port requesting authentication 143 * @param protocol The protocol requesting authentication 144 * @param prompt The prompt to display to the user when requesting 145 * authentication info 146 * @param scheme The authentication scheme in use 147 * 148 * @return A <code>PasswordAuthentication</code> object with the user's 149 * authentication info. 150 * 151 * @exception SecurityException If the caller does not have permission to 152 * perform this operation 153 */ 154 public static PasswordAuthentication requestPasswordAuthentication(InetAddress addr, 155 int port, 156 String protocol, 157 String prompt, 158 String scheme) 159 throws SecurityException 160 { 161 return requestPasswordAuthentication(null, addr, port, protocol, prompt, 162 scheme); 163 } 164 165 /** 166 * This method is called whenever a username and password for a given 167 * network operation is required. First, a security check is made to see 168 * if the caller has the "requestPasswordAuthentication" 169 * permission. If not, the method thows an exception. If there is no 170 * default <code>Authenticator</code> object, the method then returns 171 * <code>null</code>. Otherwise, the default authenticators's instance 172 * variables are initialized and it's <code>getPasswordAuthentication</code> 173 * method is called to get the actual authentication information to return. 174 * This method is the preferred one as it can be used with hostname 175 * when addr is unknown. 176 * 177 * @param host The hostname requesting authentication 178 * @param addr The address requesting authentication 179 * @param port The port requesting authentication 180 * @param protocol The protocol requesting authentication 181 * @param prompt The prompt to display to the user when requesting 182 * authentication info 183 * @param scheme The authentication scheme in use 184 * 185 * @return A <code>PasswordAuthentication</code> object with the user's 186 * authentication info. 187 * 188 * @exception SecurityException If the caller does not have permission to 189 * perform this operation 190 * 191 * @since 1.4 192 */ 193 public static PasswordAuthentication requestPasswordAuthentication(String host, 194 InetAddress addr, 195 int port, 196 String protocol, 197 String prompt, 198 String scheme) 199 throws SecurityException 200 { 201 SecurityManager sm = System.getSecurityManager(); 202 if (sm != null) 203 sm.checkPermission(new NetPermission("requestPasswordAuthentication")); 204 205 if (defaultAuthenticator == null) 206 return null; 207 208 defaultAuthenticator.host = host; 209 defaultAuthenticator.addr = addr; 210 defaultAuthenticator.port = port; 211 defaultAuthenticator.protocol = protocol; 212 defaultAuthenticator.prompt = prompt; 213 defaultAuthenticator.scheme = scheme; 214 215 return defaultAuthenticator.getPasswordAuthentication(); 216 } 217 218 /* 219 * Constructors 220 */ 221 222 /** 223 * Default, no-argument constructor for subclasses to call. 224 */ 225 public Authenticator() 226 { 227 } 228 229 /* 230 * Instance Methods 231 */ 232 233 /** 234 * This method returns the address of the site that is requesting 235 * authentication. 236 * 237 * @return The requesting site's address 238 */ 239 protected final InetAddress getRequestingSite() 240 { 241 return addr; 242 } 243 244 /** 245 * Returns the hostname of the host or proxy requesting authorization, 246 * or <code>null</code> if not available. 247 * 248 * @return The name of the host requesting authentication, or 249 * <code>null</code> if it is not available. 250 * 251 * @since 1.4 252 */ 253 protected final String getRequestingHost() 254 { 255 return host; 256 } 257 258 /** 259 * This method returns the port of the site that is requesting 260 * authentication. 261 * 262 * @return The requesting port 263 */ 264 protected final int getRequestingPort() 265 { 266 return port; 267 } 268 269 /** 270 * This method returns the requesting protocol of the operation that is 271 * requesting authentication 272 * 273 * @return The requesting protocol 274 */ 275 protected final String getRequestingProtocol() 276 { 277 return protocol; 278 } 279 280 /** 281 * Returns the prompt that should be used when requesting authentication 282 * information from the user 283 * 284 * @return The user prompt 285 */ 286 protected final String getRequestingPrompt() 287 { 288 return prompt; 289 } 290 291 /** 292 * This method returns the authentication scheme in use 293 * 294 * @return The authentication scheme 295 */ 296 protected final String getRequestingScheme() 297 { 298 return scheme; 299 } 300 301 /** 302 * This method is called whenever a request for authentication is made. It 303 * can call the other getXXX methods to determine the information relevant 304 * to this request. Subclasses should override this method, which returns 305 * <code>null</code> by default. 306 * 307 * @return The <code>PasswordAuthentication</code> information 308 */ 309 protected PasswordAuthentication getPasswordAuthentication() 310 { 311 return null; 312 } 313} // class Authenticator