Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> java >> [ net overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of java.net.URLConnection JAVADOC | Sourc code of java.net.URLConnection SOURCE | Download java.net.URLConnection DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

java.net
Class URLConnection  view URLConnection download URLConnection.java

java.lang.Object
  extended byjava.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 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.

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 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.

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.

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.

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 FileNameMap object being used to decode MIME types by file extension.

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.

Since:
1.2

getContentHandler

private ContentHandler getContentHandler(java.lang.String contentType)

initializeDateFormats

private static void initializeDateFormats()
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> java >> [ net overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of java.net.URLConnection JAVADOC | Sourc code of java.net.URLConnection SOURCE | Download java.net.URLConnection DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD