001    /* Authenticator.java -- Abstract class for obtaining authentication info
002       Copyright (C) 1998, 2000, 2003 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.net;
039    
040    
041    /**
042      * This abstract class provides a model for obtaining authentication
043      * information (in the form of a username and password) required by
044      * some network operations (such as hitting a password protected
045      * web site).
046      * <p>
047      * To make use of this feature, a programmer must create a subclass
048      * that knows how to obtain the necessary info.  An example
049      * would be a class that popped up a dialog box to prompt the user.
050      * After creating an instance of that subclass, the static
051      * <code>setDefault</code> method of this class is called to set up
052      * that instance as the object to use on subsequent calls to obtain
053      * authorization.
054      *
055      * @since 1.2
056      *
057      * @author Aaron M. Renn (arenn@urbanophile.com)
058      * @status Believed to be JDK 1.4 complete
059      */
060    public abstract class Authenticator
061    {
062      /*
063       * Class Variables
064       */
065    
066      /**
067        * This is the default Authenticator object to use for password requests
068        */
069      private static Authenticator defaultAuthenticator;
070    
071      /*
072       * Instance Variables
073       */
074    
075      /**
076        * The hostname of the site requesting authentication
077        */
078      private String host;
079    
080      /**
081        * InternetAddress of the site requesting authentication
082        */
083      private InetAddress addr;
084    
085      /**
086        * The port number of the site requesting authentication
087        */
088      private int port;
089    
090      /**
091        * The protocol name of the site requesting authentication
092        */
093      private String protocol;
094    
095      /**
096        * The prompt to display to the user when requesting authentication info
097        */
098      private String prompt;
099    
100      /**
101        * The authentication scheme in use
102        */
103      private String scheme;
104    
105      /*
106       * Class Methods
107       */
108    
109      /**
110        * This method sets the default <code>Authenticator</code> object (an
111        * instance of a subclass of <code>Authenticator</code>) to use when
112        * prompting the user for
113        * information.  Note that this method checks to see if the caller is
114        * allowed to set this value (the "setDefaultAuthenticator" permission)
115        * and throws a <code>SecurityException</code> if it is not.
116        *
117        * @param defAuth The new default <code>Authenticator</code> object to use
118        *
119        * @exception SecurityException If the caller does not have permission
120        * to perform this operation
121        */
122      public static void setDefault(Authenticator defAuth)
123      {
124        SecurityManager sm = System.getSecurityManager();
125        if (sm != null)
126          sm.checkPermission(new NetPermission("setDefaultAuthenticator"));
127    
128        defaultAuthenticator = defAuth;
129      }
130    
131      /**
132        * This method is called whenever a username and password for a given
133        * network operation is required.  First, a security check is made to see
134        * if the caller has the "requestPasswordAuthentication"
135        * permission.  If not, the method thows an exception.  If there is no
136        * default <code>Authenticator</code> object, the method then returns
137        * <code>null</code>.  Otherwise, the default authenticators's instance
138        * variables are initialized and it's <code>getPasswordAuthentication</code>
139        * method is called to get the actual authentication information to return.
140        *
141        * @param addr The address requesting authentication
142        * @param port The port requesting authentication
143        * @param protocol The protocol requesting authentication
144        * @param prompt The prompt to display to the user when requesting
145        *        authentication info
146        * @param scheme The authentication scheme in use
147        *
148        * @return A <code>PasswordAuthentication</code> object with the user's
149        *         authentication info.
150        *
151        * @exception SecurityException If the caller does not have permission to
152        *         perform this operation
153        */
154      public static PasswordAuthentication requestPasswordAuthentication(InetAddress addr,
155                                                                         int port,
156                                                                         String protocol,
157                                                                         String prompt,
158                                                                         String scheme)
159        throws SecurityException
160      {
161        return requestPasswordAuthentication(null, addr, port, protocol, prompt,
162                                             scheme);
163      }
164    
165      /**
166        * This method is called whenever a username and password for a given
167        * network operation is required.  First, a security check is made to see
168        * if the caller has the "requestPasswordAuthentication"
169        * permission.  If not, the method thows an exception.  If there is no
170        * default <code>Authenticator</code> object, the method then returns
171        * <code>null</code>.  Otherwise, the default authenticators's instance
172        * variables are initialized and it's <code>getPasswordAuthentication</code>
173        * method is called to get the actual authentication information to return.
174        * This method is the preferred one as it can be used with hostname
175        * when addr is unknown.
176        *
177        * @param host The hostname requesting authentication
178        * @param addr The address requesting authentication
179        * @param port The port requesting authentication
180        * @param protocol The protocol requesting authentication
181        * @param prompt The prompt to display to the user when requesting
182        *        authentication info
183        * @param scheme The authentication scheme in use
184        *
185        * @return A <code>PasswordAuthentication</code> object with the user's
186        *         authentication info.
187        *
188        * @exception SecurityException If the caller does not have permission to
189        *         perform this operation
190        *
191        * @since 1.4
192        */
193      public static PasswordAuthentication requestPasswordAuthentication(String host,
194                                                                         InetAddress addr,
195                                                                         int port,
196                                                                         String protocol,
197                                                                         String prompt,
198                                                                         String scheme)
199        throws SecurityException
200      {
201        SecurityManager sm = System.getSecurityManager();
202        if (sm != null)
203          sm.checkPermission(new NetPermission("requestPasswordAuthentication"));
204    
205        if (defaultAuthenticator == null)
206          return null;
207    
208        defaultAuthenticator.host = host;
209        defaultAuthenticator.addr = addr;
210        defaultAuthenticator.port = port;
211        defaultAuthenticator.protocol = protocol;
212        defaultAuthenticator.prompt = prompt;
213        defaultAuthenticator.scheme = scheme;
214    
215        return defaultAuthenticator.getPasswordAuthentication();
216      }
217    
218      /*
219       * Constructors
220       */
221    
222      /**
223        * Default, no-argument constructor for subclasses to call.
224        */
225      public Authenticator()
226      {
227      }
228    
229      /*
230       * Instance Methods
231       */
232    
233      /**
234        * This method returns the address of the site that is requesting
235        * authentication.
236        *
237        * @return The requesting site's address
238        */
239      protected final InetAddress getRequestingSite()
240      {
241        return addr;
242      }
243    
244      /**
245       * Returns the hostname of the host or proxy requesting authorization,
246       * or <code>null</code> if not available.
247       *
248       * @return The name of the host requesting authentication, or
249       * <code>null</code> if it is not available.
250       *
251       * @since 1.4
252       */
253      protected final String getRequestingHost()
254      {
255        return host;
256      }
257    
258      /**
259        * This method returns the port of the site that is requesting
260        * authentication.
261        *
262        * @return The requesting port
263        */
264      protected final int getRequestingPort()
265      {
266        return port;
267      }
268    
269      /**
270        * This method returns the requesting protocol of the operation that is
271        * requesting authentication
272        *
273        * @return The requesting protocol
274        */
275      protected final String getRequestingProtocol()
276      {
277        return protocol;
278      }
279    
280      /**
281        * Returns the prompt that should be used when requesting authentication
282        * information from the user
283        *
284        * @return The user prompt
285        */
286      protected final String getRequestingPrompt()
287      {
288        return prompt;
289      }
290    
291      /**
292        * This method returns the authentication scheme in use
293        *
294        * @return The authentication scheme
295        */
296      protected final String getRequestingScheme()
297      {
298        return scheme;
299      }
300    
301      /**
302        * This method is called whenever a request for authentication is made.  It
303        * can call the other getXXX methods to determine the information relevant
304        * to this request.  Subclasses should override this method, which returns
305        * <code>null</code> by default.
306        *
307        * @return The <code>PasswordAuthentication</code> information
308        */
309      protected PasswordAuthentication getPasswordAuthentication()
310      {
311        return null;
312      }
313    } // class Authenticator