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