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
}
