java.net
Class URLConnection

java.lang.Object
  extended by java.net.URLConnection
Direct Known Subclasses:
HttpURLConnection, JarURLConnection

public abstract class URLConnection
extends Object

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.

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.

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.

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.

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.


Field Summary
protected  boolean allowUserInteraction
          This variable determines whether or not interaction is allowed with the user.
protected  boolean connected
          Indicates whether or not a connection has been established to the destination specified in the URL
protected  boolean doInput
          Indicates whether or not input can be read from this URL
protected  boolean doOutput
          Indicates whether or not output can be sent to this URL
protected  long ifModifiedSince
          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.
protected  URL url
          This is the URL associated with this connection
protected  boolean useCaches
          If this flag is set, the protocol is allowed to cache data whenever it can (caching is not guaranteed).
 
Constructor Summary
protected URLConnection(URL url)
          Creates a URL connection to a given URL.
 
Method Summary
 void addRequestProperty(String key, String value)
          Adds a new request property by a key/value pair.
abstract  void connect()
          Establishes the actual connection to the URL associated with this connection object
 boolean getAllowUserInteraction()
          Returns a boolean flag indicating whether or not user interaction is allowed for this connection.
 int getConnectTimeout()
          Returns the connection timeout speed, in milliseconds, or zero if the timeout is infinite or not set.
 Object getContent()
          This method returns the content of the document pointed to by the URL as an Object.
 Object getContent(Class[] classes)
          Retrieves the content of this URLConnection
 String getContentEncoding()
          Returns the value of the content-encoding field or null if it is not known or not present.
 int getContentLength()
          Returns the value of the content-length header field or -1 if the value is not known or not present.
 String getContentType()
          Returns the the content-type of the data pointed to by the URL.
 long getDate()
          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.
static boolean getDefaultAllowUserInteraction()
          Returns the default flag for whether or not interaction with a user is allowed.
static String getDefaultRequestProperty(String key)
          Deprecated. 1.3 The method getRequestProperty should be used instead. This method does nothing now.
 boolean getDefaultUseCaches()
          Returns the default value used to determine whether or not caching of documents will be done when possible.
 boolean getDoInput()
          Returns the value of a flag indicating whether or not input is going to be done for this connection.
 boolean getDoOutput()
          Returns a boolean flag indicating whether or not output will be done on this connection.
 long getExpiration()
          Returns the value of the expires header or 0 if not known or present.
static FileNameMap getFileNameMap()
          This method returns the FileNameMap object being used to decode MIME types by file extension.
 String getHeaderField(int index)
          Return a String representing the header value at the specified index.
 String getHeaderField(String name)
          Returns a String representing the value of the header field having the named key.
 long getHeaderFieldDate(String name, long defaultValue)
          Returns the value of the named header field as a date.
 int getHeaderFieldInt(String name, int defaultValue)
          Returns the value of the named header field as an int.
 String getHeaderFieldKey(int index)
          Returns a String representing the header key at the specified index.
 Map<String,List<String>> getHeaderFields()
          Returns an unmodifiable Map containing all sent header fields.
 long getIfModifiedSince()
          Returns the ifModified since instance variable.
 InputStream getInputStream()
          Returns an InputStream for this connection.
 long getLastModified()
          Returns the value of the last-modified header field or 0 if not known known or not present.
 OutputStream getOutputStream()
          Returns an OutputStream for this connection.
 Permission getPermission()
          This method returns a Permission object representing the permissions required to access this URL.
 int getReadTimeout()
          Returns the read timeout, in milliseconds, or zero if the timeout is infinite or not set.
 Map<String,List<String>> getRequestProperties()
          Returns an unmodifiable Map containing the request properties.
 String getRequestProperty(String key)
          Returns the value of the named request property.
 URL getURL()
          Returns the URL object associated with this connection
 boolean getUseCaches()
          Returns a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.
static String guessContentTypeFromName(String filename)
          Returns the MIME type of a file based on the name of the file.
static String guessContentTypeFromStream(InputStream is)
          Returns the MIME type of a stream based on the first few characters at the beginning of the stream.
 void setAllowUserInteraction(boolean allow)
          Sets a boolean flag indicating whether or not user interaction is allowed for this connection.
 void setConnectTimeout(int timeout)
          Set the connection timeout speed, in milliseconds, or zero if the timeout is to be considered infinite.
static void setContentHandlerFactory(ContentHandlerFactory factory)
          Sets the ContentHandlerFactory for an application.
static void setDefaultAllowUserInteraction(boolean allow)
          Sets the default flag for whether or not interaction with a user is allowed.
