Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.net

Class URLConnection

java.lang.Object
|
+--java.net.URLConnection


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.

Author:

Field Summary

booleanallowUserInteraction

This variable determines whether or not interaction is allowed with the user.
booleanconnected

Indicates whether or not a connection has been established to the destination specified in the URL
booleandoInput

Indicates whether or not input can be read from this URL
booleandoOutput

Indicates whether or not output can be sent to this URL
longifModifiedSince

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.
java.net.URLurl

This is the URL associated with this connection
booleanuseCaches

If this flag is set, the protocol is allowed to cache data whenever it can (caching is not guaranteed).

Constructor Summary

URLConnection(java.net.URL url)

This constructs a URLConnection from a URL object

Method Summary

voidconnect()

Establishes the actual connection to the URL associated with this connection object
booleangetAllowUserInteraction()

Returns a boolean flag indicating whether or not user interaction is allowed for this connection.
java.lang.ObjectgetContent()

This method returns the content of the document pointed to by the URL as an Object.
java.lang.StringgetContentEncoding()

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

Returns the value of the content-length header field or -1 if the value is not known or not present.
java.lang.StringgetContentType()

Returns the the content-type of the data pointed to by the URL.
longgetDate()

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 booleangetDefaultAllowUserInteraction()

Returns the default flag for whether or not interaction with a user is allowed.
static java.lang.StringgetDefaultRequestProperty(java.lang.String key)

Returns the default value of a request property.
booleangetDefaultUseCaches()

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

Returns the value of a flag indicating whether or not input is going to be done for this connection.
booleangetDoOutput()

Returns a boolean flag indicating whether or not output will be done on this connection.
longgetExpiration()

Returns the value of the expires header or 0 if not known or present.
static java.net.FileNameMapgetFileNameMap()

This method returns the FileNameMap object being used to decode MIME types by file extension.
java.lang.StringgetHeaderField(int index)

Return a String representing the header value at the specified index.
java.lang.StringgetHeaderField(java.lang.String name)

Returns a String representing the value of the header field having the named key.
longgetHeaderFieldDate(java.lang.String key, long def)

Returns the value of the named header field as a date.
intgetHeaderFieldInt(java.lang.String key, int def)

Returns the value of the named header field as an int.
java.lang.StringgetHeaderFieldKey(int index)

Returns a String representing the header key at the specified index.
longgetIfModifiedSince()

Returns the ifModified since instance variable.
java.io.InputStreamgetInputStream()

Returns an InputStream for this connection.
longgetLastModified()

Returns the value of the last-modified header field or 0 if not known known or not present.
java.io.OutputStreamgetOutputStream()

Returns an OutputStream for this connection.
java.security.PermissiongetPermission()

This method returns a Permission object representing the permissions required to access this URL.
java.util.MapgetRequestProperties()

Returns an unmodifiable Map containing the request properties.
java.lang.StringgetRequestProperty(java.lang.String key)

Returns the value of the named request property.
java.net.URLgetURL()

Returns the URL object associated with this connection
booleangetUseCaches()

Returns a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.
static java.lang.StringguessContentTypeFromName(java.lang.String filename)

Returns the MIME type of a file based on the name of the file.
static java.lang.StringguessContentTypeFromStream(java.io.InputStream is)

Returns the MIME type of a stream based on the first few characters at the beginning of the stream.
voidsetAllowUserInteraction(boolean allow)

Sets a boolean flag indicating whether or not user interaction is allowed for this connection.
static synchronized voidsetContentHandlerFactory(java.net.ContentHandlerFactory fac)

Set's the ContentHandlerFactory for an application.
static synchronized voidsetDefaultAllowUserInteraction(boolean allow)

Sets the default flag for whether or not interaction with a user is allowed.
static synchronized voidsetDefaultRequestProperty(java.lang.String key, java.lang.String value)

Sets the default value of a request property.
synchronized voidsetDefaultUseCaches(boolean use)

Sets the default value used to determine whether or not caching of documents will be done when possible.
voidsetDoInput(boolean input)

Returns the value of a flag indicating whether or not input is going to be done for this connection.
voidsetDoOutput(boolean output)

