java.net
Class URLConnection

java.lang.Object   
  java.net.URLConnection

Direct Known Subclasses:

HttpURLConnection , JarURLConnection

public abstract class URLConnection
extends Object   

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL. In general, creating a connection to a URL is a multistep process:

openConnection()	connect()
Manipulate parameters that affect the connection to the remote resource.	Interact with the resource; query header fields and contents.

---------------------------->
time

1. The connection object is created by invoking the openConnection method on a URL.
2. The setup parameters and general request properties are manipulated.
3. The actual connection to the remote object is made, using the connect method.
4. The remote object becomes available. The header fields and the contents of the remote object can be accessed.

The setup parameters are modified using the following methods:

• setAllowUserInteraction
• setDoInput
• setDoOutput
• setIfModifiedSince
• setUseCaches

and the general request properties are modified using the method:

• setRequestProperty

Default values for the AllowUserInteraction and UseCaches parameters can be set using the methods setDefaultAllowUserInteraction and setDefaultUseCaches.

Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.

The following methods are used to access the header fields and the contents after the connection is made to the remote object:

• getContent
• getHeaderField
• getInputStream
• getOutputStream

Certain header fields are accessed frequently. The methods:

• getContentEncoding
• getContentLength
• getContentType
• getDate
• getExpiration
• getLastModifed

provide convenient access to these fields. The getContentType method is used by the getContent method to determine the type of the remote object; subclasses may find it convenient to override the getContentType method.

In the common case, all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface, there are only two interesting methods: getInputStream and getContent, which are mirrored in the URL class by convenience methods.

More information on the request properties and header fields of an http connection can be found at:

 http://www.ietf.org/rfc/rfc2068.txt
 

Note about fileNameMap: In versions prior to JDK 1.1.6, field fileNameMap of URLConnection was public. In JDK 1.1.6 and later, fileNameMap is private; accessor and mutator methods getFileNameMap and setFileNameMap are added to access it. This change is also described on the Compatibility page. Invoking the close() methods on the InputStream or OutputStream of an URLConnection after a request may free network resources associated with this instance, unless particular protocol specifications specify different behaviours for it.

Since:

JDK1.0

See Also:

URL.openConnection() , connect() , getContent() , getContentEncoding() , getContentLength() , getContentType() , getDate() , getExpiration() , getHeaderField(int) , getHeaderField(java.lang.String) , getInputStream() , getLastModified() , getOutputStream() , setAllowUserInteraction(boolean) , setDefaultUseCaches(boolean) , setDoInput(boolean) , setDoOutput(boolean) , setIfModifiedSince(long) , setRequestProperty(java.lang.String, java.lang.String) , setUseCaches(boolean)

Field Summary

protected boolean	allowUserInteraction If true, this URL is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog.
protected boolean	connected If false, this connection object has not created a communications link to the specified URL.
protected boolean	doInput This variable is set by the setDoInput method.
protected boolean	doOutput This variable is set by the setDoOutput method.
protected long	ifModifiedSince Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time.
protected URL	url The URL represents the remote object on the World Wide Web to which this connection is opened.
protected boolean	useCaches If true, the protocol is allowed to use caching whenever it can.

Constructor Summary

protected

URLConnection (URL url) Constructs a URL connection to the specified URL.

Method Summary

