|
|||||||||
| Home >> All >> java >> [ net overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.net
Class URLConnection

java.lang.Objectjava.net.URLConnection
- Direct Known Subclasses:
- HttpURLConnection, JarURLConnection
- public abstract class URLConnection
- extends java.lang.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 |
private static java.text.SimpleDateFormat[] |
dateFormats
|
private static boolean |
dateformats_initialized
|
private static boolean |
defaultAllowUserInteraction
This is the default value that will be used to determine whether or not user interaction should be allowed. |
private static boolean |
defaultUseCaches
This is the default flag indicating whether or not to use caches to store the data returned from a server |
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 |
private static ContentHandlerFactory |
factory
This is the ContentHandlerFactory set by the caller, if any |
private static FileNameMap |
fileNameMap
This is an object that maps filenames to MIME types. |
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. |
private java.text.ParsePosition |
position
|
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(java.lang.String key,
java.lang.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. |
java.lang.Object |
getContent()
This method returns the content of the document pointed to by the URL as an Object. |
java.lang.Object |
getContent(java.lang.Class[] classes)
Retrieves the content of this URLConnection |
java.lang.String |
getContentEncoding()
Returns the value of the content-encoding field or null if it is not known or not present. |
private ContentHandler |
getContentHandler(java.lang.String contentType)
|
int |
getContentLength()
Returns the value of the content-length header field or -1 if the value is not known or not present. |
java.lang.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 java.lang.String |
getDefaultRequestProperty(java.lang.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. |
java.lang.String |
getHeaderField(int index)
Return a String representing the header value at the specified index. |
java.lang.String |
getHeaderField(java.lang.String name)
Returns a String representing the value of the header field having the named key. |
long |
getHeaderFieldDate(java.lang.String name,
long defaultValue)
Returns the value of the named header field as a date. |
int |
getHeaderFieldInt(java.lang.String name,
int defaultValue)
Returns the value of the named header field as an int. |
java.lang.String |
getHeaderFieldKey(int index)
Returns a String representing the header key at the specified index. |
java.util.Map |
getHeaderFields()
Returns a map of all sent header fields |
long |
getIfModifiedSince()
Returns the ifModified since instance variable. |
java.io.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. |
java.io.OutputStream |
getOutputStream()
Returns an OutputStream for this connection. |
java.security.Permission |
getPermission()
This method returns a Permission object representing the
permissions required to access this URL. |
java.util.Map |
getRequestProperties()
Returns an unmodifiable Map containing the request properties. |
java.lang.String |
getRequestProperty(java.lang.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 java.lang.String |
guessContentTypeFromName(java.lang.String filename)
Returns the MIME type of a file based on the name of the file. |
static java.lang.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. |
private static void |
initializeDateFormats()
|
void |
setAllowUserInteraction(boolean allow)
Sets a boolean flag indicating whether or not user interaction is allowed for this connection. |
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(java.lang.String key,
java.lang.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 |
setRequestProperty(java.lang.String key,
java.lang.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. |
java.lang.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 |
fileNameMap
private static FileNameMap fileNameMap
- This is an object that maps filenames to MIME types. The interface
to do this is implemented by this class, so just create an empty
instance and store it here.
factory
private static ContentHandlerFactory factory
- This is the ContentHandlerFactory set by the caller, if any
defaultAllowUserInteraction
private static boolean defaultAllowUserInteraction
- This is the default value that will be used to determine whether or
not user interaction should be allowed.
defaultUseCaches
private static boolean defaultUseCaches
- This is the default flag indicating whether or not to use caches to
store the data returned from a server
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
dateFormats
private static java.text.SimpleDateFormat[] dateFormats
dateformats_initialized
private static boolean dateformats_initialized
position
private java.text.ParsePosition position
| 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.
| Method Detail |
connect
public abstract void connect()
throws java.io.IOException
- Establishes the actual connection to the URL associated with this
connection object
getURL
public URL getURL()
- Returns the URL object associated with this connection
getContentLength
public int getContentLength()
- Returns the value of the content-length header field or -1 if the value
is not known or not present.
getContentType
public java.lang.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()
getContentEncoding
public java.lang.String getContentEncoding()
- Returns the value of the content-encoding field or null if it is not
known or not present.
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.
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.
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.
getHeaderField
public java.lang.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
getHeaderField
public java.lang.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.
getHeaderFields
public java.util.Map getHeaderFields()
- Returns a map of all sent header fields
- Since:
- 1.4
getHeaderFieldInt
public int getHeaderFieldInt(java.lang.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.
getHeaderFieldDate
public long getHeaderFieldDate(java.lang.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.
getHeaderFieldKey
public java.lang.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.
getContent
public java.lang.Object getContent() throws java.io.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 implementsImageProducer. 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
ContentHandlerFactoryis 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 theInputStreamreturned bygetInputStream(). Note that the default implementation ofgetInputStream()throws aUnknownServiceExceptionso subclasses are encouraged to override this method.
getContent
public java.lang.Object getContent(java.lang.Class[] classes) throws java.io.IOException
- Retrieves the content of this URLConnection
getPermission
public java.security.Permission getPermission() throws java.io.IOException
- This method returns a
Permissionobject representing the permissions required to access this URL. This method returnsjava.security.AllPermissionby default. Subclasses should override it to return a more specific permission. For example, an HTTP URL should return an instance ofSocketPermissionfor 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.
getInputStream
public java.io.InputStream getInputStream() throws java.io.IOException
- Returns an InputStream for this connection. As this default
implementation returns null, subclasses should override this method
getOutputStream
public java.io.OutputStream getOutputStream() throws java.io.IOException
- Returns an OutputStream for this connection. As this default
implementation returns null, subclasses should override this method
toString
public java.lang.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()
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.
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.
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
getDoOutput
public boolean getDoOutput()
- Returns a boolean flag indicating whether or not output will be done
on this connection. This defaults to false.
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.
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.
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
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
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.
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.
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.
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
getDefaultUseCaches
public boolean getDefaultUseCaches()
- Returns the default value used to determine whether or not caching
of documents will be done when possible.
setDefaultUseCaches
public void setDefaultUseCaches(boolean use)
- Sets the default value used to determine whether or not caching
of documents will be done when possible.
setRequestProperty
public void setRequestProperty(java.lang.String key, java.lang.String value)
- Sets the value of the named request property
- Since:
- 1.4
addRequestProperty
public void addRequestProperty(java.lang.String key, java.lang.String value)
- Adds a new request property by a key/value pair.
This method does not overwrite existing properties with the same key.
- Since:
- 1.4
getRequestProperty
public java.lang.String getRequestProperty(java.lang.String key)
- Returns the value of the named request property.
getRequestProperties
public java.util.Map getRequestProperties()
- Returns an unmodifiable Map containing the request properties.
- Since:
- 1.4
setDefaultRequestProperty
public static void setDefaultRequestProperty(java.lang.String key, java.lang.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.
- Sets the default value of a request property. This will be used for all connections unless the value of the property is manually overridden.
getDefaultRequestProperty
public static java.lang.String getDefaultRequestProperty(java.lang.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.
- Returns the default value of a request property. This will be used for all connections unless the value of the property is manually overridden.
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.
guessContentTypeFromName
public static java.lang.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.
guessContentTypeFromStream
public static java.lang.String guessContentTypeFromStream(java.io.InputStream is) throws java.io.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.
getFileNameMap
public static FileNameMap getFileNameMap()
- This method returns the
FileNameMapobject being used to decode MIME types by file extension.- Since:
- 1.2
setFileNameMap
public static void setFileNameMap(FileNameMap map)
- This method sets the
FileNameMapobject being used to decode MIME types by file extension.- Since:
- 1.2
getContentHandler
private ContentHandler getContentHandler(java.lang.String contentType)
initializeDateFormats
private static void initializeDateFormats()
|
|||||||||
| Home >> All >> java >> [ net overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
JAVADOC
java.net.URLConnection