1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 /*
38 * @(#)Authenticator.java 1.9 07/05/04
39 */
40
41 package javax.mail;
42
43 import java.net.InetAddress;
44
45 /**
46 * The class Authenticator represents an object that knows how to obtain
47 * authentication for a network connection. Usually, it will do this
48 * by prompting the user for information.
49 * <p>
50 * Applications use this class by creating a subclass, and registering
51 * an instance of that subclass with the session when it is created.
52 * When authentication is required, the system will invoke a method
53 * on the subclass (like getPasswordAuthentication). The subclass's
54 * method can query about the authentication being requested with a
55 * number of inherited methods (getRequestingXXX()), and form an
56 * appropriate message for the user.
57 * <p>
58 * All methods that request authentication have a default implementation
59 * that fails.
60 *
61 * @see java.net.Authenticator
62 * @see javax.mail.Session#getInstance(java.util.Properties,
63 * javax.mail.Authenticator)
64 * @see javax.mail.Session#getDefaultInstance(java.util.Properties,
65 * javax.mail.Authenticator)
66 * @see javax.mail.Session#requestPasswordAuthentication
67 * @see javax.mail.PasswordAuthentication
68 *
69 * @author Bill Foote
70 * @author Bill Shannon
71 * @version 1.9, 05/04/07
72 */
73
74 // There are no abstract methods, but to be useful the user must
75 // subclass.
76 public abstract class Authenticator {
77
78 private InetAddress requestingSite;
79 private int requestingPort;
80 private String requestingProtocol;
81 private String requestingPrompt;
82 private String requestingUserName;
83
84 private void reset() {
85 requestingSite = null;
86 requestingPort = -1;
87 requestingProtocol = null;
88 requestingPrompt = null;
89 requestingUserName = null;
90 }
91
92 /**
93 * Ask the authenticator for a password.
94 * <p>
95 *
96 * @param addr The InetAddress of the site requesting authorization,
97 * or null if not known.
98 * @param port the port for the requested connection
99 * @param protocol The protocol that's requesting the connection
100 * (@see java.net.Authenticator.getProtocol())
101 * @param prompt A prompt string for the user
102 *
103 * @return The username/password, or null if one can't be gotten.
104 */
105 final PasswordAuthentication requestPasswordAuthentication(
106 InetAddress addr, int port, String protocol,
107 String prompt, String defaultUserName) {
108
109 reset();
110 requestingSite = addr;
111 requestingPort = port;
112 requestingProtocol = protocol;
113 requestingPrompt = prompt;
114 requestingUserName = defaultUserName;
115 return getPasswordAuthentication();
116 }
117
118 /**
119 * @return the InetAddress of the site requesting authorization, or null
120 * if it's not available.
121 */
122 protected final InetAddress getRequestingSite() {
123 return requestingSite;
124 }
125
126 /**
127 * @return the port for the requested connection
128 */
129 protected final int getRequestingPort() {
130 return requestingPort;
131 }
132
133 /**
134 * Give the protocol that's requesting the connection. Often this
135 * will be based on a URLName.
136 *
137 * @return the protcol
138 *
139 * @see javax.mail.URLName#getProtocol
140 */
141 protected final String getRequestingProtocol() {
142 return requestingProtocol;
143 }
144
145 /**
146 * @return the prompt string given by the requestor
147 */
148 protected final String getRequestingPrompt() {
149 return requestingPrompt;
150 }
151
152 /**
153 * @return the default user name given by the requestor
154 */
155 protected final String getDefaultUserName() {
156 return requestingUserName;
157 }
158
159 /**
160 * Called when password authentication is needed. Subclasses should
161 * override the default implementation, which returns null. <p>
162 *
163 * Note that if this method uses a dialog to prompt the user for this
164 * information, the dialog needs to block until the user supplies the
165 * information. This method can not simply return after showing the
166 * dialog.
167 * @return The PasswordAuthentication collected from the
168 * user, or null if none is provided.
169 */
170 protected PasswordAuthentication getPasswordAuthentication() {
171 return null;
172 }
173 }
Save This Page