URLConnection.java: Import classes directly.

2003-04-06  Michael Koch  <konqueror@gmx.de>

	* java/net/URLConnection.java:
	Import classes directly.
	(URLConnection): Merged class documentation with classpath.
	(url): Moved, documentation from classpath added.
	(doInput): Moved, documentation from classpath added.
	(doOutput): Moved, documentation from classpath added.
	(allowUserInteraction): Moved.
	(useCaches): Moved, documentation from classpath added.
	(ifModifiedSince): Moved, documentation from classpath added.
	(connected): Moved, documentation from classpath added.

From-SVN: r65301

libjava/ChangeLog

@@ -1,3 +1,16 @@
+2003-04-06  Michael Koch  <konqueror@gmx.de>
+
+	* java/net/URLConnection.java:
+	Import classes directly.
+	(URLConnection): Merged class documentation with classpath.
+	(url): Moved, documentation from classpath added.
+	(doInput): Moved, documentation from classpath added.
+	(doOutput): Moved, documentation from classpath added.
+	(allowUserInteraction): Moved.
+	(useCaches): Moved, documentation from classpath added.
+	(ifModifiedSince): Moved, documentation from classpath added.
+	(connected): Moved, documentation from classpath added.
+
 2003-04-06  Michael Koch  <konqueror@gmx.de>
 
 	* java/io/FileInputStream.java

libjava/java/net/URLConnection.java

@@ -38,7 +38,11 @@ exception statement from your version. */
 
 package java.net;
 
-import java.io.*;
+import java.io.InputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.security.Permission;
+import java.security.AllPermission;
 import java.text.ParsePosition;
 import java.text.SimpleDateFormat;
 import java.util.Date;
@@ -46,15 +50,8 @@ import java.util.Locale;
 import java.util.Hashtable;
 import java.util.Map;
 import java.util.StringTokenizer;
-import java.security.Permission;
-import java.security.AllPermission;
 import gnu.gcj.io.MimeTypes;
 
-/**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date March 5, 1999.
- */
-
 /**
  * Written using on-line Java Platform 1.2 API Specification, as well
  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
@@ -62,15 +59,39 @@ import gnu.gcj.io.MimeTypes;
  *    getContent method assumes content type from response; see comment there.
  */
 
+/**
+ * This class models a connection that retrieves the information pointed
+ * to by a URL object.  This is typically a connection to a remote node
+ * on the network, but could be a simple disk read.
+ * <p>
+ * A URLConnection object is normally created by calling the openConnection()
+ * method of a URL object.  This method is somewhat misnamed because it does
+ * not actually open the connection.  Instead, it return an unconnected
+ * instance of this object.  The caller then has the opportunity to set
+ * various connection options prior to calling the actual connect() method.
+ * <p>
+ * After the connection has been opened, there are a number of methods in
+ * this class that access various attributes of the data, typically
+ * represented by headers sent in advance of the actual data itself.
+ * <p>
+ * Also of note are the getInputStream and getContent() methods which allow
+ * the caller to retrieve the actual data from the connection.  Note that
+ * for some types of connections, writing is also allowed.  The setDoOutput()
+ * method must be called prior to connecing in order to enable this, then
+ * the getOutputStream method called after the connection in order to
+ * obtain a stream to write the output to.
+ * <p>
+ * The getContent() method is of particular note.  This method returns an
+ * Object that encapsulates the data returned.  There is no way do determine
+ * the type of object that will be returned in advance.  This is determined
+ * by the actual content handlers as described in the description of that
+ * method.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ */
 public abstract class URLConnection
 {
-  protected URL url;
-  protected boolean doInput = true;
-  protected boolean doOutput = false;
-  protected boolean allowUserInteraction;
-  protected boolean useCaches;
-  protected long ifModifiedSince = 0L;
-  protected boolean connected = false;
   private static boolean defaultAllowUserInteraction = false;
   private static boolean defaultUseCaches = true;
   private static FileNameMap fileNameMap;  // Set by the URLConnection subclass.
@@ -81,6 +102,50 @@ public abstract class URLConnection
   private static SimpleDateFormat dateFormat1, dateFormat2, dateFormat3;
   private static boolean dateformats_initialized = false;
 
+  /**
+   * This is the URL associated with this connection
+   */
+  protected URL url;
+
+  /**
+   * Indicates whether or not input can be read from this URL
+   */
+  protected boolean doInput = true;
+  
+  /**
+   * Indicates whether or not output can be sent to this URL
+   */
+  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
+   * must a get a fresh copy of the data.
+   * <p>
+   * This field is set by the setUseCaches method and returned by the
+   * getUseCaches method.
+   *
+   * Its default value is that determined by the last invocation of
+   * setDefaultUseCaches
+   */
+  protected boolean useCaches;
+
+  /**
+   * If this value is non-zero, then the connection will only attempt to
+   * fetch the document pointed to by the URL if the document has been
+   * modified more recently than the date set in this variable.  That date
+   * should be specified as the number of seconds since 1/1/1970 GMT.
+   */
+  protected long ifModifiedSince = 0L;
+
+  /**
+   * Indicates whether or not a connection has been established to the
+   * destination specified in the URL
+   */
+  protected boolean connected = false;
+  
   /**
    * Creates a URL connection to a given URL. A real connection is not made.
    * Use #connect to do this.