java.net
Class URLConnection

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

public abstract class URLConnection

extends Object

A class to represent an active connection to an object represented by a URL. It is an abstract class that must be subclassed to implement a connection.

Field Summary

protected boolean	allowUserInteraction
protected boolean	connected
protected boolean	doInput
protected boolean	doOutput
protected long	ifModifiedSince
protected URL	url
protected boolean	useCaches

Constructor Summary

protected

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

Method Summary

abstract void	connect() URLConnection objects go through two phases: first they are created, then they are connected.
boolean	getAllowUserInteraction()
Object	getContent() Gets the object referred to by this URL.
String	getContentEncoding() Gets the content encoding.
int	getContentLength() Gets the content length.
String	getContentType() Gets the content type.
long	getDate() Gets the sending date of the object.
static boolean	getDefaultAllowUserInteraction()
static String	getDefaultRequestProperty(String key)
boolean	getDefaultUseCaches() Sets/gets the default value of the UseCaches flag.
boolean	getDoInput()
boolean	getDoOutput()
long	getExpiration() Gets the expriation date of the object.
String	getHeaderField(int n) Returns the value for the nth header field.
String	getHeaderField(String name) Gets a header field by name.
long	getHeaderFieldDate(String name, long Default) Gets a header field by name.
int	getHeaderFieldInt(String name, int Default) Gets a header field by name.
String	getHeaderFieldKey(int n) Returns the key for the nth header field.
long	getIfModifiedSince()
InputStream	getInputStream() Calls this routine to get an InputStream that reads from the object.
long	getLastModified() Gets the last modified date of the object.
OutputStream	getOutputStream() Calls this routine to get an OutputStream that writes to the object.
String	getRequestProperty(String key)
URL	getURL() Gets the URL for this connection.
boolean	getUseCaches()
protected static String	guessContentTypeFromName(String fname) A useful utility routine that tries to guess the content-type of an object based upon its extension.
protected static String	guessContentTypeFromStream(InputStream is) This method is used to check for files that have some type that can be determined by inspection.
void	setAllowUserInteraction(boolean allowuserinteraction) Some URL connections occasionally need to to interactions with the user.
static void	setContentHandlerFactory(ContentHandlerFactory fac) Sets the ContentHandler factory.
static void	setDefaultAllowUserInteraction(boolean defaultallowuserinteraction) Sets/gets the default value of the allowUserInteraction flag.
static void	setDefaultRequestProperty(String key, String value) Sets/gets the default value of a general request property.
void	setDefaultUseCaches(boolean defaultusecaches)
void	setDoInput(boolean doinput) A URL connection can be used for input and/or output.
void	setDoOutput(boolean dooutput) A URL connection can be used for input and/or output.
void	setIfModifiedSince(long ifmodifiedsince) Some protocols support skipping fetching unless the object is newer than some amount of time.
void	setRequestProperty(String key, String value) Sets/gets a general request property.
void	setUseCaches(boolean usecaches) Some protocols do caching of documents.
String	toString() Returns the String representation of the 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

doInput

protected boolean doInput

doOutput

protected boolean doOutput

allowUserInteraction

protected boolean allowUserInteraction

useCaches

protected boolean useCaches

ifModifiedSince

protected long ifModifiedSince

connected

protected boolean connected

Constructor Detail

URLConnection

protected URLConnection(URL url)

Constructs a URL connection to the specified URL.

Parameters:

url - the specified URL

Method Detail

connect

public abstract void connect()
                      throws IOException

URLConnection objects go through two phases: first they are created, then they are connected. After being created, and before being connected, various options can be specified (eg. doInput, UseCaches, ...). After connecting, it is an Error to try to set them. Operations that depend on being connected, like getContentLength, will implicitly perform the connection if necessary. Connecting when already connected does nothing.

IOException

getURL

public URL getURL()

Gets the URL for this connection.

getContentLength

public int getContentLength()

Gets the content length. Returns -1 if not known.

getContentType

public String getContentType()

Gets the content type. Returns null if not known.

getContentEncoding

public String getContentEncoding()

Gets the content encoding. Returns null if not known.

getExpiration

public long getExpiration()

Gets the expriation date of the object. Returns 0 if not known.

getDate

public long getDate()

Gets the sending date of the object. Returns 0 if not known.

getLastModified

public long getLastModified()

Gets the last modified date of the object. Returns 0 if not known.

getHeaderField

public String getHeaderField(String name)

Gets a header field by name. Returns null if not known.

Parameters:

name - the name of the header field

getHeaderFieldInt

public int getHeaderFieldInt(String name,
                             int Default)

Gets a header field by name. Returns null if not known. The field is parsed as an integer. This form of getHeaderField exists because some connection types (e.g. http-ng) have pre-parsed headers and this allows them to override this method and short-circuit the parsing.

Parameters:

name - the name of the header field

Default - the value to return if the field is missing or malformed.

getHeaderFieldDate

public long getHeaderFieldDate(String name,
                               long Default)

