*/
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 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
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.
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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
*/
}
/**
- * 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
*/
}
/**
- * 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
}
/**
- * 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
}
/**
- * 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
}
/**
- * 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
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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()
{
}
/**
- * 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
*
}
/**
- * 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()
{
}
/**
- * 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
*/
}
/**
- * 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()
{
}
/**
- * 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
*
}
/**
- * 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()
{
}
/**
- * 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
}
/**
- * 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()
{
}
/**
- * 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
*/
}
/**
- * 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
}
/**
- * 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
*
}
/**
- * 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
*
}
/**
- * 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
*/
projects / gcc.git / commitdiff