All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object | +----java.net.URLConnection
URLConnection
is the superclass
of all classes that represent a communications link between the
application and a URL. Instances of this class can be used both to
read from and to write to the resource referenced by the URL. In
general, creating a connection to a URL is a multistep process:
openConnection() |
connect() |
---|---|
Manipulate parameters that affect the connection to the remote resource. | Interact with the resource; query header fields and contents. |
openConnection
method on a URL.
connect
method.
The setup parameters are modified using the following methods:
- setAllowUserInteraction
- setDoInput
- setDoOutput
- setIfModifiedSince
- setUseCaches
and the general request properties are modified using the method:
- setRequestProperty
Default values for the AllowUserInteraction
and
UseCaches
parameters can be set using the methods
setDefaultAllowUserInteraction
and
setDefaultUseCaches
. Default values for general
request properties can be set using the
setDefaultRequestProperty
method.
Each of the above set
methods has a corresponding
get
method to retrieve the value of the parameter or
general request property. The specific parameters and general
request properties that are applicable are protocol specific.
The following methods are used to access the header fields and the contents after the connection is made to the remote object:
- getContent
- getHeaderField
- getInputStream
- getOutputStream
Certain header fields are accessed frequently. The methods:
- getContentEncoding
- getContentLength
- getContentType
- getDate
- getExpiration
- getLastModified
provide convenient access to these fields. The
getContentType
method is used by the
getContent
method to determine the type of the remote
object; subclasses may find it convenient to override the
getContentType
method.
In the common case, all of the pre-connection parameters and
general request properties can be ignored: the pre-connection
parameters and request properties default to sensible values. For
most clients of this interface, there are only two interesting
methods: getInputStream
and getObject
,
which are mirrored in the URL
class by convenience methods.
More information on the request properties and header fields of
an http
connection can be found at:
http://www.w3.org/hypertext/WWW/Protocols/HTTP1.0/draft-ietf-http-spec.html
Note about fileNameMap
: In versions prior to JDK 1.1.6,
field fileNameMap
of URLConnection
was public.
In JDK 1.1.6 and later, fileNameMap
is private; accessor
method getFileNameMap()
and mutator method
setFileNameMap(FileNameMap)
are added to access it.
This change is also described on the
JDK 1.1.x Compatibility page.
true
, this URL
is being examined in
a context in which it makes sense to allow user interactions such
as popping up an authentication dialog.
false
, this connection object has not created a
communications link to the specified URL.
setDoInput
method.
setDoOutput
method.
true
, the protocol is allowed to use caching
whenever it can.
allowUserInteraction
field for
this object.
content-encoding
header field.
content-length
header field.
content-type
header field.
date
header field.
allowUserInteraction
field.
URLConnection
's
useCaches
flag.
URLConnection
's
doInput
flag.
URLConnection
's
doOutput
flag.
expires
header field.
n
th header field.
n
th header field.
ifModifiedSince
field.
last-modified
header field.
URLConnection
's URL
field.
URLConnection
's
useCaches
field.
allowUserInteraction
field of
this URLConnection
.
ContentHandlerFactory
of an
application.
allowUserInteraction
field for all future
URLConnection
objects to the specified value.
useCaches
field to the
specified value.
doInput
field for this
URLConnection
to the specified value.
doOutput
field for this
URLConnection
to the specified value.
ifModifiedSince
field of
this URLConnection
to the specified value.
useCaches
field of this
URLConnection
to the specified value.
String
representation of this URL connection.
protected URL url
The value of this field can be accessed by the
getURL
method.
The default value of this variable is the value of the URL
argument in the URLConnection
constructor.
protected boolean doInput
setDoInput
method. Its
value is returned by the getDoInput
method.
A URL connection can be used for input and/or output. Setting the
doInput
flag to true
indicates that
the application intends to read data from the URL connection.
The default value of this field is true
.
protected boolean doOutput
setDoOutput
method. Its
value is returned by the getDoInput
method.
A URL connection can be used for input and/or output. Setting the
doOutput
flag to true
indicates
that the application intends to write data to the URL connection.
The default value of this field is false
.
protected boolean allowUserInteraction
true
, this URL
is being examined in
a context in which it makes sense to allow user interactions such
as popping up an authentication dialog. If false
,
then no user interaction is allowed.
The value of this field can be set by the
setAllowUserInteraction
method.
Its value is returned by the
getAllowUserInteraction
method.
Its default value is the value of the argument in the last invocation
of the setDefaultAllowUserInteraction
method.
protected boolean useCaches
true
, the protocol is allowed to use caching
whenever it can. If false
, the protocol must always
try to get a fresh copy of the object.
This field is set by the setUseCaches
method. Its
value is returned by the getUseCaches
method.
Its default value is the value given in the last invocation of the
setDefaultUseCaches
method.
protected long ifModifiedSince
A nonzero value gives a time as the number of seconds since January 1, 1970, GMT. The object is fetched only if it has been modified more recently than that time.
This variable is set by the setIfModifiedSince
method. Its value is returned by the
getIfModifiedSince
method.
The default value of this field is 0
, indicating
that the fetching must always occur.
protected boolean connected
false
, this connection object has not created a
communications link to the specified URL. If true
,
the communications link has been established.
protected URLConnection(URL url)
public static FileNameMap getFileNameMap()
public static void setFileNameMap(FileNameMap map)
public abstract void connect() throws IOException
If the connect
method is called when the connection
has already been opened (indicated by the connected
field having the value true
), the call is ignored.
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 (e.g., doInput and 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.
public URL getURL()
URLConnection
's URL
field.
URLConnection
's URL
field.
public int getContentLength()
content-length
header field.
-1
if the content length is
not known.
public String getContentType()
content-type
header field.
null
if not known.
public String getContentEncoding()
content-encoding
header field.
null
if not known.
public long getExpiration()
expires
header field.
public long getDate()
date
header field.
0
if not known. The value returned is the
number of seconds since January 1, 1970 GMT.
public long getLastModified()
last-modified
header field.
The result is the number of seconds since January 1, 1970 GMT.
URLConnection
was last modified, or 0 if not known.
public String getHeaderField(String name)
null
if there is no such field in the header.
public int getHeaderFieldInt(String name, int Default)
This form of getHeaderField
exists because some
connection types (e.g., http-ng
) have pre-parsed
headers. Classes for that connection type can override this method
and short-circuit the parsing.
Default
value is returned if the field is
missing or malformed.
public long getHeaderFieldDate(String name, long Default)
This form of getHeaderField
exists because some
connection types (e.g., http-ng
) have pre-parsed
headers. Classes for that connection type can override this method
and short-circuit the parsing.
Default
argument is returned if the field is
missing or malformed.
public String getHeaderFieldKey(int n)
n
th header field.
n
th header field,
or null
if there are fewer than n
fields.
public String getHeaderField(int n)
n
th header field.
It returns null
if there are fewer than
n
fields.
This method can be used in conjunction with the
getHeaderFieldKey
method to iterate through all
the headers in the message.
n
th header field.
public Object getContent() throws IOException
This method first determines the content type of the object by
calling the getContentType
method. If this is
the first time that the application has seen that specific content
type, a content handler for that content type is created:
setContentHandlerFactory
method, the
createContentHandler
method of that instance is called
with the content type as an argument; the result is a content
handler for that content type.
createContentHandler
method returns
null
, then the application loads the class named:
sun.net.www.content.<contentType>
period
('.'), and all other non-alphanumeric characters
with the underscore character '_
'. The alphanumeric
characters are specifically the 26 uppercase ASCII letters
'A
' through 'Z
', the 26 lowercase ASCII
letters 'a
' through 'z
', and the 10 ASCII
digits '0
' through '9
'. If the specified
class does not exist, or is not a subclass of
ContentHandler
, then an
UnknownServiceException
is thrown.
instanceOf
operation
should be used to determine the specific kind of object
returned.
public InputStream getInputStream() throws IOException
public OutputStream getOutputStream() throws IOException
public String toString()
String
representation of this URL connection.
URLConnection
.
public void setDoInput(boolean doinput)
doInput
field for this
URLConnection
to the specified value.
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.
public boolean getDoInput()
URLConnection
's
doInput
flag.
URLConnection
's
doInput
flag.
public void setDoOutput(boolean dooutput)
doOutput
field for this
URLConnection
to the specified value.
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.
public boolean getDoOutput()
URLConnection
's
doOutput
flag.
URLConnection
's
doOutput
flag.
public void setAllowUserInteraction(boolean allowuserinteraction)
allowUserInteraction
field of
this URLConnection
.
public boolean getAllowUserInteraction()
allowUserInteraction
field for
this object.
allowUserInteraction
field for
this object.
public static void setDefaultAllowUserInteraction(boolean defaultallowuserinteraction)
allowUserInteraction
field for all future
URLConnection
objects to the specified value.
public static boolean getDefaultAllowUserInteraction()
allowUserInteraction
field.
Ths 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.
allowUserInteraction
field.
public void setUseCaches(boolean usecaches)
useCaches
field of this
URLConnection
to the specified value.
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.
public boolean getUseCaches()
URLConnection
's
useCaches
field.
URLConnection
's
useCaches
field.
public void setIfModifiedSince(long ifmodifiedsince)
ifModifiedSince
field of
this URLConnection
to the specified value.
public long getIfModifiedSince()
ifModifiedSince
field.
ifModifiedSince
field.
public boolean getDefaultUseCaches()
URLConnection
's
useCaches
flag.
Ths 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.
URLConnection
's
useCaches
flag.
public void setDefaultUseCaches(boolean defaultusecaches)
useCaches
field to the
specified value.
public void setRequestProperty(String key, String value)
accept
").
public String getRequestProperty(String key)
public static void setDefaultRequestProperty(String key, String value)
URLConnection
is created, it is initialized with
these properties.
accept
").
public static String getDefaultRequestProperty(String key)
public static synchronized void setContentHandlerFactory(ContentHandlerFactory fac)
ContentHandlerFactory
of an
application. It can be called at most once by an application.
The ContentHandlerFactory
instance is used to
construct a content handler from a content type
protected static String guessContentTypeFromName(String fname)
getContentType
method.
public static String guessContentTypeFromStream(InputStream is) throws IOException
getContentType
method.
Ideally, this routine would not be needed. But many
http
servers return the incorrect content type; in
addition, there are many nonstandard extensions. Direct inspection
of the bytes to determine the content type is often more accurate
than believing the content type claimed by the http
server.
null
if none
can be determined.
All Packages Class Hierarchy This Package Previous Next Index