Gets a header field by name. Returns null if not known. The field will be parsed as a date. This form of getHeaderField exists because some connection types (eg. http-ng) have pre-parsed headers. This allows them to override this method and short-circuit the parsing.

Parameters:

name - the name of the header field

Default - the value to return if the field is missing or malformed.

getHeaderFieldKey

public String getHeaderFieldKey(int n)

Returns the key for the nth header field. Returns null if there are fewer than n fields. This can be used to iterate through all the headers in the message.

getHeaderField

public String getHeaderField(int n)

Returns the value for the nth header field. Returns null if there are fewer than n fields. This can be used in conjunction with getHeaderFieldKey to iterate through all the headers in the message.

getContent

public Object getContent()
                  throws IOException

Gets the object referred to by this URL. For example, if it refers to an image the object will be some subclass of Image. The instanceof operator should be used to determine what kind of object was returned.

Returns:

the object that was fetched.

Throws:

UnknownServiceException - If the protocol does not support content.

IOException

getInputStream

public InputStream getInputStream()
                           throws IOException

Calls this routine to get an InputStream that reads from the object. Protocol implementors should use this if appropriate.

Throws:

UnknownServiceException - If the protocol does not support input.

IOException

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Calls this routine to get an OutputStream that writes to the object. Protocol implementors should use this if appropriate.

Throws:

UnknownServiceException - If the protocol does not support output.

IOException

toString

public String toString()

Returns the String representation of the URL connection.

Overrides:

toString in class Object

setDoInput

public void setDoInput(boolean doinput)

A URL connection can be used for input and/or output. Set the DoInput flag to true if you intend to use the URL connection for input, false if not. The default is true unless DoOutput is explicitly set to true, in which case DoInput defaults to false.

getDoInput

public boolean getDoInput()

setDoOutput

public void setDoOutput(boolean dooutput)

A URL connection can be used for input and/or output. Set the DoOutput flag to true if you intend to use the URL connection for output, false if not. The default is false.

getDoOutput

public boolean getDoOutput()

setAllowUserInteraction

public void setAllowUserInteraction(boolean allowuserinteraction)

Some URL connections occasionally need to to interactions with the user. For example, the http protocol may need to pop up an authentication dialog. But this is only appropriate if the application is running in a context where there is a user. The allowUserInteraction flag allows these interactions when true. When it is false, they are not allowed and an exception is tossed. The default value can be set/gotten using setDefaultAllowUserInteraction, which defaults to false.

getAllowUserInteraction

public boolean getAllowUserInteraction()

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean defaultallowuserinteraction)

Sets/gets the default value of the allowUserInteraction flag. This default is "sticky", being a part of the static state of all URLConnections. This flag applies to the next, and all following URLConnections that are created.

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()

setUseCaches

public void setUseCaches(boolean usecaches)

Some protocols do caching of documents. Occasionally, it is important to be able to "tunnel through" and ignore the caches (e.g. the "reload" button in a browser). If the UseCaches flag on a connection is true, the connection is allowed to use whatever caches it can. If false, caches are to be ignored. The default value comes from DefaultUseCaches, which defaults to true.

getUseCaches

public boolean getUseCaches()

setIfModifiedSince

public void setIfModifiedSince(long ifmodifiedsince)

Some protocols support skipping fetching unless the object is newer than some amount of time. The ifModifiedSince field may be set/gotten to define this time.

getIfModifiedSince

public long getIfModifiedSince()

getDefaultUseCaches

public boolean getDefaultUseCaches()

Sets/gets the default value of the UseCaches flag. This default is "sticky", being a part of the static state of all URLConnections. This flag applies to the next, and all following, URLConnections that are created.

setDefaultUseCaches

public void setDefaultUseCaches(boolean defaultusecaches)

setRequestProperty

public void setRequestProperty(String key,
                               String value)

Sets/gets a general request property.

Parameters:

key - The keyword by which the request is known (eg "accept")

value - The value associated with it.

getRequestProperty

public String getRequestProperty(String key)

setDefaultRequestProperty

public static void setDefaultRequestProperty(String key,
                                             String value)

Sets/gets the default value of a general request property. When a URLConnection is created, it is initialized with these properties.

Parameters:

key - The keyword by which the request is known (eg "accept")

value - The value associated with it.

getDefaultRequestProperty

public static String getDefaultRequestProperty(String key)

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory fac)

Sets the ContentHandler factory.

Parameters:

fac - the desired factory

Throws:

Error - If the factory has already been defined.

guessContentTypeFromName

protected static String guessContentTypeFromName(String fname)

A useful utility routine that tries to guess the content-type of an object based upon its extension.

guessContentTypeFromStream

protected static String guessContentTypeFromStream(InputStream is)
                                            throws IOException

This method is used to check for files that have some type that can be determined by inspection. The bytes at the beginning of the file are examined loosely. In an ideal world, this routine would not be needed, but in a world where http servers lie about content-types and extensions are often non-standard, direct inspection of the bytes can make the system more robust. The stream must support marks (e.g. have a BufferedInputStream somewhere).

IOException