URL
represents a Uniform Resource
Locator, a pointer to a "resource" on the World
Wide Web. A resource can be something as simple as a file or a
directory, or it can be a reference to a more complicated object,
such as a query to a database or to a search engine. More
information on the types of URLs and their formats can be found at:
http://archive.ncsa.uiuc.edu/SDG/Software/Mosaic/Demo/url-primer.html
In general, a URL can be broken into several parts. The previous
example of a URL indicates that the protocol to use is
http
(HyperText Transfer Protocol) and that the
information resides on a host machine named
www.ncsa.uiuc.edu
. The information on that host
machine is named /SDG/Software/Mosaic/Demo/url-primer.html
. The exact
meaning of this name on the host machine is both protocol
dependent and host dependent. The information normally resides in
a file, but it could be generated on the fly. This component of
the URL is called the path component.
A URL can optionally specify a "port", which is the
port number to which the TCP connection is made on the remote host
machine. If the port is not specified, the default port for
the protocol is used instead. For example, the default port for
http
is 80
. An alternative port could be
specified as:
http://archive.ncsa.uiuc.edu:80/SDG/Software/Mosaic/Demo/url-primer.html
The syntax of URL
is defined by RFC 2396: Uniform
Resource Identifiers (URI): Generic Syntax, amended by RFC 2732: Format for
Literal IPv6 Addresses in URLs. The Literal IPv6 address format
also supports scope_ids. The syntax and usage of scope_ids is described
here.
A URL may have appended to it a "fragment", also known as a "ref" or a "reference". The fragment is indicated by the sharp sign character "#" followed by more characters. For example,
http://java.sun.com/index.html#chapter1
This fragment is not technically part of the URL. Rather, it
indicates that after the specified resource is retrieved, the
application is specifically interested in that part of the
document that has the tag chapter1
attached to it. The
meaning of a tag is resource specific.
An application can also specify a "relative URL", which contains only enough information to reach the resource relative to another URL. Relative URLs are frequently used within HTML pages. For example, if the contents of the URL:
contained within it the relative URL:http://java.sun.com/index.html
it would be a shorthand for:FAQ.html
http://java.sun.com/FAQ.html
The relative URL need not specify all the components of a URL. If the protocol, host name, or port number is missing, the value is inherited from the fully specified URL. The file component must be specified. The optional fragment is not inherited.
The URL class does not itself encode or decode any URL components
according to the escaping mechanism defined in RFC2396. It is the
responsibility of the caller to encode any fields, which need to be
escaped prior to calling URL, and also to decode any escaped fields,
that are returned from URL. Furthermore, because URL has no knowledge
of URL escaping, it does not recognise equivalence between the encoded
or decoded form of the same URL. For example, the two URLs:
http://foo.com/hello world/ and http://foo.com/hello%20worldwould be considered not equal to each other.
Note, the java.net.URI class does perform escaping of its component fields in certain circumstances. The recommended way to manage the encoding and decoding of URLs is to use java.net.URI , and to convert between these two classes using and .
The URLEncoder and URLDecoder classes can also be used, but only for HTML form encoding, which is not the same as the encoding scheme defined in RFC2396.
URL
object from the specified
protocol
, host
, port
number, and file
.
host
can be expressed as a host name or a literal
IP address. If IPv6 literal address is used, it should be
enclosed in square brackets ('[' and ']'), as
specified by RFC 2732;
However, the literal IPv6 address format defined in RFC 2373: IP
Version 6 Addressing Architecture is also accepted.
Specifying a port
number of -1
indicates that the URL should use the default port for the
protocol.
If this is the first URL object being created with the specified
protocol, a stream protocol handler object, an instance of
class URLStreamHandler
, is created for that protocol:
URLStreamHandlerFactory
as the stream handler factory,
then the createURLStreamHandler
method of that instance
is called with the protocol string as an argument to create the
stream protocol handler.
URLStreamHandlerFactory
has yet been set up,
or if the factory's createURLStreamHandler
method
returns null
, then the constructor finds the
value of the system property:
If the value of that system property is notjava.protocol.handler.pkgs
null
,
it is interpreted as a list of packages separated by a vertical
slash character '|
'. The constructor tries to load
the class named:
where <package> is replaced by the name of the package and <protocol> is replaced by the name of the protocol. If this class does not exist, or if the class exists but it is not a subclass of<package>.<protocol>.Handler
URLStreamHandler
, then the next package
in the list is tried.
If this class does not exist, or if the class exists but it is not a subclass of<system default package>.<protocol>.Handler
URLStreamHandler
, then a
MalformedURLException
is thrown.
Protocol handlers for the following protocols are guaranteed to exist on the search path :-
Protocol handlers for additional protocols may also be available.http, https, ftp, file, and jar
No validation of the inputs is performed by this constructor.
protocol
name, host
name, and file
name. The
default port for the specified protocol is used.
This method is equivalent to calling the four-argument
constructor with the arguments being protocol
,
host
, -1
, and file
.
No validation of the inputs is performed by this constructor.
URL
object from the specified
protocol
, host
, port
number, file
, and handler
. Specifying
a port
number of -1
indicates that
the URL should use the default port for the protocol. Specifying
a handler
of null
indicates that the URL
should use a default stream handler for the protocol, as outlined
for:
java.net.URL#URL(java.lang.String, java.lang.String, int,
java.lang.String)
If the handler is not null and there is a security manager,
the security manager's checkPermission
method is called with a
NetPermission("specifyStreamHandler")
permission.
This may result in a SecurityException.
No validation of the inputs is performed by this constructor.
URL
object from the String
representation.
This constructor is equivalent to a call to the two-argument
constructor with a null
first argument.
The reference is parsed into the scheme, authority, path, query and fragment parts. If the path component is empty and the scheme, authority, and query components are undefined, then the new URL is a reference to the current document. Otherwise, the fragment and query parts present in the spec are used in the new URL.<scheme>://<authority><path>?<query>#<fragment>
If the scheme component is defined in the given spec and does not match the scheme of the context, then the new URL is created as an absolute URL based on the spec alone. Otherwise the scheme component is inherited from the context URL.
If the authority component is present in the spec then the spec is treated as absolute and the spec authority and path will replace the context authority and path. If the authority component is absent in the spec then the authority of the new URL will be inherited from the context.
If the spec's path component begins with a slash character "/" then the path is treated as absolute and the spec path replaces the context path.
Otherwise, the path is treated as a relative path and is appended to the context path, as described in RFC2396. Also, in this case, the path is canonicalized through the removal of directory changes made by occurences of ".." and ".".
For a more detailed description of URL parsing, refer to RFC2396.
If the given object is not a URL then this method immediately returns
false
.
Two URL objects are equal if they have the same protocol, reference equivalent hosts, have the same port number on the host, and the same file and fragment of the file.
Two hosts are considered equivalent if both host names can be resolved into the same IP addresses; else if either host name can't be resolved, the host names must be equal without regard to case; or both host names equal to null.
Since hosts comparison requires name resolution, this operation is a blocking operation.
Note: The defined behavior for equals
is known to
be inconsistent with virtual hosting in HTTP.
URL
.openConnection().getContent()
openConnection().getContent(Class[])
URL
. If the URL scheme or the URLStreamHandler
for the URL do not define a default port number,
then -1 is returned.URL
.
The returned file portion will be
the same as getPath()
, plus the concatenation of
the value of getQuery()
, if any. If there is
no query portion, this method and getPath()
will
return identical results.URL
, if applicable.
The format of the host conforms to RFC 2732, i.e. for a
literal IPv6 address, this method will return the IPv6 address
enclosed in square brackets ('[' and ']').URL
.URL
.URL
.URL
.URL
.URL
.The hash code is based upon all the URL components relevant for URL comparison. As such, this operation is a blocking operation.
wait
methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized
statement
that synchronizes on the object.
Class,
by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait
methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify
method for a
description of the ways in which a thread can become the owner of
a monitor.
URLConnection
object that represents a
connection to the remote object referred to by the URL
.
A new connection is opened every time by calling the
openConnection
method of the protocol handler for
this URL.
If for the URL's protocol (such as HTTP or JAR), there exists a public, specialized URLConnection subclass belonging to one of the following packages or one of their subpackages: java.lang, java.io, java.util, java.net, the connection returned will be of that subclass. For example, for HTTP an HttpURLConnection will be returned, and for JAR a JarURLConnection will be returned.
URL
and returns an
InputStream
for reading from that connection. This
method is a shorthand for:
openConnection().getInputStream()
Returns true
if this URL
and the
other
argument are equal without taking the
fragment component into consideration.
URLStreamHandlerFactory
.
This method can be called at most once in a given Java Virtual
Machine.
The URLStreamHandlerFactory
instance is used to
construct a stream protocol handler from a protocol name.
If there is a security manager, this method first calls
the security manager's checkSetFactory
method
to ensure the operation is allowed.
This could result in a SecurityException.
URL
. The
string is created by calling the toExternalForm
method of the stream protocol handler for this object.URL
. The
string is created by calling the toExternalForm
method of the stream protocol handler for this object.new URI (this.toString())
.
Note, any URL instance that complies with RFC 2396 can be converted to a URI. However, some URLs that are not strictly in compliance can not be converted to a URI.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify
method or the
notifyAll
method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) { while (<condition does not hold>) obj.wait(); ... // Perform action appropriate to condition }This method should only be called by a thread that is the owner of this object's monitor. See the
notify
method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) { while (<condition does not hold>) obj.wait(timeout); ... // Perform action appropriate to condition }(For more information on this topic, see Section 3.2.3 in Doug Lea's "Concurrent Programming in Java (Second Edition)" (Addison-Wesley, 2000), or Item 50 in Joshua Bloch's "Effective Java Programming Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify
method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait
method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify
method
or the notifyAll
method.
timeout
milliseconds plus nanos
nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) { while (<condition does not hold>) obj.wait(timeout, nanos); ... // Perform action appropriate to condition }This method should only be called by a thread that is the owner of this object's monitor. See the
notify
method for a
description of the ways in which a thread can become the owner of
a monitor.