1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.net; 19 20/** 21 * An implementation of this class is able to obtain authentication information 22 * for a connection in several ways. For this purpose it has to set the default 23 * authenticator which extends {@code Authenticator} by {@code 24 * setDefault(Authenticator a)}. Then it should override {@code 25 * getPasswordAuthentication()} which dictates how the authentication info is 26 * obtained. Usually, it prompts the user for the required input. 27 * 28 * @see #setDefault 29 * @see #getPasswordAuthentication 30 */ 31public abstract class Authenticator { 32 33 // the default authenticator that needs to be set 34 private static Authenticator thisAuthenticator; 35 36 private String host; 37 private InetAddress addr; 38 private int port; 39 private String protocol; 40 private String prompt; 41 private String scheme; 42 private URL url; 43 private RequestorType rt; 44 45 /** 46 * Returns the collected username and password for authorization. The 47 * subclass has to override this method to return a value different to the 48 * default which is {@code null}. 49 * <p> 50 * Returns {@code null} by default. 51 * 52 * @return collected password authentication data. 53 */ 54 protected PasswordAuthentication getPasswordAuthentication() { 55 return null; 56 } 57 58 /** 59 * Returns the port of the connection that requests authorization. 60 * 61 * @return port of the connection. 62 */ 63 protected final int getRequestingPort() { 64 return this.port; 65 } 66 67 /** 68 * Returns the address of the connection that requests authorization or 69 * {@code null} if unknown. 70 * 71 * @return address of the connection. 72 */ 73 protected final InetAddress getRequestingSite() { 74 return this.addr; 75 } 76 77 /** 78 * Returns the realm (prompt string) of the connection that requests 79 * authorization. 80 * 81 * @return prompt string of the connection. 82 */ 83 protected final String getRequestingPrompt() { 84 return this.prompt; 85 } 86 87 /** 88 * Returns the protocol of the connection that requests authorization. 89 * 90 * @return protocol of the connection. 91 */ 92 protected final String getRequestingProtocol() { 93 return this.protocol; 94 } 95 96 /** 97 * Returns the scheme of the connection that requests authorization, for 98 * example HTTP Basic Authentication. 99 * 100 * @return scheme of the connection. 101 */ 102 protected final String getRequestingScheme() { 103 return this.scheme; 104 } 105 106 /** 107 * Invokes the methods of the registered 108 * authenticator to get the authentication info. 109 * 110 * @return password authentication info or {@code null} if no authenticator 111 * exists. 112 * @param rAddr 113 * address of the connection that requests authentication. 114 * @param rPort 115 * port of the connection that requests authentication. 116 * @param rProtocol 117 * protocol of the connection that requests authentication. 118 * @param rPrompt 119 * realm of the connection that requests authentication. 120 * @param rScheme 121 * scheme of the connection that requests authentication. 122 */ 123 public static synchronized PasswordAuthentication requestPasswordAuthentication( 124 InetAddress rAddr, int rPort, String rProtocol, String rPrompt, 125 String rScheme) { 126 if (thisAuthenticator == null) { 127 return null; 128 } 129 // set the requester info so it knows what it is requesting 130 // authentication for 131 thisAuthenticator.addr = rAddr; 132 thisAuthenticator.port = rPort; 133 thisAuthenticator.protocol = rProtocol; 134 thisAuthenticator.prompt = rPrompt; 135 thisAuthenticator.scheme = rScheme; 136 thisAuthenticator.rt = RequestorType.SERVER; 137 138 // returns the authentication info obtained by the registered 139 // Authenticator 140 return thisAuthenticator.getPasswordAuthentication(); 141 } 142 143 /** 144 * Sets {@code a} as the default authenticator. It will be called whenever 145 * the realm that the URL is pointing to requires authorization. 146 * 147 * @param a 148 * authenticator which has to be set as default. 149 */ 150 public static void setDefault(Authenticator a) { 151 thisAuthenticator = a; 152 } 153 154 /** 155 * Invokes the methods of the registered 156 * authenticator to get the authentication info. 157 * 158 * @return password authentication info or {@code null} if no authenticator 159 * exists. 160 * @param rHost 161 * host name of the connection that requests authentication. 162 * @param rAddr 163 * address of the connection that requests authentication. 164 * @param rPort 165 * port of the connection that requests authentication. 166 * @param rProtocol 167 * protocol of the connection that requests authentication. 168 * @param rPrompt 169 * realm of the connection that requests authentication. 170 * @param rScheme 171 * scheme of the connection that requests authentication. 172 */ 173 public static synchronized PasswordAuthentication requestPasswordAuthentication( 174 String rHost, InetAddress rAddr, int rPort, String rProtocol, 175 String rPrompt, String rScheme) { 176 if (thisAuthenticator == null) { 177 return null; 178 } 179 // set the requester info so it knows what it is requesting 180 // authentication for 181 thisAuthenticator.host = rHost; 182 thisAuthenticator.addr = rAddr; 183 thisAuthenticator.port = rPort; 184 thisAuthenticator.protocol = rProtocol; 185 thisAuthenticator.prompt = rPrompt; 186 thisAuthenticator.scheme = rScheme; 187 thisAuthenticator.rt = RequestorType.SERVER; 188 189 // returns the authentication info obtained by the registered 190 // Authenticator 191 return thisAuthenticator.getPasswordAuthentication(); 192 } 193 194 /** 195 * Returns the host name of the connection that requests authentication or 196 * {@code null} if unknown. 197 * 198 * @return name of the requesting host or {@code null}. 199 */ 200 protected final String getRequestingHost() { 201 return host; 202 } 203 204 /** 205 * Invokes the methods of the registered 206 * authenticator to get the authentication info. 207 * 208 * @return password authentication info or {@code null} if no authenticator 209 * exists. 210 * @param rHost 211 * host name of the connection that requests authentication. 212 * @param rAddr 213 * address of the connection that requests authentication. 214 * @param rPort 215 * port of the connection that requests authentication. 216 * @param rProtocol 217 * protocol of the connection that requests authentication. 218 * @param rPrompt 219 * realm of the connection that requests authentication. 220 * @param rScheme 221 * scheme of the connection that requests authentication. 222 * @param rURL 223 * url of the connection that requests authentication. 224 * @param reqType 225 * requestor type of the connection that requests authentication. 226 */ 227 public static PasswordAuthentication requestPasswordAuthentication( 228 String rHost, InetAddress rAddr, int rPort, String rProtocol, 229 String rPrompt, String rScheme, URL rURL, 230 Authenticator.RequestorType reqType) { 231 if (thisAuthenticator == null) { 232 return null; 233 } 234 // sets the requester info so it knows what it is requesting 235 // authentication for 236 thisAuthenticator.host = rHost; 237 thisAuthenticator.addr = rAddr; 238 thisAuthenticator.port = rPort; 239 thisAuthenticator.protocol = rProtocol; 240 thisAuthenticator.prompt = rPrompt; 241 thisAuthenticator.scheme = rScheme; 242 thisAuthenticator.url = rURL; 243 thisAuthenticator.rt = reqType; 244 245 // returns the authentication info obtained by the registered 246 // Authenticator 247 return thisAuthenticator.getPasswordAuthentication(); 248 249 } 250 251 /** 252 * Returns the URL of the authentication request. 253 * 254 * @return authentication request url. 255 */ 256 protected URL getRequestingURL() { 257 return url; 258 } 259 260 /** 261 * Returns the type of this request, it can be {@code PROXY} or {@code SERVER}. 262 * 263 * @return RequestorType of the authentication request. 264 */ 265 protected Authenticator.RequestorType getRequestorType() { 266 return rt; 267 } 268 269 /** 270 * Enumeration class for the origin of the authentication request. 271 */ 272 public enum RequestorType { 273 274 /** 275 * Type of proxy server 276 */ 277 PROXY, 278 279 /** 280 * Type of origin server 281 */ 282 SERVER 283 } 284} 285