java.net
public abstract class URLConnection extends Object
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.
Modifier and Type | Field and Description |
---|---|
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).
|
Modifier | Constructor and Description |
---|---|
protected |
URLConnection(URL url)
Creates a URL connection to a given URL.
|
Modifier and Type | Method and Description |
---|---|
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.
|
protected boolean allowUserInteraction
protected boolean connected
protected boolean doInput
protected boolean doOutput
protected boolean useCaches
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
protected long ifModifiedSince
protected URLConnection(URL url)
connect()
to do this.url
- The Object to create the URL connection toconnect()
public abstract void connect() throws IOException
IOException
- if an error occurspublic URL getURL()
public int getConnectTimeout()
public void setConnectTimeout(int timeout) throws IllegalArgumentException
IllegalArgumentException
if timeout < 0.timeout
- the timeout, in milliseconds.IllegalArgumentException
public int getReadTimeout()
setReadTimeout(int)
public void setReadTimeout(int timeout) throws IllegalArgumentException
IllegalArgumentException
if timeout < 0.timeout
- - The timeout, in milliseconds.IllegalArgumentException
- if timeout is negative.getReadTimeout()
public int getContentLength()
public String getContentType()
public String getContentEncoding()
public long getExpiration()
public long getDate()
public long getLastModified()
public String getHeaderField(int index)
getHeaderField(int)
method allows access to the corresponding
key for this header fieldindex
- The index into the header field list to retrieve the value forpublic String getHeaderField(String name)
name
- The key of the header fieldpublic Map<String,List<String>> getHeaderFields()
public int getHeaderFieldInt(String name, int defaultValue)
name
- The header field key to lookupdefaultValue
- The defaule value if the header field is not found
or can't be parsed.public long getHeaderFieldDate(String name, long defaultValue)
name
- The name of the header fielddefaultValue
- The default date if the header field is not found
or can't be converted.public String getHeaderFieldKey(int index)
getHeaderField(int)
method allows access to the corresponding
value for this tag.index
- The index into the header field list to retrieve the key for.public Object getContent() throws IOException
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.
IOException
- If an error with the connection occurs.UnknownServiceException
- If the protocol does not support the
content type at all.public Object getContent(Class[] classes) throws IOException
classes
- The allowed classes for the contentIOException
- If an error occursUnknownServiceException
- If the protocol does not support the
content typepublic Permission getPermission() throws IOException
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.
IOException
- If the computation of the permission requires
network or file I/O and an exception occurs while computing itpublic InputStream getInputStream() throws IOException
IOException
- If an error occursUnknownServiceException
- If the protocol does not support inputpublic OutputStream getOutputStream() throws IOException
IOException
- If an error occursUnknownServiceException
- If the protocol does not support outputpublic String toString()
toString
in class Object
Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
public void setDoInput(boolean input)
input
- true
if input is to be done,
false
otherwiseIllegalStateException
- If already connectedpublic boolean getDoInput()
public void setDoOutput(boolean output)
output
- ture if output is to be done, false otherwiseIllegalStateException
- If already connectedpublic boolean getDoOutput()
public void setAllowUserInteraction(boolean allow)
allow
- true if user interaction should be allowed, false otherwise.IllegalStateException
- If already connectedpublic boolean getAllowUserInteraction()
public static void setDefaultAllowUserInteraction(boolean allow)
allow
- true to allow user interaction, false otherwisepublic static boolean getDefaultAllowUserInteraction()
public void setUseCaches(boolean usecaches)
usecaches
- The new valueIllegalStateException
- If already connectedpublic boolean getUseCaches()
public void setIfModifiedSince(long ifmodifiedsince)
ifmodifiedsince
- The new value in milliseconds
since January 1, 1970 GMTIllegalStateException
- If already connectedpublic long getIfModifiedSince()
public boolean getDefaultUseCaches()
public void setDefaultUseCaches(boolean use)
use
- true to use caches if possible by default, false otherwisepublic void setRequestProperty(String key, String value)
key
- The name of the propertyvalue
- The value of the propertyIllegalStateException
- If already connectedNullPointerException
- If key is nullgetRequestProperty(String key)
,
addRequestProperty(String key, String value)
public void addRequestProperty(String key, String value)
key
- Key of the property to addvalue
- Value of the Property to addIllegalStateException
- If already connectedNullPointerException
- If key is nullgetRequestProperty(String)
,
setRequestProperty(String, String)
public String getRequestProperty(String key)
key
- The name of the propertynull
if key is null.IllegalStateException
- If already connectedsetRequestProperty(String, String)
,
addRequestProperty(String, String)
public Map<String,List<String>> getRequestProperties()
IllegalStateException
- If already connectedpublic static void setDefaultRequestProperty(String key, String value)
key
- The request property name the default is being set forvalue
- The value to set the default tosetRequestProperty(String, String)
public static String getDefaultRequestProperty(String key)
key
- The request property to return the default value ofgetRequestProperty(String)
public static void setContentHandlerFactory(ContentHandlerFactory factory)
factory
- The ContentHandlerFactory for this applicationError
- If the factory has already been definedSecurityException
- If a security manager exists and its
checkSetFactory method doesn't allow the operationpublic static String guessContentTypeFromName(String filename)
filename
- The filename to determine the MIME type forpublic static String guessContentTypeFromStream(InputStream is) throws IOException
NOTE: Overriding MIME types sent from the server can be obnoxious to user's. See Internet Exploder 4 if you don't believe me.
is
- The InputStream to determine the MIME type fromIOException
- If an error occurspublic static FileNameMap getFileNameMap()
FileNameMap
object being used
to decode MIME types by file extension.FileNameMap
.public static void setFileNameMap(FileNameMap map)
FileNameMap
object being used
to decode MIME types by file extension.map
- The FileNameMap
.SecurityException
- If a security manager exists and its
checkSetFactory method doesn't allow the operation