Packages This Package Prev Next Index
§4.8 Class URL
public final class java.net.URL
extends java.lang.Object (I-§1.12)
{
// Constructors
public URL(String spec); §4.8.1
public URL(String protocol, String host, §4.8.2
int port, String file);
public URL(String protocol, String host, String file); §4.8.3
public URL(URL context, String spec); §4.8.4
// Methods
public boolean equals(Object obj); §4.8.5
public final Object getContent(); §4.8.6
public String getFile(); §4.8.7
public String getHost(); §4.8.8
public int getPort(); §4.8.9
public String getProtocol(); §4.8.10
public String getRef(); §4.8.11
public int hashCode(); §4.8.12
public URLConnection openConnection(); §4.8.13
public final InputStream openStream(); §4.8.14
public boolean sameFile(URL other); §4.8.15
public static void §4.8.16
setURLStreamHandlerFactory(URLStreamHandlerFactory fac);
public String toExternalForm(); §4.8.17
public String toString(); §4.8.18
}
Class 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 format can be found at:
In general, an URL can be broken into several parts. The above URL indicates that the
protocol to use is http ("HyperText Transport Protocol"), that the information resides on a
host whose name is www.ncsa.uiuc.edu. The information on that host machine is named
demoweb/url--primer.html. The exact meaning of is name on the host machine is both protocol- and host-dependent. The information could reside in a file or could be generated on-
the-fly.
A URL can optionally contain a "port," which is the port number to which the connection
is made on the remote host. If the port is not specified, the default port for the URL is
used instead. For example, the default port for http, is 80. An alternative port could be specified as:
A URL may have appended to it an "anchor", which is indicated by the sharp sign character "#" followed by more characters. For example
This 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 "myinfo" 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 URL
contained within it a reference to the URL "FAQ.html", it would be a shorthand for
The relative URL need not specify all the components of a URL. Missing components are
inherited from the fully specified URL.
URL
public URL(String spec)
throws MalformedURLException
- Creates a URL object from the String representation.
- This constructor is equivalent to a call to the two-argument constructor
(I-§4.8.4) with a null first argument.
- Parameters:
spec
-
the String to parse as a URL
- Throws
- MalformedURLException (I-§4.15)
- If the string specifies an unknown protocol.
URL
public URL(String protocol, String host, int port,
String file)
throws MalformedURLException
- Creates a URL object from the specified protocol, host, port number, and file.
- If this is the first URL object being created with the specified protocol, a
stream protocol handler object, an instance of class URL-Stream-Handler
(I-§4.11), is created for that protocol:
- If the application has previously set up an instance of
URL--Stream--Handler--Factory as the stream handler factory (I-§4.8.16), then the
createURLStreamHandler (I-§4.14.1) method of that instance is called with the
protocol string as an argument to create the stream protocol handler.
- If no 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 (I-§1.18.9)
java.handler.protol.pkgs
If the value of that system property is not null, it is interpreted as a list of
packages separated by a vertical slash character '|'. The constructor tries to
load the class named
<package>.<protocol>.Handler
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 exists, or if it
the class exists but it is not a subclass of URL-Stream-Handler, then the next
package in the list is tried.1
- If the previous step fails to find a protocol handler, then the constructor tries
to load the class named
sun.net.www.protocol.<protocol>.Handler
If this class does not exist, or if t the class exists but it is not a subclass of
URL-Stream-Handler, then a MalformedURLException is thrown.
- Parameters:
protocol
-
the name of the protocol
host
-
the name of the host
port
-
the port number
file
-
the name of the information
- Throws
- MalformedURLException (I-§4.15)
- if an unknown protocol is specified.
URL
public URL(String protocol, String host, String file)
throws MalformedURLException
- Creates an absolute URL from the specified protocol name, host name, and
file name. The default port for the specified protocol is used.
- The constructor searches for an appropriate URLStreamHandler (I-§4.11)
as outlined above in I--§4.8.2.
- Parameters:
protocol
-
the protocol to use
host
-
the host to connect to
file
-
the name of the information
- Throws
- MalformedURLException (I-§4.15)
- if an unknown protocol is specified.
URL
public URL(URL context, String spec)
throws MalformedURLException
- Creates a URL by parsing the String specification within a specified context: If the context argument is not null and the spec argument is a partial
URL specification, then any of the strings missing components are inherited from the context argument.
- The specification given by the String argument is parsed to determine if it
specifies a protocol. If the String contains an ASCII colon ':' character
before the first occurrence of of an ASCII slash character '/', then the characters before the colon comprise the protocol.
- If the context argument isn't null, then the protocol is copied from the
context argument.
- If the context argument is null, then a MalformedURLException is thrown.
- If the context argument is null, or specifies a different protocol than the
specification argument, the context argument is ignored.
- If the context argument isn't null and specifies the same protocol as the
specification, the host, port number, and file are copied from the context
argument into the newly created URL.
The constructor then searches for an appropriate stream protocol handler
of type URLStreamHandler (I-§4.11) as outlined above in I--§4.8.2. The
stream protocol handler's parseURL method (I-§4.11.3) is called to parse
the remaining fields of the specification that override any defaults set by
the context argument.
- Parameters:
context:
-
the context in which to parse the specification
spec
-
a String representation of a URL
- Throws
- MalformedURLException (I-§4.15)
- If no protocol is specified, or an unknown protocol is found.
equals
public boolean equals(Object obj)
- The result is true if and only if the argument is not null and is a URL object
that represents the same URL as this object. Two URL objects are equal if
they have the same protocol, reference the same host, the same port number on the host, and the same information on the host.
- Parameters:
obj
-
the URL to compare against
- Returns:
- true if the objects are the same; false otherwise.
- Overrides:
- equals in class Object (I-§1.12.3).
getContent
public final Object getContent()
throws IOException
- Determines the contents of this URL. This method is a shorthand for
getFile
public String getFile()
- Returns:
- the information field of this URL.
getHost
public String getHost()
- Returns:
- the host name field of this URL.
getPort
public int getPort()
- Returns:
- the port number of this URL.
getProtocol
public String getProtocol()
- Returns:
- the name of the protocol of this URL.
getRef
public String getRef()
- Returns:
- the anchor (also known as the "reference") of this URL.
hashCode
public int hashCode()
- Returns:
- a hash code for this URL.
- Overrides:
- hashCode in class Object (I-§1.12.6).
openConnection
public URLConnection openConnection()
throws IOException
- Creates (if not already in existence) a URLConnection object that represents
a connection to the remote object referred to by the URL.
- The connection is opened by calling the openConnection method (I-§4.11.2)
of the protocol handler (I-§4.8.2) for this URL.
- Returns:
- a URLConnection (I-§4.9) to the URL.
- Throws
- IOException (I-§2.29)
- If an I/O exception occurs.
openStream
public final InputStream openStream()
throws IOException
- Opens a connection to this URL and return a stream for reading from that
connection. This method is a shorthand for
sameFile
public boolean sameFile(URL other)
- Returns true if the this URL and the other argument both refer to the same
resource; the two URLs might not both contain the same anchor.
- Parameters:
other
-
the URL to compare against
- Returns:
- true if they reference the same remote object; false otherwise.
setURLStreamHandlerFactory
public static void
setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
- Sets an application's URLStreamHandlerFactory (I-§4.14). This method can
be called at most once by an application.
- The URLStreamHandlerFactory instance is used to construct a stream protocol
handler (I-§4.8.2) from a protocol name.
- Parameters:
fac
-
the desired factory
- Throws
- Error (I-§1.48)
- If the application has already set a factory.
toExternalForm
public String toExternalForm()
- Constructs a string representation of this URL. The string is created by
calling the toExternalForm method (I-§4.11.5) of the stream protocol handler (I-§4.8.2) for this object.
- Returns:
- a string representation of this object.
toString
public String toString()
- Creates a string representation of this object. This method calls the
to-External-Form method (I-§4.8.17) and returns its value.
- Returns:
- a string representation of this object.
- Overrides:
- toString in class Object (I-§1.12.9).
1
Step 2 is new in Java 1.1.
Packages This Package Prev Next Index
Java API Document (HTML generated by dkramer on April 22, 1996)
Copyright © 1996 Sun Microsystems, Inc.
All rights reserved
Please send any comments or corrections to doug.kramer@sun.com