KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > mail > Authenticator


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