Java Fundamental Classes Reference

Previous Chapter 15
The java.net Package
Next
 

URL

Name

URL

Synopsis

Class Name:

java.net.URL

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

java.io.Serializable

Availability:

JDK 1.0 or later

Description

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.

Class Summary

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);
}

Constructors

URL

public URL(String spec) throws MalformedURLException

Parameters

spec

A String that represents a URL.

Throws

MalformedURLException

If the string is incorrectly constructed or specifies an unknown protocol.

Description

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).

public URL(URL context, String spec) throws MalformedURLException

Parameters

context

A base URL that provides the context for parsing spec.

spec

A String that represents a URL.

Throws

MalformedURLException

If the string is incorrectly constructed or specifies an unknown protocol.

Description

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 

Parameters

protocol

A protocol.

host

A hostname.

file

A filename.

Throws

MalformedURLException

If an unknown protocol is specified.

Description

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 

Parameters

protocol

A protocol.

host

A hostname.

port

A port number or -1 to use the default port for the protocol.

file

A filename.

Throws

MalformedURLException

If an unknown protocol is specified.

Description

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:

  1. If an application has set up a URLStreamHandlerFactory by calling setURLStreamHandlerFactory(), the constructor calls the createURLStreamHandler() method of that object to create the protocol handler. The protocol is passed as a String argument to that method.

  2. If no URLStreamHandlerFactory has been established, or the createURLStreamHandler() method returns null, the constructor retrieves the value of the system property java.protocol.handler.pkgs. If this value is not null, it is interpreted as a list of packages separated by vertical bar (|) characters. The constructor then tries to load the class named package.protocol.Handler, where package is the name of the first package in the list and protocol is the name of the protocol. If the class exists, and is a subclass of URLStreamHandler, it is used as the URLStreamHandler for the protocol. If the class does not exist, or if it exists but is not a subclass of URLStreamHandler, the constructor tries the next package in the list.

  3. If the previous step fails to find an appropriate protocol handler, the constructor tries to load the class named sun.net.www.protocol.protocol.Handler, where protocol is the name of the protocol. If the class exists and is a subclass of URLStreamHandler, it is used as the URLStreamHandler for the protocol. If the class does not exist, or if it exists but is not a subclass of URLStreamHandler, a MalformedURLException is thrown.

Class Methods

setURLStreamHandlerFactory

 public static synchronized void setURLStreamHandlerFactory(URLStreamHandlerFactory fac) 

Parameters

fac

An object that implements URLStreamHandlerFactory.

Throws

Error

If the factory has already been defined.

SecurityException

If the application does not have permission to set the factory.

Description

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.

Instance Methods

equals

public boolean equals(Object obj)

Parameters

obj

The object to be compared with this object.

Returns

true

if the objects are equivalent;

false

if they are not.

Overrides

Object.equals()

Description

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.

getContent

public Object getContent() throws IOException

Returns

The Object created from the resource represented by this URL.

Throws

IOException

If any kind of I/O error occurs.

Description

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.

getFile

public String getFile()

Returns

The filename of the URL.

Description

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.

getHost

public String getHost()

Returns

The hostname of the URL.

Description

This method returns the hostname from this URL.

getPort

public int getPort()

Returns

The port number of the URL.

Description

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.

getProtocol

public String getProtocol()

Returns

The protocol of the URL.

Description

This method returns the protocol of this URL. Some examples of protocols are: http, ftp, and mailto.

getRef

public String getRef()

Returns

The reference of the URL.

Description

This method returns the reference, or anchor, of this URL.

hashCode

public int hashCode()

Returns

The hashcode of the URL.

Overrides

Object.hashCode()

Description

This method returns a hashcode for this object.

openConnection

public URLConnection openConnection() throws IOException

Returns

A URLConnection object for the URL.

Throws

IOException

If any kind of I/O error occurs.

Description

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.

openStream

public final InputStream openStream() throws IOException

Returns

A InputStream that reads from this URL.

Throws

IOException

If any kind of I/O error occurs.

Description

This method returns an InputStream object that reads the content of the given URL. The method is shorthand for calling openConnection().getInputStream().

sameFile

public boolean sameFile(URL other)

Parameters

other

The URL to compare.

Returns

A boolean value that indicates if this URL is equivalent to other with the exception of references.

Description

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().

toExternalForm

public String toExternalForm)

Returns

A string representation of the URL.

Description

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.

toString

public String toString()

Returns

A string representation of the URL.

Overrides

Object.toString()

Description

This method returns a string representation of this URL by calling toExternalForm().

Protected Instance Methods

set

 protected void set(String protocol, String host, int port, String file, String ref) 

Parameters

protocol

A protocol.

host

A hostname.

port

A port number.

file

A filename.

ref

A reference.

Description

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.

Inherited Methods

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

See Also

ContentHandler, Error, InputStream, IOException, MalformedURLException, SecurityException, URLConnection, URLStreamHandler, URLStreamHandlerFactory


Previous Home Next
SocketImplFactory Book Index URLConnection

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java