This abstract class defines a network
connection to an object specified by a URL.
URL.openConnection( ) returns a
URLConnection instance. You should use a
URLConnection object when you want more control
over the downloading of data than is available through the simpler
URL methods. connect( )
actually establishes the network connection. Some methods must be
called before the connection is made, and others depend on being
connected. The methods that depend on being connected call
connect( ) themselves if no connection exists yet,
so you never need to call this method explicitly. The
getContent( ) methods are just like the same-named
methods of the URL class: they download the data
referred to by the URL and parse it into an appropriate type of
object (such as a string or an image). In Java 1.3 and later, there
is a version of getContent( ) that allows you to
specify the types of parsed objects that you are willing to accept by
passing an array of Class objects. If you prefer
to parse the URL content yourself instead of calling
getContent( ), you can call
getInputStream( ) (and getOutputStream(
) if the URL protocol supports writing) to obtain a stream
through which you can read (or write) data from (or to) the resource
identified by the URL.
Before a connection is established, you may want to set request
fields (such as HTTP request headers) to refine the URL request. Use
setRequestProperty( ) to set a new value for a
named header. In Java 1.4 and later, you can use
addRequestProperty( ) to add a new comma-separated
item to an existing header. Java 1.4 also added
geTRequestProperties( ), a method that returns the
current set of request properties in the form of an unmodifiable
Map object that maps request header names to
List objects that contain the string value or
values for the named header.
Once a connection has been established, there
are a number of methods you can call to obtain information from the
"response headers" of the URL.
getContentLength( ), getContentType(
), getContentEncoding( ),
getExpiration( ), getdate( ),
and getLastModified( ) return the appropriate
information about the object referred to by the URL, if that
information can be determined (e.g., from HTTP header fields).
getHeaderField(
) returns an HTTP header field specified by
name or by number. getHeaderFieldInt(
) and getHeaderFieldDate( )
return the value of a named header field parsed as an integer or a
date. In Java 1.4 and later, getHeaderFields(
) returns an unmodifiable
Map object that maps response header names to an
unmodifiable List that contains the string value
or values for the named header.
There are a number of options you can specify to control how the
URLConnection behaves. These options are set with
the various set( ) methods and may be queried with
corresponding get( ) methods. The options must be
set before the connect( ) method is called.
setDoInput( )
and setDoOutput(
) allow you to specify whether you are using the
URLConnection for input and/or output (input-only
by default). setAllowUserInteraction(
) specifies whether user interaction (such as
typing a password) is allowed during the data transfer
(false by default).
setDefaultAllowUserInteraction(
) is a class method that allows you to change
the default value for user interaction. setUseCaches(
)
allows you to specify whether a cached version of the URL can be
used. You can set this to false to force a URL to
be reloaded. setDefaultUseCaches(
) sets the default value for
setUseCaches( ). setIfModifiedSince(
) allows you to specify that a URL should
not be fetched unless it has been modified since a specified time (if
it is possible to determine its modification date). In
Java 5.0 and later, you can specify
how long a URLConnection should wait while
connecting or reading data with setConnectTimeout(
)
and setReadTimeout( ).
public abstract class
URLConnection {
// Protected Constructors
protected
URLConnection (URL
url );
// Public Class Methods
public static boolean
getDefaultAllowUserInteraction ( );
1.1 public static FileNameMap
getFileNameMap ( ); synchronized
public static String
guessContentTypeFromName (String
fname );
public static String
guessContentTypeFromStream (java.io.InputStream
is )
throws java.io.IOException;
public static void
setContentHandlerFactory (ContentHandlerFactory
fac ); synchronized
public static void
setDefaultAllowUserInteraction (boolean
defaultallowuserinteraction );
1.1 public static void
setFileNameMap (FileNameMap
map );
// Public Instance Methods
1.4 public void
addRequestProperty (String
key , String
value );
public abstract void
connect ( ) throws java.io.IOException;
public boolean
getAllowUserInteraction ( );
5.0 public int
getConnectTimeout ( );
public Object
getContent ( ) throws java.io.IOException;
1.3 public Object
getContent (Class[ ]
classes ) throws java.io.IOException;
public String
getContentEncoding ( );
public int
getContentLength ( );
public String
getContentType ( );
public long
getDate ( );
public boolean
getDefaultUseCaches ( );
public boolean
getDoInput ( );
public boolean
getDoOutput ( );
public long
getExpiration ( );
public String
getHeaderField (int
n ); constant
public String
getHeaderField (String
name ); constant
public long
getHeaderFieldDate (String
name , long
Default );
public int
getHeaderFieldInt (String
name , int
Default );
public String
getHeaderFieldKey (int
n ); constant
1.4 public java.util.Map<String,java.util.List<String>>
getHeaderFields ( );
public long
getIfModifiedSince ( );
public java.io.InputStream
getInputStream ( ) throws java.io.IOException;
public long
getLastModified ( );
public java.io.OutputStream
getOutputStream ( ) throws java.io.IOException;
1.2 public java.security.Permission
getPermission ( )
throws java.io.IOException;
5.0 public int
getReadTimeout ( );
1.4 public java.util.Map<String,java.util.List<String>>
getRequestProperties ( );
public String
getRequestProperty (String
key );
public URL
getURL ( );
public boolean
getUseCaches ( );
public void
setAllowUserInteraction (boolean
allowuserinteraction );
5.0 public void
setConnectTimeout (int
timeout );
public void
setDefaultUseCaches (boolean
defaultusecaches );
public void
setDoInput (boolean
doinput );
public void
setDoOutput (boolean
dooutput );
public void
setIfModifiedSince (long
ifmodifiedsince );
5.0 public void
setReadTimeout (int
timeout );
public void
setRequestProperty (String
key , String
value );
public void
setUseCaches (boolean
usecaches );
// Public Methods Overriding Object
public String
toString ( );
// Protected Instance Fields
protected boolean
allowUserInteraction ;
protected boolean
connected ;
protected boolean
doInput ;
protected boolean
doOutput ;
protected long
ifModifiedSince ;
protected URL
url ;
protected boolean
useCaches ;
// Deprecated Public Methods
# public static String
getDefaultRequestProperty (String
key ); constant
# public static void
setDefaultRequestProperty (String
key ,
String
value ); empty
}