 |
Chapter 15 The java.net Package |
 |
|
Chapter 15 The java.net Package |
|
java.net.URL
java.lang.Object
None
java.io.Serializable
JDK 1.0 or later
The URL class represents a Uniform Resource Locator, or URL. The class provides methods for retrieving the various parts of a URL and also access to the resource itself.
An absolute URL consists of a protocol, a hostname, a port number, a filename, and an optional reference, or anchor. For example, consider the following URL:
http://www.woolf.net:81/books/Orlando/chapter4.html#p6
This URL consists of the following parts:
| Part | Value |
|---|---|
|
Protocol |
http |
|
Hostname |
www.woolf.net |
|
Port number |
81 |
|
Filename |
/books/Orlando/chapter4.html |
|
Reference |
p6 |
A relative URL specifies only enough information to locate the resource relative to another URL. The filename component is the only part that must be specified for a relative URL. If the protocol, hostname, or port number is not specified, the value is taken from a fully specified URL. For example, the following is a relative URL based on the absolute URL above:
chapter6.html
This relative URL is equivalent to the following absolute URL:
http://www.woolf.net:81/books/Orlando/chapter6.html
The URL class also provides access to the resource itself, through the getContent(), openConnection(), and openStream() methods. However, these are all convenience functions: other classes do the actual work of accessing the resource.
A protocol handler is an object that knows how to deal with a specific protocol. For example, an http protocol handler opens a connection to an http host. In java.net, subclasses of URLStreamHandler deal with different protocols. A URLStreamHandlerFactory selects a subclass of URLStreamHandler based on a MIME type. Once the URLStreamHandler has established a connection with a host using a specific protocol, a subclass of ContentHandler retrieves resource data from the host and creates an object from it.
public final class java.net.URL extends java.lang.Object
implements java.io.Serializable {
// Constructors
public URL(String spec);
public URL(URL context, String spec);
public URL(String protocol, String host, String file);
public URL(String protocol, String host, int port, String file);
// Class Methods
public static synchronized void setURLStreamHandlerFactory(
URLStreamHandlerFactory fac);
// Instance Methods
public boolean equals(Object obj);
public final Object getContent();
public String getFile();
public String getHost();
public int getPort();
public String getProtocol();
public String getRef();
public int hashCode();
public URLConnection openConnection();
public final InputStream openStream();
public boolean sameFile(URL other);
public String toExternalForm();
public String toString();
// Protected Instance Methods
protected void set(String protocol, String host, int port,
String file, String ref);
}
A String that represents a URL.
If the string is incorrectly constructed or specifies an unknown protocol.
This constructor creates a URL by parsing the given string. The string should specify an absolute URL. Calling this constructor is equivalent to calling URL(null, spec).
A base URL that provides the context for parsing spec.
A String that represents a URL.
If the string is incorrectly constructed or specifies an unknown protocol.
This constructor creates a URL relative to the base URL specified by context. If context is not null, and spec specifies a partial URL, the missing parts of spec are inherited from context.
The given string is first parsed to see if it specifies a protocol. If the string contains a colon (:) before the first occurrence of a slash (/), the characters before the colon comprise the protocol.
If spec does not specify a protocol, and context is not null, the protocol is inherited from context, as are the hostname, port number, and filename. If context is null in this situation, the constructor throws a MalformedURLException.
If spec does specify a protocol, and context is null or specifies a different protocol, the context argument is ignored and spec should specify an absolute URL. If context specifies the same protocol as spec, the hostname, port number, and filename from context are inherited.
Once the constructor has created a fully specified URL object, it searches for an appropriate protocol handler of type URLStreamHandler, as described for URL(String, String, int, String). Then the parseURL() method of the URLStreamHandleris called to parse the remainder of the URL so that the fields in spec can override any values inherited from context.
public URL(String protocol, String host, String file) throws MalformedURLException
A protocol.
A hostname.
A filename.
If an unknown protocol is specified.
This constructor creates a URL with the given protocol, hostname, and filename. The port number is set to the default port for the given protocol. Calling this constructor is equivalent to calling URL(protocol, host, -1, file).
public URL(String protocol, String host, int port, String file) throws MalformedURLException
A protocol.
A hostname.
A port number or -1 to use the default port for the protocol.
A filename.
If an unknown protocol is specified.
This constructor creates a URL with the given protocol, hostname, port number, and filename.
If this is the first URL object being created with the specified protocol, a protocol handler of type URLStreamHandler is created for the protocol. Here are the steps that are taken to create a protocol handler:
public static synchronized void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
An object that implements URLStreamHandlerFactory.
If the factory has already been defined.
If the application does not have permission to set the factory.
This method tells the URL class to use the given URLStreamHandlerFactory object for handling all URL objects. The purpose of this mechanism is to allow a program that hosts applets, such as a web browser, control over the creation of URLStreamHandler objects.
The object to be compared with this object.
if the objects are equivalent;
if they are not.
Object.equals()
This method returns true if obj is an instance of URL with the same protocol, hostname, port number, and filename as this URL. The reference is only compared if it is not null in this URL.
The Object created from the resource represented by this URL.
If any kind of I/O error occurs.
This method returns the content of the URL, encapsulated in an object that is appropriate for the type of the content. The method is shorthand for calling openConnection().getContent(), which uses a ContentHandler object to retrieve the content.
The filename of the URL.
This method returns the name of the file of this URL. Note that the file can be misleading; although the resource represented by this URL may be a file, it can also be generated on the fly by the server.
The hostname of the URL.
This method returns the hostname from this URL.
The port number of the URL.
This method returns the port number of this URL. If a port number is not specified for this URL, meaning it uses the default port for the protocol, -1 is returned.
The protocol of the URL.
This method returns the protocol of this URL. Some examples of protocols are: http, ftp, and mailto.
The reference of the URL.
This method returns the reference, or anchor, of this URL.
The hashcode of the URL.
Object.hashCode()
This method returns a hashcode for this object.
A URLConnection object for the URL.
If any kind of I/O error occurs.
This method returns a URLConnection than manages a connection to the resource represented by this URL. If there is not already an open connection, the method opens a connection by calling the openConnection() method of the URLStreamHandler for this URL. A URLStreamHandler for the protocol of the URL is created by the constructor of the URL.
A InputStream that reads from this URL.
If any kind of I/O error occurs.
This method returns an InputStream object that reads the content of the given URL. The method is shorthand for calling openConnection().getInputStream().
The URL to compare.
A boolean value that indicates if this URL is equivalent to other with the exception of references.
This method returns true if this object and the given URL object specify the same protocol, specify hosts that have the same IP address, specify the same port number, and specify the same filename. The filename comparison is case-sensitive. References specified by the URLs are not considered by this method. This method is a helper method for equals().
A string representation of the URL.
This method returns a string representation of this URL. The string representation is determined by the protocol of the URL. The method calls the toExternalForm() method of the URLStreamHandler for this URL. A URLStreamHandler for the protocol of the URL is created by the constructor of the URL.
A string representation of the URL.
Object.toString()
This method returns a string representation of this URL by calling toExternalForm().
protected void set(String protocol, String host, int port, String file, String ref)
A protocol.
A hostname.
A port number.
A filename.
A reference.
This method sets the protocol, hostname, port number, filename, and reference of this URL. The method is called by a URLStreamHandler to set the parts of the URL. A URLStreamHandler for the protocol of the URL is created by the constructor of the URL. It is this URLStreamHandler that parses the URL string. This method is used after parsing to set the values of the URL.
| Method | Inherited From | Method | Inherited From |
|---|---|---|---|
|
clone() |
Object |
finalize() |
Object |
|
getClass() |
Object |
notify() |
Object |
|
notifyAll() |
Object |
wait() |
Object |
|
wait(long) |
Object |
wait(long, int) |
Object |
ContentHandler, Error, InputStream, IOException, MalformedURLException, SecurityException, URLConnection, URLStreamHandler, URLStreamHandlerFactory
|
 |
|
| SocketImplFactory |  |
URLConnection |
