Re: java.net.Authenticator

[Michael Koch <konqueror at gmx dot de>]

> * Please post a ChangeLog entry along with a patch.  Thanks.
>
> * Could you write javadoc for the new methods you added?
>   Since this file already has javadoc, our policy is not to add new
>   methods which don't have documentation.
>
> Otherwise this patch is fine.

yep, will do.

here is the missing documentation.


Michael
Index: ChangeLog
===================================================================
RCS file: /cvs/gcc/gcc/libjava/ChangeLog,v
retrieving revision 1.1415
diff -u -b -r1.1415 ChangeLog
--- ChangeLog	27 Aug 2002 17:47:25 -0000	1.1415
+++ ChangeLog	27 Aug 2002 18:09:06 -0000
@@ -1,5 +1,9 @@
 2002-08-27  Michael Koch <konqueror@gmx.de>
 
+	* java/net/Authenticator.java: added some documentation.
+
+2002-08-27  Michael Koch <konqueror@gmx.de>
+
 	* java/net/BindException.java,
 	java/net/JarURLConnection.java,
 	java/net/FileNameMap.java,
Index: java/net/Authenticator.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/net/Authenticator.java,v
retrieving revision 1.4
diff -u -b -r1.4 Authenticator.java
--- java/net/Authenticator.java	21 Aug 2002 05:34:45 -0000	1.4
+++ java/net/Authenticator.java	27 Aug 2002 18:09:06 -0000
@@ -150,7 +150,7 @@
   * @param port The port requesting authentication
   * @param protocol The protocol requesting authentication
   * @param prompt The prompt to display to the user when requesting 
-           authentication info
+  *        authentication info
   * @param scheme The authentication scheme in use
   * 
   * @return A <code>PasswordAuthentication</code> object with the user's 
@@ -169,6 +169,31 @@
 }
 
 /**
+  * This method is called whenever a username and password for a given
+  * network operation is required.  First, a security check is made to see
+  * if the caller has the "requestPasswordAuthentication"
+  * permission.  If not, the method thows an exception.  If there is no
+  * default <code>Authenticator</code> object, the method then returns
+  * <code>null</code>.  Otherwise, the default authenticators's instance
+  * variables are initialized and it's <code>getPasswordAuthentication</code>
+  * method is called to get the actual authentication information to return.
+  * This method is the preferred one as it can be used with hostname
+  * when addr is unknown.
+  *
+  * @param host The hostname requesting authentication
+  * @param addr The address requesting authentication
+  * @param port The port requesting authentication
+  * @param protocol The protocol requesting authentication
+  * @param prompt The prompt to display to the user when requesting 
+  *        authentication info
+  * @param scheme The authentication scheme in use
+  *
+  * @return A <code>PasswordAuthentication</code> object with the user's 
+  *         authentication info.
+  *
+  * @exception SecurityException If the caller does not have permission to 
+  *         perform this operation
+  *
  * @since 1.4
  */
 public static PasswordAuthentication
@@ -194,6 +219,9 @@
 }
 
 /**
+ *  Returns the hostname of the host or proxy requesting authorization,
+ *  or null if not available.
+ *
  *  @since 1.4
  */
 protected final String getRequestingHost()