void	addRequestProperty (String key, String value) Adds a general request property specified by a key-value pair.
abstract void	connect () Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
boolean	getAllowUserInteraction () Returns the value of the allowUserInteraction field for this object.
int	getConnectTimeout () Returns setting for connect timeout.
Object	getContent () Retrieves the contents of this URL connection.
Object	getContent (Class [] classes) Retrieves the contents of this URL connection.
String	getContentEncoding () Returns the value of the content-encoding header field.
int	getContentLength () Returns the value of the content-length header field.
String	getContentType () Returns the value of the content-type header field.
long	getDate () Returns the value of the date header field.
static boolean	getDefaultAllowUserInteraction () Returns the default value of the allowUserInteraction field.
static String	getDefaultRequestProperty (String key) Deprecated. The instance specific getRequestProperty method should be used after an appropriate instance of URLConnection is obtained.
boolean	getDefaultUseCaches () Returns the default value of a URLConnection's useCaches flag.
boolean	getDoInput () Returns the value of this URLConnection's doInput flag.
boolean	getDoOutput () Returns the value of this URLConnection's doOutput flag.
long	getExpiration () Returns the value of the expires header field.
static FileNameMap	getFileNameMap () Loads filename map (a mimetable) from a data file.
String	getHeaderField (int n) Returns the value for the nth header field.
String	getHeaderField (String name) Returns the value of the named header field.
long	getHeaderFieldDate (String name, long Default) Returns the value of the named field parsed as date.
int	getHeaderFieldInt (String name, int Default) Returns the value of the named field parsed as a number.
String	getHeaderFieldKey (int n) Returns the key for the nth header field.
Map <String ,List <String >>	getHeaderFields () Returns an unmodifiable Map of the header fields.
long	getIfModifiedSince () Returns the value of this object's ifModifiedSince field.
InputStream	getInputStream () Returns an input stream that reads from this open connection.
long	getLastModified () Returns the value of the last-modified header field.
OutputStream	getOutputStream () Returns an output stream that writes to this connection.
Permission	getPermission () Returns a permission object representing the permission necessary to make the connection represented by this object.
int	getReadTimeout () Returns setting for read timeout.
Map <String ,List <String >>	getRequestProperties () Returns an unmodifiable Map of general request properties for this connection.
String	getRequestProperty (String key) Returns the value of the named general request property for this connection.
URL	getURL () Returns the value of this URLConnection's URL field.
boolean	getUseCaches () Returns the value of this URLConnection's useCaches field.
static String	guessContentTypeFromName (String fname) Tries to determine the content type of an object, based on the specified "file" component of a URL.
static String	guessContentTypeFromStream (InputStream is) Tries to determine the type of an input stream based on the characters at the beginning of the input stream.
void	setAllowUserInteraction (boolean allowuserinteraction) Set the value of the allowUserInteraction field of this URLConnection.
void	setConnectTimeout (int timeout) Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection.
static void	setContentHandlerFactory (ContentHandlerFactory fac) Sets the ContentHandlerFactory of an application.
static void	setDefaultAllowUserInteraction (boolean defaultallowuserinteraction) Sets the default value of the allowUserInteraction field for all future URLConnection objects to the specified value.
static void	setDefaultRequestProperty (String key, String value) Deprecated. The instance specific setRequestProperty method should be used after an appropriate instance of URLConnection is obtained. Invoking this method will have no effect.
void	setDefaultUseCaches (boolean defaultusecaches) Sets the default value of the useCaches field to the specified value.
void	setDoInput (boolean doinput) Sets the value of the doInput field for this URLConnection to the specified value.
void	setDoOutput (boolean dooutput) Sets the value of the doOutput field for this URLConnection to the specified value.
static void	setFileNameMap (FileNameMap map) Sets the FileNameMap.
void	setIfModifiedSince (long ifmodifiedsince) Sets the value of the ifModifiedSince field of this URLConnection to the specified value.
void	setReadTimeout (int timeout) Sets the read timeout to a specified timeout, in milliseconds.
void	setRequestProperty (String key, String value) Sets the general request property.
void	setUseCaches (boolean usecaches) Sets the value of the useCaches field of this URLConnection to the specified value.
String	toString () Returns a String representation of this URL connection.

Methods inherited from class java.lang.Object

clone , equals , finalize , getClass , hashCode , notify , notifyAll , wait , wait , wait

Field Detail

url

protected URL    url

The URL represents the remote object on the World Wide Web to which this connection is opened.

The value of this field can be accessed by the getURL method.

The default value of this variable is the value of the URL argument in the URLConnection constructor.

See Also:

getURL() , url

doInput

protected boolean doInput

This variable is set by the setDoInput method. Its value is returned by the getDoInput method.

A URL connection can be used for input and/or output. Setting the doInput flag to true indicates that the application intends to read data from the URL connection.

The default value of this field is true.

See Also:

getDoInput() , setDoInput(boolean)

doOutput

protected boolean doOutput

This variable is set by the setDoOutput method. Its value is returned by the getDoOutput method.

A URL connection can be used for input and/or output. Setting the doOutput flag to true indicates that the application intends to write data to the URL connection.

The default value of this field is false.

See Also:

getDoOutput() , setDoOutput(boolean)

allowUserInteraction

protected boolean allowUserInteraction

If true, this URL is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog. If false, then no user interaction is allowed.

The value of this field can be set by the setAllowUserInteraction method. Its value is returned by the getAllowUserInteraction method. Its default value is the value of the argument in the last invocation of the setDefaultAllowUserInteraction method.

See Also:

getAllowUserInteraction() , setAllowUserInteraction(boolean) , setDefaultAllowUserInteraction(boolean)

useCaches

protected boolean useCaches

If true, the protocol is allowed to use caching whenever it can. If false, the protocol must always try to get a fresh copy of the object.

This field is set by the setUseCaches method. Its value is returned by the getUseCaches method.

Its default value is the value given in the last invocation of the setDefaultUseCaches method.

See Also:

setUseCaches(boolean) , getUseCaches()