static void setDefaultRequestProperty(String key, String value)
          Deprecated. 1.3 The method setRequestProperty should be used instead. This method does nothing now.
 void setDefaultUseCaches(boolean use)
          Sets the default value used to determine whether or not caching of documents will be done when possible.
 void setDoInput(boolean input)
          Sets the value of a flag indicating whether or not input is going to be done for this connection.
 void setDoOutput(boolean output)
          Sets a boolean flag indicating whether or not output will be done on this connection.
static void setFileNameMap(FileNameMap map)
          This method sets the FileNameMap object being used to decode MIME types by file extension.
 void setIfModifiedSince(long ifmodifiedsince)
          Sets the ifModified since instance variable.
 void setReadTimeout(int timeout)
          Set the read timeout, in milliseconds, or zero if the timeout is to be considered infinite.
 void setRequestProperty(String key, String value)
          Sets the value of the named request property.
 void setUseCaches(boolean usecaches)
          Sets a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.
 String toString()
          The methods prints the value of this object as a String by calling the toString() method of its associated URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

allowUserInteraction

protected boolean allowUserInteraction
This variable determines whether or not interaction is allowed with the user. For example, to prompt for a username and password.


connected

protected boolean connected
Indicates whether or not a connection has been established to the destination specified in the URL


doInput

protected boolean doInput
Indicates whether or not input can be read from this URL


doOutput

protected boolean doOutput
Indicates whether or not output can be sent to this URL


useCaches

protected boolean useCaches
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.

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


ifModifiedSince

protected long ifModifiedSince
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.


url

protected URL url
This is the URL associated with this connection

Constructor Detail

URLConnection

protected URLConnection(URL url)
Creates a URL connection to a given URL. A real connection is not made. Use connect() to do this.

Parameters:
url - The Object to create the URL connection to
See Also:
connect()
Method Detail

connect

public abstract void connect()
                      throws IOException
Establishes the actual connection to the URL associated with this connection object

Throws:
IOException - if an error occurs

getURL

public URL getURL()
Returns the URL object associated with this connection

Returns:
The URL for this connection.

getConnectTimeout

public int getConnectTimeout()
Returns the connection timeout speed, in milliseconds, or zero if the timeout is infinite or not set.

Returns:
The timeout.
Since:
1.5

setConnectTimeout

public void setConnectTimeout(int timeout)
                       throws IllegalArgumentException
Set the connection timeout speed, in milliseconds, or zero if the timeout is to be considered infinite. Note that in certain socket implementations/platforms this method may not have any effect. Throws an IllegalArgumentException if timeout < 0.

Parameters:
timeout - the timeout, in milliseconds.
Throws:
IllegalArgumentException
Since:
1.5

getReadTimeout

public int getReadTimeout()
Returns the read timeout, in milliseconds, or zero if the timeout is infinite or not set.

Returns:
The timeout.
Since:
1.5
See Also:
setReadTimeout(int)

setReadTimeout

public void setReadTimeout(int timeout)
                    throws IllegalArgumentException
Set the read timeout, in milliseconds, or zero if the timeout is to be considered infinite. Note that in certain socket implementations/platforms this method may not have any effect. Throws an IllegalArgumentException if timeout < 0.

Parameters:
timeout - - The timeout, in milliseconds.
Throws:
IllegalArgumentException - if timeout is negative.
Since:
1.5
See Also:
getReadTimeout()

getContentLength

public int getContentLength()
Returns the value of the content-length header field or -1 if the value is not known or not present.

Returns:
The content-length field

getContentType

public String getContentType()
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()

Returns:
The content MIME type

getContentEncoding

public String getContentEncoding()
Returns the value of the content-encoding field or null if it is not known or not present.

Returns:
The content-encoding field

getExpiration

public long getExpiration()
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.

Returns:
The expiration time.

getDate

public long getDate()
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.

Returns:
The document date

getLastModified

public long getLastModified()
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.

Returns:
The last modified time

getHeaderField

public String getHeaderField(int index)
Return a String representing the header value 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 key for this header field

Parameters:
index - The index into the header field list to retrieve the value for
Returns:
The header value or null if index is past the end of the headers

getHeaderField

public String getHeaderField(String name)
Returns a String representing the value of the header field having the named key. Returns null if the header field does not exist.

Parameters:
name - The key of the header field
Returns:
The value of the header field as a String

getHeaderFields

public Map<String,List<String>> getHeaderFields()
Returns an unmodifiable Map containing all sent header fields.

Returns:
The map of header fields. The map consists of String keys with an unmodifiable List of String objects as value.
Since:
1.4

getHeaderFieldInt

public int getHeaderFieldInt(String name,
                             int defaultValue)
Returns the value of the named header field as an int. If the field is not present or cannot be parsed as an integer, the default value will be returned.

Parameters:
name - The header field key to lookup
defaultValue - The defaule value if the header field is not found or can't be parsed.
Returns:
The value of the header field or the default value if the field is missing or malformed

getHeaderFieldDate

public long getHeaderFieldDate(String name,
                               long defaultValue)
Returns the value of the named header field as a date. This date will be the number of seconds since midnight 1/1/1970 GMT or the default value if the field is not present or cannot be converted to a date.

Parameters:
name - The name of the header field
defaultValue - The default date if the header field is not found or can't be converted.
Returns:
The date value of the header filed or the default value if the field is missing or malformed

getHeaderFieldKey

public String getHeaderFieldKey(int index)
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.

Parameters:
index - The index into the header field list to retrieve the key for.
Returns:
The header field key or null if index is past the end of the headers.

getContent

public Object getContent()
                  throws IOException
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.

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. If this handler does not exist, the method will simple return the InputStream returned by getInputStream(). Note that the default implementation of getInputStream() throws a UnknownServiceException so subclasses are encouraged to override this method.

Returns:
the content
Throws:
IOException - If an error with the connection occurs.
UnknownServiceException - If the protocol does not support the content type at all.

getContent

public Object getContent(Class[] classes)
                  throws IOException
Retrieves the content of this URLConnection

Parameters:
classes - The allowed classes for the content
Returns:
the content
Throws:
IOException - If an error occurs
UnknownServiceException - If the protocol does not support the content type

getPermission

public Permission getPermission()
                         throws IOException
This method returns a Permission object representing the permissions required to access this URL. This method returns java.security.AllPermission by default. Subclasses should override it to return a more specific permission. For example, an HTTP URL should return an instance of SocketPermission for the appropriate host and port.

Note that because of items such as HTTP redirects, the permission object returned might be different before and after connecting.

Returns:
A Permission object
Throws:
IOException - If the computation of the permission requires network or file I/O and an exception occurs while computing it

getInputStream

public InputStream getInputStream()
                           throws IOException
Returns an InputStream for this connection. As this default implementation returns null, subclasses should override this method

Returns:
An InputStream for this connection
Throws:
IOException - If an error occurs
UnknownServiceException - If the protocol does not support input

getOutputStream

public OutputStream getOutputStream()
                             throws IOException
Returns an OutputStream for this connection. As this default implementation returns null, subclasses should override this method

Returns:
An OutputStream for this connection
Throws:
IOException - If an error occurs
UnknownServiceException - If the protocol does not support output

toString

public String toString()
The methods prints the value of this object as a String by calling the toString() method of its associated URL. Overrides Object.toString()

Overrides:
toString in class Object
Returns:
A String representation of this object
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

setDoInput

public void setDoInput(boolean input)
Sets 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.

Parameters:
input - true if input is to be done, false otherwise
Throws:
IllegalStateException - If already connected

getDoInput

public boolean getDoInput()
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.

Returns:
true if input is to be done, false otherwise

setDoOutput

public void setDoOutput(boolean output)
Sets a boolean flag indicating whether or not output will be done on this connection. The default value is false, so this method can be used to override the default

Parameters:
output - ture if output is to be done, false otherwise
Throws:
IllegalStateException - If already connected

getDoOutput

public boolean getDoOutput()
Returns a boolean flag indicating whether or not output will be done on this connection. This defaults to false.

Returns:
true if output is to be done, false otherwise

setAllowUserInteraction

public void setAllowUserInteraction(boolean allow)
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.

Parameters:
allow - true if user interaction should be allowed, false otherwise.
Throws:
IllegalStateException - If already connected

getAllowUserInteraction

public boolean getAllowUserInteraction()
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.

Returns:
true if user interaction is allowed, false otherwise

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean allow)
Sets the default flag for whether or not interaction with a user is allowed. This will be used for all connections unless overridden

Parameters:
allow - true to allow user interaction, false otherwise

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()
Returns the default flag for whether or not interaction with a user is allowed. This will be used for all connections unless overridden

Returns:
true if user interaction is allowed, false otherwise

setUseCaches

public void setUseCaches(boolean usecaches)
Sets a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.

Parameters:
usecaches - The new value
Throws:
IllegalStateException - If already connected

getUseCaches

public boolean getUseCaches()
Returns a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.