Returns a boolean flag indicating whether or not output will be done on this connection.
static voidsetFileNameMap(java.net.FileNameMap fileNameMap)

This method set the FileNameMap object being used to decode MIME types by file extension.
voidsetIfModifiedSince(long modified_since)

Sets the ifModified since instance variable.
voidsetRequestProperty(java.lang.String key, java.lang.String value)

Sets the value of the named request property
voidsetUseCaches(boolean use_caches)

Sets a boolean flag indicating whether or not caching will be used (if possible) to store data downloaded via the connection.
java.lang.StringtoString()

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

Field Details

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


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


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


Constructor Details

URLConnection

protected URLConnection(java.net.URL url)

This constructs a URLConnection from a URL object

Parameters:


Method Details

connect

public void connect()

Establishes the actual connection to the URL associated with this connection object


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:


getContent

public Object getContent()

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. is tried. The default class will also be used if the content handler factory returns a null content handler.

Throws:


getContentEncoding

public String getContentEncoding()

Returns the value of the content-encoding field or null if it is not known or not present.

Returns:


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:


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:


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:


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 overidden

Returns:


getDefaultRequestProperty

public static String getDefaultRequestProperty(java.lang.String key)

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:

Returns:


getDefaultUseCaches

public boolean getDefaultUseCaches()

Returns the default value used to determine whether or not caching of documents will be done when possible.

Returns:


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:


getDoOutput

public boolean getDoOutput()

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

Returns:


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:


getFileNameMap

public static FileNameMap getFileNameMap()

This method returns the FileNameMap object being used to decode MIME types by file extension.

Returns:


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 getHeaderFieldKey(int) method allows access to the corresponding key for this header field

Parameters:

Returns:


getHeaderField

public String getHeaderField(java.lang.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:

Returns:


getHeaderFieldDate

public long getHeaderFieldDate(java.lang.String key, long def)

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:


getHeaderFieldInt

public int getHeaderFieldInt(java.lang.String key, int def)

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:


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:

Returns:


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:


getInputStream

public InputStream getInputStream()

Returns an InputStream for this connection. As this default implementation returns null, subclasses should override this method

Returns:

Throws:


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:


getOutputStream

public OutputStream getOutputStream()

Returns an OutputStream for this connection. As this default implementation returns null, subclasses should override this method

Returns:

Throws:


getPermission

public Permission getPermission()

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:

Throws:


getRequestProperties

public Map getRequestProperties()

Returns an unmodifiable Map containing the request properties.

Since:

getRequestProperty

public String getRequestProperty(java.lang.String key)

Returns the value of the named request property.

Parameters:

Returns:


getURL

public URL getURL()

Returns the URL object associated with this connection

Returns:


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:


guessContentTypeFromName

public static String guessContentTypeFromName(java.lang.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:

Returns:


guessContentTypeFromStream

public static String guessContentTypeFromStream(java.io.InputStream is)

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:

Returns:

Throws:


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:


setContentHandlerFactory

public static synchronized void setContentHandlerFactory(java.net.ContentHandlerFactory fac)

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.

Parameters:


setDefaultAllowUserInteraction

public static synchronized 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:


setDefaultRequestProperty

public static synchronized void setDefaultRequestProperty(java.lang.String key, java.lang.String value)

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:


setDefaultUseCaches

public synchronized void setDefaultUseCaches(boolean use)

Sets the default value used to determine whether or not caching of documents will be done when possible.

Parameters:


setDoInput

public void setDoInput(boolean input)

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.

Parameters:


setDoOutput

public void setDoOutput(boolean output)

Returns 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:


setFileNameMap

public static void setFileNameMap(java.net.FileNameMap fileNameMap)

This method set the FileNameMap object being used to decode MIME types by file extension.

Parameters:


setIfModifiedSince

public void setIfModifiedSince(long modified_since)

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:


setRequestProperty

public void setRequestProperty(java.lang.String key, java.lang.String value)

Sets the value of the named request property

Parameters:


setUseCaches

public void setUseCaches(boolean use_caches)

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

Parameters:


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()

Returns: