2003-05-02 Michael Koch <konqueror@gmx.de>

	* java/net/JarURLConnection.java
	(JarURLConnection): Class documentation merged with classpath.
	(getJarFileURL): Moved and documentation merged with classpath.
	(getEntryName): Likewise.
	(JarURLConnection): Documentation merged with classpath.
	(getJarEntry): Likewise.
	(getJarFile): Likewise.
	* java/net/PlainDatagramSocketImpl.java:
	Class documentation moved.
	* java/net/URLConnection.java
	(fileNameMap): Moved and documentation merged with classpath.
	(factory): Likewise.
	(defaultAllowUserInteraction): Likewis.
	(defaultUseCaches): Likewise.
	(allowUserInteraction): Likewise.
	(connected): Likewise.
	(url): Likewise.
	(connect): Documentation merged with classpath.
	(getURL): Likewise.
	(getContentLength): Likewise.
	(getContentType): Likewise.
	(getContentEncoding): Likewise.
	(getExpiration): Likewise.
	(getDate): Likewise.
	(getLastModified): Likewise.
	(getHeaderField): Likewise.
	(getContent): Likewise.
	(getPermission): Likewise.
	(getInputStream): Likewise.
	(getOutputStream): Likewise.
	(toString): Likewise.
	(getDoInput): Likewise.
	(getDoOutput): Likewise.
	(setAllowUserInteraction): Likewise.
	(getAllowUserInteraction): Likewise.
	(setDefaultAllowUserInteraction): Likewise.
	(getDefaultAllowUserInteraction): Likewise.
	(setUseCaches): Likewise.
	(getUseCaches): Likewise.
	(setIfModifiedSince): Likewise.
	(getIfModifiedSince): Likewise.
	(setDefaultRequestProperty): Likewise.
	(getDefaultRequestProperty): Likewise.
	(setContentHandlerFactory): Likewise.
	(setFileNameMap): Likewise.

From-SVN: r66379

4 files changed, 276 insertions, 69 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 91f92ad..a5c8498 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,5 +1,53 @@
 2003-05-02  Michael Koch  <konqueror@gmx.de>
 
+	* java/net/JarURLConnection.java
+	(JarURLConnection): Class documentation merged with classpath.
+	(getJarFileURL): Moved and documentation merged with classpath.
+	(getEntryName): Likewise.
+	(JarURLConnection): Documentation merged with classpath.
+	(getJarEntry): Likewise.
+	(getJarFile): Likewise.
+	* java/net/PlainDatagramSocketImpl.java:
+	Class documentation moved.
+	* java/net/URLConnection.java
+	(fileNameMap): Moved and documentation merged with classpath.
+	(factory): Likewise.
+	(defaultAllowUserInteraction): Likewis.
+	(defaultUseCaches): Likewise.
+	(allowUserInteraction): Likewise.
+	(connected): Likewise.
+	(url): Likewise.
+	(connect): Documentation merged with classpath.
+	(getURL): Likewise.
+	(getContentLength): Likewise.
+	(getContentType): Likewise.
+	(getContentEncoding): Likewise.
+	(getExpiration): Likewise.
+	(getDate): Likewise.
+	(getLastModified): Likewise.
+	(getHeaderField): Likewise.
+	(getContent): Likewise.
+	(getPermission): Likewise.
+	(getInputStream): Likewise.
+	(getOutputStream): Likewise.
+	(toString): Likewise.
+	(getDoInput): Likewise.
+	(getDoOutput): Likewise.
+	(setAllowUserInteraction): Likewise.
+	(getAllowUserInteraction): Likewise.
+	(setDefaultAllowUserInteraction): Likewise.
+	(getDefaultAllowUserInteraction): Likewise.
+	(setUseCaches): Likewise.
+	(getUseCaches): Likewise.
+	(setIfModifiedSince): Likewise.
+	(getIfModifiedSince): Likewise.
+	(setDefaultRequestProperty): Likewise.
+	(getDefaultRequestProperty): Likewise.
+	(setContentHandlerFactory): Likewise.
+	(setFileNameMap): Likewise.
+
+2003-05-02  Michael Koch  <konqueror@gmx.de>
+
 	* java/net/InetAddress.java:
 	Merged class documentation with classpath.
 	* java/net/JarURLConnection.java:
diff --git a/libjava/java/net/JarURLConnection.java b/libjava/java/net/JarURLConnection.java
index b8fcbf5..a1f1d0d 100644
--- a/libjava/java/net/JarURLConnection.java
+++ b/libjava/java/net/JarURLConnection.java
@@ -54,9 +54,29 @@ import java.util.Hashtable;
 import java.security.cert.Certificate;
 
 /**
+ * This abstract class represents a common superclass for implementations
+ * of jar URL's.  A jar URL is a special type of URL that allows JAR
+ * files on remote systems to be accessed.  It has the form:
+ * <p>
+ * jar:<standard URL pointing to jar file>!/file/within/jarfile
+ * <p> for example:
+ * <p>
+ * jar:http://www.urbanophile.com/java/foo.jar!/com/urbanophile/bar.class
+ * <p>
+ * That example URL points to the file /com/urbanophile/bar.class in the
+ * remote JAR file http://www.urbanophile.com/java/foo.jar.  The HTTP
+ * protocol is used only as an example.  Any supported remote protocol
+ * can be used.
+ * <p>
+ * This class currently works by retrieving the entire jar file into a
+ * local cache file, then performing standard jar operations on it.
+ * (At least this is true for the default protocol implementation).
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Kresten Krab Thorup <krab@gnu.org>
- * @since 1.2
  * @date Aug 10, 1999.
+ *
+ * @since 1.2
  */
 public abstract class JarURLConnection extends URLConnection
 {
@@ -74,18 +94,10 @@ public abstract class JarURLConnection extends URLConnection
   // Cached JarURLConnection's 
   static Hashtable conn_cache = new Hashtable();
 
-  public URL getJarFileURL ()
-  {
-    return jarFileURL;
-  }
-
-  public String getEntryName ()
-  {
-    return element;
-  }
-
   /**
-   * Creates a new JarURLConnection
+   * Creates a JarURLConnection from an URL object
+   *
+   * @param URL url The URL object for this connection.
    *
    * @exception MalformedURLException If url is invalid
    *
@@ -108,6 +120,29 @@ public abstract class JarURLConnection extends URLConnection
     element = (bang+2==spec.length() ? null : spec.substring (bang+2));
   }
 
+  /**
+   * This method returns the "real" URL where the JarFile is located.
+   * //****Is this right?*****
+   *
+   * @return The remote URL
+   */
+  public URL getJarFileURL ()
+  {
+    return jarFileURL;
+  }
+
+  /**
+   * Returns the "entry name" portion of the jar URL.  This is the portion
+   * after the "!/" in the jar URL that represents the pathname inside the
+   * actual jar file.
+   *
+   * @return The entry name.
+   */
+  public String getEntryName ()
+  {
+    return element;
+  }
+
   public synchronized void connect() throws IOException
   {
     // Call is ignored if already connected.
@@ -201,6 +236,8 @@ public abstract class JarURLConnection extends URLConnection
   /**
    * Return the JAR entry object for this connection, if any
    *
+   * @return The jar entry
+   *
    * @exception IOException If an error occurs
    */
   public JarEntry getJarEntry () throws IOException
@@ -250,10 +287,11 @@ public abstract class JarURLConnection extends URLConnection
   /**
    * Return the JAR file for this connection
    *
+   * @return The JarFile object
+   *
    * @exception IOException If an error occurs
    */
-  public abstract JarFile getJarFile() throws IOException;
-
+  public abstract JarFile getJarFile () throws IOException;
 
   // Steal and borrow from protocol/file/Connection.java
 
diff --git a/libjava/java/net/PlainDatagramSocketImpl.java b/libjava/java/net/PlainDatagramSocketImpl.java
index a526aca..69e1788 100644
--- a/libjava/java/net/PlainDatagramSocketImpl.java
+++ b/libjava/java/net/PlainDatagramSocketImpl.java
@@ -37,12 +37,8 @@ exception statement from your version. */
 
 
 package java.net;
-import java.io.IOException;
 
-/**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date May 3, 1999.
- */
+import java.io.IOException;
 
 /**
  * Written using on-line Java Platform 1.2 API Specification, as well
@@ -50,6 +46,10 @@ import java.io.IOException;
  * Status:  Believed complete and correct.
  */
 
+/**
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @date May 3, 1999.
+ */
 class PlainDatagramSocketImpl extends DatagramSocketImpl
 {
   // These fields are mirrored for use in native code to avoid cpp conflicts
diff --git a/libjava/java/net/URLConnection.java b/libjava/java/net/URLConnection.java
index 9820430..f7e8690 100644
--- a/libjava/java/net/URLConnection.java
+++ b/libjava/java/net/URLConnection.java
@@ -92,22 +92,43 @@ import gnu.gcj.io.MimeTypes;
  */
 public abstract class URLConnection
 {
+  /**
+   * This is an object that maps filenames to MIME types.  The interface
+   * to do this is implemented by this class, so just create an empty
+   * instance and store it here.
+   */
+  private static FileNameMap fileNameMap;
+ 
+  /**
+   * This is the ContentHandlerFactory set by the caller, if any
+   */
+  private static ContentHandlerFactory factory;
+  
+  /**
+   * This is the default value that will be used to determine whether or
+   * not user interaction should be allowed.
+   */
   private static boolean defaultAllowUserInteraction = false;
+  
+  /**
+   * This is the default flag indicating whether or not to use caches to
+   * store the data returned from a server
+   */
   private static boolean defaultUseCaches = true;
-  private static FileNameMap fileNameMap;  // Set by the URLConnection subclass.
-  private static ContentHandlerFactory factory;
-  private static ContentHandler contentHandler;
-  private static Hashtable handlers = new Hashtable();
-  private static Locale locale; 
-  private static SimpleDateFormat dateFormat1, dateFormat2, dateFormat3;
-  private static boolean dateformats_initialized = false;
 
   /**
-   * This is the URL associated with this connection
+   * This variable determines whether or not interaction is allowed with
+   * the user.  For example, to prompt for a username and password.
    */
-  protected URL url;
+  protected boolean allowUserInteraction;
 
   /**
+   * Indicates whether or not a connection has been established to the
+   * destination specified in the URL
+   */
+  protected boolean connected = false;
+  
+  /**
    * Indicates whether or not input can be read from this URL
    */
   protected boolean doInput = true;
@@ -117,8 +138,6 @@ public abstract class URLConnection
    */
   protected boolean doOutput = false;
   
-  protected boolean allowUserInteraction;
-
   /**
    * If this flag is set, the protocol is allowed to cache data whenever
    * it can (caching is not guaranteed). If it is not set, the protocol
@@ -141,11 +160,16 @@ public abstract class URLConnection
   protected long ifModifiedSince = 0L;
 
   /**
-   * Indicates whether or not a connection has been established to the
-   * destination specified in the URL
+   * This is the URL associated with this connection
    */
-  protected boolean connected = false;
-  
+  protected URL url;
+
+  private static ContentHandler contentHandler;
+  private static Hashtable handlers = new Hashtable();
+  private static Locale locale; 
+  private static SimpleDateFormat dateFormat1, dateFormat2, dateFormat3;
+  private static boolean dateformats_initialized = false;
+
   /**
    * Creates a URL connection to a given URL. A real connection is not made.
    * Use #connect to do this.
@@ -162,15 +186,15 @@ public abstract class URLConnection
   }
 
   /**
-   * Creates a real connection to the object references by the URL given
-   * to the constructor
-   *
-   * @exception IOException If an error occurs
+   * Establishes the actual connection to the URL associated with this
+   * connection object
    */
   public abstract void connect() throws IOException;
 
   /**
-   * Returns ths URL to the object.
+   * Returns the URL object associated with this connection
+   *
+   * @return The URL for this connection.
    */
   public URL getURL()
   {
@@ -178,7 +202,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the content-length header field
+   * Returns the value of the content-length header field or -1 if the value
+   * is not known or not present.
+   *
+   * @return The content-length field
    */
   public int getContentLength()
   {
@@ -186,7 +213,14 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the content-type header field
+   * Returns the the content-type of the data pointed to by the URL.  This
+   * method first tries looking for a content-type header.  If that is not
+   * present, it attempts to use the file name to determine the content's
+   * MIME type.  If that is unsuccessful, the method returns null.  The caller
+   * may then still attempt to determine the MIME type by a call to
+   * guessContentTypeFromStream()
+   *
+   * @return The content MIME type
    */
   public String getContentType()
   {
@@ -194,7 +228,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the content-encoding header field
+   * Returns the value of the content-encoding field or null if it is not
+   * known or not present.
+   * 
+   * @return The content-encoding field
    */
   public String getContentEncoding()
   {
@@ -202,7 +239,11 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the expires header field
+   * Returns the value of the expires header or 0 if not known or present.
+   * If populated, the return value is number of seconds since midnight
+   * on 1/1/1970 GMT.
+   *
+   * @return The expiration time.
    */
   public long getExpiration()
   {
@@ -210,7 +251,12 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the date header field
+   * Returns the date of the document pointed to by the URL as reported in
+   * the date field of the header or 0 if the value is not present or not
+   * known. If populated, the return value is number of seconds since
+   * midnight on 1/1/1970 GMT.
+   *
+   * @return The document date
    */
   public long getDate()
   {
@@ -218,7 +264,11 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the last-modified header field
+   * Returns the value of the last-modified header field or 0 if not known known
+   * or not present.  If populated, the return value is the number of seconds
+   * since midnight on 1/1/1970.
+   *
+   * @return The last modified time
    */
   public long getLastModified()
   {
@@ -237,7 +287,8 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of the header filed specified by name
+   * Returns a String representing the value of the header field having
+   * the named key.  Returns null if the header field does not exist.
    *
    * @param name The name of the header field
    */
@@ -311,7 +362,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the key of the n-th header field
+   * Returns a String representing the header key at the specified index.
+   * This allows the caller to walk the list of header fields.  The analogous
+   * getHeaderField(int) method allows access to the corresponding value for
+   * this tag.
    *
    * @param num The number of the header field
    */
@@ -322,7 +376,19 @@ public abstract class URLConnection
   }
 
   /**
-   * Retrieves the content of this URLConnection
+   * This method returns the content of the document pointed to by the URL
+   * as an Object.  The type of object depends on the MIME type of the
+   * object and particular content hander loaded.  Most text type content
+   * handlers will return a subclass of InputStream.  Images usually return
+   * a class that implements ImageProducer.  There is not guarantee what
+   * type of object will be returned, however.
+   * <p>
+   * This class first determines the MIME type of the content, then creates
+   * a ContentHandler object to process the input.  If the ContentHandlerFactory
+   * is set, then that object is called to load a content handler, otherwise
+   * a class called gnu.java.net.content.<content_type> is tried.
+   * The default class will also be used if the content handler factory returns
+   * a null content handler.
    *
    * @exception IOException If an error occurs
    * @exception UnknownServiceException If the protocol does not support the
@@ -356,9 +422,15 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns a permission object representing the permission necessary to make
-   * the connection represented by this object. This method returns null if no
-   * permission is required to make the connection.
+   * This method returns a <code>Permission</code> object representing the
+   * permissions required to access this URL.  This method returns
+   * <code>java.security.AllPermission</code> by default.  Subclasses should
+   * override it to return a more specific permission.  For example, an
+   * HTTP URL should return an instance of <code>SocketPermission</code>
+   * for the appropriate host and port.
+   * <p>
+   * Note that because of items such as HTTP redirects, the permission
+   * object returned might be different before and after connecting.
    *
    * @exception IOException If the computation of the permission requires
    * network or file I/O and an exception occurs while computing it
@@ -370,7 +442,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the input stream of the URL connection
+   * Returns an InputStream for this connection.  As this default
+   * implementation returns null, subclasses should override this method
+   *
+   * @return An InputStream for this connection
    *
    * @exception IOException If an error occurs
    * @exception UnknownServiceException If the protocol does not support input
@@ -383,7 +458,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the output stream of the URL connection
+   * Returns an OutputStream for this connection.  As this default
+   * implementation returns null, subclasses should override this method
+   *
+   * @return An OutputStream for this connection
    *
    * @exception IOException If an error occurs
    * @exception UnknownServiceException If the protocol does not support output
@@ -396,7 +474,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns a string representation of the URL connection object
+   * The methods prints the value of this object as a String by calling the
+   * toString() method of its associated URL.  Overrides Object.toString()
+   * 
+   * @return A String representation of this object
    */
   public String toString()
   {
@@ -419,7 +500,11 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the current value of the doInput field
+   * Returns the value of a flag indicating whether or not input is going
+   * to be done for this connection.  This default to true unless the
+   * doOutput flag is set to false, in which case this defaults to false.
+   *
+   * @return true if input is to be done, false otherwise
    */
   public boolean getDoInput()
   {
@@ -442,7 +527,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the current value of the doOutput field
+   * Returns a boolean flag indicating whether or not output will be done
+   * on this connection.  This defaults to false.
+   *
+   * @return true if output is to be done, false otherwise
    */
   public boolean getDoOutput()
   {
@@ -450,7 +538,9 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets a new value to the allowUserInteraction field
+   * Sets a boolean flag indicating whether or not user interaction is
+   * allowed for this connection.  (For example, in order to prompt for
+   * username and password info.
    *
    * @param allowed The new value
    *
@@ -465,7 +555,11 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the current value of the allowUserInteraction field
+   * Returns a boolean flag indicating whether or not user interaction is
+   * allowed for this connection.  (For example, in order to prompt for
+   * username and password info.
+   *
+   * @return true if user interaction is allowed, false otherwise
    */
   public boolean getAllowUserInteraction()
   {
@@ -473,7 +567,8 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets the default value if the allowUserInteraction field
+   * Sets the default flag for whether or not interaction with a user
+   * is allowed.  This will be used for all connections unless overridden
    *
    * @param allowed The new default value
    */
@@ -483,7 +578,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the default value of the allowUserInteraction field
+   * Returns the default flag for whether or not interaction with a user
+   * is allowed.  This will be used for all connections unless overridden
+   *
+   * @return true if user interaction is allowed, false otherwise
    */
   public static boolean getDefaultAllowUserInteraction()
   {
@@ -491,7 +589,8 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets a new value to the useCaches field
+   * Sets a boolean flag indicating whether or not caching will be used
+   * (if possible) to store data downloaded via the connection.
    *
    * @param usecaches The new value
    *
@@ -506,7 +605,10 @@ public abstract class URLConnection
   }
 
   /**
-   * The current value of the useCaches field
+   * Returns a boolean flag indicating whether or not caching will be used
+   * (if possible) to store data downloaded via the connection.
+   *
+   * @return true if caching should be used if possible, false otherwise
    */
   public boolean getUseCaches()
   {
@@ -514,7 +616,11 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets the value of the ifModifiedSince field
+   * Sets the ifModified since instance variable.  If this value is non
+   * zero and the underlying protocol supports it, the actual document will
+   * not be fetched unless it has been modified since this time.  The value
+   * passed should  be 0 if this feature is to be disabled or the time expressed
+   * as the number of seconds since midnight 1/1/1970 GMT otherwise.
    *
    * @param ifmodifiedsince The new value in milliseconds
    * since January 1, 1970 GMT
@@ -530,7 +636,13 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the current value of the ifModifiedSince field
+   * Returns the ifModified since instance variable.  If this value is non
+   * zero and the underlying protocol supports it, the actual document will
+   * not be fetched unless it has been modified since this time.  The value
+   * returned will be 0 if this feature is disabled or the time expressed
+   * as the number of seconds since midnight 1/1/1970 GMT otherwise
+   *
+   * @return The ifModifiedSince value
    */
   public long getIfModifiedSince()
   {
@@ -546,7 +658,8 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets the default value of the useCaches field
+   * Sets the default value used to determine whether or not caching
+   * of documents will be done when possible.
    *
    * @param defaultusecaches The new default value
    */
@@ -639,7 +752,9 @@ public abstract class URLConnection
   }
 
   /**
-   * Defines a default request property
+   * Sets the default value of a request property.  This will be used
+   * for all connections unless the value of the property is manually
+   * overridden.
    *
    * @param key The key of the property
    * @param value The value of the property
@@ -655,7 +770,9 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns the value of a default request property
+   * Returns the default value of a request property.  This will be used
+   * for all connections unless the value of the property is manually
+   * overridden.
    *
    * @param key The key of the default property
    *
@@ -672,7 +789,10 @@ public abstract class URLConnection
   }
 
   /**
-   * Sets a ContentHandlerFactory
+   * Set's the ContentHandlerFactory for an application.  This can be called
+   * once and only once.  If it is called again, then an Error is thrown.
+   * Unlike for other set factory methods, this one does not do a security
+   * check prior to setting the factory.
    *
    * @param fac The ContentHandlerFactory
    *
@@ -739,7 +859,8 @@ public abstract class URLConnection
   }
 
   /**
-   * Returns a filename map (a mimetable)
+   * This method returns the <code>FileNameMap</code> object being used
+   * to decode MIME types by file extension.
    *
    * @since 1.2
    */