 |
Chapter 15 The java.net Package |
 |
|
Chapter 15 The java.net Package |
|
java.net.URLConnection
java.lang.Object
java.net.HttpURLConnection
None
JDK 1.0 or later
The URLConnection class is an abstract class that represents a connection to a URL. A subclass of URLConnection supports a protocol-specific connection. A URLConnection can both read from and write to a URL.
A URLConnection object is created when the openConnection() method is called for a URL object. At this point, the actual connection has not yet been made, so setup parameters and general request properties can be modified for the specific connection. The various set methods control the setup parameters and request properties. Then the actual connection is made by calling the connect() method. Finally, the remote object becomes available, and the header fields and the content are accessed using various get methods.
The URLConnection class defines quite a few methods for setting parameters and retrieving information. Fortunately, for simple connections, all of the setup parameters and request properties can be left alone, as they all have reasonable default values. In most cases, you'll only be interested in the getInputStream() and getContent() methods. getInputStream() provides an InputStream that reads from the URL, while getContent() uses a ContentHandler to return an Object that represents the content of the resource. These methods are mirrored by the openStream() and getContent() convenience methods in the URL class.
public abstract class java.net.URLConnection extends java.lang.Object {
// Variables
protected boolean allowUserInteraction;
protected boolean connected;
protected boolean doInput;
protected boolean doOutput;
public static FileNameMap fileNameMap; // New in 1.1
protected long ifModifiedSince;
protected URL url;
protected boolean useCaches;
// Constructors
protected URLConnection(URL url);
// Class Methods
public static boolean getDefaultAllowUserInteraction();
public static String getDefaultRequestProperty(String key);
protected static String guessContentTypeFromName(String fname);
public static String guessContentTypeFromStream(InputStream is);
public static synchronized void setContentHandlerFactory(
ContentHandlerFactory fac);
public static void setDefaultAllowUserInteraction(
boolean defaultallowuserinteraction);
public static void setDefaultRequestProperty(String key,
String value);
// Instance Methods
public abstract void connect();
public boolean getAllowUserInteraction();
public Object getContent()
public String getContentEncoding();
public int getContentLength();
public String getContentType();
public long getDate();
public boolean getDefaultUseCaches();
public boolean getDoInput();
public boolean getDoOutput();
public long getExpiration();
public String getHeaderField(int n);
public String getHeaderField(String name);
public long getHeaderFieldDate(String name, long default);
public int getHeaderFieldInt(String name, int default);
public String getHeaderFieldKey(int n);
public long getIfModifiedSince();
public InputStream getInputStream();
public long getLastModified();
public OutputStream getOutputStream();
public String getRequestProperty(String key);
public URL getURL();
public boolean getUseCaches();
public void setAllowUserInteraction(boolean allowuserinteraction);
public void setDefaultUseCaches(boolean defaultusecaches);
public void setDoInput(boolean doinput);
public void setDoOutput(boolean dooutput);
public void setIfModifiedSince(long ifmodifiedsince);
public void setRequestProperty(String key, String value);
public void setUseCaches(boolean usecaches);
public String toString();
}
A flag that indicates whether or not user interaction is enabled for this connection. If this variable is true, it is possible to allow user interactions such as popping up dialog boxes. If it is false, no user interaction is allowed. The variable can be set by setAllowUserInteraction() and retrieved by getAllowUserInteraction(). The default value is false, unless the setDefaultAllowUserInteraction() method has been called, in which case that method call controls the default value.
A flag that indicates whether or not this object has established a connection to a remote host.
A flag that indicates whether or not this connection is enabled for input. Setting this variable to true indicates that the connection is going to read data. The variable can be set by setDoInput() and retrieved by getDoInput(). The default value is true.
A flag that indicates whether or not this connection is enabled for output. Setting this variable to true indicates that the connection is going to write data. The variable can be set by setDoOutput() and retrieved by getDoOutput(). The default value is false.
New as of JDK 1.1
A reference to the object that maps filename extensions to MIME type strings. This variable is used in guessContentTypeFromName().
A time value, specified as the number of seconds since January 1, 1970, that controls whether or not a resource is fetched based on its last modification time. Some protocols do not bother to retrieve a resource if there is a current local cached copy. However, if the resource has been modified more recently than ifModifiedSince, it is retrieved. If ifModifiedSince is 0, the resource is always retrieved. The variable can be set by setIfModifiedSince() and retrieved by getIfModifiedSince(). The default value is 0, which means that the resource must always be retrieved.
The resource to which this URLConnection connects. This variable is set to the value of the URL argument in the URLConnection constructor. It can be retrieved by getURL().
A flag that indicates whether or not locally cached resources are used. Some protocols cache documents. If this variable is true, the protocol is allowed to use caching whenever possible. If it is false, the protocol must always try to retrieve the resource. The variable can be set by setUseCaches() and retrieved by getUseCaches(). The default value is true, unless the setDefaultUseCaches() method has been called, in which case that method call controls the default value.
The URL to access.
This constructor creates a URLConnection object to manage a connection to the destination specified by the given URL. The actual connection is not created, however.
true if user interaction is allowed by default; false otherwise.
This method returns the default value of the allowUserInteraction variable for all instances of URLConnection. The default value is false, unless the setDefaultAllowUserInteraction() method has been called, in which case that method call controls the default value.
The name of a request property.
The default value of the named request property.
This method returns the default value for the request property named by the key parameter.
A String that contains the name of a file.
A guess at the MIME type of the given file, or null if a guess cannot be made.
This method uses the FileNameMap specified by the variable fileNameMap to return a MIME content type for the given filename.
protected static String guessContentTypeFromStream(InputStream is) throws IOException
The input stream to inspect
A guess at the MIME type of the given input stream, or null if a guess cannot be made.
If any kind of I/O error occurs.
This method looks at the first few bytes of an InputStream and returns a guess of the MIME content type. Note that the InputStream must support marks, which usually means that there is a BufferedInputStream at some level. Here are some strings that are recognized and the inferred content type:
| String | MIME Type Guess |
|---|---|
|
#def |
image/x-bitmap |
|
<! |
text/html |
|
<body |
text/html |
|
<head> |
text/html |
|
<html> |
text/html |
|
! XPM2 |
image/x-pixmap |
|
GIF8 |
image/gif |
public static synchronized void setContentHandlerFactory(ContentHandlerFactory fac)
An object that implements ContentHandlerFactory.
If the factory has already been defined.
If the application does not have permission to set the factory.
This method tells the URLConnection class to use the given ContentHandlerFactory object for all URLConnection objects. The purpose of this mechanism is to allow a program that hosts applets, such as a web browser, control over the creation of ContentHandler objects.
public static void setDefaultAllowUserInteraction( boolean defaultallowuserinteraction)
The new default value.
This method sets the default value of the allowUserInteraction variable for all new instances of URLConnection.
public static void setDefaultRequestProperty(String key, String value)
The name of a request property.
The new default value.
This method sets the default value of the request property named by the key parameter.
If any kind of I/O error occurs.
When a URLConnection object is created, it is not immediately connected to the resource specified by its associated URL object. This method actually establishes the connection. If this method is called after the connection has been established, it does nothing.
Before the connection is established, various parameters can be set with the set methods. After the connection has been established, it is an error to try to set these parameters.
As they retrieve information about the resource specified by the URL object, many of the get methods require that the connection be established. If the connection has not been established when one of these methods is called, the connection is established implicitly.
true if user interaction is allowed for this connection; false otherwise.
This method returns the value of the allowUserInteraction variable for this URLConnection.
public Object getContent() throws IOException, UnknownServiceException
An Object created from this URLConnection.
If any kind of I/O error occurs.
If the protocol cannot support the content type.
This method retrieves the content of the resource specified by the URL object associated with this URLConnection. If the connection for this object has not been established, the method implicitly establishes it.
The method returns an object that encapsulates the content of the connection. For example, for a connection that has content type image/jpeg, the method might return a object that belongs to subclass of Image, or for content type text/plain, it might return a String. The instanceof operator should determine the specific type of object that is returned.
The method first determines the content type of the connection by calling getContentType(). If this is the first time the content type has been seen, a content handler of type ContentHandler is created for the content type. Here are the steps that are taken to create a content handler:
The content encoding, or null if it is not known.
This method retrieves the content encoding of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the content-encoding header field. If the connection for this object has not been established, the method implicitly establishes it.
The content length or -1 if it is not known.
This method retrieves the content length of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the content-length header field. If the connection for this object has not been established, the method implicitly establishes it.
The content type, or null if it is not known.
This method retrieves the content type of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the content-type header field. This string is generally be a MIME type, such as image/jpeg or text/html. If the connection for this object has not been established, the method implicitly establishes it.
The content date, or 0 if it is not known.
This method retrieves the date of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the date header field. The date is returned as the number of seconds since January 1, 1970. If the connection for this object has not been established, the method implicitly establishes it.
true if the use of caches is allowed by default; false otherwise.
This method returns the default value of the useCaches variable for all instances of URLConnection. The default value is true, unless the setDefaultUseCaches() method has been called, in which case that method call controls the default value.
true if this URLConnection is to be used for input; false otherwise.
This method returns the value of the doInput variable for this URLConnection.
true if this URLConnection is to be used for output; false otherwise.
This method returns the value of the doOutput variable for this URLConnection.
The content expiration date, or if it is not known.
This method retrieves the expiration date of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the expires header field. The date is returned as the number of seconds since January 1, 1970. If the connection for this object has not been established, the method implicitly establishes it.
A header field index.
The value of the header field with the given index, or null if n is greater than the number of fields in the header.
This method retrieves the value of the header field at index n of the resource specified by the URL object associated with this URLConnection. If the connection for this object has not been established, the method implicitly establishes it.
A header field name.
The value of the named header field, or null if the header field is not known or its value cannot be determined.
This method retrieves the value of the named header field of the resource specified by the URL object associated with this URLConnection. This method is a helper for methods like getContentEncoding() and getContentType(). If the connection for this object has not been established, the method implicitly establishes it.
A header field name.
A default date value.
The value of the named header field parsed as a date value, or default if the field is missing or cannot be parsed.
This method retrieves the value of the named header field of the resource specified by the URL object associated with this URLConnection and parses it as a date value. The date is returned as the number of seconds since January 1, 1970. If the value of the header field cannot be determined or it is not a properly formed date, the given default value is returned. If the connection for this object has not been established, the method implicitly establishes it.
A header field name.
A default value.
The value of the named header field parsed as a number, or default if the field is missing or cannot be parsed.
This method retrieves the value of the named header field of the resource specified by the URL object associated with this URLConnection and parses it as a number. If the value of the header field cannot be determined or it is not a properly formed integer, the given default value is returned. If the connection for this object has not been established, the method implicitly establishes it.
A header field index.
The name of the header field at the given index, or null if n is greater than the number of fields in the header.
This method retrieves the name of the header field at index n of the resource specified by the URL object associated with this URLConnection. If the connection for this object has not been established, the method implicitly establishes it.
The value of the ifModifiedSince variable.
This method returns the value of the ifModifiedSince variable for this URLConnection.
public InputStream getInputStream() throws IOException, UnknownServiceException
An InputStream that reads data from this connection.
If any kind of I/O error occurs.
If this protocol does not support input.
This method returns an InputStream that reads the contents of the resource specified by the URL object associated with this URLConnection.
The content last-modified date, or if it is not known.
This method retrieves the last-modified date of the resource specified by the URL object associated with this URLConnection. In other words, the method returns the value of the last-modified header field. The date is returned as the number of seconds since January 1, 1970. If the connection for this object has not been established, the method implicitly establishes it.
public OutputStream getOutputStream() throws IOException, UnknownServiceException
An OutputStream that writes data to this connection.
If any kind of I/O error occurs.
If this protocol does not support output.
This method returns an OutputStream that writes to the resource specified by the URL object associated with this URLConnection.
The name of a request property.
The value of the named request property.
This method returns the value of the request property named by the key parameter.
The URL that this connection accesses.
This method returns a reference to the URL associated with this object. This is the value of the url variable for this URLConnection.
true if this URLConnection uses caches; false otherwise.
This method returns the value of the useCaches variable for this URLConnection.
A boolean value that indicates whether user interaction is allowed or not.
If this method is called after the connection has been established.
This method sets the value of the allowUserInteraction variable for this URLConnection. This method must be called before this object establishes a connection.
The new default value.
This method sets the default value of the useCaches variable for all new instances of URLConnection.
A boolean value that indicates if this connection is to be used for input.
If this method is called after the connection has been established.
This method sets the value of the doInput variable for this URLConnection. This method must be called before this object establishes a connection.
A boolean value that indicates if this connection is to be used for output.
If this method is called after the connection has been established.
This method sets the value of the doOutput variable for this URLConnection. This method must be called before this object establishes a connection.
A time value, specified as the number of seconds since January 1, 1970.
If this method is called after the connection has been established.
This method sets the value of the ifModifiedSince variable for this URLConnection. This method must be called before this object establishes a connection.
The name of a request property.
The new value.
If this method is called after the connection has been established.
This method sets the value of the request property named by the key parameter.
A boolean value that indicates if this connection uses caches.
If this method is called after the connection has been established.
This method sets the value of the useCaches variable for this URLConnection. This method must be called before this object establishes a connection.
A string representation of the URLConnection.
Object.toString()
This method returns a string representation of this URLConnection.
| Method | Inherited From | Method | Inherited From |
|---|---|---|---|
|
clone() |
Object |
equals(Object) |
Object |
|
finalize() |
Object |
getClass() |
Object |
|
hashCode() |
Object |
notify() |
Object |
|
notifyAll() |
Object |
wait() |
Object |
|
wait(long) |
Object |
wait(long, int) |
Object |
ContentHandler, ContentHandlerFactory, Error, FileNameMap, HttpURLConnection, IllegalAccessError, InputStream, IOException, OutputStream, SecurityException, UnknownServiceException, URL, URLStreamHandler, URLStreamHandlerFactory
|
 |
|
| URL |  |
URLEncoder |