Returns:
true if caching should be used if possible, false otherwise

setIfModifiedSince

public void setIfModifiedSince(long ifmodifiedsince)
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.

Parameters:
ifmodifiedsince - The new value in milliseconds since January 1, 1970 GMT
Throws:
IllegalStateException - If already connected

getIfModifiedSince

public long getIfModifiedSince()
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

Returns:
The ifModifiedSince value

getDefaultUseCaches

public boolean getDefaultUseCaches()
Returns the default value used to determine whether or not caching of documents will be done when possible.

Returns:
true if caches will be used, false otherwise

setDefaultUseCaches

public void setDefaultUseCaches(boolean use)
Sets the default value used to determine whether or not caching of documents will be done when possible.

Parameters:
use - true to use caches if possible by default, false otherwise

setRequestProperty

public void setRequestProperty(String key,
                               String value)
Sets the value of the named request property. This method does overwrite the value of existing properties with the new value.

Parameters:
key - The name of the property
value - The value of the property
Throws:
IllegalStateException - If already connected
NullPointerException - If key is null
Since:
1.4
See Also:
getRequestProperty(String key), addRequestProperty(String key, String value)

addRequestProperty

public void addRequestProperty(String key,
                               String value)
Adds a new request property by a key/value pair. This method does not overwrite existing properties with the same key.

Parameters:
key - Key of the property to add
value - Value of the Property to add
Throws:
IllegalStateException - If already connected
NullPointerException - If key is null
Since:
1.4
See Also:
getRequestProperty(String), setRequestProperty(String, String)

getRequestProperty

public String getRequestProperty(String key)
Returns the value of the named request property.

Parameters:
key - The name of the property
Returns:
Value of the property, or null if key is null.
Throws:
IllegalStateException - If already connected
See Also:
setRequestProperty(String, String), addRequestProperty(String, String)

getRequestProperties

public Map<String,List<String>> getRequestProperties()
Returns an unmodifiable Map containing the request properties.

Returns:
The map of properties. The map consists of String keys with an unmodifiable List of String objects as value.
Throws:
IllegalStateException - If already connected
Since:
1.4

setDefaultRequestProperty

public static void setDefaultRequestProperty(String key,
                                             String value)
Deprecated. 1.3 The method setRequestProperty should be used instead. This method does nothing now.

Sets the default value of a request property. This will be used for all connections unless the value of the property is manually overridden.

Parameters:
key - The request property name the default is being set for
value - The value to set the default to
See Also:
setRequestProperty(String, String)

getDefaultRequestProperty

public static String getDefaultRequestProperty(String key)
Deprecated. 1.3 The method getRequestProperty should be used instead. This method does nothing now.

Returns the default value of a request property. This will be used for all connections unless the value of the property is manually overridden.

Parameters:
key - The request property to return the default value of
Returns:
The value of the default property or null if not available
See Also:
getRequestProperty(String)

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory factory)
Sets 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.

Parameters:
factory - The ContentHandlerFactory for this application
Throws:
Error - If the factory has already been defined
SecurityException - If a security manager exists and its checkSetFactory method doesn't allow the operation

guessContentTypeFromName

public static String guessContentTypeFromName(String filename)
Returns the MIME type of a file based on the name of the file. This works by searching for the file's extension in a list of file extensions and returning the MIME type associated with it. If no type is found, then a MIME type of "application/octet-stream" will be returned.

Parameters:
filename - The filename to determine the MIME type for
Returns:
The MIME type String

guessContentTypeFromStream

public static String guessContentTypeFromStream(InputStream is)
                                         throws IOException
Returns the MIME type of a stream based on the first few characters at the beginning of the stream. This routine can be used to determine the MIME type if a server is believed to be returning an incorrect MIME type. This method returns "application/octet-stream" if it cannot determine the MIME type.

NOTE: Overriding MIME types sent from the server can be obnoxious to user's. See Internet Exploder 4 if you don't believe me.

Parameters:
is - The InputStream to determine the MIME type from
Returns:
The MIME type
Throws:
IOException - If an error occurs

getFileNameMap

public static FileNameMap getFileNameMap()
This method returns the FileNameMap object being used to decode MIME types by file extension.

Returns:
The FileNameMap.
Since:
1.2

setFileNameMap

public static void setFileNameMap(FileNameMap map)
This method sets the FileNameMap object being used to decode MIME types by file extension.

Parameters:
map - The FileNameMap.
Throws:
SecurityException - If a security manager exists and its checkSetFactory method doesn't allow the operation
Since:
1.2