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 18 package 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 */ 31 public 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 */ getPasswordAuthentication()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 */ getRequestingPort()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 */ getRequestingSite()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 */ getRequestingPrompt()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 */ getRequestingProtocol()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 */ getRequestingScheme()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 */ requestPasswordAuthentication( InetAddress rAddr, int rPort, String rProtocol, String rPrompt, String rScheme)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 */ setDefault(Authenticator a)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 */ requestPasswordAuthentication( String rHost, InetAddress rAddr, int rPort, String rProtocol, String rPrompt, String rScheme)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 */ getRequestingHost()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 */ requestPasswordAuthentication( String rHost, InetAddress rAddr, int rPort, String rProtocol, String rPrompt, String rScheme, URL rURL, Authenticator.RequestorType reqType)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 */ getRequestingURL()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 */ getRequestorType()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